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 SMO Decision Index

📋 Documentation Files

Quick Start & Overview

• W10-DELIVERY.md - Executive summary, what's delivered, acceptance criteria
• W10-IMPLEMENTATION.md - Full 13-test-case specification (A-H format)

---

🚀 Getting Started (5 minutes)

1. Read W10-DELIVERY.md (2 min)
2. Database: No migration needed (Decision model already exists)
3. Start server: npm run dev
4. Test: Follow Test Checklist in W10-IMPLEMENTATION.md

---

📁 Code Organization

API Routes

• src/app/api/candidates/[id]/decision/route.ts (NEW)
  • GET: Fetch decision (HR/Manager/SMO/Admin)
  • POST: Finalize decision (SMO/Admin only)

UI Components

• src/app/(app)/candidates/[id]/_tabs/SmoDecisionTab.tsx (NEW)
  • Editable form (SMO/Admin when TO_SMO)
  • Read-only history (if decision exists)
  • Status checks & warnings

Updated Files

• src/app/(app)/candidates/[id]/page.tsx - Added SMO Decision tab
• src/lib/validation/schemas.ts - Added decisionSchema
• src/lib/events/emitter.ts - Created domain event stub

---

🧪 Test Matrix

Test Case	Description	Expected
1	View decision (HR)	Read-only ✅
2	Finalize - Approve	Status updates ✅
3	Finalize - Reject with notes	Status updates ✅
4	Finalize - Reject without notes	Validation error ✅
5	Finalize - KIV with notes	Status updates ✅
6	Second submit	409 Conflict ✅
7	Wrong status	Read-only message ✅
8	Non-SMO user	Read-only form ✅
9	Admin can finalize	Status updates ✅
10	Unauthenticated	401 Unauthorized ✅
11	Missing candidate	404 Not Found ✅
12	Audit logs	DECISION_FINALIZED + CANDIDATE_STATUS_UPDATED ✅
13	Domain event	Console: [DomainEvent] DecisionUpdated ✅

---

📊 API Reference

GET /api/candidates/:id/decision

Auth: HR/Manager/SMO/Admin
Response:

{
  "candidateId": "...",
  "decision": {
    "id": "...",
    "decision": "APPROVED|REJECTED|KIV",
    "notes": "...",
    "decidedBy": { "id": "...", "email": "...", "fullName": "..." },
    "decidedAt": "2026-01-23T18:30:00Z"
  }
}
// or null if not decided yet

POST /api/candidates/:id/decision

Auth: SMO/Admin only
Body:

{
  "decision": "APPROVED|REJECTED|KIV",
  "notes": "optional for APPROVE, required for REJECT/KIV"
}

Response (200):

{
  "success": true,
  "status": "APPROVED|REJECTED|KIV",
  "decision": "APPROVED|REJECTED|KIV",
  "decidedAt": "2026-01-23T18:30:00Z"
}

Response (400): Validation error

{
  "error": "Validation failed",
  "details": { "fieldErrors": {...} }
}

Response (409): Already decided

{
  "error": "Decision already finalized (immutable)"
}

---

🔑 Key Implementation Details

Validation Rules

• Decision must be APPROVED, REJECTED, or KIV
• Notes required if REJECTED or KIV
• Notes optional if APPROVED
• Candidate must be in TO_SMO status to finalize

Transactional Behavior

1. Create Decision record
2. Update Candidate status (TO_SMO → APPROVED/REJECTED/KIV)
3. Both succeed or both fail (atomic)

Immutability

• Once decision created, cannot update or delete
• Second POST returns 409 Conflict
• No PATCH/PUT endpoints

Audit Trail

• DECISION_FINALIZED: Records decision + notes
• CANDIDATE_STATUS_UPDATED: Records status transition + reason

Domain Events

• DecisionUpdated emitted to console
• W16 will implement outbox table + notification routing
• Payload includes: candidateId, decision, decidedBy, notes, timestamp

---

❓ FAQ

Q: Can a candidate see their decision?
A: No. Current implementation is internal only (SMO → HR). W16+ may add candidate notifications.

Q: Can a decision be changed?
A: No. Decision is immutable. Second POST returns 409.

Q: Are notes required for APPROVED decisions?
A: No. Notes are optional for APPROVED, required for REJECTED/KIV.

Q: What happens to the offer letter?
A: Not implemented in W10 (out of scope per requirements). W11+ will handle offer uploads.

Q: Who gets notified when decision is finalized?
A: Currently no notifications sent (DecisionUpdated event is stubbed). W16 will implement notification routing.

---

📝 Notes

• No database migration required
• No offer letter upload in W10
• Domain event stub only (console logging)
• Next phase (W11): Offer letter management