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

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