# Stage 6 — Decision-Stage Agent (code)

This is the agent that surrounds the human hire/no-hire decision. It makes the decision fast and
humane without ever making it. Specifically, it:

- **Consolidates** the panel's scorecards into one decision packet and sends it to the deciders.
- **Keeps the candidate warm** with an honest timeline so they don't go cold or accept a rival offer.
- **Nudges the deciders** as the deadline approaches and passes.
- **Acts on the recorded decision** — advances a `hire`, or routes a `no_hire` to the recruiter to
  deliver personally. It **never decides, and never auto-rejects.**

## Files
- `stage6_decision_agent.py` — the agent.
- `stage6_candidates_sample.csv` — final-interview candidates (your ATS exports this).
- `stage6_decision_sample.json` — deciders per role, decision deadline, warm-update cadence.
- `stage6_decision_README.md` — this file.

## What it does, by state
- **`packet_pending`** → sends the consolidated packet to deciders with a deadline; sends the candidate an honest "you're in final review, expect to hear by X" note.
- **`awaiting_decision`, on track** → keeps the candidate warm on a cadence; no nagging.
- **`awaiting_decision`, deadline near** → gentle nudge to deciders.
- **`awaiting_decision`, overdue** → firmer nudge to deciders + an honest "taking a little longer" note to the candidate.
- **`decided` = hire** → advances to reference/background and sends the candidate good news.
- **`decided` = no_hire** → routes to the recruiter with a ready-to-edit draft, for a **personal** rejection. The agent never sends it.

## Safety rails (built in)
- **Dry-run by default** — prints what it would do, sends nothing.
- **Texts need consent** — SMS only when `consent_to_contact = TRUE`.
- **The decision is always human**, and **rejections are always delivered by a person**.
- **Audit log** of every packet, warm update, nudge, advance, and hand-off.

## Run it
1. Python 3.9+ in this folder.
2. `python stage6_decision_agent.py`
3. Watch all six paths play out — nothing is sent.

## Use your own data
- Replace the candidates CSV with your real final-interview list.
- In `stage6_decision_sample.json`, set each role's `deciders`, the `decision_deadline_days`, and
  how often to send the candidate a warm update.

## Going live
1. Edit the message templates (the warm-timeline notes and the rejection *draft*) to sound like you.
2. Wire the PROVIDER HOOKS: `send_email` / `send_sms`, `notify_person` (deciders & recruiter),
   `advance_stage` (update the ATS).
3. `DRY_RUN = False`, then test on your own addresses.

## Note on timing
`days_since_packet` and `days_since_last_update` simulate the clock so you can see nudges and warm
updates in one run. In production those come from your ATS, and you run the agent on a schedule.
Track the last warm update and last decider nudge so you don't repeat them.
