cohorte 2.10.0 → 3.0.0-dev.0

package/core/commands/cohorte-intake.md

@@ -1,92 +0,0 @@
----
-description: Triage anything that arrives — a ticket, a client email, a stack trace, a Slack thread — into the pipeline's entry point: a patch handoff or a brainstorm seed.
-argument-hint: [paste the raw material — ticket, email, trace, thread — or empty to be asked]
----
-
-You are the **intake triager**. Work is arriving from OUTSIDE the pipeline — a bug report, a
-client email, a support thread, a stack trace, a half-idea — and today a human distills it by
-hand before anything can start. Your job is that distillation: read the raw material, decide
-which door it enters through, and stage a handoff the next command can consume verbatim.
-
-> Read `PIPELINE.md` §`pipeline-profile` first — `name`, `one_liner`, `surfaces` (to guess which
-> surface a symptom lives in) and `ui_language`. _Skip the re-read if it's already in your
-> context this session and unmodified since._ Read `specs/_decisions.md` §Live if it exists —
-> an incoming request that contradicts a settled decision must be flagged as such, not triaged
-> as a fresh idea.
-
-## 1. Ingest & triage
-
-The material is pasted after the command; nothing pasted ⇒ ask for it and wait (paste, file
-path, or a `gh issue view <n>` you run yourself when they name an issue number). Then decide —
-and say which signals decided it:
-
-- **Bug** — existing behavior misbehaving: a repro or trace, "used to work", an error message,
-  a version where it broke. → §2.
-- **Feature** — behavior that does not exist yet: "could we", "it should also", a workflow the
-  product doesn't cover. → §3.
-- **Both tangled together** (a bug report whose fix half describes a new feature): split it —
-  §2 for the defect, §3 for the rest — and say you split it.
-- **Neither** (a question, a config issue on their side, praise, noise): say so in one line and
-  stop. Not everything that arrives is work; inventing a spec from noise costs a whole pipeline
-  run downstream.
-
-Pick a short kebab-case **slug** from the content (`checkout-double-charge`, `csv-export`) —
-it becomes the join key for the file, the kanban card and the follow-up command.
-
-## 2. Bug → a `/cohorte-patch` handoff
-
-Distill the raw material into exactly the structure `/cohorte-patch` §1 interviews for — so the
-patch triage starts loaded instead of re-asking:
-
-- **Symptom** — one sentence, observed behavior vs expected.
-- **Repro** — numbered steps as far as the material supports them; mark every step you inferred
-  (`(inferred)`) rather than silently guessing. A trace with no steps ⇒ the trace IS the repro
-  material, say so.
-- **Environment** — version/browser/OS/role if present; `unknown` where absent.
-- **Suspected surface(s)** — map the symptom onto `surfaces[]` by what the paths/stack frames
-  name; a guess is fine, label it one.
-- **Severity signal** — who is blocked and how hard, in the reporter's own words.
-
-**Stage it** to `specs/reports/intake-<slug>.md` (overwrite; `mkdir -p specs/reports` first —
-the gitignored buffer dir, so the handoff survives a `/clear`). Then:
-
-> **Kanban** (SCHEMA.md §Kanban): run
-> `<core>/pipeline/scripts/kanban-move.sh auto patch-<slug> ideas --title "[patch] <one-line title>"`.
-> The id is **`patch-<slug>`, prefix included, and the title prefix is `[patch]`** — that is the
-> exact join key and the exact title `/cohorte-patch` §1 looks for, so its later move finds THIS
-> card instead of creating a duplicate and stranding this one in Ideas (the failure SCHEMA
-> §Kanban's "tag before you move" exists to prevent). `auto` resolves the board from the config
-> itself and exits 0 with a `kanban: <reason>` line when there is none — so **never decide "no
-> board is configured" without running it**.
-
-Close with: `→ /cohorte-patch <slug>` — `/cohorte-patch` reads the staged
-`specs/reports/intake-<slug>.md` when it exists, so the triage starts loaded. Do **not** run it
-yourself — freezing a spec is a decision the human confirms, and intake's job ends at the door.
-
-## 3. Feature → a `/cohorte-brainstorm` seed
-
-Distill into the seed the panel argues best about:
-
-- **Title + one-liner** — in the product's language (`ui_language` for user-facing wording).
-- **Who is asking & why now** — verbatim quotes where the material has them; the panel argues
-  better against a real voice than a paraphrase.
-- **Goals / explicit non-goals** — only what the material actually states; never pad.
-- **Open questions** — every ambiguity you'd otherwise have guessed at, as questions. This list
-  is the seed's real value: it is the brainstorm's agenda.
-- **Prior art in this repo** — one grep pass: existing specs/decisions touching the same area
-  (`grep -l` over `specs/*.md`, redirected — never a file read per name). Contradicts a
-  `_decisions.md` line ⇒ name the line verbatim; the panel must argue against it knowingly.
-
-**Stage it** to `specs/reports/intake-<slug>.md` (overwrite), then the kanban call with the
-bare id: `<core>/pipeline/scripts/kanban-move.sh auto <slug> ideas --title "<title>"` (same
-"never decide without running it" rule as §2). The card is the board's join key; **the seed
-itself travels in the staged file** — `/cohorte-brainstorm <slug>` reads
-`specs/reports/intake-<slug>.md` when it exists, so the panel argues against the distillate,
-not against a bare slug.
-
-Close with: `→ /cohorte-brainstorm <slug>` — the seed is on disk and on the board;
-**recommend a `/clear` first**, the handoff is complete.
-
-In chat print ONLY: the triage verdict + its signals (one line), the staged file path, the
-kanban result line, and the follow-up command. Never echo the full distillate into chat — it
-is on disk, and this session's history is re-sent at input price on every turn.

package/core/commands/cohorte-patch.md

@@ -1,118 +0,0 @@
----
-description: Triage a bug and freeze a minimal patch spec — the cheap entry into the pipeline for a fix, no brainstorm, no contract.
-argument-hint: [bug description / stack trace / issue text — or empty to pick from the kanban]
----
-
-You run the **patch triage** in the main thread — interactive, with the human. This is the bug-fix
-entry point: it produces `specs/patch-<slug>.md` and stops. Everything after it is the normal
-pipeline (`/cohorte-build` → `/cohorte-review` → `/cohorte-fix`* → `/cohorte-ship`), unchanged — the
-patch spec is a spec, so those commands consume it as-is. Splitting it this way is the point: each
-phase is a fresh session with the artifact on disk, instead of one long thread paying for the whole
-cycle at input price on every turn.
-
-Bug (may be empty): **$ARGUMENTS**
-
-> Read `PIPELINE.md` §`pipeline-profile` first: `surfaces` (paths — this is what you map the bug onto)
-> and `vcs`. _Skip the re-read if it's already in your context this session and unmodified since._
-> Do NOT read `specs/_decisions.md`: a bug fix decides nothing transverse, and the journal is for
-> decisions that outlive a feature.
->
-> **Kanban** (SCHEMA.md §Kanban): two moves, and their **order is load-bearing** — §1 settles the
-> slug and moves the card to `spec`, §4 moves it to `ready` at freeze. Both are one call to
-> `<core>/pipeline/scripts/kanban-move.sh auto patch-<slug> <stage> [--title "[patch] <human title>"]`.
-> The slug is settled first precisely because the move needs it: a card cannot be joined on an id
-> that doesn't exist yet. `auto` resolves the board from the config itself and exits 0
-> with a `kanban: <reason>` line when there is none — so **never decide "no board is configured"
-> without running it**. Reading the Ideas column at §1 still needs the board path: get it from a
-> `kanban-move.sh` run, or grep the config for `boards[<PIPELINE name>]`.
-
-## 1. Get the bug
-
-If `$ARGUMENTS` is non-empty, restate it in one line and confirm you've got it — and if it is
-(or names) a slug with a staged `specs/reports/intake-<slug>.md`, **read that file first**: it is
-`/cohorte-intake`'s distillate (symptom, repro with inferred steps labeled, environment, suspected
-surfaces, severity signal), so this triage starts loaded instead of re-asking. Keep intake's slug —
-its kanban card is already tagged `#patch-<slug>` and titled `[patch] …`, exactly what the move
-below joins on.
-
-If it is empty: when a board is configured and its **Ideas** column has cards, list them (with any
-sub-bullet notes as context) — **cards titled `[patch]` first**, since those are the ones a human
-filed as bugs — and let the human pick one. Otherwise ask **"What's broken?"**. Either way, wait.
-
-Then **settle the id, before anything moves.** Derive `<slug>` (kebab-case, from the symptom —
-`500-on-empty-cart`, not `bug-42`) and confirm it. The `feature_id` is **`patch-<slug>`**, prefix
-included: it is the join key for the kanban card, the spec filename, the branch and every later
-command, so the prefix is part of the id itself, not decoration on the card.
-
-**Kanban, in this order:**
-
-1. **If the human picked an Ideas card, tag it FIRST.** Ideas cards are free text with no
-   `#<feature_id>`, and the move script joins on that tag: move before tagging and it finds nothing,
-   creates a second card, and strands the untagged original in Ideas forever. One targeted Edit
-   appending `  #patch-<slug>` to that line, located by `grep -n` — never a full board read.
-2. `<core>/pipeline/scripts/kanban-move.sh auto patch-<slug> spec --title "[patch] <human title>"` —
-   which moves the (now tagged) card, or creates one under `--title` if the human typed a fresh bug.
-   Report what it printed — `moved #…` or `kanban: <reason>` — never a guess about which happened.
-
-## 2. Triage — three questions, not an interview
-
-`/cohorte-spec` walks a template section by section because a feature has to be *designed*. A bug is
-already specified by reality; your job is to pin it down, not to explore it. Ask only what you
-genuinely cannot infer from the input, batched into ONE message:
-
-1. **Repro** — the shortest deterministic path to the symptom. No repro ⇒ ask whether they want you
-   to go find one first (a diagnosis session, no spec) or to freeze it as a hypothesis and let the
-   implementer confirm. Never invent a repro to fill the section.
-2. **Expected behaviour** — often the whole spec. "It should 404, not 500" is a complete contract.
-3. **Blast radius** — what must NOT change. This becomes §7 Out of scope, and it is what stops a fix
-   from becoming a refactor.
-
-Then locate it yourself — do not make the human do it. Use the retrieval provider if one is wired,
-else grep for the symptom's strings/identifiers. Read only the files the trail actually names.
-Report the suspected `file:line` in one line and let them confirm or correct it.
-
-## 3. Map it onto surfaces — as many as it takes
-
-Match the suspected cause and the fix's blast radius against `surfaces[].path`. **A patch is not
-capped at one surface**: a bug that spans an API validator and the form feeding it is one bug with
-one repro, and splitting it into two specs would give each half a contract it doesn't have. List the
-surfaces you're claiming, one line each, with why.
-
-**The one escalation that is not a judgment call:** if the fix needs **new** contract surface area —
-a new endpoint, a new shared type, a new field crossing surfaces — stop. That is a feature wearing a
-bug's clothes, and §5 is the only channel that keeps two surfaces in agreement about a shape that
-doesn't exist yet. Say so plainly and send the human to `/cohorte-spec`. Changing an **existing**
-contract entry is fine: describe the delta in §5 and continue.
-
-## 4. Freeze the patch spec
-
-Write `specs/patch-<slug>.md` from `<core>/templates/patch.template.md` with `status: frozen`, filled
-from §§1–3. **Create the file — do not ask the human to.** Budget: **~60 lines**. A patch spec that
-wants 200 is a feature or a refactor — say which and route it (`/cohorte-spec`, or an item on
-`specs/refactor-backlog.md`).
-
-Two sections carry the weight, and both are cheap to get wrong:
-
-- **§4 Regression test** — name the test file and what it asserts. It replaces §5 as the thing the
-  reviewer checks the diff against, so "add a test" is not enough: say what fails today and why. A
-  patch whose test can only be written after the cause is found says exactly that.
-- **§5/§9 keep the feature spec's numbers** (contract delta, acceptance). `review.md` and
-  `implementer.template.md` name "contract §5, acceptance §9" verbatim — renumbering them here would
-  silently point both agents at the wrong section. The template already does this; don't "fix" it.
-
-**Postcondition:** `grep -q '^status: frozen' specs/patch-<slug>.md` — if it fails the freeze didn't
-land; fix it before pointing the human at `/cohorte-build`. Chain the second kanban move onto that
-same Bash call — `kanban-move.sh auto patch-<slug> ready` (the card is already tagged and on the
-board from §1, so this one needs no `--title`) — and report what it printed: `moved #…` or
-`kanban: <reason>`, never a guess.
-
-## 5. Hand off
-
-Print the spec path, the surfaces, and the branch to cut: `<prefix>patch-<slug>`, where `<prefix>` is
-`vcs.patch_branch_prefix` — falling back to `fix/` on a profile that predates the key. If `isolation.enabled`
-and the fix is big enough to want its own worktree, mention `scripts/new-feature.sh patch-<slug>`;
-most patches don't need it.
-
-Then: `/cohorte-build patch-<slug>` — and **recommend a `/clear` first**. The spec is on disk; the
-lead's triage history is re-sent at input price on every turn it survives, and `/cohorte-build`
-re-reads everything it needs.

package/core/commands/cohorte-refactor.md

@@ -1,59 +0,0 @@
----
-model: sonnet
-description: Apply the refactor backlog for one or more domains via the surface implementer agents (TDD-first, parallel across independent surfaces), then re-verify.
-argument-hint: <domain…> (one or more surface keys, "shared", or "all")
----
-
-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`.
->
-<!-- cohorte:if workflows -->
-> **Workflow variant** (opt-in — SCHEMA.md §Workflows): for BIG domains (many open backlog items
-> across several surfaces), on Claude Code ≥ 2.1.154 with workflows enabled, the human can ask to
-> "run the refactor workflow" (`<core>/workflows/refactor.js`). For a handful of items this
-> conversational path is cheaper — and it stays the default and the fallback.
-<!-- cohorte:endif -->
-
-## 1. Gather
-
-- Read `specs/refactor-backlog.md`; select the items for `$ARGUMENTS` (`all` = every domain with
-  open items).
-- Map each domain to a surface. `shared` = the contract package (`contract.path`), owned by you/lead —
-  refactor it directly, don't dispatch.
-
-## 2. Dispatch the surface's implementer agent — TDD-first, stateless
-
-Spawn the matching `<surface.agent>` with the template below (as `subagent_type: <surface.agent>`).
-Keep it **byte-identical across loop
-rounds** (only the final items slot varies — it sits at the end so repeats hit the prompt cache), and
-never paste a diff — the agent computes its own, scoped to its tree:
-
-> "Refactor pass on your surface (no feature spec). Read
-> `PIPELINE.md` first. **Add the missing tests FIRST** (pin current behavior / cover the entry
-> points), watch them pass, **then** refactor to clear each item. Preserve current public behavior
-> unless an item marks it a bug. Migrations stay additive. Need the current state of your tree?
-> Compute it yourself: `git diff <default_branch> -- <surface.path>`. Lint + format before handoff;
-> return the handoff in the format your agent instructions define. Backlog items for YOUR surface
-> (self-contained — clear exactly these, reading only the files they name): <the domain's open
-> `- [ ]` lines verbatim, with exact file paths>."
-
-**Parallel when domains are independent:** if the human passed several domains (or `all`), dispatch
-their implementers **concurrently in a single message** — surface trees are disjoint by construction,
-so parallel is safe. Exception: `shared` (the contract package) never joins a parallel batch — the
-slices import it, so refactor it alone, first.
-
-- **Preserve current public behavior** unless a finding marks it a bug/convention violation — existing
-  code has no contract spec, so don't silently change shapes.
-- Migrations stay **additive**; never `PIPELINE.md` §`gate.deny` commands.
-- Touch only its surface; lint + format before handoff.
-
-## 3. Verify & loop
-
-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
-`/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.

package/core/commands/cohorte-retro.md

@@ -1,85 +0,0 @@
----
-description: Mine the accumulated review findings across features for repeating patterns, and turn the ones the human ratifies into PIPELINE.md §Conventions rules the next build already follows.
-argument-hint: [last <n> | all]  (default: every feature with a report on disk)
----
-
-You are running the **retrospective**. Every review this pipeline has run left structured
-residue on disk — verdicts, Remediation rounds, deferred backlog items. A finding that shows up
-once is a bug; the same finding shape across features is a **missing rule**, and the pipeline
-has a place for rules the implementers actually read: `PIPELINE.md` §Conventions, baked into
-each surface agent at render time. This command closes that loop: findings → patterns →
-ratified rules → re-rendered agents. The next build then never produces the finding again —
-which is cheaper than any number of review rounds catching it.
-
-> Read `PIPELINE.md` §`pipeline-profile` (`surfaces`, and skim the existing §Conventions
-> stanzas — a rule that already exists is a finding about *enforcement*, not a missing rule)
-> and `specs/_decisions.md` §Live. _Skip the re-read if already in context and unmodified._
-
-## 1. Collect — mechanical, redirected, no judgment yet
-
-Scope: `all` (default), or `last <n>` features by spec mtime. In as few Bash calls as possible,
-**always redirected to `specs/reports/retro-scan.txt` and grepped — never into your context**:
-
-- `specs/reports/*.verdict.json` — per feature: `blocking_items` (normalized identities),
-  `severity`, per-surface counts. The freshest machine record, one per feature.
-- Every non-`_` spec's `## Remediation` section — the **persistent** history (verdict.json is
-  overwritten per round; Remediation accumulates, and collapsed rounds still carry their
-  count line). Grep the item lines: `- [x?] <SEVERITY> · <file:line> · <kind> · <fix>`.
-- `specs/refactor-backlog.md` — the `deferred:<id>` tagged items: debt reviews kept finding
-  but no feature owned.
-
-A repo with fewer than two features' worth of residue ⇒ say the retro has nothing statistical
-to stand on yet, name what exists, and stop — one feature's findings are that feature's story,
-not a pattern.
-
-## 2. Patterns — what repeats, with the evidence attached
-
-A **pattern** is a finding shape that recurs where recurrence means something:
-
-- same `kind` × same surface across **≥ 2 features** (e.g. `security` findings on `backend`
-  twice running — the strongest signal there is);
-- the same file/module named by findings from **≥ 2 features** (a hotspot no single fix loop
-  owns);
-- the same *fix wording* family recurring (e.g. three "add the authz check" fixes = one
-  missing authorization convention);
-- a `deferred:` cluster in one domain — debt the reviews keep re-discovering because no rule
-  makes the implementers avoid adding to it.
-
-For each pattern, produce: the evidence lines **verbatim** (`<feature> · <severity> · <file> ·
-<problem/fix>`), the count, and ONE drafted convention rule — **rule-shaped**: a sentence an
-implementer can follow and a reviewer can test a diff against, placed under `### Shared` or the
-owning `### Surface: <key>`. Not advice ("be careful with auth") — a rule ("every route under
-`apps/api/src/routes/` calls `authorize()` before its handler; no exceptions without a spec
-§5 note"). Skip any pattern the existing §Conventions already covers — report those separately
-as **enforcement gaps** (the rule exists and reviews keep finding violations: that is input for
-the human, not a new rule).
-
-## 3. Ratify — the human picks; nothing lands without them
-
-Present a compact table: pattern → evidence count → drafted rule → target stanza. Then **stop
-and ask** which to adopt (all / some / none — none is a fine outcome and says the rulebook fits
-the codebase). Rules are standing law every future dispatch pays tokens to carry: the human
-decides what becomes law, exactly as they freeze specs.
-
-## 4. Apply — and keep the baked slices honest
-
-For each adopted rule, in this order:
-
-1. Append it to `PIPELINE.md` §Conventions under its stanza (create the `### Surface: <key>`
-   stanza if absent; keep it rule-shaped, one line each).
-2. **Re-render every affected surface agent** per SCHEMA.md §Rendering step 2 — the
-   `<SURFACE_CONVENTIONS>` slice is **baked at render time**, so a §Conventions edit without a
-   re-render produces the worst outcome available: reviewers (who read the prose live) enforce
-   a rule implementers (who carry the stale bake) have never seen, and every future review
-   round re-finds the pattern this retro just paid to close. If you cannot re-render on this
-   runtime, say so and route to `/cohorte-update-pipeline` (its reconcile step 2 re-renders) —
-   but then the rule is **pending**, and you say that too.
-3. Append ONE line per adopted rule to `specs/_decisions.md` §Live (SCHEMA.md §Decisions):
-   `- <date> · conventions · <rule, compressed> — because <kind>×<n> across <features> · retro`.
-   A retro rule is a standing decision; the journal is where the next `/cohorte-spec` learns it
-   without re-mining the reports.
-
-In chat print ONLY: patterns found / adopted / skipped (one line each), enforcement gaps, which
-agents were re-rendered (or the pending route), and the decisions lines appended. The evidence
-stays in `specs/reports/retro-scan.txt`. **Recommend a `/clear`** — everything that matters is
-now in `PIPELINE.md`, the rendered agents, and the journal.

package/core/commands/cohorte-review.md

@@ -1,270 +0,0 @@
----
-model: sonnet
-description: Dispatch the read-only review agent to audit the feature against its frozen spec.
-argument-hint: <feature_id>
----
-
-You are the **lead**. Dispatch the review for feature **$ARGUMENTS**.
-
-> Read `PIPELINE.md` §`vcs.default_branch` (diff base) and the `surfaces`/`contract`/`commands` fields.
-> _Skip the re-read if it's already in your context this session and unmodified since._
->
-> **Kanban** (SCHEMA.md §Kanban): run
-> `<core>/pipeline/scripts/kanban-move.sh auto $ARGUMENTS review`. `auto` resolves the board from the config itself and
-> exits 0 with a `kanban: <reason>` line when there is none — so **never decide "no board is
-> configured" without running it**. _(PR mode — `--pr` below — skips this entirely: an incoming
-> PR is not a pipeline feature and has no card.)_
->
-<!-- cohorte:if workflows -->
-> **Workflow variant** (opt-in — SCHEMA.md §Workflows): on Claude Code ≥ 2.1.154 with workflows
-> enabled, the human can ask to "run the review workflow" (`<core>/workflows/review.js`) instead.
-> This conversational path stays the default and the fallback; `/cohorte-doctor` shows which is available.
-<!-- cohorte:endif -->
-
-## PR mode — review an INCOMING pull request (`--pr <num>` or a PR URL)
-
-If `$ARGUMENTS` contains `--pr <num>` (or a GitHub PR URL — extract the number), this is not a
-pipeline feature: it is **someone else's work arriving**, reviewed with the same reviewers and the
-same report format, without pretending it went through the pipeline. What that changes, explicitly:
-**no spec** (nothing to check conformance against — reviewers run in audit mode: conventions +
-correctness + security + TDD coverage only), **no kanban move**, **no verdict.json**, **no DoD
-tick, no freshness stamp, no metrics line** — those certify pipeline features, and this is not one.
-Requires `vcs.host: github` + `gh`; otherwise say so and stop.
-
-1. **Fetch into a throwaway worktree — never touch the current checkout.** One Bash call:
-   `gh pr view <num> --json title,baseRefName,headRefName,author` (relay the one-line summary), then
-   `git fetch -f origin pull/<num>/head:cohorte-pr-<num> <baseRefName> && git worktree add ../<repo>-pr-<num> cohorte-pr-<num>`
-   — `-f` so a branch left behind by a crashed earlier run updates instead of failing, and the
-   **base ref is fetched too**: the diff below is against `origin/<baseRefName>`, and a stale
-   local base blames the PR for every commit it merely hasn't rebased onto yet.
-   The human's tree, branch and stamps stay untouched; every later step runs `-C` that worktree.
-2. **Mechanical checks inside the worktree — the commands directly, NEVER `preflight.sh`.** The
-   script's whole point is stamping `<state>/preflight.ok` in the MAIN checkout (it resolves
-   through `git-common-dir` on purpose), so running it here would overwrite the human's stamp
-   with the PR tree's digest — greening pipeline review dispatches of a tree nobody preflighted,
-   then blocking them once the worktree is gone. Instead: install dependencies first
-   (`commands.install` — a bare `worktree add` has no `node_modules`), then run the profile's
-   typecheck/lint-quiet/test-quiet yourself, each appended to the worktree's
-   `specs/reports/pr-<num>.preflight.txt`, stopping at the first failure. **Red does NOT get
-   reviewers** — same economics as §0 (a reviewer on code that doesn't compile rediscovers what
-   `tsc` printed for free) — but unlike §0 it is not an abort: the mechanical failures ARE the
-   review (severity CRITICAL, kind `quality`, the failing command + last lines) — jump to
-   step 4. An *environmental* failure (install itself failed, a missing service) is reported as
-   "not verifiable here", never as a finding against the PR.
-3. **Stage + dispatch — §1's staging procedure and §2's dispatch, minus everything spec-shaped**
-   (there is no `specs/<id>.md` to confirm and no small-diff fast path — an unknown author's
-   diff always gets a full reviewer), with three substitutions: the diff is
-   `git diff origin/<baseRefName>...HEAD` (**three-dot** — only the PR's own commits, not the
-   base's drift), staged diffs and file paths are **absolute paths into the worktree**
-   (reviewers are stateless — they must not read the main checkout), and the dispatch template's
-   spec/contract slots read
-   `spec: none (incoming PR — audit mode: PIPELINE.md conventions + quality/security/TDD only,
-   skip spec conformance)` · `contract: none`. Roll call + merge per §3 (retry once, `unreviewed`
-   forbids a clean verdict), same capped REVIEW REPORT.
-4. **Stage the report to the MAIN checkout's `specs/reports/pr-<num>.md`** (it must outlive the
-   worktree), print the verdict + severity table + CRITICAL/security digests in chat. Then —
-   **always ask the human first, posting is outward-facing** — offer:
-   `gh pr comment <num> --body-file specs/reports/pr-<num>.md` (prefix the body with one line:
-   `Automated review — cohorte pipeline (advisory)`). Never post without the explicit go-ahead;
-   "no" leaves the report on disk and that is a complete outcome.
-5. **Teardown, always** (also after a red preflight or a dead reviewer):
-   `git worktree remove --force ../<repo>-pr-<num> && git branch -D cohorte-pr-<num>`.
-
-Everything below this line is the normal pipeline-feature flow.
-
-## 0. Deterministic pre-flight — no agents while red
-
-Run the profile's mechanical gates in ONE Bash call via the shipped script
-(`<core>/pipeline/scripts/preflight.sh`); note the epoch (`date +%s`) in the same call — §3's
-metrics line needs it:
-
-```
-<core>/pipeline/scripts/preflight.sh specs/reports/$ARGUMENTS.preflight.txt \
-  "<commands.typecheck>" "<commands.lint_quiet, else lint>" "<commands.test_quiet, else test>"
-```
-
-- **Non-zero exit** ⇒ the script already printed the raw last-40 lines. **STOP: relay them verbatim
-  and spawn NO agent** — a compiler/test failure needs `/cohorte-fix` (or the human), not a review that
-  rediscovers it at agent prices. This abort is the whole point of the step. Before stopping, write
-  the **aborted verdict** (§3's contract, degraded form) so an automated driver gets a diagnosis
-  rather than silence:
-  `{"id":"$ARGUMENTS","phase":"review","ts":"<ISO>","aborted":"preflight","verdict":"BLOCK","blocking":null}`
-  → `specs/reports/$ARGUMENTS.verdict.json`. One `printf`, in the same Bash call.
-<!-- cohorte:if hooks -->
-- **Zero exit** ⇒ it stamped `<state>/preflight.ok`, which the gate hook checks before letting
-  `review` dispatches through (SCHEMA.md §Preflight). Continue.
-<!-- cohorte:else -->
-- **Zero exit** ⇒ it stamped `<state>/preflight.ok`. Nothing enforces that stamp on this runtime, so
-  §2 does not start until you have seen this line: a review of red code is the one failure mode this
-  step exists to prevent, and here only you can prevent it (SCHEMA.md §Preflight). Continue.
-<!-- cohorte:endif -->
-- Script absent (older core) ⇒ run the three commands yourself, each redirected into
-  `specs/reports/$ARGUMENTS.preflight.txt`, aborting on the first failure the same way.
-
-## 1. Gather the inputs for stateless reviewers
-
-- Confirm `specs/$ARGUMENTS.md` exists.
-- **Compute the diff ONCE — `--stat` first, patches only for retained surfaces.** One call:
-  `git diff <default_branch> --stat > specs/reports/$ARGUMENTS.stat.txt`, then grep that file to
-  group the changed paths by `surfaces[].path` prefix (deterministic — don't reason it out file by
-  file). Paths under no surface (contract file, root config) are the **`shared` remainder**: attach
-  them to the most relevant surface's reviewer and say so in its dispatch. A surface with no changed
-  paths gets no reviewer — and no `.diff` is ever generated for it.
-- **Stage the hunks once per touched surface** (reviewers are read-only — no Bash — so the staged
-  diff file is the ONLY way they can review hunks instead of re-reading whole files, and staging it
-  here means N reviewers never re-run git N times). Regenerated every round:
-  `git diff <default_branch> -- <surface.path> > specs/reports/$ARGUMENTS.<surface.key>.diff`
-  (same gitignored buffer dir as the reports). For the surface that carries the shared remainder,
-  append the remainder pathspecs to its command so its `.diff` includes them. Never print a diff into
-  your own context — redirect straight to the file.
-
-## 2. Dispatch review agents — one per touched surface, IN PARALLEL
-
-Spawn ONE `review` agent per surface that has changed files, in a **single message** (one dispatch
-each, like `/cohorte-build`) so they run concurrently — NEVER serially: review wall-clock must be the
-slowest surface, not the sum. A diff touching a single surface ⇒ a single reviewer.
-
-**Small-diff fast path (re-reviews only):** if a surface's staged diff is tiny (≤2 files and ≤~40
-changed lines), touches no contract file, and every open finding it addresses is non-security
-LOW/MEDIUM, skip the dispatch: verify the hunks yourself against the open Remediation items (did the
-prescribed fixes land? — NOT a de-novo audit) and write the same REVIEW REPORT into the §3 flow.
-First-round reviews, contract changes, and security findings always get a full reviewer. For each
-reviewed surface:
-
-Keep the dispatch prompt **byte-identical across features and rounds** except the variable block,
-which sits at the END so every repeat hits the prompt-cache prefix:
-
-> `subagent_type: review` (or this runtime's equivalent) — "Review one feature surface against its frozen spec. Read `PIPELINE.md`
-> first (flags + the §Conventions/§Testing slice for your scope). Check spec conformance first, then
-> correctness, security, conventions, RBAC/mobile-first _if the profile enables them_, and TDD
-> coverage. Your dispatch names a staged diff file — read it FIRST; open a full source file only when
-> a finding demands it. Emit the REVIEW REPORT in the capped format your agent instructions define —
-> every finding self-sufficient (`file:line` · severity · type · one-line concrete fix), no code
-> excerpts. — Variable slots: feature `$ARGUMENTS` · scope: the `<surface.key>` surface only · spec:
-> `specs/$ARGUMENTS.md` (source of truth) · contract: `<contract.path>/$ARGUMENTS.<ext>` · staged
-> diff: `specs/reports/$ARGUMENTS.<surface.key>.diff` · changed files (`--stat`): <list>."
-
-§0's preflight call already gave you the wall-clock start (`date +%s` in the same call) — §3's
-metrics line needs it.
-
-## 3. Merge & relay the verdict
-
-**Roll call FIRST — a dead reviewer is not a clean surface.** Every surface you dispatched in §2 must
-come back with a REVIEW REPORT. A reviewer that died (rate limit, transport error, exhausted context)
-returns **nothing**, and zero findings from a dead reviewer is byte-identical to zero findings from a
-genuinely clean one — which is how "every reviewer crashed" reads as the strongest possible verdict
-from no evidence at all (SCHEMA.md §Dead agents). So:
-
-- **Retry a silent surface ONCE**, byte-identical dispatch. Most deaths are transient, and the staged
-  diff is already on disk — the retry costs one agent, not a re-review.
-- **Silent twice ⇒ that surface is `unreviewed`.** Name it in the report under
-  `## NOT reviewed (no verdict on these)`, list it in the verdict JSON's `unreviewed`, and **refuse to
-  score `SHIP`** — the merged verdict is at least `REVISE`. Absence of evidence is not evidence of
-  absence, and it must never reach `/cohorte-ship` or tick a DoD box.
-- **Never re-review the other surfaces** to compensate: their reports are valid and already on disk.
-
-Then merge the returned reports into **one** REVIEW REPORT (same template): findings concatenated and
-re-ordered by severity, counts summed, duplicates collapsed, verdict = the worst returned
-(`BLOCK` > `REVISE` > `SHIP`). The `## Deferred` sections merge the same way (dedupe by
-`file` + problem) and stay **out of the severity table and out of the verdict** — see §3.5, which
-routes them. Append ONE metrics line for the batch to the **main checkout's**
-`$(dirname "$(git rev-parse --git-common-dir)")/<state>/pipeline-metrics.jsonl` (rules in
-`/cohorte-build` §4; never a bare relative path — from a worktree that strands the lines): `{"ts":"<ISO>","feature":"$ARGUMENTS","phase":"review","seconds":<wall-clock>,"surfaces":{"<key>":"<verdict>:<finding count>",…}}`.
-**Stage the full report to `specs/reports/$ARGUMENTS.md`** (overwrite) — a gitignored buffer so a
-`/cohorte-fix` after a `/clear` can still read the findings; the `specs/reports/` subfolder is skipped by the
-non-recursive `specs/*.md` glob, so it's never mistaken for a spec (no phantom card, no bogus stage).
-**Write the machine-readable verdict** to `specs/reports/$ARGUMENTS.verdict.json` (overwrite) — on
-**every** run, including the small-diff fast path of §2 and a `SHIP`. This file is the ONLY contract
-between the pipeline and any automated driver, which parses no prose:
-
-```json
-{ "id": "$ARGUMENTS", "phase": "review", "ts": "<ISO>", "verdict": "REVISE",
-  "findings": 7, "blocking": 2, "security": 1, "deferred": 3, "unreviewed": [],
-  "severity": {"CRITICAL": 1, "HIGH": 2, "MEDIUM": 3, "LOW": 1},
-  "surfaces": {"backend": {"verdict":"BLOCK","findings":4,"blocking":2}},
-  "blocking_items": ["backend|apps/api/src/routes/order.ts|missing authz on post"],
-  "fingerprint": "b3f1c2a90d4e5f67" }
-```
-
-- **`blocking` = CRITICAL findings + `security` findings, deduplicated** (a finding that is both
-  counts once). That is exactly the agent's existing verdict rule restated as a number, so
-  `blocking == 0` ⟺ `verdict == SHIP`. HIGH/MEDIUM/LOW quality findings are **not** blocking and
-  must never cost a driver an iteration — a *human* routes them in the verdict branch below
-  (a `/cohorte-fix` pass, or a deliberate park in the backlog); a driver ignores them.
-- **`blocking_items`** — one normalized string per **distinct** blocking finding (deduplicated —
-  two findings sharing surface, file and problem head are one identity), `<surface>|<file>|<problem>`:
-  the file path **without the `:line`** (a fix that inserts lines shifts every line below it — a
-  line-bearing identity would change every pass and the drift detection would never fire), and the
-  **problem**, not the fix, cut to its first 8 words, lowercased, every run of non-alphanumerics
-  collapsed to one space. Identity of a finding, not its wording.
-- **`fingerprint`** — computed in the same Bash call, never by hand:
-  `printf '%s\n' "<item>" … | LC_ALL=C sort | sha256sum | cut -c1-16` (`shasum -a 256` where there
-  is no `sha256sum`). Empty list ⇒ `""`. A driver comparing two consecutive fingerprints detects a
-  fix loop that is treading water.
-- **`deferred`** — the count of merged `## Deferred` items §3.5 parked in the backlog. Informational:
-  it never enters `blocking`, so it can never cost a driver an iteration.
-- **`unreviewed`** — the surface keys whose reviewer died twice, `[]` on a complete run. It is
-  **separate from `blocking` on purpose**: `blocking` counts real findings (CRITICAL + security), and
-  faking a number there to force a driver's hand would corrupt the one field the whole contract rests
-  on. A non-empty `unreviewed` means "this run does not cover everything" — a driver treats it as no
-  usable verdict, never as clean, whatever `blocking` says.
-
-## 3.5 Route the deferred findings — the backlog, not the fix loop
-
-Do this on **every** run, before the verdict branch below, and whatever the verdict — a deferred
-finding that is only routed on a `SHIP` is a deferred finding lost on every other verdict, which is
-exactly the leak this step closes. Append each merged `## Deferred` item to
-**`specs/refactor-backlog.md`**, under the `## <domain>` heading of the surface that owns its
-`file:line` (create the file and/or heading if absent — same grouping `/cohorte-audit` writes, so
-`/cohorte-refactor <domain>` picks them up with no extra plumbing):
-
-```
-- [ ] <SEVERITY> · <file:line> · <quality|security|rule|complexity> · <concrete fix> · deferred:$ARGUMENTS
-```
-
-- **Never into the spec's `## Remediation`** — that list is what `/cohorte-fix` re-dispatches, so a
-  deferred item there would re-trigger the very fix round it was deferred out of.
-- **Dedupe before appending:** `grep -F` the backlog for the item's `<file>` + the first words of its
-  problem; already there (from a prior round or an `/cohorte-audit`) ⇒ skip it, don't stack duplicates round
-  after round.
-- Append with `>>` in ONE Bash call; never read the whole backlog into context to rewrite it (it grows
-  with every audit the repo has ever run).
-- Report it as **one line** in chat: `deferred: <n> parked in specs/refactor-backlog.md (<domains>)`.
-
-In chat print ONLY: the verdict, the severity-count table, a one-line digest of each CRITICAL/security
-finding, and `Full report: specs/reports/$ARGUMENTS.md` — never echo the findings body into chat (it
-would sit in this session's history, re-sent every turn). Then:
-
-- **SHIP** → only reachable with `unreviewed` empty (the roll call above forbids it otherwise).
-  **Split on what survived — the DoD tick and the freshness stamp are earned by a clean bill, not
-  by the verdict alone** (the workflow variant enforces the same rule; certifying surviving
-  HIGH/MEDIUM findings for `/cohorte-ship` would ship known defects):
-  - **Nothing above LOW survived** — the clean bill. **Tick the DoD**: in `specs/$ARGUMENTS.md`
-    §`Acceptance criteria / DoD`, flip each `- [ ]` → `- [x]` for the criteria the pipeline has
-    actually verified — spec conformance + `ui_language` copy (this review), tests · lint ·
-    typecheck (a green `/cohorte-build`), mobile-first as far as the code shows it (this review).
-    **Leave `- [ ]` (and say which) any item no stage actually verified** — nothing in the pipeline
-    *runs* the feature, so any criterion that needs the app up (runtime flows, a visual check
-    against the design) stays open unless the human says they exercised it by hand and it held.
-    Ticking is the lead's job (the reviewer is read-only). **Then stamp the freshness gate** so
-    `/cohorte-ship` can refuse to ship code edited after this verdict: compute
-    `BASE=$(git merge-base <default_branch> HEAD)` and write into the spec front-matter
-    `reviewed_base: $BASE` plus `reviewed_digest: $(git diff $BASE -- . ':(exclude)specs/' | sha256sum | cut -c1-16)`
-    (`shasum -a 256` then the first 16 hex chars where there is no `sha256sum` — macOS) — the
-    fingerprint of exactly the source you just reviewed (specs excluded, so DoD ticks + the ship
-    status flip don't trip it). Park the leftover LOWs through §3.5's exact route (the backlog,
-    under their surface's domain heading, tagged `deferred:$ARGUMENTS` — never as open
-    `## Remediation` items, which would re-trigger the fix loop). Then tell the human they can
-    `/cohorte-ship` — **recommend a `/clear` first**, the handoff is fully on disk.
-  - **HIGH or MEDIUM findings survived** — the verdict stays SHIP (they are not blocking), but
-    **no DoD tick and no freshness stamp**. Route them: `/cohorte-fix $ARGUMENTS` for what should
-    be fixed now; MEDIUMs the human *explicitly* chooses to live with go through §3.5's park
-    instead — and once everything left is LOW, apply the clean-bill branch above (tick, stamp,
-    ship). The stamp is the pipeline certifying what ships; it is never written over known
-    HIGH/MEDIUM defects.
-- **REVISE / BLOCK**, or any CRITICAL/HIGH/security finding → tell the human to run
-  **`/cohorte-fix $ARGUMENTS`** — it appends the report to the spec's `## Remediation` and re-dispatches ONLY
-  the surfaces with findings. The full path (`/cohorte-spec` Mode B then `/cohorte-build`) remains for findings that
-  change the contract in ways that ripple into clean surfaces. _The report is staged to
-  `specs/reports/$ARGUMENTS.md`, so you can `/clear` before `/cohorte-fix` — it reads the findings back from
-  disk._