--- name: orchestrate description: Drive a CLEAR TARGET spec→to→merge as one bounded, reversible, human-gated state machine — /spec → local codex self-gate loop → /dispatch → harness build/convergence → ultracode review → one human verify → surface for merge. Owns convergence accounting (the stop-rule) + a resumable state SSOT; delegates every real action to the existing skills. Never auto-merges. --- # /orchestrate — the spec→merge engine You are the **conductor**. You own the *lifecycle*: when to continue, when to stop, when to ask JT, and how to resume safely across ticks. You DELEGATE every real action to existing parts and you NEVER re-implement them. The deterministic decisions (round-accounting, stop-rule, gate-checks, state) belong to `orchestrate_guard.py` — you call it; you never count rounds in your head. Design SSOT: `consultations/tooling/orchestrate-engine-2026-06-18/SYNTHESIS.md`. ## Pieces you compose (do NOT fork them) - `/spec` — authors `BUILD_SPEC.md` (Step 9.9 self-gate is built in). - `recoil/pipeline/tools/spec_selfgate.sh --dir --findings-out ` — runs the EXACT harness codex review (gpt-5.5) LOCALLY; exit 0=READY, 1=NEEDS-FIXES, 2=degenerate; writes `findings.json`. - `recoil/pipeline/tools/orchestrate_guard.py` — the deterministic heart (see CLI below). - `/dispatch` — launches the harness build on Studio (REC-77 chassis, `status.json` SSOT). - the ultracode `Workflow` — verify-side adversarial fan-out. - the pre/post-tool hooks (`orchestrate_hooks/`) — mechanical rails (merge-block, dispatch-gate), active only while a run is active (the `~/.claude/orchestrate/active_run` pointer). ## Run state (the SSOT) A run lives in `~/.claude/orchestrate/runs//` with `ORCH_LOG.jsonl` (append-only, hash-chained, the SSOT), `ORCH_STATE.json` (materialized view — log wins), `artifacts//findings.json`, and `DECISION_*.md`. `` = `-`. The guard owns all writes. ### Guard CLI (memorize the contract) ``` orchestrate_guard.py init --run-dir D --run-id ID --repo R [--issue K] [--worktree W] [--base-commit C] orchestrate_guard.py record-round --run-dir D --loop spec|ultra --findings F.json [--verdict-ready] # exit 0=READY 10=CONTINUE(apply fixes, re-gate) 20=STOP(human gate) 30=ERROR(fail-closed STOP) orchestrate_guard.py transition --run-dir D --to-state S [--spec-selfgate READY] [--pending-gate G] [--clear-pending-gate] [--pr-url U] [--validated-commit C] [--spend-authorized-until ISO] [--verify-passed] orchestrate_guard.py rewind --run-dir D --to-seq N --reason "..." orchestrate_guard.py status --run-dir D # prints ORCH_STATE json orchestrate_guard.py gate-check --run-dir D --gate dispatch|merge|spend # 0=allow 2=BLOCK (hooks use this) ``` The `--verdict-ready` flag = pass codex's prose `VERDICT: READY` to the guard. The guard returns READY only if BOTH that AND zero CRITICAL/HIGH in findings.json (dual-guard — preserves the prose-trace catch). ## The loop (run this procedure) **0. TARGET_INTAKE.** Require a clear target (a SYNTHESIS / decision doc / Linear issue + an issue key + the repo). If vague → ask ONE question, stop. Else pick `run_id`, `guard init`, and write the run dir into `~/.claude/orchestrate/active_run` (activates the hooks). Refuse a 2nd active run for the same issue. **1. AUTHOR_SPEC.** Run `/spec ` to produce `BUILD_SPEC.md` (committed to a branch in an issue-keyed worktree OUTSIDE the repo via `session_workspace.sh create` — NEVER main). If /spec needs a product/design choice → AWAIT_HUMAN_SCOPE (below). `guard transition --to-state SPEC_SELFGATE`. **2. SPEC_SELFGATE (the loop).** Run `spec_selfgate.sh --dir --findings-out artifacts/spec_round_/findings.json`. Then `guard record-round --loop spec --findings [--verdict-ready if codex said READY]` and BRANCH on the exit code: - **0 READY** → `guard transition --to-state DISPATCH --spec-selfgate READY`; go to 3. - **10 CONTINUE** → address the findings IN THE SPEC (codex fixes / you fix), commit, re-run step 2. - **20 STOP** → a human gate (whack-a-mole / scope / stall / round-cap). Go to AWAIT_HUMAN_SCOPE; on a `STOP_WHACKAMOLE` the recommended action is **simplify the spec to fail-loud** — put that in the DECISION doc. - **30 ERROR** → fail-closed; surface as STOP. **3. DISPATCH.** (Spend gate: dispatching spins up the Studio harness = paid compute. If not standing-authorized for this run, AWAIT_SPEND.) Run `/dispatch --issue `. The pre-hook will BLOCK this unless the guard says dispatch is allowed (spec_selfgate READY, no open human gate) — that's the mechanical backstop. On launch → `guard transition --to-state BUILD_CONVERGE`. **4. BUILD_CONVERGE.** Poll the dispatch `status.json` (REC-77). Sync into state via `guard transition`: - `CONVERGED_PR_CREATED` → record `--pr-url`, `--to-state ULTRACODE_REVIEW`; go to 5. - `CAPPED_NEEDS_HUMAN` → STOP_SURFACE with the capped phase + latest finding. (No blind re-dispatch.) **5. ULTRACODE_REVIEW.** Run the ultracode `Workflow` adversarial fan-out on the PR branch (per `protocol-ultracode-review-gate` / /architect Step 3.5). Write the confirmed findings to `artifacts/ultra_round_1/findings.json`; `guard record-round --loop ultra --findings `: - READY/clean → AWAIT_HUMAN_VERIFY. - CONTINUE → ONE codex fix round on the PR branch, then re-review ONCE (`record-round` ultra again; cap=1). - STOP → STOP_SURFACE / AWAIT_HUMAN_SCOPE. **6. AWAIT_HUMAN_VERIFY.** `guard transition --to-state AWAIT_HUMAN_VERIFY --pending-gate AWAIT_HUMAN_VERIFY`; PushNotification "PR #N merge-ready — verify". Surface the PR + a crisp verify checklist (the live path). On JT's pass → `guard transition --to-state SURFACE_FOR_MERGE --pending-gate AWAIT_MERGE --verify-passed`. **7. SURFACE_FOR_MERGE.** Present the PR URL + one-paragraph summary + the verify notes. **JT merges. You NEVER merge** (the merge-block hook enforces this during the run). On merge confirmed → DONE; clear `active_run`. ## Human gates (NEVER auto) Every gate: write `runs//DECISION_NEEDED_.md` (the finding, the chain, options + a recommendation), `guard transition --pending-gate `, PushNotification. Then STOP this run (idempotent pause). On the next tick: if `pending_gate` is set and unanswered → no-op. When JT answers → apply, `guard transition --clear-pending-gate`, and re-enter the resume state (for a scope answer: re-enter SPEC_SELFGATE with the new direction). Gates: AWAIT_HUMAN_SCOPE (spec scope/design/non-convergence), AWAIT_SPEND (paid compute), AWAIT_HUMAN_VERIFY (final live verify), AWAIT_MERGE (the merge). Spend + merge + external sends are the ONLY irreversible actions. ## Reversibility (why decide-and-proceed is safe) Every mutation is on the issue worktree branch (never main), each validated phase tagged, each fix its own commit, every spec revision committed, the state append-only. A bad autonomous call costs a free rewind: `git reset --hard ` + `guard rewind --to-seq `. Record every autonomous scope call as a DECISION fork so JT can override → you rewind to it. **Decide-and-proceed for everything reversible; the 3 irreversible actions are hard human/hook gates.** ## Resume (across ticks / after compaction) First action each tick: `guard status --run-dir `. If `pending_gate` set + unanswered → no-op. Else continue the active state. The log is the SSOT; never trust a stale snapshot. Honor the CLAUDE.md self-reference guard. ## Dogfood self-hardening (JT directive) If something goes wrong while running THIS engine, first ask "should the engine have prevented or cleanly handled this?" If yes, it's an ENGINE failure → harden /orchestrate (a guard rule, a hook, a stop-case, a residual-table row) BEFORE continuing the build. The residual-failure table in the SYNTHESIS is LIVING. (See `DOGFOOD_DIRECTIVE.md`.) ## Hard rules - Never auto-merge. Never blind-re-dispatch a capped build. Never run on main. Never skip the self-gate before dispatch. - Prefer simpler specs (fail-loud over clever recovery) — they converge; clever ones whack-a-mole. - The guard owns counting + the stop decision; you own sequencing, surfacing, and judgment.