roboco/docs/rag/architecture/board-programs.md

# Board Program Registry

## What It Is

Fourteen periodic/event-driven origination cycles — the Board actually doing strategic work instead of only reviewing it — ride one generic registry + engine instead of bespoke per-engine loops. `BoardProgram` (`roboco/foundation/policy/board_programs.py`) is a frozen registry entry; `PROGRAMS` holds all fourteen. `BoardProgramEngine` (`roboco/services/board_programs.py`) is the shared trigger/dedup/originate/LEARN machinery every entry rides. Every artifact any program produces is HELD — the CEO is the only path to materialization. Nothing auto-starts, auto-posts, or auto-merges.

The lifecycle is uniform across every program:

```
TRIGGER → EXPLORE → PROPOSE → DECIDE → MATERIALIZE → LEARN
 (loop)   (solo      (one verb  (CEO     (per-program   (outcome fed to
           spawn,     call,      queue,   materializer)   next cycle's
           read-only  held)      per-item)                exploration prompt)
```

## The fourteen programs

| Key | Role | Trigger | Scope | Source marker | Proposal verb | Materializer |
|-----|------|---------|-------|----------------|----------------|---------------|
| `roadmap` (Printer) | product_owner | cron, weekly | org | `board_roadmap` | `propose_roadmap` | backlog tasks, per-item CEO decision |
| `pest_control` (Pest Control) | product_owner | cron, weekly + rework-spike metric | project | `board_pest_control` | `propose_bug_hunt` | backlog tasks, per-item CEO decision |
| `spackle` (Spackle) | product_owner | cron, biweekly | project | `board_spackle` | `propose_gap_fill` | backlog tasks, per-item CEO decision |
| `scales` (Scales) | product_owner | cron, monthly | org | `board_scales` | `propose_rebalance` | mutates a LIVE task in place (reprioritize/cancel) on approval — never creates a task |
| `dogfood` (Dogfood) | product_owner | event (release-publish hook or CEO run-now) | project | `board_dogfood` | `propose_friction_fixes` | backlog tasks, per-item CEO decision |
| `periscope` (Periscope) | head_marketing | cron, weekly | org | `board_periscope` | `propose_market_brief` | held report only, no task, no per-item decision |
| `megaphone` (Megaphone) | head_marketing | cron, every 3 days | org | `board_megaphone` | `propose_editorial_post` | held X draft (existing X queue) |
| `mirror` (Mirror) | head_marketing | cron, quarterly | project | `board_mirror` | `propose_messaging_fixes` | backlog docs tasks, per-item CEO decision |
| `barfly` (Barfly) | head_marketing | cron, every 2 days | org | `board_barfly` | `propose_conversation_replies` | held X draft per reply (existing X queue) |
| `war_room` (War Room) | head_marketing | event (release-publish hook or CEO run-now) | org | `board_war_room` | `propose_campaign` | N held X drafts as one batch (existing X queue) |
| `x_feature` (feature spotlight) | head_marketing | cron, default daily | org | `x_feature_exploration` | `propose_feature_spotlight` | held X draft (existing X queue) |
| `coroner` (Coroner) | auditor | event only — no cron | org | `board_coroner` | `propose_postmortem` | a held process-change item, or a playbook drafted directly when `process_change.kind='playbook'` |
| `librarian` (Librarian) | auditor | cron, biweekly | org | `board_librarian` | `propose_playbook_drafts` | 1-3 DRAFT playbooks via `PlaybookService` directly, into the same curation queue |
| `sentinel` (Sentinel) | auditor | cron, weekly | org | `board_sentinel` | `propose_quality_report` | held report only, no task, no per-item decision |

`roadmap` and `x_feature` predate the registry; migrating them onto it was deliberately behavior-identical (Phase 1). The other twelve are new (Phase 2/3).

## Enable/Disable — no master flag

Unlike most feature-flagged subsystems, there is **no `ROBOCO_BOARD_PROGRAMS_ENABLED`**. Every program is armed independently through `program_armed(session, key)` — THE single chokepoint every origination path routes through (the cron loop, the metric-predicate check, the CEO's "run now", the strategy-engine idle trigger). It reads a settings-store row `board_program.{key}.enabled`; only `roadmap` and `x_feature` fall back to a legacy env flag (`ROBOCO_ROADMAP_ENGINE_ENABLED`; `ROBOCO_X_ENGINE_ENABLED` AND `ROBOCO_X_FEATURE_SPOTLIGHT_ENABLED`) when no settings-store row exists yet. Every other program is settings-store-only and defaults **off** — a fresh deployment originates nothing until the CEO flips a toggle on the Board Programs panel page.

The one env knob among the twelve new programs: `ROBOCO_PEST_REWORK_THRESHOLD` (default `0.3`) — the 7-day rework rate above which Pest Control's metric predicate opens a cycle off-schedule, on top of its own weekly cron. No other new program has a compose-level setting; per-program cadence overrides (when set) also live in the settings store, not env.

## Scope and dual-polarity project participation

`projects.board_programs` (migration `088`, nullable jsonb list of strings) governs which projects a program runs against or outputs into:

- **`scope="project"`** programs (they read one repo: Pest Control, Spackle, Dogfood, Mirror — see the table above) need an **affirmative opt-in**: the plain key (`"pest_control"`) must be present in the list, or the program has no opted-in project and a cycle is never even opened (`_scope_gate`). Null/absent = out.
- **`scope="org"`** programs (they read the org's own process or the external market: roadmap, Scales, Periscope, Megaphone, Barfly, War Room, Coroner, Librarian, Sentinel, x_feature) run **org-wide by default** and are excluded per-project only by the opposite-polarity entry: `"!roadmap"` opts a project OUT of that program's output. Null/absent = in.

One pure helper, `project_participates(program, board_programs_field)`, implements both polarities; `validate_board_programs_field` rejects an unknown key, a meaningless `"!"` on a project-scoped key, or a meaningless plain key on an org-scoped key. Panel: the project settings page's budget/ops card renders project-scoped programs as "participates in" checkboxes and org-scoped programs as "excluded from" checkboxes.

## The engine mechanics

`BoardProgramEngine.run_due_programs` (called by the orchestrator's `_board_program_loop` on a floor interval — the shortest registered cadence, clamped 300s-3600s) walks every CRON program: enabled → scope-gated → dedup-checked against the `board_program_cycles` ledger (migration `087`; one row per cycle, `closed_at IS NULL` = open, auto-closed the moment its exploration task goes terminal) → cron-due (`program_due`) → originate via the program's `_ORIGINATORS` callable (each program's own engine's `run_cycle`, e.g. `PestControlEngine.run_cycle`) → record the cycle row. It then separately runs every registered metric predicate (`_METRIC_PREDICATES`, today only Pest Control's rework-spike check) — cheap gates (scope, dedup) run BEFORE the predicate itself, so a multi-query metric check never runs on a tick that was always going to be rejected.

`open_program_cycle(key)` is the same enabled+scope+dedup path minus the cron-due check — the seam the CEO's panel "run now" button and the Strategy Engine's `idle` trigger both use (`docs/rag/architecture/company-layer.md`). **Only Printer is wired to the strategy-engine idle trigger** — the design intent to also trigger Coroner off `stranded_blocked` was not built; Coroner is event-only, triggered exclusively by its own three hooks (see below).

Every exploration is a **solo one-shot spawn** — the board dispatcher's `_dispatch_board_program_exploration` (a dict-dispatch table keyed by `task['source']`) routes it to a dedicated one-shot dispatcher (e.g. `_dispatch_pest_control_exploration`) that bypasses the two-reviewer board-review gate (`_handle_board_assigned_task`) entirely — a program cycle has exactly one author, never a PO+HoM pair. Every dispatcher reuses the `_board_dispatched` one-shot tracker + respawn breaker. Every program source is in the dispatchers' skip bucket (`_is_non_dev_dispatch_source`) — a program exploration task is never mistaken for delivery work.

### Coroner's event hooks

Coroner is the one program with `trigger=event` AND a real trigger wired outside the loop (unlike `war_room`, whose event trigger IS also reachable through `open_program_cycle` for a CEO on-demand run — Coroner has no on-demand path, only incidents). Three chokepoints call `CoronerEngine.open_for_incident(task_id, kind=...)` directly:

- `TaskService`'s bounce transition — a task crossing into `needs_revision` for the 3rd+ time (`revision_count >= 3`), `kind="bounced"`.
- `TaskService`'s cancel path — a task cancelled after real work had started, `kind="cancelled"`.
- The orchestrator's budget-block path — a task blocked on a budget breach, `kind="budget"`.

Only one autopsy is open at a time (the same `board_program_cycles` dedup every cron program uses); a second incident firing while one is open waits.

### War Room and Dogfood's release hooks

`WarRoomEngine.open_for_release(...)` and the release-publish path both bypass `_ORIGINATORS` entirely and open a cycle directly, mirroring Coroner's `open_for_incident` shape — War Room's release brief carries the version + curated highlights so posts never invent a feature; a CEO on-demand run (blank brief) instead rides the ordinary `open_program_cycle("war_room")` path. Dogfood similarly has a real `_ORIGINATORS["dogfood"]` binding (unlike Coroner's always-`None` stub) — a walk needs no external incident id, just the next opted-in project in rotation, so both the release-publish hook and a CEO "run now" open a cycle through the ordinary path.

### Rotation for project-scoped programs

Pest Control, Spackle, Mirror, and Dogfood share one round-robin picker, `pick_rotation_target`: among a program's opted-in projects, never-explored beats explored, else the oldest `last_opened_at` wins (read from the programs' own exploration tasks, not the LEARN ledger — a project-scoped program can run its engine's `run_cycle` directly, outside `BoardProgramEngine`, so the ledger alone would be blind to some cycles).

## LEARN

`BoardProgramEngine.record_decision(program_key, item_ref, verdict, reason, exploration_task_id=...)` accrues one CEO approve/reject onto the cycle row's `decisions` jsonb column, incrementing `items_proposed`/`items_approved`/`items_rejected`. `prior_cycle_context(program_key, limit=2)` renders the last two CLOSED cycles ("proposed N, approved N; rejected: item — reason") for injection into the NEXT cycle's exploration prompt — every producer of a per-item decision (`RoadmapService`, `PestControlService`-equivalent per-program services) calls this, so a program stops re-proposing something the CEO already rejected without explanation. This is the one genuinely new pipeline stage the registry introduced; the pre-registry roadmap/spotlight engines had no memory of prior outcomes at all.

## Panel and API

`GET /api/board-programs` and `POST /api/board-programs/{key}/run-now` (`roboco/api/routes/board_programs.py`, CEO-only, `require_ceo_role`) back the Board Programs page (Business section, `board-programs-card.tsx`): each program's live enablement, trigger kind, scope, opted-in project slugs, last-run timestamp, whether a cycle is currently open, and the most recent closed cycle's summary — plus a `Switch` that writes `board_program.{key}.enabled` through the generic feature-flag settings endpoint and a "Run now" button (disabled while a cycle is already open) that calls `open_program_cycle` off-schedule. `run-now` 404s on an unregistered key and 409s when the program is disabled, already has an open cycle, or (a project-scoped program) has no opted-in project — the three collapse into one `None` result with no finer-grained distinction available to the caller.

Per-program held artifacts reuse existing queues where the shape matches — the roadmap review queue, the X post queue (Megaphone/Barfly/War Room/spotlight all land there) — rather than growing a new panel surface per program; reports (Periscope, Sentinel) and process-change items (Coroner) and the playbook curation queue (Librarian) are the only genuinely distinct surfaces.

## Related

- CLAUDE.md's "Board Program registry" entry — the condensed architectural summary.
- `docs/rag/architecture/company-layer.md` — the Strategy Engine's `idle` → Printer trigger.
- `docs/rag/architecture/x-engine.md` — the X held-draft queue every X-bound program (Megaphone/Barfly/War Room/spotlight) materializes into.
- `docs/rag/architecture/review-findings.md` — the findings ledger Pest Control reads.
- `docs/rag/roles/auditor.md` — the playbook curation queue (`approve_playbook`/`reject_playbook`/`archive_playbook`) Coroner and Librarian both feed.
- `docs/rag/roles/product-owner.md` / `docs/rag/roles/head-marketing.md` / `docs/rag/roles/auditor.md` — each role's exact `propose_*` call shape and when it fires.