cohorte 2.8.0 → 2.9.0

package/CHANGELOG.md

@@ -7,6 +7,53 @@ short, user-facing, most recent first. One `## <version> — <YYYY-MM-DD>` secti
 > They are history and are deliberately not rewritten — every command gained a `cohorte-` prefix
 > in 2.0.0.
 
+## 2.9.0 — 2026-08-22
+
+- **`/cohorte-intake` — the door before the doors.** Work has always entered the pipeline
+  pre-distilled by a human: a ticket became a `/cohorte-patch` paste, an email became a
+  brainstorm idea, by hand. Intake does the distillation: paste anything that arrives and it
+  triages — bug ⇒ the exact structure patch interviews for (inferred repro steps labeled as
+  such); feature ⇒ a brainstorm seed whose open-questions list is the panel's agenda, with any
+  `_decisions.md` line it contradicts named; noise ⇒ says so and stops, because inventing a
+  spec from noise costs a whole pipeline run downstream. The distillate lands on disk and on
+  the kanban's Ideas column; freezing anything stays the human's move.
+
+- **`/cohorte-retro` — the pipeline learns from its own findings.** Every review leaves
+  structured residue (verdict.json, the specs' Remediation history, the deferred backlog) that
+  nothing ever read back. Retro mines it for patterns — the same finding kind on the same
+  surface across features, a hotspot module, a recurring fix family — and turns each into ONE
+  rule-shaped §Conventions line the human ratifies. Adopted rules re-render the affected
+  surface agents (the conventions slice is baked at render time — a rule without a re-render
+  is one reviewers enforce and implementers never saw) and land in the decisions journal.
+  Findings → rules → the next build never produces the finding: cheaper than any number of
+  review rounds catching it.
+
+- **`/cohorte-fleet` — parallel features get a flight controller.** The worktree isolation
+  existed; the coordination lived in your head. `plan` builds the feature×surface overlap
+  matrix from the specs themselves (contract dependencies ⇒ merge order; same-tree writes ⇒
+  serialize or drop one), provisions the worktrees, and prints one launch line per feature.
+  `status` is one row per feature ending in the single next action. `sync` does the post-merge
+  sweep everyone forgets — rebase every survivor, report conflicts verbatim to their owner's
+  session, and say out loud that a rebase invalidates the freshness stamp. What it will never
+  do is spawn the work headless: that is the retired 2.2.0 driver's grave, and each feature's
+  loop keeps running in its own supervised session.
+
+- **`/cohorte-review --pr <num>` — the pipeline reviews incoming work.** Same reviewers, same
+  report, none of the pipeline's certifications: the PR is fetched into a throwaway worktree
+  (your checkout untouched), reviewed in audit mode (no spec to conform to), and a red
+  preflight makes the mechanical failures the review instead of wasting reviewers on code that
+  doesn't compile. Posting the report as a PR comment always asks first — it is outward-facing
+  — and declining leaves the report on disk as a complete outcome.
+
+- **What a feature costs, finally on the dashboard.** The workflow paths now stamp an
+  approximate `tokens` field into their metrics lines from the runtime's own counter
+  (`budget.spent()` deltas — the figure a conversational lead cannot read), the loop's history
+  carries cost per round, and the dashboard shows `~Nk tok` per feature and per phase. Marks
+  are placed around the review child so build/fix deltas never double-count it; token-less
+  conversational lines aggregate as absent, never as "free".
+
+
+
 ## 2.8.0 — 2026-08-22
 
 - **`/cohorte-loop` is back — as a workflow, which is the whole point.** The 2.2.0 driver was

package/README.md

@@ -301,15 +301,18 @@ so a CLI pinned at an old version cannot quietly re-lay an old core.
 | Command              | Role                                                                                  |
 | -------------------- | ------------------------------------------------------------------------------------- |
 | `/cohorte-init-pipeline`     | Detect stack → interview → generate the profile + agents. Run once per project.       |
+| `/cohorte-intake [paste]`    | Triage anything that arrives (ticket, email, trace, thread) into a `/cohorte-patch` handoff or a brainstorm seed — staged to disk, carded in Ideas. |
 | `/cohorte-brainstorm`        | Interactive persona panel that pressure-tests a feature idea.                         |
 | `/cohorte-spec`              | Freeze the feature spec + contract into `specs/<id>.md` (UI features also get a standalone design brief at `specs/design/<id>.md`). Also applies review returns. |
 | `/cohorte-patch [bug]`       | Bug-fix entry: triage a bug and freeze a ~60-line patch spec (`specs/patch-<slug>.md`) whose regression test replaces the contract. Then the normal `/cohorte-build → review → ship`. |
 | `/cohorte-build <id>`        | Readiness gate on the frozen spec, then the lead authors the contract and dispatches one implementer per surface in parallel. |
-| `/cohorte-review <id>`       | Read-only review agents (one per touched surface, parallel) audit the diff vs the spec; out-of-scope findings go to the refactor backlog. |
+| `/cohorte-review <id>`       | Read-only review agents (one per touched surface, parallel) audit the diff vs the spec; out-of-scope findings go to the refactor backlog. `--pr <num>` reviews an **incoming** GitHub PR in a throwaway worktree and offers to post the report as a comment. |
 | `/cohorte-fix <id>`          | Apply a review report: remediation into the spec, re-dispatch only the surfaces with findings. |
+| `/cohorte-fleet plan\|status\|sync` | Fly several features in parallel: overlap matrix + merge order, one worktree per feature, live status, post-merge rebase sweep. Coordination only — never headless execution. |
 | `/cohorte-ship <id>`         | Release agent commits, pushes, opens the PR; watches CI; proposes worktree teardown.  |
 | `/cohorte-audit [path]`      | Prioritized refactor backlog for existing code.                                       |
 | `/cohorte-refactor <domain>` | Apply the backlog for one surface, TDD-first.                                         |
+| `/cohorte-retro [last n]`    | Mine the accumulated review findings for patterns; ratified ones become §Conventions rules and the surface agents are re-rendered — the next build never produces the finding. |
 | `/cohorte-align-ds`          | Align the code UI kit to the design system (no-op if none configured).                |
 | `/cohorte-update-pipeline`   | Refresh the installed core (global or bundled) to the latest published version.       |
 | `/cohorte-doctor`            | Diagnose the installation (core, agents↔surfaces, hooks, gate, retrieval, worktrees). |

package/core/commands/cohorte-brainstorm.md

@@ -31,7 +31,11 @@ Idea (may be empty): **$ARGUMENTS**
 
 If the idea is empty: when a board is configured and its **Ideas** column has cards, list them (with any
 sub-bullet notes as seed context) and let the human pick one — otherwise ask **"What are we building?"**.
-Either way, wait. If the idea is non-empty, restate it in one line and confirm you've got it.
+Either way, wait. If the idea is non-empty, restate it in one line and confirm you've got it — and
+**if `specs/reports/intake-<idea>.md` exists, read it FIRST**: it is `/cohorte-intake`'s staged seed
+(who is asking with verbatim quotes, goals/non-goals, an open-questions list that is this panel's
+agenda, prior art incl. any `_decisions.md` line the request contradicts). The panel argues against
+the distillate, never against the bare slug.
 
 ## Run the panel
 

package/core/commands/cohorte-fleet.md

@@ -0,0 +1,104 @@
+---
+model: sonnet
+description: Fly several features in parallel — overlap analysis and merge order, one isolated worktree per feature, a live status board, and the post-merge rebase sweep nobody remembers to do.
+argument-hint: plan <id> <id> [...] | status | sync
+---
+
+You are the **fleet controller**. Parallel features already work in this pipeline — isolated
+worktrees, per-feature DBs and ports, one session per worktree — but the coordination between
+them is tribal knowledge: which specs collide, which merges first, and who rebases the
+survivors after each ship. This command owns exactly that coordination, and deliberately
+nothing more.
+
+**What this command will never do: spawn the work headless.** The obvious "cool" version —
+fire a loop per worktree from here — is the 2.2.0 driver's grave: child sessions nobody
+supervises, stalling on prompts nobody sees. Each feature's build/review/loop runs in **its own
+worktree's session**, supervised like any other; the fleet plans, watches and rebases. State
+lives in `specs/reports/fleet.json` (the main checkout's gitignored buffer — not to be confused
+with the dashboard's multi-*project* fleet registry; this file is this repo's multi-*feature*
+flight plan).
+
+> Read `PIPELINE.md` §`pipeline-profile` first: `surfaces` (paths — the overlap analysis keys
+> on them), `contract`, `vcs.default_branch`, and the `isolation` block. _Skip the re-read if
+> already in context and unmodified since._ **`isolation.enabled: false` ⇒ stop at `plan`**:
+> N features in one checkout is a merge-conflict generator with extra steps — name the fix
+> (`/cohorte-init-pipeline` wires isolation) and go no further.
+
+## `plan <id> <id> [...]` — collide, order, provision
+
+1. **Every spec must be `frozen`** (front-matter grep, ~15-line reads — never full specs yet).
+   Anything else (`draft`, `in-review`, missing) ⇒ name it and stop; a fleet of half-frozen
+   specs is N problems flying in formation.
+2. **Overlap analysis** — read each spec's §5 contract entries and §6 surface tasks, then build
+   the matrix *feature × surface*, and flag the two collision classes:
+   - **Contract dependency** — spec B's §5 references shapes spec A introduces ⇒ B ships
+     **after** A, and B's worktree must rebase once A merges (the `sync` mode's job). This is
+     an ordering, not a blocker.
+   - **Same-tree writes** — two specs whose §6 tasks land in the same `surfaces[].path` (worse:
+     the same module). This is where parallel merges bleed; propose either an order (lighter
+     feature first) or — when the overlap is one file both must edit — say plainly that these
+     two should not fly together, and let the human drop one from the fleet.
+3. **Propose the merge order** from those edges (dependencies first, then ascending overlap),
+   show the matrix + order in a compact table, and get the human's go-ahead — the order is a
+   plan they will live with for days.
+4. **Provision worktrees** — for each feature without one: `scripts/new-feature.sh <id>` (the
+   rendered isolation script: worktree + branch + DB + port slot). Relay each script's output
+   line; a script failure stops the plan for that feature, never silently.
+5. **Write `specs/reports/fleet.json`** (overwrite): `{"ts":"<ISO>","order":[...ids in merge
+   order...],"features":{"<id>":{"worktree":"<path>","branch":"<branch>","dependsOn":[...]}}}`.
+6. **Print the launch plan** — one line per feature, in order: the worktree path to open a
+   session in, and the first command to run there (`/cohorte-build <id>`, or "ask for the loop
+   workflow: `{feature: \"<id>\"}`" on a runtime that has it). The human launches them; the
+   fleet does not.
+
+## `status` — one table, no archaeology
+
+Read `fleet.json` (absent ⇒ say `plan` comes first, stop). For each feature, **mechanical reads
+only, redirected — always from THAT feature's worktree**, never the main checkout (each worktree
+carries its own copy of `specs/<id>.md` and `specs/reports/`, and that copy is the one its run
+has been writing): `<worktree>/specs/<id>.md` front-matter `status` · the worktree's
+`specs/reports/<id>.loop.json` (`phase`/`round`/`outcome`) and `<id>.verdict.json`
+(`verdict`/`blocking`) when present · then ONE
+`git -C <worktree> fetch --quiet origin <default_branch> || true` and
+`git -C <worktree> rev-list --count origin/<default_branch>..HEAD` and `..origin/<default_branch>`
+(ahead / **behind** — behind is the number that matters, and against the *remote* ref: the local
+one goes stale the moment a PR merges on the host, which is precisely when status gets asked).
+One row per feature, in merge order:
+
+```
+<id> · <status> · loop: <phase> r<round> | <outcome> · blocking: <n> · ↑<ahead> ↓<behind> · next: <the one action>
+```
+
+`next` is the whole point of the mode: the single action per feature (a command to run in its
+worktree, "waiting on <dep> to merge", "ready to ship — its turn in the order", or "rebase
+needed — run sync"). A worktree registered in `fleet.json` but gone from
+`git worktree list` is reported as such, never silently dropped.
+
+## `sync` — the post-merge sweep
+
+Run after every merge (the human says which feature shipped, or you detect it: spec
+`status: shipped` + branch merged into `<default_branch>`):
+
+1. Drop the shipped feature from `fleet.json` (rewrite, keep order of the rest) — and if its
+   worktree still exists, remind the teardown `/cohorte-ship` proposes:
+   `scripts/remove-feature.sh <id>` (`--drop-db` at the human's call). Never run it unasked.
+2. For each surviving worktree, in merge order — `git -C <worktree> fetch origin
+   <default_branch>` **always**, then decide whether the rebase is THIS session's to run:
+   - **Tree dirty** (`git -C <worktree> status --porcelain` non-empty — the NORMAL mid-flight
+     state: feature work stays uncommitted until `/cohorte-ship`, so `git rebase` would refuse
+     with "unstaged changes" before any conflict even exists) **or a run in flight** (the
+     worktree's `loop.json` has no `outcome`): **do not touch it.** Report the row as
+     `rebase needed — run \`git rebase origin/<default_branch>\` from that worktree's own
+     session` (mutating a branch from outside its session, mid-run, is how work disappears).
+   - **Clean and idle**: rebase it, output redirected to `specs/reports/fleet-sync.txt`. A
+     conflict is reported verbatim and left for its owner (`git rebase --abort` restores) —
+     never resolved, never `--force`-anything from here.
+3. **Say the consequence out loud, per rebased (or rebase-needed) worktree:** the rebase moves
+   every commit, so any `reviewed_base`/`reviewed_digest` in that spec then describes a tree
+   that no longer exists — `/cohorte-ship` will (rightly) refuse until a fresh
+   `/cohorte-review` re-stamps it. A clean rebase is not a re-verdict; the re-review is.
+4. Reprint the `status` table.
+
+In chat, every mode prints its table/plan and nothing else — the matrix evidence and rebase
+logs live in `specs/reports/`. **Recommend a `/clear`** after `plan` (the flight plan is on
+disk; the sessions doing the flying are elsewhere anyway).

package/core/commands/cohorte-intake.md

@@ -0,0 +1,92 @@
+---
+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

@@ -28,7 +28,12 @@ Bug (may be empty): **$ARGUMENTS**
 
 ## 1. Get the bug
 
-If `$ARGUMENTS` is non-empty, restate it in one line and confirm you've got it.
+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

package/core/commands/cohorte-retro.md

@@ -0,0 +1,85 @@
+---
+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

@@ -12,7 +12,8 @@ You are the **lead**. Dispatch the review for feature **$ARGUMENTS**.
 > **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**.
+> 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
@@ -20,6 +21,57 @@ You are the **lead**. Dispatch the review for feature **$ARGUMENTS**.
 > 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

package/core/workflows/loop.js

@@ -211,6 +211,18 @@ const ITEMS = {
   },
 }
 
+// Token accounting — the one thing the conversational path cannot do (a lead cannot
+// read a subagent's token count) and a workflow can: budget.spent() is the runtime's
+// own output-token counter for this turn. Deltas between marks give an approximate
+// per-phase cost; the review CHILD workflow stamps its own review-phase line, so the
+// loop marks AROUND the child to keep build/fix deltas from double-counting it.
+const spent = () => {
+  try {
+    const v = (budget && typeof budget.spent === 'function') ? budget.spent() : 0
+    return Number.isFinite(v) ? v : 0   // a NaN here would poison every metrics JSON downstream
+  } catch { return 0 }
+}
+
 // kanban-move.sh is optional infrastructure — every prompt that runs it defines <core>
 // and tolerates its absence, per SCHEMA.md §Kanban.
 const CORE_DEF = '(<core> = .claude if .claude/pipeline/scripts/kanban-move.sh exists, else ~/.claude — ' +
@@ -403,6 +415,7 @@ const writeState = async ({ label, phaseName, outcome, reason, status: st, kanba
   if (metrics) steps.push(
     `${steps.length + 1}. Append ONE line to ${METRICS_PATH}: ` +
     `{"ts":"<ISO>","feature":"${feature}","phase":"${metrics.phase}","seconds":$(($(date +%s)-${clock || 0})),` +
+    `"tokens":${metrics.tokens || 0},` +
     `"surfaces":${JSON.stringify(metrics.surfaces)}}` + (metrics.buildJson
       ? `\n${steps.length + 2}. Write to specs/reports/${feature}.build.json (overwrite): ` +
         `{"id":"${feature}","phase":"build","ts":"<ISO>","surfaces":${JSON.stringify(metrics.surfaces)},"dead":${JSON.stringify(metrics.dead)}}`
@@ -434,6 +447,7 @@ const close = async (outcome, reason, extra = {}) => {
   return {
     id: feature, outcome, reason, rounds: history.length,
     blocking: history.length ? history[history.length - 1].blocking : null,
+    tokens: spent(),   // approx output tokens for the whole run (runtime counter)
     history, report: `specs/reports/${feature}.md`,
     ...(closed ? {} : { stateWarning: 'the closing state agent died — loop.json/status/kanban may not reflect this outcome' }),
     ...extra,
@@ -446,6 +460,7 @@ const close = async (outcome, reason, extra = {}) => {
 // build.json is stale, absent, or carries dead[], the loop builds (a full re-dispatch —
 // implementers are idempotent against a frozen contract, the same property fix rounds
 // already rely on).
+let mark = spent()
 if (fresh(facts.build) && !(facts.build.dead || []).length) {
   log('build.json is fresh with no dead surfaces — skipping the build phase, entering at review')
   await writeState({ label: 'state:enter', phaseName: 'review', status: 'in-progress', kanban: 'review' })
@@ -463,7 +478,7 @@ if (fresh(facts.build) && !(facts.build.dead || []).length) {
   await writeState({
     label: 'state:built', phaseName: dead.length ? 'build' : 'review',
     metrics: {
-      phase: 'build', buildJson: true, dead,
+      phase: 'build', buildJson: true, dead, tokens: Math.max(0, spent() - mark),
       surfaces: Object.fromEntries(built.map(b => [b.key, b.handoff == null ? 'dead' : 'ok'])),
     },
   })
@@ -479,6 +494,7 @@ if (fresh(facts.build) && !(facts.build.dead || []).length) {
 while (true) {
   phase('Review')
   await writeState({ label: `state:round-${round}`, phaseName: 'review', status: 'in-progress', kanban: 'review' })
+  const roundMark = spent()
   let review
   try {
     review = await workflow('cohorte-review', { feature })
@@ -489,9 +505,16 @@ while (true) {
     })
   }
 
+  // The review child stamps its own review-phase metrics line; marking here keeps the
+  // fix phase's delta clean of it. History carries the round's review cost.
+  mark = spent()
   const verdict = decide(review, lastKey, round, maxRounds)
   if (review && typeof review.blocking === 'number') {
-    history.push({ round, blocking: review.blocking, fingerprint: hash16((review.blockingItems || []).join('\n')) })
+    history.push({
+      round, blocking: review.blocking,
+      fingerprint: hash16((review.blockingItems || []).join('\n')),
+      tokens: Math.max(0, spent() - roundMark),
+    })
   }
 
   if (verdict.outcome === 'ship') {
@@ -587,7 +610,8 @@ while (true) {
   // exactly the batch worth recording (SCHEMA.md §Dead agents), so it lands before
   // the dead-implementers abort, with the dead surfaces named.
   await writeState({ label: `state:fixed-${round}`, phaseName: 'review', metrics: {
-    phase: 'fix', surfaces: Object.fromEntries(fixed.map(f => [f.key, f.handoff == null ? 'dead' : 'ok'])),
+    phase: 'fix', tokens: Math.max(0, spent() - mark),
+    surfaces: Object.fromEntries(fixed.map(f => [f.key, f.handoff == null ? 'dead' : 'ok'])),
   } })
   if (fixDead.length) {
     // Their items stay `- [ ]` — a dead agent never ticks a box (/cohorte-fix §3), and

package/core/workflows/review.js

@@ -42,6 +42,17 @@ const ARGS = (() => {
   }
   return args && typeof args === 'object' ? args : {}
 })()
+// Approximate cost of this run from the runtime's own output-token counter — the one
+// figure the conversational path cannot record (a lead cannot read a subagent's token
+// count; SCHEMA.md §Measuring cost). Sampled at start, delta stamped into the metrics line.
+const spentNow = () => {
+  try {
+    const v = (budget && typeof budget.spent === 'function') ? budget.spent() : 0
+    return Number.isFinite(v) ? v : 0   // a NaN here would poison the metrics JSON downstream
+  } catch { return 0 }
+}
+const spentStart = spentNow()
+
 const isSlug = s => typeof s === 'string' && /^[A-Za-z0-9._-]+$/.test(s)
 const feature = ARGS.feature
 if (!feature) throw new Error('cohorte-review needs args = {feature: "<feature_id>"}')
@@ -387,7 +398,7 @@ const staging = await agent(
   // mark ALL surfaces failed on the dashboard), and dead reviewers logged as "dead"
   // per SCHEMA.md §Dead agents — an incomplete batch is the batch worth recording.
   `3. Append one line to $(dirname "$(git rev-parse --git-common-dir)")/.claude/pipeline-metrics.jsonl: ` +
-  `{"ts":"<ISO now>","feature":"${feature}","phase":"review","seconds":0,"surfaces":{${
+  `{"ts":"<ISO now>","feature":"${feature}","phase":"review","seconds":0,"tokens":${Math.max(0, spentNow() - spentStart)},"surfaces":{${
     results.map(r => `"${r.key}":"${r.report.verdict}:${r.kept.length}"`)
       .concat(unreviewed.map(k => `"${k}":"dead"`)).join(',')}}}\n` +
   // Deferred findings must land in the backlog on EVERY verdict — parked only on a