cohorte 1.5.0 → 2.0.0

package/core/agents/implementer.template.md

@@ -1,6 +1,6 @@
 ---
 name: <SURFACE_AGENT>
-description: Implements the <SURFACE_LABEL> surface (<SURFACE_PATH>) for one feature, strictly from the frozen spec + contract, test-first TDD. Dispatched by /build. Touches only its own surface.
+description: Implements the <SURFACE_LABEL> surface (<SURFACE_PATH>) for one feature, strictly from the frozen spec + contract, test-first TDD. Dispatched by /cohorte-build. Touches only its own surface.
 tools: <SURFACE_TOOLS>
 model: <SURFACE_MODEL>
 ---
@@ -14,7 +14,7 @@ shared surface is the frozen contract and the spec.
 > (§Conventions/§Testing): your slice of them is baked into this file below (§Your conventions),
 > rendered from the profile — re-reading the prose every dispatch is exactly the cost the bake
 > removes. If the baked slice visibly contradicts `PIPELINE.md`, say so in your handoff: the profile
-> wins, and this agent file needs a re-render (`/update-pipeline`).
+> wins, and this agent file needs a re-render (`/cohorte-update-pipeline`).
 
 ## You own
 
@@ -22,7 +22,7 @@ shared surface is the frozen contract and the spec.
 
 ## Your conventions (baked from `PIPELINE.md` at render time)
 
-<!-- Rendered by /init-pipeline (and refreshed by /update-pipeline's reconcile) from
+<!-- Rendered by /cohorte-init-pipeline (and refreshed by /cohorte-update-pipeline's reconcile) from
      §Conventions `### Shared` + `### Surface: <your key>` + your §Testing lines.
      Edit conventions in PIPELINE.md, never here — this block is regenerated. -->
 

package/core/agents/release.md

@@ -1,6 +1,6 @@
 ---
 name: release
-description: Commits, pushes, and opens the PR for a SHIP-verified feature. Dispatched by /ship at the SHIP gate. Drafts the conventional commit + PR body from the spec and diff. Never edits source.
+description: Commits, pushes, and opens the PR for a SHIP-verified feature. Dispatched by /cohorte-ship at the SHIP gate. Drafts the conventional commit + PR body from the spec and diff. Never edits source.
 tools: Read, Grep, Glob, Bash
 model: haiku
 ---

package/core/agents/review.md

@@ -1,6 +1,6 @@
 ---
 name: review
-description: Read-only reviewer. Compares the implementation against the frozen spec, then audits code quality, security, and (if the profile declares it) mobile-first. Emits the REVIEW REPORT. Dispatched by /review — one per touched surface on multi-surface diffs. Cannot modify anything.
+description: Read-only reviewer. Compares the implementation against the frozen spec, then audits code quality, security, and (if the profile declares it) mobile-first. Emits the REVIEW REPORT. Dispatched by /cohorte-review — one per touched surface on multi-surface diffs. Cannot modify anything.
 tools: Read, Grep, Glob, mcp__serena
 model: sonnet
 ---
@@ -66,7 +66,7 @@ Concrete, high-signal traps to grep for per language. A surface's language comes
 - **SQL / migrations** — `UPDATE`/`DELETE` with no `WHERE`; N+1 (a query inside a loop that a JOIN
   would collapse); foreign-key columns joined/filtered without an index.
 
-## Audit mode (no feature spec — codebase refactor, dispatched by `/audit`)
+## Audit mode (no feature spec — codebase refactor, dispatched by `/cohorte-audit`)
 
 When given a **path/domain instead of a feature spec**, skip step 1 and audit the target against
 `PIPELINE.md` §Conventions as the rulebook: conventions per surface, TDD coverage (list every
@@ -81,6 +81,24 @@ domain** (same finding-line shape) instead of a SHIP/REVISE/BLOCK verdict.
 - Any **security vulnerability** ⇒ verdict **BLOCK**.
 - No CRITICAL and no security issue ⇒ verdict **SHIP**.
 
+## Deferred — real, but not this feature's problem
+
+A finding is **deferred** when it is genuinely true and genuinely **out of this feature's scope**:
+pre-existing code the staged diff did not touch, adjacent debt the spec never claims to fix, a
+convention violation that predates this work. Deferring is not softening — it is naming the right
+owner. The lead routes deferred findings to `specs/refactor-backlog.md` (they feed `/cohorte-refactor`), so
+they are **never lost and never cost a fix loop**.
+
+- **Deferred findings are separate from your findings list** and count in **no** severity row: the
+  severity table drives the verdict, and a deferred item must never force one.
+- **Deferrable:** a problem entirely in lines/files the diff did not change, whose fix is not required
+  by any acceptance criterion of this spec.
+- **NOT deferrable, ever:** anything the diff touched or introduced; any spec violation; any
+  **security** issue on a path this feature adds, calls or modifies (a pre-existing hole this feature
+  now exposes to new traffic is this feature's problem). When in doubt, it is a finding, not a deferral.
+- Cap the deferred list at **10 lines**, worst first; each carries its own out-of-scope reason so the
+  lead can route it without re-reading anything.
+
 ## Your return — the REVIEW REPORT, exactly this shape
 
 Every finding must be **self-sufficient for a stateless agent**: `file:line` · severity ·
@@ -110,6 +128,11 @@ Verdict: <SHIP | REVISE | BLOCK>
 - **[<SEVERITY>]** `<file>:<line>` · <spec-violation|quality|security> · <problem> → **Fix:** <concrete change>
 (order by severity; "None." if none; max 20 lines, one per finding, no code excerpts)
 
+## Deferred
+
+- **[<SEVERITY>]** `<file>:<line>` · <quality|security> · <problem> → **Fix:** <concrete change> · out of scope: <why this feature does not own it>
+(real but out of this feature's scope — see §Deferred; worst first; "None." if none; max 10 lines)
+
 ## Notes
 (ONLY the RBAC / mobile-first assessment when the profile enables them; omit the section otherwise)
 ```

package/core/commands/{audit.md → cohorte-audit.md}

@@ -5,9 +5,11 @@ argument-hint: [path or domain, default = whole repo]
 ---
 
 You are the **lead**. Audit **$ARGUMENTS** (default: whole repo) to drive it to a clean base. Read +
-analyze only — no fixes (those go through `/refactor`).
+analyze only — no fixes (those go through `/cohorte-refactor`).
 
-> Read `PIPELINE.md` §`commands` (the mechanical gates), `surfaces`, and §Conventions.
+> Read `PIPELINE.md` §`commands` (the mechanical gates), `surfaces`, and §Conventions — plus
+> `specs/_decisions.md` §Live if it exists (SCHEMA.md §Decisions): those standing decisions are part
+> of the rulebook you audit against, and code that contradicts one is a finding like any other.
 >
 > **Workflow variant** (opt-in — SCHEMA.md §Workflows): on Claude Code ≥ 2.1.154 with workflows
 > enabled, the human can ask to "run the audit workflow" (`<core>/workflows/audit.js` — one auditor
@@ -39,5 +41,11 @@ from your instructions), grouped by domain (one group per surface + shared). —
 Merge mechanical + convention findings into one prioritized backlog and **write
 `specs/refactor-backlog.md`**, grouped by domain, each item:
 `- [ ] <SEVERITY> · <file:line> · <rule|tdd|lint|format|type|security> · <concrete fix>`
+
+**Carry over the deferred items** before overwriting: `grep -n 'deferred:' specs/refactor-backlog.md`
+and re-emit every **open** (`- [ ]`) match verbatim under its domain, tag included. Those lines were
+put there by `/cohorte-review` §3.5 — a real finding a feature deliberately did not own — and an audit that
+blindly overwrites the file is the one way they silently disappear. Already-ticked (`- [x]`) ones are
+done: drop them.
 Print a short summary (counts per domain + top items). Tell the human: refactor a domain with
-`/refactor <domain>`.
+`/cohorte-refactor <domain>`.

package/core/commands/{brainstorm.md → cohorte-brainstorm.md}

@@ -11,6 +11,12 @@ at Finish, when a board is configured.
 > Read `PIPELINE.md` §Personas (the panel) and §`rbac` first. If `rbac.enabled`, the panel must
 > pressure-test the idea so it serves **every** role, not just admins.
 >
+> Also read `specs/_decisions.md` §Live if it exists (SCHEMA.md §Decisions) — one line per standing
+> decision. The panel argues about the idea, not about settled ground: a persona that proposes
+> something a live line already decided must be told so by another persona, and an idea that genuinely
+> needs to overturn one must say which line, out loud, so the human decides it here rather than
+> discovering the contradiction at `/cohorte-spec`.
+>
 > Template paths below (`.claude/templates/…`) resolve to `~/.claude/templates/…` when the core is
 > installed globally — read whichever exists.
 >
@@ -41,8 +47,8 @@ screens, risks, and what's explicitly out.
 
 When the human is satisfied, produce the **brainstorm return** by filling
 `.claude/templates/brainstorm-return.md` and **staging it to
-`specs/reports/<feature_id>-brainstorm.md`** (the gitignored buffer dir — `/spec` reads it from there
-when invoked with no paste). In chat print only a 3-line summary + the path. Tell them to run `/spec`
+`specs/reports/<feature_id>-brainstorm.md`** (the gitignored buffer dir — `/cohorte-spec` reads it from there
+when invoked with no paste). In chat print only a 3-line summary + the path. Tell them to run `/cohorte-spec`
 — **recommend a `/clear` first**, the return is staged on disk (pasting it remains a fallback).
 
 **Kanban:** settle the `feature_id` (kebab-case slug) the return carries — it is the card's join key
@@ -50,7 +56,7 @@ downstream. If a board is configured, **move** the card into the **Brainstorm**
 `#<feature_id>` (per §Kanban): the picked Ideas card if the human chose one, else a new card. No-op if
 no board.
 
-**Telemetry:** chain the opt-in usage ping onto that same Bash call — `/build` §4's shared form,
+**Telemetry:** chain the opt-in usage ping onto that same Bash call — `/cohorte-build` §4's shared form,
 `<phase>` = `brainstorm`, `<seconds>` = `0` (this phase is human thinking time, not pipeline
 wall-clock — the funnel signal is the event, not its duration), `<results>` = `""`. No board ⇒ still
 ping, in its own `|| true` call. Silent no-op without consent; never ask about consent here.

package/core/commands/{build.md → cohorte-build.md}

@@ -16,14 +16,17 @@ You are the **lead**. Build feature **$ARGUMENTS** from its frozen spec.
 ## 1. Load & check
 
 - Check the spec front-matter FIRST — `grep '^status:' specs/$ARGUMENTS.md` (or Read with a ~15-line
-  limit) — before any full read. If missing or `status` not `frozen`/`in-review`, stop — tell the human
-  to run `/spec` first. Only then read the body, selectively: front-matter, §5 contract, the surface
+  limit) — before any full read. Buildable statuses are `frozen`, `in-review` and `in-progress` (the
+  last one means a `/cohorte-loop` is or was driving this spec — SCHEMA.md §Spec status). `blocked` means a
+  loop gave up here: say so, and route by the spec's `## Remediation` — open items ⇒ `/cohorte-fix`, none ⇒
+  continue this build. Anything else (`draft`, missing, `shipped`) ⇒ stop and tell the human to run
+  `/cohorte-spec` first. Only then read the body, selectively: front-matter, §5 contract, the surface
   task sections, and `## Remediation` (fall back to a full read if the spec doesn't follow the
   template's headings).
 - **Route check** — if `## Remediation` has open `- [ ]` items and none requires a contract change,
-  stop and tell the human to run `/fix $ARGUMENTS` instead: it re-dispatches only the surfaces with
+  stop and tell the human to run `/cohorte-fix $ARGUMENTS` instead: it re-dispatches only the surfaces with
   findings. A full build with open items is only right when the contract change ripples into clean
-  surfaces (the case `/fix` §1 falls back here for).
+  surfaces (the case `/cohorte-fix` §1 falls back here for).
 - **Design gate** — only if `design.enabled` and the feature has UI (some surface `uses_design`): if the
   spec front-matter `design_files` is empty, ask the human for the feature's design **links** and store
   them in `design_files`, then continue. Each entry is a full self-contained link of the form
@@ -53,9 +56,62 @@ For each surface to add: infer its `key`, `path`, `label`, `agent`, `tools`, `mo
 SCHEMA.md §"Rendering / reconciling a surface agent" — write the `surfaces[]` entry + §Conventions/§Testing
 stanza into `PIPELINE.md`, render `.claude/agents/<agent>.md` from the implementer template, applying the
 shared-code rule (shared trees get a single-owner surface; cross-slice shapes go through the contract).
-This is the automatic path: you don't send the human back to `/init-pipeline`. If nothing new is needed,
+This is the automatic path: you don't send the human back to `/cohorte-init-pipeline`. If nothing new is needed,
 say so and continue. Dispatch (§3) then covers the reconciled surface list.
 
+**Adding or splitting a surface is an architectural decision** — append ONE line for it to
+`specs/_decisions.md` §Live (SCHEMA.md §Decisions; create from `.claude/templates/decisions.template.md`
+if absent), area `surfaces`, e.g.
+`- <date> · surfaces · <key> owns <path>, single owner of <what> — because <the boundary reason> · $ARGUMENTS`.
+One `>>` in the Bash call you're already making. Nothing added ⇒ nothing to append.
+
+## 1.6 Readiness verdict — the gate before N dispatches
+
+**Zero extra agents: you already hold the spec, the profile and the reconciled surface list.** The
+whole point is that a bancal spec costs one verdict here instead of N implementers discovering it in
+parallel. Judge the frozen contract on **implementability only** — never on whether the feature is a
+good idea (that was `/cohorte-brainstorm`), never by re-reading files you don't already need:
+
+1. **Contract completeness** (§5) — every endpoint/interface has method+path (or signature), auth,
+   request fields with types + validation, the success shape, and its error cases. A missing
+   **request or success shape** ⇒ `NOT-READY` (an implementer would invent it, and the other surface
+   would invent a different one). A missing **error case** ⇒ `RESERVATIONS`.
+2. **Surface coverage** — every §6 task maps to a surface in the reconciled list, and every contract
+   entry has an owner **on each side it names** (producer and consumer). A contract entry no surface
+   owns ⇒ `NOT-READY`.
+3. **Dependencies exist** — for the modules, packages, tables, env vars and shared helpers the spec
+   names as *pre-existing*: verify them in ONE Bash call (`test -f` / `grep -l` / a package-manifest
+   grep, output redirected — never a file read per name). Named as pre-existing but absent, and not
+   listed as created by this feature ⇒ `NOT-READY`.
+4. **Residual ambiguity** (§10) — an open question a surface would have to *guess* at: blocks a
+   contract decision ⇒ `NOT-READY`; merely narrows an implementation choice ⇒ `RESERVATIONS`.
+5. **Design gate** — a `uses_design` surface in scope with `design_files` still empty ⇒ `NOT-READY`
+   (this is §1's gate restated as a verdict, so an automated driver sees the same fact).
+
+Write the machine-readable verdict to `specs/reports/$ARGUMENTS.readiness.json` (overwrite,
+`mkdir -p specs/reports` first — the same gitignored buffer dir `/cohorte-review` stages into, which may not
+exist yet on a first build) — on **every** build, including `READY`. It is the only channel between this gate and a driver (`/cohorte-loop`),
+which parses no prose:
+
+```json
+{ "id": "$ARGUMENTS", "phase": "readiness", "ts": "<ISO>", "verdict": "RESERVATIONS",
+  "gaps": ["contract|POST /orders|no 409 case for a duplicate id"],
+  "surfaces": ["backend", "frontend"] }
+```
+
+- **`gaps`** — one normalized string per gap, `<check>|<where>|<what is missing>`: `<check>` is
+  `contract` · `coverage` · `dependency` · `ambiguity` · `design`; `<where>` is the contract entry,
+  surface key or dependency name (no `:line` — it shifts on every edit); `<what>` is the gap, not the
+  fix. `READY` ⇒ `[]`.
+- **`NOT-READY` ⇒ STOP: author no contract and spawn NO agent.** Print the gaps and send the human to
+  `/cohorte-spec $ARGUMENTS` to patch the contract, then re-run `/cohorte-build`. This abort is the whole point of the
+  step — a spec that cannot be built does not get cheaper by being built N times in parallel.
+- **`RESERVATIONS` ⇒ continue.** It never blocks (a gate that stalls a sound build on a missing error
+  case would cost more human round-trips than it saves): inline each gap verbatim into the dispatch of
+  the surface it affects, as an explicit assumption the agent must implement *and* flag in its handoff,
+  and relay the list to the human in one line each.
+- **`READY` ⇒ continue silently** — one line, no restatement.
+
 ## 2. Author the contract (lead-only — the single sync channel)
 
 _Only if `contract.enabled`._ From §5 of the spec, write/update the feature's contract file at
@@ -87,28 +143,57 @@ tree. For each surface in `surfaces`:
 > via `DesignSync get_file`, build mobile-first · or `none` (non-design surface, or a fix loop whose
 > open items are all non-visual)>. Open Remediation items for YOUR surface (self-contained — fix
 > exactly these, reading only the files they name; `none` ⇒ first build, implement the spec's tasks
-> for your surface): <the surface's open `- [ ]` lines verbatim, or `none`>."
+> for your surface): <the surface's open `- [ ]` lines verbatim, or `none`>. Readiness gaps for YOUR
+> surface (§1.6 `RESERVATIONS` — the spec is silent here: implement the stated assumption and flag what
+> you assumed in your handoff): <that surface's `gaps` entries verbatim, or `none`>."
+
+## 3.5 Roll call — account for EVERY dispatch before integrating
+
+A subagent can die: a rate limit mid-run, a transport error after retries, its own context exhausted.
+When it does, it returns **nothing** — and nothing is byte-identical to "a clean surface with nothing
+to report". Silence is not a green light; treat it as the failure it is (SCHEMA.md §Dead agents).
+
+- **Roll call.** Every surface you dispatched in §3 must come back with a handoff in the format its
+  agent instructions define. Missing, empty, or truncated mid-sentence ⇒ that surface is **dead**.
+- **Never infer success from silence,** and never speak for a dead agent — you did not see its work.
+- **Retry that surface ONCE, alone.** Re-dispatch it with the byte-identical §3 prompt. The other
+  surfaces' work is already on disk and untouched, so this costs one agent, not a rebuild — and most
+  deaths are transient. Never retry a surface that *did* answer.
+- **Died twice ⇒ stop guessing and look.** Run that surface's own quiet commands
+  (`<surface>.typecheck_cmd`, `lint_quiet_cmd`, `test_quiet_cmd`) with output redirected to
+  `specs/reports/$ARGUMENTS.<key>.deadcheck.txt`, then grep it — never into your context. Report the
+  three results plus which of the spec's tasks for that surface actually landed, checked against the
+  tree, not against a handoff you never got. Say plainly that the surface is **unverified**.
 
 ## 4. Integrate
 
 When all return, flag any contract mismatch or failing test from the handoffs; otherwise print one
 status line per surface (`<key> · tests pass/fail · <n> TODOs`) — do not restate handoff content.
+A dead surface (§3.5) prints `<key> · DEAD — unverified` and **the batch is never reported as ok**.
 Append **ONE line for the batch** to the **main checkout's** `.claude/pipeline-metrics.jsonl` —
 NOT the worktree's, which dies at teardown while metrics must accumulate across features. Resolve
 it from anywhere: `$(dirname "$(git rev-parse --git-common-dir)")/.claude/pipeline-metrics.jsonl`
 (in the main checkout this resolves to itself). Create it if absent; it must be gitignored.
 Compute the elapsed time in the same Bash call
 (`echo "{...\"seconds\":$(($(date +%s)-<start epoch from §2>)),...}" >> …`):
-`{"ts":"<ISO date>","feature":"$ARGUMENTS","phase":"build","seconds":<wall-clock>,"surfaces":{"<key>":"ok|error",…}}`
+`{"ts":"<ISO date>","feature":"$ARGUMENTS","phase":"build","seconds":<wall-clock>,"surfaces":{"<key>":"ok|error|dead",…}}`
+— **write this line even when a surface died.** An incomplete batch is exactly the batch worth having
+in the record; skipping the append to "wait until it's complete" silently deletes the evidence that
+anything went wrong. In the same call write the machine-readable batch result to
+`specs/reports/$ARGUMENTS.build.json` (overwrite) — the channel an automated driver reads, since it
+never sees your chat:
+`{"id":"$ARGUMENTS","phase":"build","ts":"<ISO>","surfaces":{"<key>":"ok|error|dead",…},"dead":["<key>",…]}`
 — this is the evidence SCHEMA.md §Specialization asks for before splitting a surface. In the same
 Bash call, chain the opt-in usage ping — **the shared form every phase command reuses**:
 `<core>/pipeline/scripts/telemetry-send.sh <phase> "$ARGUMENTS" <seconds> "<results>" || true`
 (`<core>` = `~/.claude` global / `.claude` bundled; here `<phase>` = `build`, `<results>` =
 `<ok,ok|error,…>`) — a silent no-op unless the human explicitly consented (SCHEMA.md §Telemetry);
-never ask about consent here. `/review` and `/fix` chain the same line with their own
+never ask about consent here. `/cohorte-review` and `/cohorte-fix` chain the same line with their own
 phase + results. The `|| true` swallows a **missing** script too, so a half-copied core goes
-silent rather than loud — `/doctor` check 1 is what catches that.
-Then tell the human: exercise the feature by hand if it's worth it, then run `/review $ARGUMENTS`.
+silent rather than loud — `/cohorte-doctor` check 1 is what catches that.
+Then tell the human: exercise the feature by hand if it's worth it, then run `/cohorte-review $ARGUMENTS` —
+unless a surface is dead, in which case say so first and let them decide whether to re-run `/cohorte-build`
+(a dead surface has no findings, so `/cohorte-fix` has nothing to re-dispatch).
 Do not run the app or migrations yourself here — building is not running.
 **Recommend a `/clear` now** — the spec, contract and diff are all on
 disk, and the lead's history is re-sent at input price on every turn it survives.

package/core/commands/{doctor.md → cohorte-doctor.md}

@@ -16,13 +16,16 @@ fix only with the human's go-ahead (or hand them the command).
    `.claude/pipeline/VERSION` bundled); `.claude/pipeline.json` names a mode + `core_version`
    coherent with the VERSION file. A **global**-mode pointer lagging the VERSION file is ⚠️, not ❌:
    nothing bumped that field before 1.2.5, so the core itself is fine and only the pointer is stale
-   ⇒ fix by running `/update-pipeline` (§3 syncs it now), or by editing the one field. Compare
-   against `npm view cohorte version` — behind ⇒ suggest `/update-pipeline`. Read `pipeline/CHANGELOG.md` for what they're missing. The router
+   ⇒ fix by running `/cohorte-update-pipeline` (§3 syncs it now), or by editing the one field. Compare
+   against `npm view cohorte version` — behind ⇒ suggest `/cohorte-update-pipeline`. Read `pipeline/CHANGELOG.md` for what they're missing. The router
    commands' step files are present — `templates/steps/init-pipeline/` non-empty (a router whose
    `templates/steps/<cmd>/` dir is missing is a partial/stale install ⇒
    re-run install/update). **Shipped scripts present and executable** in `<core>/pipeline/scripts/`:
-   `kanban-move.sh`, `telemetry-send.sh`, `preflight.sh`, `loop.sh`, `new-feature.sh.template`,
-   `remove-feature.sh.template` — ❌ any missing one. Every caller chains these with `|| true`, so an absent script is a **silent**
+   `kanban-move.sh`, `telemetry-send.sh`, `preflight.sh`, `loop.sh`, `loop-detach.sh`,
+   `new-feature.sh.template`, `remove-feature.sh.template` — ❌ any missing one.
+   `loop-detach.sh` absent is what silently turns `/cohorte-loop` back into a foreground run
+   that dies at the 600 s tool ceiling, so name it explicitly rather than folding it into
+   "some script is missing". Every caller chains these with `|| true`, so an absent script is a **silent**
    no-op (no kanban card moves, no telemetry ping, no error anywhere) — this check is the only thing
    that sees it. Also flag ❌ a `VERSION` **newer than** the other `pipeline/` files (compare mtimes):
    a version bumped without a full re-copy is a half-done update ⇒ re-run install/update.
@@ -47,6 +50,11 @@ fix only with the human's go-ahead (or hand them the command).
    it double-prompts) **with a matcher covering both `Bash` and `Task`** — a `Bash`-only matcher
    leaves the preflight phase gate dead (the 1.3.0–1.3.1 regression). Hook files exist at the
    registered paths.
+   Then the **preflight stamp is local, never versioned**: `git ls-files --error-unmatch
+   .claude/preflight.ok` must miss, and `.gitignore` must cover it. A tracked stamp is a ❌ (not a
+   ⚠️) — it records the tree it verified, the commit that carries it moves HEAD past that tree, and
+   the committed copy lands in every clone and new worktree; the gate then blocks clean trees and
+   greens unchecked ones. fix: `git rm --cached .claude/preflight.ok` + add it to `.gitignore`.
 4. **Retrieval** (if `retrieval.provider` ≠ `none`). Run the SCHEMA.md §Code retrieval health
    check: CLI resolvable from PATH, `.mcp.json` entry present in PATH-proof launcher form,
    `.serena/` gitignored, server actually connects.
@@ -67,7 +75,7 @@ fix only with the human's go-ahead (or hand them the command).
    (the install_id is the human's GDPR erasure key — see SCHEMA.md §Telemetry). Flag ❌ any
    incoherent state: `enabled: true` with no `install_id` or no `consent_date` (sending without
    recorded consent — fix: set `enabled: false` until the consent question is re-run), or a
-   `telemetry:` block missing entirely on a current core (top up via `/update-pipeline`).
+   `telemetry:` block missing entirely on a current core (top up via `/cohorte-update-pipeline`).
 8. **Workflows** (the opt-in execution path — SCHEMA.md §Workflows; the conversational commands
    stay the default, so failures here are ⚠️ at most, never ❌). Report which path this machine will
    take and why:
@@ -84,11 +92,16 @@ fix only with the human's go-ahead (or hand them the command).
    End the check with ONE summary line, e.g.
    `workflows: available (opt-in — ask to "run the review workflow")` or
    `workflows: unavailable (<first failing prerequisite>) — conversational commands (the default)`.
-9. **Specs & metrics.** Every `specs/*.md` front-matter `status` is a valid stage — excluding
-   `_`-prefixed files and `specs/refactor-backlog.md`, which `/audit` writes as a backlog, not a
-   spec, and which has no front-matter to check; `shipped` specs
+9. **Specs & metrics.** Every `specs/*.md` front-matter `status` is a valid stage — one of
+   `draft · frozen · in-progress · in-review · shipped · blocked` (SCHEMA.md §Spec status; the last two
+   are written by the `/cohorte-loop` driver, so flagging them would report the pipeline's own state as a
+   defect) — excluding
+   `_`-prefixed files (the spec template and `specs/_decisions.md`, the decision journal) and
+   `specs/refactor-backlog.md`, which `/cohorte-audit` writes as a backlog, not a
+   spec, and which has no front-matter to check. A spec left `in-progress`/`blocked` with
+   `loop_pass` > 0 is a loop that never finished ⇒ say so and name `/cohorte-loop <id> --resume`. `shipped` specs
    with a live worktree flagged (see 6). `.claude/pipeline-metrics.jsonl` and `specs/reports/` (the
-   `/review` report buffer that lets a `/fix` survive a `/clear`) are gitignored. Metrics
+   `/cohorte-review` report buffer that lets a `/cohorte-fix` survive a `/clear`) are gitignored. Metrics
    belong to the **main checkout** — a `pipeline-metrics.jsonl` inside a live feature worktree is a
    stale-core sign (its lines die at teardown) ⇒ suggest appending its lines to the main checkout's
    file and deleting the stray.

package/core/commands/{fix.md → cohorte-fix.md}

@@ -5,29 +5,29 @@ argument-hint: <feature_id> [paste REVIEW REPORT]
 ---
 
 You are the **lead**. Run the fix loop for feature **$ARGUMENTS** — the scoped, cheap path after a
-`REVISE`/`BLOCK` verdict. The full `/spec` (Mode B) + `/build` path still exists for review returns
-that change the *contract*; `/fix` is for everything else.
+`REVISE`/`BLOCK` verdict. The full `/cohorte-spec` (Mode B) + `/cohorte-build` path still exists for review returns
+that change the *contract*; `/cohorte-fix` is for everything else.
 
 > Read `PIPELINE.md` §`pipeline-profile` first: `surfaces` (paths + agent names) and `contract`.
 > _Skip the re-read if it's already in your context this session and unmodified since._
 >
 > **Kanban** (SCHEMA.md §Kanban): move card `#$ARGUMENTS` → **Fix** on ingest (it returns to **Review**
-> when `/review` re-runs). No-op silently if no board.
+> when `/cohorte-review` re-runs). No-op silently if no board.
 
 ## 1. Ingest the report
 
 - The report is either pasted after the feature id (a REVIEW REPORT, or failures the human hit by
-  hand), this session's last `/review` REVIEW REPORT, or — if the context was cleared — read from
-  `specs/reports/<id>.md`, where `/review` stages its last report for exactly this reason.
+  hand), this session's last `/cohorte-review` REVIEW REPORT, or — if the context was cleared — read from
+  `specs/reports/<id>.md`, where `/cohorte-review` stages its last report for exactly this reason.
   If you have none of these, ask for it and wait.
-- Append each finding to `specs/<id>.md` **`## Remediation`** (same format as `/spec` Mode B, under a
+- Append each finding to `specs/<id>.md` **`## Remediation`** (same format as `/cohorte-spec` Mode B, under a
   dated/numbered subheading): `- [ ] <severity> · <file:line> · <type> · <concrete fix>`. Set
   `status: in-review`. Don't pull the whole spec into context for this: grep the line numbers of the
   front-matter `status:` and the `## Remediation` heading, then Read only those regions (offset/limit)
   before editing.
 - **Contract check:** if any finding implies the frozen contract must change, update spec §5 and
-  re-author the contract file yourself now (lead-only, per `/build` §2) — agents never edit it. If
-  the contract change ripples into surfaces *without* findings, fall back to full `/build` instead
+  re-author the contract file yourself now (lead-only, per `/cohorte-build` §2) — agents never edit it. If
+  the contract change ripples into surfaces *without* findings, fall back to full `/cohorte-build` instead
   and say so.
 - **Note the epoch** (`date +%s`) in the first Bash call you make here — §3's metrics line and usage
   ping both carry `seconds`, and there is no separate timing call.
@@ -39,7 +39,7 @@ that change the *contract*; `/fix` is for everything else.
   re-dispatch them. Items outside every surface path (contract file, root config) are yours or go
   to the most relevant surface — say which.
 - Re-dispatch **ONLY the surfaces owning ≥1 item**, in parallel, in a **single message** — the exact
-  dispatch template from `/build` §3 (one byte-stable template for builds and fix loops; you do NOT
+  dispatch template from `/cohorte-build` §3 (one byte-stable template for builds and fix loops; you do NOT
   paste a diff — the agent computes its own, scoped to its tree). Fill the template's final variable
   slot with that surface's open `- [ ]` item lines **verbatim**, so the agent needs no spec re-read to
   find its work; fill the design slot with `none` when a `uses_design` surface's open items are all
@@ -50,11 +50,16 @@ that change the *contract*; `/fix` is for everything else.
 
 When the agents return:
 
+- **Roll call first (SCHEMA.md §Dead agents).** A re-dispatched agent that returns nothing has fixed
+  nothing you can verify. Retry that surface ONCE with the byte-identical dispatch; still silent ⇒ leave
+  **every one of its items `- [ ]`** (a dead agent never ticks a box — that would hide an open finding
+  from the next round and from the driver), print `<key> · DEAD — items untouched`, and say the surface
+  is unverified.
 - **Tick the resolved items.** Each handoff's `## Remediation addressed` lists what that agent fixed
   (by `file:line`). For every Remediation item an agent reports fixed, flip its `- [ ]` → `- [x]` in
   `specs/<id>.md` and append a terse ` — fixed: <what/where>` note (the convention prior rounds already
   use). Leave genuinely-unaddressed items `- [ ]` so the next loop still sees them. This keeps the
-  checkbox state honest and stops a later `/fix` from re-dispatching already-fixed items (§2). Ticking
+  checkbox state honest and stops a later `/cohorte-fix` from re-dispatching already-fixed items (§2). Ticking
   here is the lead's job — surface agents own only their tree, never the spec.
 - **Collapse fully-resolved rounds (keep the spec bounded).** When a whole dated Remediation round is now
   entirely `- [x]`, replace its item lines with a single summary line (`- <date> — <N> findings, all
@@ -62,10 +67,12 @@ When the agents return:
   re-reads each loop. Keep any round with ≥1 still-open `- [ ]` item fully expanded (§2's skip logic
   needs those checkboxes).
 - Print one status line per surface (`<key> · items fixed <n>/<m> · tests pass/fail`) — do not restate
-  handoff content — and append ONE metrics line for the batch to `pipeline-metrics.jsonl`
-  (see `/build` §4, `phase: "fix"`), chaining the opt-in usage ping in the same Bash call
+  handoff content — and append ONE metrics line for the batch to the **main checkout's**
+  `$(dirname "$(git rev-parse --git-common-dir)")/.claude/pipeline-metrics.jsonl` (never a bare
+  relative path: from a feature worktree that writes a stray sink whose lines die at teardown)
+  (rules in `/cohorte-build` §4, `phase: "fix"`), chaining the opt-in usage ping in the same Bash call
   (results = items fixed over items found across surfaces, e.g. `"5/6"`).
-- Tell the human: re-test by hand if the failures were runtime ones, and `/review $ARGUMENTS` for the
+- Tell the human: re-test by hand if the failures were runtime ones, and `/cohorte-review $ARGUMENTS` for the
   re-verdict — the re-review is what *verifies* the ticked items actually hold (a regression simply
   reappears as a new finding in the next round). **Recommend a `/clear`** — all state (spec,
   checkboxes, staged report) is on disk, and the lead's history is re-sent at input price every turn.

package/core/commands/{init-pipeline.md → cohorte-init-pipeline.md}

@@ -1,6 +1,6 @@
 ---
 description: Detect this project's stack, interview the gaps, and generate PIPELINE.md + render the agents so the portable pipeline fits this repo.
-argument-hint: (none) — one-time per project; afterwards /update-pipeline keeps everything current
+argument-hint: (none) — one-time per project; afterwards /cohorte-update-pipeline keeps everything current
 ---
 
 You are the **pipeline installer**. Your job: turn the generic pipeline into one tailored to **this**

package/core/commands/cohorte-loop.md

@@ -0,0 +1,110 @@
+---
+model: sonnet
+description: Autonomous /cohorte-build → /cohorte-review → /cohorte-fix → /cohorte-review loop for one feature, until no blocking finding remains.
+argument-hint: <feature_id> [--max=N] [--no-build] [--rebuild] [--resume]
+allowed-tools: Bash(bash ~/.claude/pipeline/scripts/loop-detach.sh:*), Bash(bash .claude/pipeline/scripts/loop-detach.sh:*), Bash(test:*), Read(specs/reports/**)
+disable-model-invocation: true
+---
+
+You are the **launcher**, not the loop. Run the driver for **$ARGUMENTS** and relay three lines.
+
+> **The driver's name has moved twice.** It was `/loop`, which Claude Code's own built-in `/loop`
+> (run a prompt on a recurring interval) silently **shadowed** — typing `/loop <id>` started the
+> interval runner with the feature id as its prompt, so the driver never ran and the session
+> reported a loop that did not exist. 1.6.0 renamed it `/drive` to escape that. 2.0.0 prefixed
+> every command with `cohorte-`, which makes shadowing impossible by construction, so the accurate
+> name is back: **`/cohorte-loop`**. The shipped script keeps its `loop.sh` name throughout.
+>
+> This command exists because a slash command cannot `/clear` itself. Every phase of the loop runs
+> as a **separate `claude -p` child session** with its own fresh context, driven by a bash script —
+> so the diff, the N review reports and the N contracts never accumulate in YOUR history, which is
+> re-sent at input price on every turn. Running the loop conversationally here would cost more than
+> the loop saves.
+
+## 1. Launch — detached, then poll
+
+The driver runs for **hours**, which rules out running it as one foreground Bash call: a single
+call is capped at 600 s, and a backgrounded one is not detached — the child stays in this session's
+process group, so a Claude Code restart, crash or laptop sleep kills `loop.sh` and every `claude -p`
+child with it, mid-write. `loop-detach.sh` puts the driver in its own `screen` session so it
+survives all of that, and `loop.sh` re-execs itself under `caffeinate` so idle sleep cannot abort
+its in-flight requests either.
+
+Launch — returns immediately:
+
+```
+test -f .claude/pipeline/scripts/loop-detach.sh \
+  && bash .claude/pipeline/scripts/loop-detach.sh start $ARGUMENTS \
+  || bash ~/.claude/pipeline/scripts/loop-detach.sh start $ARGUMENTS
+```
+
+Then poll. Each call blocks up to ~9 min (inside the tool ceiling) and prints the **status file** —
+one line per phase, plus `__EXIT__ <code>` when the run is over:
+
+```
+bash ~/.claude/pipeline/scripts/loop-detach.sh wait <feature_id>
+```
+
+**Repeat `wait` until you see `__EXIT__ <code>`.** A `__RUNNING__` line means the driver is still
+working and nothing is wrong — call `wait` again. Never conclude anything from a `__RUNNING__`;
+the run has not finished and you have no verdict to report. If the human says to stop waiting,
+tell them the run continues detached and how to follow it (`screen -r cohorte-<id>`) — do not
+kill it unless they ask.
+
+Pass `$ARGUMENTS` through untouched — `loop.sh` owns its own flag parsing (`--max=N`,
+`--no-build`, `--rebuild`, `--resume`) and exits 64 on anything it doesn't know. Don't validate flags
+yourself, don't rewrite them, don't add any.
+
+**One lid-close caveat to pass on** if the human is walking away from a laptop: `caffeinate` holds
+off *idle* sleep, but no userspace assertion can prevent lid-close sleep. Lid open, or clamshell
+mode (AC + external display + external input).
+
+**Resume is the human's call, not yours.** The loop records its position in the spec's front-matter
+(`status: in-progress` · `loop_pass` · `loop_phase` — SCHEMA.md §Spec status), so a run killed by a
+dead session, a ceiling or a `blocked` exit can continue with `--resume` instead of re-paying the
+passes it already made. If the human types `/cohorte-loop <id>` on a spec whose front-matter says
+`status: in-progress` or `blocked` with `loop_pass` > 1, say so in one line and ask whether to resume
+or restart — never silently add the flag, and never silently restart from pass 1.
+
+**Never read `specs/reports/<id>.loop.log`.** It holds the full transcript of every child session —
+the entire diff, every review report, every fix handoff. Pulling it into this session re-imports
+exactly the context the loop was built to keep out, and it is the one mistake that turns this
+command into the most expensive one in the pipeline. Point the human at the path instead; they can
+open it in an editor for free. The same goes for the per-surface `.diff` and `.preflight.txt` files.
+
+`<id>.loop.status` is the **other** file and is safe: it is the driver's stdout, one line per phase.
+`wait` already prints it, so you never need to Read it yourself. Two files, one letter apart —
+`.log` is the expensive one.
+
+## 2. Report — three lines, from the exit code
+
+`wait` prints one line per phase, one closing line, and `__EXIT__ <code>`; that is your raw
+material, and that code is the exit code the table below is keyed on. For exit
+**1** or **3** only, also Read `specs/reports/<id>.verdict.json` (small, structured, safe) to name
+the remaining findings — never the markdown report, which is the findings body in full. For exit
+**4**, Read `specs/reports/<id>.readiness.json` instead (also small) and relay its `gaps`. On any
+other exit the closing line already carries the deferred count, so read nothing.
+
+| exit | meaning | what to say |
+| ---- | ------- | ----------- |
+| `0` | clean | no blocking findings left; the human can `/cohorte-ship <id>` |
+| `1` | ceiling hit | the fix was progressing but ran out of passes ⇒ re-run with a higher `--max` |
+| `2` | no usable verdict | `/cohorte-review` produced nothing, or aborted on a red preflight — the closing line says which; point at `specs/reports/<id>.preflight.txt` |
+| `3` | non-convergent | the same blocking findings survived a fix pass; a higher `--max` will NOT help — the human needs to look at them (list them from the verdict) |
+| `4` | not implementable | `/cohorte-build`'s readiness gate returned `NOT-READY` — the frozen spec cannot be built and **no agent ran**; Read `specs/reports/<id>.readiness.json` (small, structured) and relay its `gaps`, then point at `/cohorte-spec <id>`. More passes cannot fix this |
+| `64` | usage | relay the script's own message verbatim |
+
+Then print exactly three lines and nothing else — plus a fourth **only when the verdict carries
+`deferred` > 0** (findings that were real but out of this feature's scope, parked in the backlog by
+`/cohorte-review` §3.5; they are not blocking and never cost a pass, but they are not nothing either):
+
+```
+outcome:    <one clause — clean / ceiling / no verdict / non-convergent / not implementable / usage>
+iterations: <n> review pass(es)<, m fix pass(es) committed>
+remaining:  <blocking count + one short phrase per blocking item, or "none">
+deferred:   <n> parked in specs/refactor-backlog.md — /cohorte-refactor <domain> when you want them
+```
+
+Add at most one follow-up sentence: the next command to run. Never restate a finding's fix, never
+summarize the log, never open the diff. Each fix pass is already committed
+(`loop(<id>): fix pass <i>`) — say so on a non-zero exit, since those commits are the way back.

package/core/commands/{refactor.md → cohorte-refactor.md}

@@ -4,7 +4,7 @@ description: Apply the refactor backlog for one or more domains via the surface
 argument-hint: <domain…> (one or more surface keys, "shared", or "all")
 ---
 
-You are the **lead**. Refactor domain **$ARGUMENTS** to match `PIPELINE.md`, using the `/audit` backlog.
+You are the **lead**. Refactor domain **$ARGUMENTS** to match `PIPELINE.md`, using the `/cohorte-audit` backlog.
 
 > Read `PIPELINE.md` §`surfaces` (map the domain → a surface + its agent + commands) and §`contract`.
 >
@@ -50,7 +50,7 @@ slices import it, so refactor it alone, first.
 After each agent returns: its surface's `test_quiet_cmd`/`lint_quiet_cmd` (else the `tail -40`
 fallback — SCHEMA.md §Output discipline), `commands.typecheck`, `commands.format --check` (redirect
 output to a file and grep it — don't print gate output into your context). Then verify each backlog item cleared by checking its `file:line` directly — do NOT re-run
-`/audit` per round (that repeats the repo-wide gates + a review dispatch you don't need); one optional
-final `/audit` once ALL dispatched domains are clean is enough. Check cleared items off in
+`/cohorte-audit` per round (that repeats the repo-wide gates + a review dispatch you don't need); one optional
+final `/cohorte-audit` once ALL dispatched domains are clean is enough. Check cleared items off in
 `specs/refactor-backlog.md`. Loop until each dispatched domain is clean. Verification is per-domain
 even when the dispatch was parallel — one failing surface loops alone, the others don't redo work.