# Grants Runbook

# Grants Pipeline Runbook

Operator guide for the CTH Grants Pipeline -- a deadline-watcher state machine with 3 HITL gates.

## Architecture

The grants pipeline runs daily at 08:00 America/Bogota (13:00 UTC) via systemd timer.
It scans the Grants Opportunities Monday board for actionable rows and advances each
opportunity through an 8-step state machine.

Key principle: The pod NEVER auto-submits. It produces a ready-to-submit package;
a human performs the final submission.

## State Machine

```
evaluating -> fit_score -> go_no_go HITL1 -> scoping -> budgeting HITL2
-> drafting -> eval -> awaiting_HITL HITL3 -> ready_to_submit -> human submits
```

Terminal states: submitted, won, lost, no_go.

## HITL Gates

### Gate 1 -- GO / NO-GO (step 03)
- Approver: Gideon
- Auto GO: fit score >= 35/45
- Auto NO-GO: fit score < 25/45
- Conditional 25-34: requires explicit approval via Telegram inline keyboard
- Timeout: 30 minutes, run terminates cleanly, retries next tick

### Gate 2 -- Budget Review (step 05)
- Approver: Delegate
- Blocking gate: salary > 40 pct, run blocked until restructured or waived
- Red flags: overhead > cap, missing M&E line, routes to HITL for review
- Budget restructuring guidance provided in Telegram message

### Gate 3 -- Pre-Submission (step 07)
- Approver: Delegate
- Every pre-submission checklist line must be YES or explicitly waived
- Posts assembled package links + 24h deadline buffer reminder
- On approval: stage = ready_to_submit, pod STOPS

## How to Submit (Human)

After the pod marks an opportunity as ready_to_submit:
1. Review the package links posted in agent-ops
2. Verify all checklist items in the Grants HITL Approvals board
3. Submit via the funder portal or email as specified
4. Update the Grants Opportunities board: stage to submitted
5. Record submission details in Monday

## Manual Trigger

```bash
sudo systemctl start cth-runner@grants.service
```

## Logs

```bash
sudo journalctl -u cth-runner@grants.service -f
```

## Monday Boards

- Grants Opportunities: 18414094447 -- source/state board
- Grants Workflow Runs: 18414094534 -- per-tick run state
- Grants HITL Approvals: 18414094587 -- approval records
- Grants Audit Log: 18414094632 -- forensic trail for Advisory Board
- Grants Recovery Actions: 18414094675 -- failure tracking

## Planning Horizon

- Scan: 90 days before deadline, opportunities appear on radar
- Action required: 45 days before deadline, must be actively progressing
- Capacity guard: max 2 active drafts simultaneously