@getarbiter/cli 0.5.0

package/dist/templates/claude/skills/wave-drain/SKILL.md.ejs

@@ -0,0 +1,491 @@
+---
+name: wave-drain
+description: Use when draining the open backlog at maximum throughput. Batch up to ~10 workable issues into a WAVE, plan and review the wave once cumulatively, dispatch parallel TDD agents in isolated worktrees, then integrate into a SINGLE wave PR merged GREEN. Issues that cannot proceed become needs-human with a blocker report. The orchestrator directs parallel agents — it never implements.
+argument-hint: '[--wave-size N] [--max-parallel N]'
+title: 'Wave Drain'
+doc_version: '2.0.0'
+status: active
+last_review: '2026-07-10'
+owner: ''
+canonical_id: ''
+tags: ['audience/agent', 'audience/dev', 'kind/internal', 'kind/orchestration']
+related: ['epic-decompose', 'understand-code', 'tdd', 'verification', 'ssot-navigation']
+---
+
+# Wave Drain
+
+**Goal:** Drain the open backlog at maximum throughput. Every workable issue ends either
+**merged** (inside a wave PR merged GREEN) or **needs-human** with a blocker report.
+
+**Mental model:** You are the Claude Code **orchestrator**. You do **not** implement — you
+**direct parallel agents**. Tokens are saved by running the heavy ceremony **once per wave**
+(one cumulative plan, one plan review, one code review, one full gate, one PR), never by
+skipping phases.
+
+> `/ship` drives **one issue → one PR**. Wave Drain is its multi-issue sibling: **N issues →
+> one wave PR**, reusing the same engine and the same gates.
+
+**Legality (ADR-103):** parallel write-agents are in-contract ONLY under the rule-50
+carve-out — every agent in a **dedicated worktree** (`/wt-open`), on a **distinct branch**,
+with **plan-manifest-disjoint file-sets**. Dependency changes (`package.json`/lockfiles),
+main-tree edits and tags stay serial-only. **Convergence model (owner-ratified
+2026-07-10):** on arbiter-governed repos every wave converges into **ONE wave PR** — the
+parallelism is in HOW the wave is built, never in N PRs racing to `main`. For repos
+WITHOUT arbiter governance, see the **cross-repo appendix** at the end (N-PR +
+merge-train).
+
+## Primitives
+
+| Primitive                                                  | Role here                                                                                             |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `/ship`                                                    | Pipeline reference for the per-issue phase contract (plan → red-team → TDD → review → verify → merge) |
+| `arbiter task init / advance / record-red / recover / get` | The state engine each agent anchors its work to                                                       |
+| `/wt-open`, `/wt-close`, `/wt-prune`, `/wt-list`           | Isolated git worktrees, one per group                                                                 |
+| `arbiter gate-exec -- <cmd>`                               | Per-repo gate mutex (flock(1)): serializes expensive gates across parallel agents (ADR-103)           |
+| `arbiter worktree prune --stale [h]`                       | Zombie reaper: merged/inactive clean worktrees, dry-run default (ADR-103)                             |
+| Skill `epic-decompose`                                     | Only if an entangled issue must be split before batching                                              |
+| Skill `understand-code`                                    | Per-agent code comprehension before editing                                                           |
+| Skill `tdd`                                                | The red → green → refactor loop every agent runs per unit                                             |
+| Skill `verification`                                       | Claim-based verification on the cumulative branch before the gate                                     |
+| Skill `ssot-navigation`                                    | Locate invariants / SSOT before touching guarded files                                                |
+
+---
+
+## Phase 0 — Triage + Wave composition
+
+1. `gh issue list --state open` (this repo). **Exclude** anything labelled `blocked`,
+   `needs-human`, `epic`, or `needs-clarification`.
+   1b. **Readiness gate (INV-138)** — for each issue that survives the label filter AND is
+   about to be selected into the wave (never a mass sweep of the whole backlog), run:
+
+   ```bash
+   gh issue view <n> --json body -q .body > /tmp/issue-<n>.md
+   node scripts/issue-readiness.mjs --body-file /tmp/issue-<n>.md --emit-comment
+   ```
+
+   Exit 1 (not ready — missing explicit `AC-N:` acceptance criteria, non-goals, or
+   files/contracts touched) ⇒ label it `needs-clarification`, post the emitted comment
+   (skip the comment when the label is already present), and **exclude it from the wave**.
+   Underspecification is paid here, as a prompt before dispatch — not after review as a
+   thrown-away PR. Exit 2 (gh/network error) ⇒ treat the issue as not composable this wave.
+   If `scripts/issue-readiness.mjs` does not exist in this repo (Track-B emission is a
+   tracked follow-up, ADR-110), a `Cannot find module` failure is never a "not ready"
+   verdict — record `readiness: script absent — skipped` in the wave roster and move on.
+   The skip is declared, never silent: an unrecorded skip is indistinguishable from a
+   forgotten step.
+
+2. Compose a **WAVE**: up to **10 issues**, partitioned into **groups** of **≤5 issues** each,
+   grouped by module / dependency. Independent groups are parallelizable. Entangled issues
+   (shared modules, or a declared `conflicts-with:#N`) go in the **same group** or get
+   **split** first via `epic-decompose`.
+3. Record the wave roster: for each group list its issues, target modules, and the
+   conflict-risk ordering you will use at integration.
+
+A group is the unit of parallelism. Keep groups module-coherent so two agents never edit the
+same file concurrently (see `.claude/rules/50-batch-execution.md` — the ADR-103 carve-out is
+what makes parallel write-agents legal, and its disjoint-file-set condition is satisfied
+HERE, at composition time).
+
+**Declared conflicts:** an issue labelled/marked `conflicts-with:#N` goes in the **same
+group as #N** (serial lane, same worktree, sequential) — never in a parallel group. This is
+declarative and cheap; the integration merge + single gate remain the safety net for
+conflicts nobody declared.
+
+## Phase 0.5 — Harvest the finding spool (#1404)
+
+Before composing the wave's work, **drain the incidental-finding spool into tracked issues** so
+findings noticed in prior waves become first-class backlog candidates instead of rotting in
+`.arbiter/findings/`:
+
+```bash
+# arbiter findings promote/list was removed in the B-prune (#1817 B2) — no CLI
+# automation ships for this step anymore. Inspect the spool directly:
+cat .arbiter/findings/*.jsonl 2>/dev/null | jq -s '.'
+```
+
+Each shard entry is a finding recorded via `arbiter note` (fingerprinted by file+kind+text, line
+excluded). Triage manually: drop entries whose file/graph-node no longer exists at HEAD, skip
+anything already tracked by an open issue, and `gh issue create` the survivors yourself
+(`finding`+`tech-debt`+`priority/Pn` labels). The spool being absent/empty is a clean no-op.
+
+**Newly-triaged `severity: low` findings are candidate issues for THIS wave** — fold them into the
+Phase 0 triage roster (subject to the same workability filter). Higher-severity findings enter
+the backlog like any other issue.
+
+### Transactional claim (#1378)
+
+**Check-ALL-then-claim-ALL** to avoid race conditions when multiple drain runs overlap:
+
+```bash
+# 1. Verify ALL selected issues are still open and unassigned
+for issue in $WAVE_ISSUES; do
+  state=$(gh issue view "$issue" --json state,assignees --jq '{state:.state,assignees:(.assignees|length)}')
+  echo "$state" | jq -e '.state == "OPEN" and .assignees == 0' > /dev/null || { echo "Issue #$issue not claimable"; exit 1; }
+done
+
+# 2. Claim ALL atomically
+claimed=()
+for issue in $WAVE_ISSUES; do
+  if gh issue edit "$issue" --assignees @me; then
+    claimed+=("$issue")
+  else
+    for c in "${claimed[@]}"; do gh issue edit "$c" --remove-assignee @me; done
+    echo "Claim failed for #$issue — rolled back all assignments"; exit 1
+  fi
+done
+```
+
+**Rules:**
+
+- Never claim before verifying. A closed or already-assigned issue must be excluded.
+- Never swallow `gh issue edit` errors — propagate them and trigger rollback.
+- On partial failure, release all already-claimed issues before aborting.
+- If rollback itself fails, log the orphaned claims explicitly for manual cleanup.
+
+---
+
+## Phase 1 — One cumulative plan (session model — plan synthesis is a judgment stage)
+
+Write **a single cumulative plan** for the whole wave to `.claude/plans/wave-N.md`. For each
+group include a **manifest**:
+
+- **Files** the group will touch — file-sets must be disjoint across parallel groups
+  (ADR-103 carve-out condition; overlap → same group, serial)
+  - **Read-set** — files/globs the group is expected to READ beyond its write set (M6 #1943;
+    reads bounded socially, writes mechanically)
+- **Invariants** in scope (from `GLOBAL_INVARIANTS.md` + `AGENTS.md` — cite INV-IDs)
+- **Acceptance-criteria anchor (INV-138)** — per issue, copy the issue's criteria
+  **verbatim** into a `## Acceptance Criteria` block (plus `## Non-Goals`) under the
+  group's section, **namespacing each id per issue**: issue #123's `AC-1` becomes
+  `AC-123.1` in the wave plan (duplicate bare ids across issues are a gate error).
+  Tests and review cite these frozen ids, never a re-reading of the issue: the anchor —
+  not the implementing agent's interpretation — is the DoD.
+- **TDD units** (the red → green slices) — each unit names the `AC-N` id(s) it proves
+- **Conflict risks** vs other groups (which files / interfaces overlap)
+
+This manifest is the group's **merge contract** (INV-138): acceptance criteria + repo
+policy + required tests + CI expectations + review/security surfaces + dependencies,
+derived BEFORE writing. Code and tests are born against it — adversarial review judges
+the diff against it before integration, which is what kills accordion PRs.
+
+Every implementation agent will **anchor its `arbiter task` to its group's section** of this
+plan (CANON-16, enforced by the `pre-edit-plan-anchor` hook). No per-issue plans.
+
+---
+
+## Phase 2 — One plan review
+
+Run the plan gate **once** on the cumulative plan: dispatch the plan-review agents against
+`.claude/plans/wave-N.md` and record their verdict in
+`.arbiter/evidence/plan-review/<id>/latest.json` (the review-dispatch CLI was removed in #1817 —
+the gate now reads that evidence file, it is not a single command).
+
+In parallel, dispatch a **tier-Standard red-team** (3 agents) against the cumulative plan.
+
+- **CRITICAL** → rework the plan (**max 2 cycles**, then escalate to a human).
+- **PASS** = **GO for the entire wave**.
+
+## Phase 2.5 — Per-issue 3-hop plan gate (default-on)
+
+Every issue in the wave gets a **per-issue 3-hop plan trail as issue comments before any
+code**:
+
+1. **hop 1/3** — draft plan (comment headed `## Piano hop 1/3` or `## Plan hop 1/3`)
+2. **hop 2/3** — adversarial red-team: every finding with `file:line` evidence and a verdict
+3. **hop 3/3** — final plan incorporating every finding (or refuting it with evidence)
+
+The orchestrator verifies the trail **deterministically via `gh`**: three hop-header
+comments, each carrying at least one `file:line` evidence marker and a non-trivial body.
+The quality of the hops is model-side — this check catches absence, not proforma.
+
+The gate is default-on and unconditional: a plan discovered wrong at integration costs the
+whole group's rework, which is far more than the gate's explicit up-front cost. That cost
+scales with the tier, not with enthusiasm — hop 2's adversarial pass runs with the tier's
+`refutation_skeptics` count from `.claude/agent-dispatch-matrix.json` (XS/S = 1 skeptic,
+Standard = 3). The `needs-plan` label no longer switches the gate on (it is always on); it
+raises hop 2 to the Standard floor (3 skeptics) for architectural or ambiguous-scope
+issues regardless of tier.
+
+---
+
+## Phase 3 — Parallel execution (scale out)
+
+Spawn **one agent per group** in an **isolated worktree** (`/wt-open`, a branch per group).
+`--max-parallel` defaults to **<%= maxParallelWorktrees %>** from
+`automation.maxParallelWorktrees` (or the collaboration-mode default when absent).
+Effective cap: **`min(--max-parallel, nproc - 2, wave size)`** — the mutex serializes the
+GATE, not the workers' implicit builds, so leave the box headroom.
+
+**Worktree discipline (speed):** inside a worktree run **only light checks** — targeted
+`vitest` + the lint from `post-edit-dispatch`. The **full gate is forbidden in worktrees**; it
+runs **once**, on integration.
+
+**Gate mutex (ADR-103):** any expensive gate that could run concurrently with another
+agent's gate on the same repo (parallel waves, ship agents, overnight batches) goes through
+`arbiter gate-exec -- <gate-cmd>`. The wait is kernel-side (`flock(1)`, blocking) and the
+lock releases if the gate-exec supervisor is SIGKILL/OOM-killed; killing the Arbiter Node
+PID alone leaves that supervisor holding — no 1h stale stall, no poll loop. Linux tracks ordinary
+process-group escapes by an inherited sentinel; a payload that deliberately closes it before
+escaping is outside the guarantee and can outlive mutex release.
+Where `flock(1)` does not exist (macOS base system, Windows) `gate-exec` fails closed:
+degrade the wave to serial (`--max-parallel 1`).
+
+**Cache isolation:** `arbiter worktree open` links `node_modules` with the
+`symlink-children` strategy — `.vite`/`.cache` stay per-worktree, so parallel builds cannot
+corrupt one shared cache into spurious reds. Belt-and-braces in each worker brief:
+`export VITE_CACHE_DIR="$PWD/.cache/vite"`.
+
+**M16 handoff-contract: subagents never own waits** — worker briefs end at commit + launch + structured handoff
+{SHA, worktree, PID, exit-file, log} with an explicit END-TURN; ALL watches belong to the
+coordinator (`bg-run.sh` + `pid-watch.sh`, #2103).
+
+**Anti-stall (two DIFFERENT problems — never conflate them):**
+
+- **Gate-wait** is deterministic: `gate-exec` blocks in the foreground — issue **ONE** wait
+  and let the kernel queue you. Never poll for the lock, never close a turn "checking back
+  later" on a mutex.
+- **Turn-stall** (an agent idling mid-task) is only **bounded**, never prevented, by the
+  **watchdog sweep**: at every orchestrator turn boundary, reconcile REAL state — `gh pr
+checks`, `gh issue view`, `arbiter worktree list`, DONE reports — and re-dispatch, mark
+  `needs-human`, or reap what stalled beyond its budget. Never rely on memory of what
+  agents "should" be doing; never close an orchestrator turn passively waiting on a PR —
+  arm auto-merge and let the NEXT sweep observe it.
+
+Each agent's loop:
+
+```bash
+arbiter task init --plan <wave-N.md#group-anchor>   # anchor to the group's plan section
+# invoke the tdd skill per unit: red → verify-red → green → verify-green → refactor
+# targeted tests green
+git commit                                          # format enforced by post-commit-check
+```
+
+Every worker brief names the `tdd` skill explicitly — a worker that starts from
+implementation code has skipped the red step, and the pre-push tdd-evidence check will fail
+its branch structurally (see Iron Law below).
+
+Then emit a **DONE report**: files touched, tests added, commits, and `findings[]`.
+
+#### Canonical finding shape (#1404)
+
+The DONE-report `findings[]` use the **same `FindingEntry` shape as `arbiter note`** — the SSOT is
+`src/commands/task-note.ts` (interface `FindingEntry`). This is what lets a finding flow straight
+into the `.arbiter/findings` spool and get triaged manually (see "Phase 0.5 — Harvest the finding
+spool" above) in the next wave, with fingerprint dedup using the SAME material as `task-note.ts`
+`computeFingerprint` (so a finding is never double-filed). Do **not** invent a parallel free-prose
+shape.
+
+Each finding is one object with these fields (`graphNode` and `auditorHint` are optional; every
+other field is required):
+
+```json
+{
+  "ts": "2026-06-16T00:00:00.000Z",
+  "note": "duplicated retry helper — extract a shared utility",
+  "kind": "dup",
+  "severity": "low",
+  "foundDuring": "#1404",
+  "file": "src/commands/findings-promote.ts",
+  "line": 120,
+  "sha": "deadbeefcafef00d",
+  "graphNode": "src/commands/findings-promote.ts#revalidate",
+  "fingerprint": "<sha1 of kind+normalizedPath+symbol+normalizedNote>",
+  "auditorHint": "code-quality"
+}
+```
+
+- `kind` — finding class: `dup` | `smell` | `risk` | `debt` | `note`.
+- `severity` — `low` | `med` | `high` | `info` (drives the promoted issue's `priority/Pn` label).
+- `line` — number or `null`; it is **excluded** from the fingerprint.
+- `graphNode` — optional graph-node id; **omitted** (not a key) when absent.
+- `auditorHint` — optional; the `auditor-routing.json` auditor whose remit covers the finding.
+
+The cheapest way to honour this shape is to capture findings in-band with `arbiter note` (which
+writes exactly this entry); the DONE report then just mirrors what is already in the spool.
+
+**A blocked agent → mark its issue `needs-human` and STOP that agent. It does NOT block the
+wave.** The rest of the wave proceeds.
+
+---
+
+## Phase 4 — Local integration (one PR per wave)
+
+1. Create a local integration branch `wave-N-integration` **from `main`** (never commit to
+   `main`).
+2. **Merge the DONE worktrees sequentially**, minimum-overlap first, with the order computed
+   from the REAL branches — `git diff --name-only main...<branch>` per branch, fewest shared
+   files first — not from the plan's estimates. Conflicts → hand to a dedicated conflict
+   agent with the relevant DONE reports.
+3. **On the cumulative branch, once only — multiagent code review:**
+   - Route auditors:
+     `[ -f scripts/route-auditors.mjs ] && node scripts/route-auditors.mjs --size-floor Standard || echo "route-auditors: script absent — skipped"`
+     (arbiter's own wave-routing helper; a generated project does not receive it. The skip
+     is declared, never silent — record it in the wave roster and route the auditors by hand.)
+   - Self-review pass + **Adversarial Verifier**: trace each feature end-to-end, hunt dead
+     code and unwired options.
+   - **FIT rubric (INV-138):** the review judges fit against the frozen anchor, not just
+     code quality — for **each** `AC-N` in each group's `## Acceptance Criteria` block,
+     cite the diff/test line that proves it; any criterion without cited evidence ⇒
+     REJECT for that group. Non-goals violated ⇒ scope-creep finding. Record the
+     per-criterion verdicts in `.arbiter/evidence/ac-fit/wave-N.json` (schema
+     `arbiter-ac-fit-v1`), then run the deterministic check — anchor AND all-PASS fit:
+     `[ -f scripts/check-acceptance.mjs ] && node scripts/check-acceptance.mjs --plan .claude/plans/wave-N.md --ac-fit .arbiter/evidence/ac-fit/wave-N.json || echo "check-acceptance: script absent — skipped"`
+     (arbiter's own AC-fit verifier; a generated project does not receive it. When it is
+     absent the per-criterion verdicts above are still MANDATORY — record
+     `ac-fit: script absent — verdicts reviewed by hand` so the skip stays visible.)
+   - Write the **evidence file** (fail-closed, INV-114).
+   - Any still-unresolved `redTeamFindings` cap their mapped auditor's score (`[RT-xx UNRESOLVED]`).
+   - **CRITICAL / MAJOR** → dispatch a fixer agent.
+4. **Commit the cumulative candidate and all review/evidence artifacts.** This is the final
+   pre-gate commit. The working tree must be clean; nothing may be committed after L2 because
+   `gate-pass.json` is bound to the exact HEAD and tree hash.
+5. **Verify, then gate:**
+
+   Run the `verification` skill on the cumulative branch first (claim-based pass: every
+   claim in the DONE reports gets checked against the tree, not trusted), then the gate:
+
+   ```bash
+   # skill: verification — claim-based pass on the cumulative branch first
+   # FULL GATE → writes gate-pass.json; under the per-repo mutex (ADR-103) so a
+   # concurrent agent's gate never interleaves with this one:
+   arbiter gate-exec -- node scripts/check-all.mjs L2
+   ```
+
+   `gate-pass.json` is required by the `enforce-gate-before-pr` hook.
+
+6. **RED → root-cause structural fix** (never `--no-verify`, never skip). If the culprit is
+   one group, **revert that group's merge** → mark its issues `needs-human` → the wave
+   continues with the rest. **Any reverted/redone group and any FIT REJECT is rework
+   data**: append the why × where-caught before proceeding —
+   `node scripts/rework-log.mjs add --issue <n> --reason <r> --caught review` (taxonomy in
+   the script; `report` mode shows which issue-template section is leaking).
+7. **One PR per wave.** Body: a table mapping each issue → its commit, and **one `Closes #N`
+   line per issue** — never a comma-separated list (`Closes #N1, #N2, ...`); GitHub's
+   closing-keyword parser only reliably auto-closes the first issue in such a list on
+   admin/rebase-merge (#1766). Merge **only with checks GREEN**:
+
+   ```bash
+   gh pr create --title "wave(N): <summary>" --body "<issue→commit table>
+
+   Closes #N1
+   Closes #N2
+   ..."
+<%_ const _waveCollaborationMode = typeof collaborationMode === 'string' ? collaborationMode : ''; const _waveMergeMode = typeof mergeMode === 'string' ? mergeMode : (typeof solo !== 'undefined' && solo !== null && typeof solo.mergeMode === 'string' ? solo.mergeMode : 'direct'); if (_waveCollaborationMode === 'trunk-solo' && _waveMergeMode === 'pr-ff') { _%>
+   node scripts/pr-merge-watch.mjs \
+     "$(gh repo view --json nameWithOwner -q .nameWithOwner)" \
+     "$(gh pr view --json number -q .number)"
+<%_ } else { _%>
+   gh pr checks --watch
+   gh pr merge --merge        # only when CI is GREEN
+<%_ } _%>
+   # post-merge: confirm every ref closed, close stragglers. arbiter's own helper —
+   # absent in a generated project, where the skip is declared and the refs checked by hand.
+   [ -f scripts/verify-pr-closes.mjs ] && node scripts/verify-pr-closes.mjs <PR#> \
+     || echo "verify-pr-closes: script absent — skipped"
+   ```
+
+   CI red → root-cause fix → re-gate (PRs are owned until merged green).
+
+8. `/wt-close` (harvest) + `arbiter worktree prune --stale 24` (review the dry-run report,
+   then re-run with `--execute`) → `/clear` → **next wave**, until the backlog is empty. The
+   reaper also runs inside the watchdog sweep, so a crashed worker's zombie worktree never
+   outlives the wave (dirty trees are never touched — INV-96).
+
+   **M6 touched-vs-manifest GO condition (#1943):** before merging each group's branch, run
+   `node scripts/check-touched-vs-manifest.mjs --plan .claude/plans/wave-N.md --group <G>
+--base main --branch <group-branch>` — this verifies touched(G) ⊆ declared(G) for one group;
+   it does not prove cross-group pairwise disjointness. Non-zero ⇒ the group is not clear to
+   merge (root-cause: either the manifest was under-declared or the agent scope-crept). A
+   read-set row absent from the manifest fails the check for that group the same way: an
+   omitted row must not be able to disarm the check it feeds — fix the plan's manifest, then
+   re-run.
+
+---
+
+## Iron Law
+
+- **No group enters integration** without TDD + targeted tests **green**.
+- **Nothing reaches `main`** without: red-team on the plan, multiagent review + adversarial
+  verify, and a **full gate GREEN** on the wave PR.
+- The ceremony is **per-wave, not per-issue** — that is where the tokens are saved, **not by
+  skipping it**.
+- **Iff-closure contract (field-validated 2026-08-09):** an issue closes ⟺ (E2E evidence ∧
+  doc evidence) — real-binary proof (bake/fixture/consumer/live-CI, never unit-only) AND
+  doc gates green with content updated. The PR body carries a per-issue evidence table; an
+  issue missing either half gets NO `Closes` line — it stays open with a comment naming
+  the missing half. Post-merge-only evidence (a live nightly, a consumer run) closes the
+  issue AFTER that run is green, not at merge.
+- **RED-first branch construction:** the pre-push tdd-evidence check RE-RUNS the RED at its
+  pinned `test_commit_sha` — order every branch test(RED)→fix→evidence-pinned-to-the-test-
+  commit, `observed_failure` matching the re-run format exactly. Fix-before-test ordering
+  fails verification structurally, not stylistically.
+- **Leads run composed L1 before the DONE report:** the worktree pre-commit skips L1
+  (#1695) — sub-check spot-checks miss bake goldens, examples drift, docs-gate, format.
+  Full `check-all.mjs L1` in the worktree is part of every lead brief's exit criteria.
+- **Snapshot conflicts: regenerate, never hand-resolve.** Generated artifacts (bake
+  goldens, examples/**, manifests) conflicting at merge: take either side, then rebuild +
+  regenerate on the MERGED tree and audit the diff (hash-only expected, file-list moves
+  explained, nothing disappears).
+- **Runner contention is not a test failure:** `status: null`/exit 137 on the single-slot
+  runner = SIGKILL from parallel-workflow racing. Re-run after the queue drains; never
+  patch the test.
+- **Premise falsification with line-drift awareness:** locate issue-body claims BY
+  CONTENT, never by cited line numbers (audits go stale in days); re-verify every premise
+  on the CURRENT tree before implementing.
+
+## Stop conditions (fail-closed)
+
+STOP, write a blocker report, mark the issue `needs-human`, and **move on** when you hit:
+
+- An invariant violation → **cite the INV-ID**.
+- An unauthorized edit to an SSOT or read-only file.
+- An orphan TODO (no task ID).
+- An `any` type / placeholder left in edited code.
+- **2 failed plan-review cycles.**
+
+A stop never halts the whole wave — it removes one group/issue and the wave proceeds.
+
+## Completion
+
+Done **only when the backlog is empty** — every issue is either **merged** or **needs-human
+with a stated reason**. Emit a final report: **issue → outcome + PR**.
+
+---
+
+## Appendix — Cross-repo manual protocol (repos WITHOUT arbiter governance)
+
+On a repo with no `arbiter.json` (no `/drain`, no engine) the wave technique still applies,
+but the convergence model flips: **N PRs + auto-merge armed + merge-train** (this is where
+the train is native — PRs are the only integration unit). Field-proven 2026-07-09/10.
+
+1. **Worktrees + branches:** one `git worktree add` per issue, one branch per agent, disjoint
+   file-sets — the ADR-103 conditions apply verbatim even without the engine.
+2. **Gate mutex (one-liner):** no `arbiter gate-exec` here — use flock directly,
+   parameterized on the repo's own gate:
+
+   ```bash
+   flock /tmp/<repo>-gate.lock -c '<gate-cmd>'   # e.g. 'make gate' or './run.sh ci'
+   ```
+
+   Same semantics: kernel wait, kernel release when the direct flock process is
+   SIGKILL/OOM-killed, one foreground wait.
+
+3. **Per-PR convergence:** each finished issue → its own PR with auto-merge armed. Never
+   watch-loop a PR; the sweep observes.
+4. **Merge-train (integration net):** when **≥3 PRs** are green-and-armed, build a local
+   train branch from `main`, merge the PR branches sequentially (minimum-overlap order from
+   the REAL `git diff --name-only`), run the full gate ONCE on the train under the flock
+   one-liner, and only then let the train land. The train catches integration defects that
+   are invisible to each green PR alone.
+
+**Caveats (explicit — these are the failure modes the governed wave-PR model eliminates
+structurally):**
+
+- **Crash mid-train (#4):** recovery is stateless — recompute from `gh pr list` +
+  `git branch`/`worktree list`; never from memory. Do not close issues/PRs until the train
+  itself is merged.
+- **Branch protection (#6):** verify the target repo's required checks BEFORE relying on
+  train-only CI — if required checks are per-PR, each PR still needs its own green CI.
+- **Exclusion instability (#7):** when a branch is EXCLUDED from the train (conflict/red),
+  recompute the train order from scratch and re-examine branches that assumed the excluded
+  content — the minimum-overlap order is NOT stable under exclusions.

package/dist/templates/codex/CODEX.md.ejs

@@ -0,0 +1,140 @@
+# <%= projectName %> — Codex Configuration
+
+> **Governance rules are in `AGENTS.md` (canonical, AAIF standard).**
+> This file adds OpenAI Codex-specific configuration only.
+
+---
+
+## Quick Reference
+
+| Fact | Value |
+|------|-------|
+| **Project** | <%= projectName %> |
+| **Test** | `<%= testCommand %>` |
+| **Gate** | `node scripts/check-all.mjs` |
+| **Full governance** | `../AGENTS.md` |
+
+---
+
+## Startup Protocol (Read First)
+
+1. Read `AGENTS.md` — this contains ALL governance rules and invariants
+2. Read `docs/architecture/ARCHITECTURE.md` if it exists
+3. Check current branch: must be `task/#NNN-description` (not `main`)
+4. If no task branch exists, create one before any edits
+
+## Execution Model
+
+Codex operates via explicit plans. Before any implementation:
+
+1. Create a plan in `.agents/plan/PLAN.json`
+2. List all files to modify with their operations
+3. Identify invariants that apply
+4. Await GO from the user
+
+## Plan Schema
+
+The plan is validated by `arbiter verify plan` against the `PlanJsonV1` schema
+(the contract). Unknown fields are stripped, so only the fields below are
+honoured.
+
+```json
+{
+  "task_id": "#NNN",
+  "scope": {
+    "track": "A",
+    "paths": ["src/feature.ts"]
+  },
+  "files": [
+    {
+      "path": "src/feature.ts",
+      "operation": "modify"
+    }
+  ],
+  "invariants": {
+    "ui_language": "EN",
+    "no_skips": true
+  },
+  "invariant_ids": ["INV-01", "INV-22"],
+  "review_bridge": { "enabled": true, "reviewer": "bridge-reviewer", "fail_on_warn": false }
+}
+```
+
+- `task_id` matches `#<issue-number>`.
+- `scope.track` is the evidence track (`A|B|C|D`).
+- `files[].operation` is `create|modify|delete`.
+- `invariants` is a **policy object** (`ui_language:"EN"` asserts the change
+  adds no non-EN UI strings; `no_skips:true` asserts no skipped tests) — it is
+  NOT a list of invariant IDs.
+- `invariant_ids` lists the SSOT invariants (`INV-NN`) the plan intends to
+  honour — this is where invariant IDs belong, not in `invariants`.
+- `review_bridge` is required (`run_id` is generated by `arbiter verify plan`
+  into the review output, not supplied in the plan).
+
+## Task Workflow
+
+Follow this lifecycle for every task:
+
+1. **Start**: Read GitHub issue → read `AGENTS.md` → create `task/#NNN-description` branch
+2. **Plan**: Create `.agents/plan/PLAN.json` with file manifest and invariants
+3. **Implement**: Write tests first, then implementation. Run `<%= testCommand %>` after each unit
+4. **Gate**: `node scripts/check-all.mjs L1` before commit, `node scripts/check-all.mjs L2` before push
+5. **Finalize**: Commit → push → PR → verify CI → merge
+
+## Command Translation
+
+| Claude Code | Codex Equivalent |
+|-------------|-----------------|
+| `/ship #NNN` | **Orchestration entrypoint** — drive an issue to a merged PR |
+| `/task` | Low-level engine/CLI: `arbiter task init/advance/record-red/recover/get` |
+| `<%= testCommand %>` | Run tests for this stack |
+| `node scripts/check-all.mjs L1` | Run before each commit |
+| `node scripts/check-all.mjs L2` | Run before push/PR |
+
+## Hard Stops
+
+All hard stops from `AGENTS.md` apply. Additionally:
+- Never edit without a plan in `.agents/plan/PLAN.json`
+- Never commit directly to `main`
+- Never skip the gate
+
+---
+
+## Known Limitations — Codex Governance Parity
+
+Codex has a hook system (`[features] hooks`), but it covers a smaller set of
+events than Claude Code. The table below is **generated from
+the actual Claude-track inventory for this configuration** (ADR-106, arbiter
+#1966) — do not edit it by hand; it is re-derived on every generation and
+checked against the emitted hook inventory by the arbiter parity gate.
+
+Hooks marked as *bridged* run in real time on Codex too, via
+`.codex/config.toml` → `codex-adapter.mjs`. Everything else is covered at
+gate time (`node scripts/check-all.mjs`) or is manual discipline, as stated.
+
+**A bridged hook only runs once you approve it.** Codex requires a one-time
+trust approval per project hook entry (stored as a `trusted_hash` under
+`[hooks.state]` in `~/.codex/config.toml`); an unapproved entry is skipped
+**silently** — no warning, no exit code, the guard simply does not run, and the
+table above then overstates your real coverage. Approve them once interactively,
+or pass `codex exec --dangerously-bypass-hook-trust` in automation. Editing
+`.codex/config.toml` re-invalidates the approval for the entries it changes.
+
+| Claude Code Hook | What it enforces | Codex equivalent |
+|-----------------|-----------------|------------------|
+<% for (const row of knownLimitations.hooks) { -%>
+| `<%= row.name %>` | <%- row.enforces %> | <%- row.codexEquivalent %> |
+<% } -%>
+
+Claude-only surfaces with no Codex equivalent (by design, ADR-106 — accurate
+disclosure, not implementation parity):
+
+- **Commands** (<%= knownLimitations.commands.length %>): <%- knownLimitations.commands.map((c) => '`/' + c + '`').join(', ') %>
+- **Agents** (<%= knownLimitations.agents.length %>): <%- knownLimitations.agents.map((a) => '`' + a + '`').join(', ') %>
+- **Skills** (<%= knownLimitations.skills.length %>): <%- knownLimitations.skills.map((s) => '`' + s + '`').join(', ') %>
+- **Rules not derived into the Codex track** (<%= knownLimitations.claudeOnlyRules.length %>): <%- knownLimitations.claudeOnlyRules.map((r) => '`' + r + '`').join(', ') %> — each is coupled to a Claude-only mechanism (knowledge-map routing, brainstorm hook, `/impact` skill, CLOSER hook)
+
+**Decision:** This gap is intentional. OpenAI Codex has no plugin/hook extension
+point at the time of writing. When Codex adds a hook system, `codex-adapter.mjs`
+should be extended to bridge these checks. Gate-level enforcement catches all
+critical violations before merge.