Codex 5.3 Refactor Note: Canonical refactor plan: docs/CODEX-5.3-REFACTOR-PLAN.md. This document is retained for historical and implementation context during the refactor.

W10 Quick Reference

🎯 What is W10?

W10 SMO Decision is the final approval stage where:

SMO/Admin reviews candidate escalated to TO_SMO
Finalizes decision: APPROVED, REJECTED, or KIV
Updates candidate status immutably
Logs audit events for compliance
Emits domain event for W16 notifications

🚀 5-Minute Quick Start

1. Verify Setup

npm run dev  # Start server
# Ensure candidate exists with status: TO_SMO

2. Navigate

Login as SMO user → Candidates → Select candidate → SMO Decision tab

3. Finalize

Select decision: APPROVED, REJECTED, or KIV
Add notes (required for REJECT/KIV)
Click "Finalize Decision"

4. Verify

✅ Status changes to APPROVED/REJECTED/KIV
✅ Form becomes read-only
✅ Server logs: [DomainEvent] DecisionUpdated: {...}

📝 Files Created

File	Type	Purpose
`src/app/api/candidates/[id]/decision/route.ts`	API	GET/POST decision
`src/app/(app)/candidates/[id]/_tabs/SmoDecisionTab.tsx`	Component	Decision form + history
`src/lib/events/emitter.ts`	Lib	Domain event stub
`W10-IMPLEMENTATION.md`	Docs	Full specification
`W10-DELIVERY.md`	Docs	Delivery summary
`W10-INDEX.md`	Docs	Navigation index

🔄 Decision Flow

Candidate at TO_SMO
        ↓
SMO reviews & decides
        ↓
POST /api/candidates/[id]/decision
        ↓
Validate (notes required for REJECT/KIV)
        ↓
Create Decision record (immutable)
        ↓
Update Candidate status
        ↓
Log audit events (DECISION_FINALIZED + CANDIDATE_STATUS_UPDATED)
        ↓
Emit DecisionUpdated event
        ↓
Candidate → APPROVED/REJECTED/KIV (final)

✅ Acceptance Checklist

SMO can finalize decision (APPROVED/REJECTED/KIV)
Notes required for REJECTED/KIV
Decision immutable (409 on retry)
Status updates: TO_SMO → final
Audit logged
Domain event emitted
RBAC enforced (SMO/Admin only)
No offer letter upload

🧪 Minimal Test

Create candidate with status TO_SMO
As SMO user, visit /candidates/[id]?tab=smo-decision
Select APPROVED, click "Finalize Decision"
Verify:
- Candidate status = APPROVED
- Form = read-only
- Server console = [DomainEvent] DecisionUpdated: {...}
- Audit logs = DECISION_FINALIZED + CANDIDATE_STATUS_UPDATED

🔐 Access Control

Role	Can View	Can Finalize
HR	✅	❌
Manager	✅	❌
SMO	✅	✅
Admin	✅	✅

📊 API Endpoints

GET /api/candidates/:id/decision

Auth: HR/Manager/SMO/Admin
Returns: Decision if exists, else null

POST /api/candidates/:id/decision

Auth: SMO/Admin only
Body: { decision, notes? }
Validates: TO_SMO status, notes required for REJECT/KIV
Immutable: 409 if already exists
Returns: { success, status, decision, decidedAt }

📚 Full Documentation

W10-DELIVERY.md - Delivery summary
W10-IMPLEMENTATION.md - Detailed specification (13 tests)
W10-INDEX.md - Navigation + API reference

❓ Common Questions

Q: What if candidate is not TO_SMO?
A: Form shows "Not in SMO review stage" and is read-only.

Q: Can I change my decision?
A: No. Decision is immutable. Second POST returns 409 Conflict.

Q: Are notes always required?
A: Only for REJECTED/KIV. Optional for APPROVED.

Q: Who gets notified?
A: Domain event emitted (stub). W16 will route to notifications.

Q: What about the offer letter?
A: Not in W10. W11+ will handle offer uploads.

🛠️ Troubleshooting

Problem: Form shows "Not in SMO review stage"
→ Candidate status is not TO_SMO. Escalate via Manager Review tab first.

Problem: Cannot click "Finalize Decision" button
→ Check user role (must be SMO/Admin). Check candidate status (must be TO_SMO).

Problem: Got 409 Conflict error
→ Decision already exists (immutable). Refresh page to see finalized decision.

Problem: Domain event not showing in console
→ Check server logs (not browser console). Event logs on POST success.

📞 Support

For issues or questions:

Review W10-IMPLEMENTATION.md Test Checklist
Check API responses for error details
Review audit logs for history