Policy Lifecycle State Machine

stateDiagram-v2
    [*] --> draft : Manager/Admin creates policy\n(blank or from template)

    draft --> pending_approval : Manager submits for review\nPOST /api/policies/{id}/submit\n[or POST /api/policies/{id}/approval-request]

    pending_approval --> draft : Admin rejects\nPOST /api/policies/{id}/approve {action:"reject"}\n→ notifies creator with rejection reason

    pending_approval --> approved : Admin approves\nPOST /api/policies/{id}/approve {action:"approve"}\n[self-approval blocked if adminCount > 1]

    approved --> published : Admin publishes\nPOST /api/policies/{id}/publish\n→ notifies all scoped employees

    published --> expiring : Cron job detects\nexpirationDate ≤ 30 days away

    expiring --> expired : Cron job detects\nexpirationDate passed

    expired --> draft : Admin renews (content changed)\nPOST /api/policies/{id}/renew {contentChanged:true}

    expiring --> published : Admin renews (dates only)\nPOST /api/policies/{id}/renew {contentChanged:false}

    draft --> [*] : Admin hard-deletes draft\nDELETE /api/policies/{id}

    note right of draft
        Template linkage fields:
        • sourceTemplateId
        • sourceVersion
        • sections[]
        Template update flow:
        templateUpdateAvailable → banner shown
        ↓ accept: merge template sections
        ↓ dismiss: clear flag
    end note

    note right of pending_approval
        Approval thread:
        GET /api/policies/{id}/approval-request
        POST /api/policies/{id}/approval-request/comment
        Comments visible to creator + reviewers
    end note

    note right of published
        Acknowledgment:
        POST /api/policies/{id}/acknowledge
        Tracks per-user annual sign-off
        needsAcknowledgment flag on GET /api/policies/{id}
    end note