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:
- Review the package links posted in agent-ops
- Verify all checklist items in the Grants HITL Approvals board
- Submit via the funder portal or email as specified
- Update the Grants Opportunities board: stage to submitted
- Record submission details in Monday
Manual Trigger
sudo systemctl start cth-runner@grants.service
Logs
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