drive-epic

# Drive an epic lane You were launched to **drive one epic/track lane** (`SESSION_EPIC` is set). You are **NOT** the main orchestrator. This skill is the portable playbook every non-Claude driver — and Claude when driving a track — follows so orchestration behaves the same regardless of which model is in the seat. **Golden rule of this skill: it teaches the *method*, never the *roster*.** Who is in which lane, which model fits which task, and the current width (CodexBar pace/reserve + disk headroom, not a fixed cap) are **live data** that change; always read them fresh from the served rules and catalog, never from memory: - `GET http://127.0.0.1:8765/api/rules` — model-assignment (routing SSOT), review-seat economics, cross-family pairing. Served first; supports `If-None-Match`. - `scripts/config/model_catalog.yaml` — machine-enforced quality floors + ordered peer tiers per task-risk. - `docs/best-practices/agent-activity-matrix.md` §2/§2b — roster + no-idle capacity routing. **Driver role (not a clerk).** You own the lane's judgment: what is wrong, what is next, which model×harness should do it, whether the artifact actually worked, and what residual remains. Dispatch exists so the fleet does the volume; it is not a substitute for thinking. Always use established best practice (`docs/best-practices/` and the live prior art for the domain); find and fix the root cause before treating a symptom. You decide in-scope calls. You are not a designated advisor (Fable/Astra) and not the CF of record for work you drove — you *do* read the review and the diff before you merge. Spend other seats to keep this context on the hard turn, not to avoid a decision you can already make. Unused paid quota is waste (§2c); manufactured work is a defect. Judgment is not implementation — seat no-solo rules still bind. ## Do not make the operator repeat this These four were already binding and this seat still dropped them. They are checked every cycle, before any status sentence. 1. **DoR before dispatch.** Start substantive work only when the task card and the dispatch preflight are both green. Chat "ready" is not DoR. Tables: `docs/best-practices/task-quality.md` and `/api/rules` → `operator-expectations.md` §3b. 2. **DoD before "done".** Done means the user-visible outcome is verified, git hygiene is done, and GitHub hygiene is done. A dispatch, a branch, an open PR, green CI, or "Next:" is not Done. The driver merges after exact-head cross-family APPROVE and green CI on that head. Do not ask the operator to merge. Same sources, §3a. 3. **Git and GitHub hygiene.** The primary checkout stays on `main` and is read-only. Edits, commits, and PRs happen only in `.worktrees/dispatch/<agent>/<task>/`. Every commit has an `X-Agent` trailer. Never push to `main`. No PR, draft or ready, before exact-head cross-family APPROVE — a draft starts CI here. After `MERGED`, `merge_closeout --apply` must prove the remote branch is gone, the local branch is gone, and no worktree remains. A non-zero closeout is a blocker. 4. **Know every worker's status.** Do not say a worker is running, finished, or stuck unless `delegate.py status <task-id>` was run in this turn. Keep the task id, that status, and the branch head. After every dispatch, arm `delegate.py wait <task-id>` before the turn ends. This seat has no Monitor tool; §5's Monitor path does not wake it. When the wait returns, read the result and take the next action. A finished worker that sits until the operator asks is a driver defect. If any claim you are about to make (a lane name, a cap, a word/stress/morphology fact, a gate status, a count) is not in fresh tool output, **STOP and run the tool** — every verifiable claim is tool-backed (deterministic-over-hallucination). **Work-board orientation surface:** `GET http://127.0.0.1:8765/api/work/v1/projection` returns the merged work board — issues, PRs, dispatch tasks, and reviews — with each item carrying a rule-derived `health` (`ON_TRACK` / `AT_RISK` / `OFF_TRACK` / `UNKNOWN` — authority missing/stale, pairs with the `INSPECT_UNKNOWN` safe action; see `HEALTH_RANK` in `scripts/work/attention.py`), an `attention_rank`, and a `safe_next_action`. Query it at orient and again when picking the next unblocked action (§2); it is a queue INPUT alongside your stream/GH/issue sources, never a replacement for them. **Stream next-queue:** `GET http://127.0.0.1:8765/api/work/v1/next?stream=<your-stream>` returns a compact, stream-scoped actionable pick list (default `limit` 7). Consult it at orient and next-action time alongside the projection — also a queue INPUT, never a replacement. Cold (absent) cache → `503` `building` + `retry_after_s` (does not trigger a build); unknown `stream` → `400` with `valid_streams`. --- ## The loop (run it every cycle) ### 0. Orient ```bash curl -sS --max-time 2 "http://127.0.0.1:8765/api/orient?lean=true" || true curl -sS --max-time 2 "http://127.0.0.1:8765/api/work/v1/projection" || true # best-effort: local server, degraded/absent sources are normal curl -sS --max-time 2 "http://127.0.0.1:8765/api/work/v1/next?stream=<your-stream>" || true # stream-scoped pick list (#6880) .venv/bin/python -m scripts.fleet_comms plane-status # message-plane mode/parity ``` Know your `SESSION_EPIC`, your stream, and your handoff slot (the launcher already claimed the stream lease — do **not** open or resume it yourself). Establish your session-health signal **by seat**: **grok / gemini / kimi** have a canary lane — `.venv/bin/python -m scripts.session_canary.{grok,gemini,kimi}_lane mint --epic <epic>`; **Claude / Sonnet** have **no** canary lane and use the native SessionStart / PostCompact hook chain + thread-handoff instead (do not call a non-existent `<model>_lane`). ### 0a. Required live-driver inbox drain — cycle start At the start of **every** cycle, inspect this driver's legacy inbox. The live loop — not a detached `process-*` / `ask-*` worker — must read and apply every message marked `unread` or `read-but-not-live-consumed`, then record that consumption explicitly: ```bash .venv/bin/python -m scripts.ai_agent_bridge inbox --for "$SESSION_HANDOFF_AGENT" .venv/bin/python -m scripts.ai_agent_bridge ack --consumed-by-live-driver <message-id> [<message-id> ...] ``` Never use a plain `ack` for messages this live loop has consumed: plain acknowledgement also records one-shot/headless processing and is not delivery proof for the live driver. ### 0b. Optional Monitor inbox-watcher wakeup — cold start only At cold-start, **if your harness has a Monitor-equivalent**, invoke it once with that harness's `persistent`/timeout option, pointed at this one shell command: ```bash scripts/ai_agent_bridge/inbox_watch.sh "$SESSION_HANDOFF_AGENT" ``` This is a **wakeup signal only**: each stdout line says that an unconsumed legacy message exists, with its id, sender, request id, and a bounded preview. It never reads the full body into your context and never marks a message consumed. You still must run the existing required `0a` / `4a` / `5a` / `8a` inbox-drain steps to read, apply, and explicitly live-consume everything the signal points at; those steps remain the universal fallback for every seat, watcher or not. Direct confirmation exists only for **Claude Code, Gemini/AGY, and Grok CLI**. For any other harness, ask the running agent directly whether it has an equivalent before using one; do not infer it from documentation or `--help`. Stop a running watcher cleanly with `scripts/ai_agent_bridge/inbox_watch.sh --stop "$SESSION_HANDOFF_AGENT"`; if a crashed process leaves a stale pidfile, the operating system releases its advisory lock and the next watcher replaces the recorded pid safely. ### 0c. Hramatka epic — dual-repo queue (epic #4542 only) If `SESSION_EPIC` is Hramatka (public #4542), the priority/ownership queue is private BOARD `learn-ukrainian-infra-private#349`, not the public epic body. Cold-start read order: **private #349 → private open PRs → public PRs linked from #4542 only.** Public #4542 is charter + bare pointer — never generate or mirror a public checklist from the private board (leak + dual-write). GitHub issue/PR state in either repo remains the factual SSOT for open/closed; #349 is the priority queue, not a duplicate status feed. Operator-only host mutation (private #360, #212) is **ESCALATE**, not solo action, on missing GO. If #349 and any other queue view disagree, **#349 wins** — correct the other view the same session. Full contract: `docs/runbooks/hramatka-driver-queue.md`. Before a new dispatch, scope, or PR, run `scripts.fleet.hramatka_scope_gate` as specified in that runbook; only `ALLOW` permits the new action. ### 0d. CORE V7 `--upgrade` / A1 rollout (epics #7994 / #7995) This is **not** `$track-completion` (fresh CORE) and **not** a second driver skill. Same `$drive-epic` loop. Product loop and scars: [`docs/epics/a1-upgrade-operating-rules.md`](../../../../docs/epics/a1-upgrade-operating-rules.md). Writer/reviewer seats live there and in `/api/rules` — do not freeze a roster here. **Done** is the learner URL on the canonical track (`/a1/<slug>/` for this epic), with Pages only on present-tense operator GO (§7-rollout). Engine-on-`main` and `run_lesson_gates` green in a worktree are **not** done. Binding for this lane: 1. Preserve-and-expand archived `a1-v1` (or the stated archive). Do not rebuild by hand. Do not rewrite original prose because an upgrade activity is wrong — drop or replace the **invented** pair; show archive vs upgrade when a CF finding looks like a rewrite. 2. The **driver does not decide Ukrainian**. Gemini writes; Astra reviews; they settle language. Do not referee stress, letters, or morphology in the driver seat. 3. **Machinery is Fable 5.1, not Sonnet** (operator 2026-09-18). Advanced machinery (`scripts/`, gates, the writer-prompt contract) goes to `claude-fable-5-1` with `--mode danger`. Claude `workspace-write` does not grant writes, so that mode returns a no-op. A bug found in the old module is fixed by this machine: the writer is not given the bad content, and the gate fails if it comes back. Do not hand-edit the lesson, the plan, or `lessons.yaml` to hide it. Do not start the paid writer until a rendered prompt is clean of the reported defect. The driver does not solo-implement. 4. Content PRs are **scripts-free**. One Astra CF per content PR. While CF/CI runs on module N, package N+1 (pipeline). Do not dump every module on one reviewer in one turn. 5. After gates pass in a worktree, **open the content PR the same session**. Sitting on green worktrees is a driver defect (§2a / §2c). ### 1. Read topology + metrics (don't hold state — query it) ```bash .venv/bin/python -m scripts.fleet_comms metrics # efficiency metrics (no content) .venv/bin/python -m scripts.fleet_comms backlog # pending/dispatched delivery .venv/bin/python -m scripts.fleet_comms dead-letters # stuck deliveries ``` Fleet-comms externalizes topology + usage so you decide against fresh state, not a stale in-context snapshot. For per-lane budget health before dispatch: `.venv/bin/python -m scripts.fleet.capacity_pick` then `scripts/delegate.py dispatch --check-budget` (or `LU_DISPATCH_CHECK_BUDGET=1`) (+ `/api/state/routing-budget` for subscription lanes). **Pre-dispatch pace check (binding):** read `.venv/bin/python -m scripts.fleet.usage show` (or the `capacity_pick` pace column) before every implement dispatch — a lane at/ahead of pace or in deficit (`will_last_to_reset=False`) is not a dispatch target while a cool lane has reserve. ### 2. Pick the next unblocked action Source of next work: your epic's stream tail / handoff, open GH issues for the epic, the build/review queue, the Work API projection's ranked attention list (§0), and `GET /api/work/v1/next?stream=<your-stream>` — cross-check against them before committing to an action. **Step 0 of any dispatch:** `gh pr list --state all --search "<issue-nr>"` by issue reference (an open issue ≠ unfixed; a sibling PR may already carry it). If nothing genuinely fits a free lane, log it and leave it idle — never manufacture busywork (quality > utilization). ### 2-epic. Epic issue ownership cycle (binding — operator 2026-08-28) You are an **epic orchestrator**, not a clerk waiting on one PR. Every cycle must advance the epic's open issue set: 1. **Inventory** — open GitHub issues for this epic/stream (plus Work API `/next` + grok-bot QA issues per §2b). Quote the count. 2. **Disposition each item** — for every open issue, exactly one of: - **in_flight** (named PR/task id + head), - **dispatch now** (ROUTING_CARD + `capacity_pick` / `/api/state/routing-budget` + `--check-budget`), - **named hold** with one §2c code (`dependency_blocked | authoring_wip_cap | review_wip_cap | ci_capacity | worktree_wip_cap | disk_capacity | integration_wip_cap | human_decision | no_ready_work`). 3. **Silence is a defect** — an open epic issue with no disposition is a driver failure. 4. **Closeout** — after merge: close the issue (or prove residual), then follow §7a order (P0 reaper first, then branch deletion). Merge alone is not done. **Anti-passive (all seats, Cursor especially):** while CF or CI runs on unit N, you **must** either dispatch the next ready epic child or emit a §2c disposition code in the same turn. Ending a turn with only "waiting on review/CI" and no fill/disposition is forbidden. Overnight/session gaps do not excuse an unfinished CLEAN/MERGEABLE PR — re-read checks and finish merge/hygiene on the next live turn. ### 2a. NO FABRICATED DONE (binding all epic drivers) - Never invent acceptance thresholds the operator, issue, or epic goal did not set. - Never declare a goal done while measured residual remains in the same mandate unless tools prove it impossible or the operator accepted it on the issue. - Never end with "when you want" or an "optional next" for in-scope residual — dispatch it. - Never relabel unfinished work as an intentional skip without issue text or tool proof. - Before "done" or handback, quote the tool residual count; `residual > 0` requires a next dispatch in the same session. ### 2b. Grok-bot QA findings — queue input, not a fleet seat Grok Bot (`app/cursor`) is an **external QA observer** — it reads CI/site signals and files labeled GitHub issues; drivers consume those issues through the normal loop above like any other open issue. It is **never** a dispatch target: no `--agent grok-bot`, no `ask-grok-bot`, no fleet-comms seat. If Grok Bot ever authors a PR, same-family Grok must not CF it — route to an outside-family reviewer per §6. Full contract: `docs/runbooks/grok-bot-qa-observer.md`. ### 2c. No idle lanes — subscription min-max (binding, all driver seats) Idle paid lanes are direct financial loss (operator 2026-08-17). This generalizes the Grok-seat fleet-first *utilization* rule to **every** driver seat. **Definitions.** *Free lane* — healthy, budget-eligible seat with no live assignment. *Ready item* — queued work that is valuable, unblocked, and has an integration path. *Compatible / independent* — the item fits the free lane and does not collide with in-flight units (paths, review identity, or a hard dependency). *Settle event* — any dispatch/review/CI terminal or decision point. *Grace period* — the short fill window after a settle event before a hold is allowed. *Epic done* — operator goal met with tool-backed residual 0, or operator-accepted residual on the issue. **Precedence (strict):** correctness/quality → safety/resource bounds → dependency/critical-path → utilization. Later items never override earlier ones. 1. **Waits are dispatch windows.** After any dispatch or review ask, **before** holding, fill every free lane with a compatible ready item (unblocked work, banked follow-ups, or prep the next program child whose dependency allows it). Idle free lane + ready item = utilization failure. 2. **Authorized idle is not a utilization failure.** A settle-hold must name one code: `dependency_blocked | authoring_wip_cap | review_wip_cap | ci_capacity | worktree_wip_cap | disk_capacity | integration_wip_cap | human_decision | no_ready_work`. Silence is not a disposition. 3. **Pipeline with a depth limit.** While CF/CI runs on unit N, author N+1 only up to the WIP/resource cap. Unit N **regains priority** the moment review feedback returns. Never serialize implement → review → delta with idle gaps. 4. **Ready-work forecast.** An unfinished epic needs a current ready-work forecast. An empty ready queue requires an explicit disposition, not silence. File banked follow-ups as GitHub issues when identified. Empty stream `/next` is a driver defect unless the epic is done or a disposition applies. 5. **Anti-gaming.** No placeholder agents, artificial task splitting, premature PRs, or speculative work without an integration path. §2 still binds: never manufacture busywork (quality > utilization). Disk wins every conflict (#M-14 — `df` + `du` of `.worktrees` before fan-out; reap first). Mechanical reminder + disposition telemetry (#6976/#6998). At every dispatch/review settle, evaluate eligible ready items and first-class admission WIP limits (authoring / review / CI / worktrees / disk / integration) plus queue readiness. The reminder fires only when something is eligible; then dispatch or pass a structured code. Unknown codes are rejected. Do not add a raw idle-time threshold. Guardrail-authorized idle is not a failure. `driver_breadth_report --enforce` fails the breadth floor (unless NOTE-waived) and MISSING/DISHONEST idle dispositions — never opportunity-seconds. ```bash .venv/bin/python -m scripts.orchestration.dispatch_settle task --task-id <id> \