cohorte 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -3,6 +3,56 @@
 Entries are shown by `/update-pipeline` ("What's new") after a core refresh. Keep them short,
 user-facing, most recent first. One `## <version> — <YYYY-MM-DD>` section per release.
 
+## 1.1.1 — 2026-07-29
+
+- **Fix: pipeline metrics survive worktree teardown.** With `isolation.enabled` the lead session
+  runs inside the feature worktree, so metrics lines landed in the worktree's `.claude/` and were
+  deleted with it — defeating their purpose (cross-feature evidence for surface splits, dashboard
+  history). All phases now append to the **main checkout's** `.claude/pipeline-metrics.jsonl`,
+  resolved from anywhere via `git rev-parse --git-common-dir`; `/doctor` flags a stray metrics file
+  inside a worktree as a stale-core sign.
+
+## 1.1.0 — 2026-07-29
+
+> **The token-economy release.** A full audit of the core (40 verified fixes) cuts the pipeline's
+> consumption by an estimated 40–60% per feature, and the pipeline no longer inherits your session's
+> model for orchestration. Plus: pipeline metrics in the dashboard, CI on the core, and a documented
+> parallel-features workflow.
+
+- **Byte-stable dispatches.** One dispatch template for builds AND fix loops; variable parts
+  (design links, open Remediation items inlined verbatim) sit at the end so repeats hit the prompt
+  cache. The lead never pastes a diff — agents compute their own, scoped to their tree. On fix
+  loops, implementers no longer re-read the spec at all.
+- **Reviewers read hunks, not whole files.** `/review` stages each surface's diff to
+  `specs/reports/<id>.<key>.diff`; tiny re-reviews skip the dispatch entirely (fast path); the
+  merged report is staged to disk with only a verdict summary printed; LOW-only findings defer to
+  the refactor backlog instead of forcing a fix cycle.
+- **`/smoke` is now an agent.** A new pinned `smoke` agent runs infra/curl/UI checks so logs,
+  response bodies, and screenshots never enter (and re-bill in) your session's history.
+- **Model pins everywhere.** The `review` agent and the 10 mechanical commands
+  (build/review/fix/smoke/ship/audit/refactor/doctor/align-ds/update-pipeline) are pinned
+  `model: sonnet` — orchestration runs on Sonnet even if your session runs Opus/Fable. `/doctor`
+  checks agent AND command pins; the profile template's frontend example no longer suggests
+  `inherit`.
+- **Leaner outputs.** Handoff + review-report formats are inlined in the agent bodies (no template
+  probe), templates de-boilerplated, the design brief is authored once to `specs/design/<id>.md`,
+  metrics collapsed to one JSONL line per phase, and every command's closing now *recommends*
+  `/clear` (all state is on disk by design).
+- **Pipeline metrics in the dashboard.** New per-project panel: wall-clock per phase, fix rounds,
+  and per-surface results from `.claude/pipeline-metrics.jsonl` — see which phase/surface dominates
+  before tuning anything.
+- **`kanban-move.sh`.** Card moves (move/create/dedupe/`--pr`) now run as a script outside the
+  agent's context; installed to `<core>/pipeline/scripts/`, with the manual grep-based op as
+  fallback.
+- **Spec size budget.** `/spec` targets ≤~300 lines and proposes a feature split beyond that —
+  every spec line is paid `surfaces × dispatches` times.
+- **Parallel features documented.** README: one session per feature, worktree isolation as the
+  safety mechanism, ship-then-rebase rule; `/doctor` prints the live slot table when ≥2 features
+  run in parallel.
+- **CI on the core.** `scripts/validate-core.mjs` + GitHub Actions: frontmatter/pin invariants,
+  render placeholders, cross-references, installer coverage (would have caught the smoke-agent
+  install gap this release also fixes), plus an end-to-end install dry-run.
+
 ## 1.0.0 — 2026-07-28
 
 > **Renamed `thebidouille-agents` → `cohorte`** and cut the first stable release. The npm package,

package/README.md

@@ -237,6 +237,38 @@ lever: long sessions (>150k) are expensive even when cached. Each command tells
 safe to clear. If you'd rather stay in one session, `/compact` mid-task does the lighter version. (Claude
 can't fire `/clear` itself — it's a client-side command; the pipeline just makes it always safe to type.)
 
+### Run features in parallel — one session per feature
+
+With `isolation.enabled`, every feature already gets its own worktree, ports, and database
+(`scripts/new-feature.sh <id>` — slots tracked in `.worktrees/slots.tsv`). That isolation is exactly
+what makes **parallel features** safe, and it's the real throughput multiplier when you're rate-limited:
+while feature A's `/build` runs its agents (minutes of wall-clock you'd otherwise spend waiting), a
+second Claude Code session can `/spec` or `/review` feature B.
+
+The pattern:
+
+```
+session 1 (main checkout):   /spec feat-a → /build feat-a  (agents run…)
+session 2 (main checkout):   /spec feat-b → /build feat-b  (agents run…)
+session 1:                   /smoke feat-a → /review feat-a → /ship feat-a
+session 2:                   /smoke feat-b → …
+```
+
+Rules that make it safe:
+
+- **One feature per session.** All lead-side state is keyed by feature id on disk
+  (`specs/<id>.md`, `<contract.path>/<id>.*`, `specs/reports/<id>*`), so sessions never share state —
+  but a single session interleaving two features accumulates both in its context, paying for both.
+- **Disjoint surfaces per feature are guaranteed** (each worktree is a full checkout), and each
+  feature's DB/ports come from its slot — `/smoke` runs collide on neither.
+- **The contract package is the one shared tree.** Two features editing
+  `<contract.path>/<their-own-id>.<ext>` never conflict (one file per feature); merge order only
+  matters if a later feature *imports* an earlier one's contract — ship the dependency first.
+- `/ship` one at a time: it commits from the feature's branch and the freshness gate keeps a stale
+  verdict from shipping; after each merge, rebase the other live worktrees (`git rebase main`) so
+  their eventual reviews diff against reality.
+- `/doctor` check 6 shows the live slot table (feature ↔ worktree ↔ ports) when you lose track.
+
 ## License
 
 [AGPL-3.0](LICENSE). Free to use, including commercially — but if you modify it and distribute it

package/core/agents/implementer.template.md

@@ -12,11 +12,8 @@ shared surface is the frozen contract and the spec.
 > **First action, always:** read `PIPELINE.md` — the whole machine block (§`pipeline-profile`; it is the
 > shared contract: surfaces, contract, gate). Then in §Conventions read ONLY the `### Shared` stanza and
 > your own `### Surface: <your key>` stanza (Grep for your key; the other surfaces' stanzas are another
-> agent's rules — skip them), plus §Testing. You have no memory; re-read your slice + the spec every
-> dispatch — but never load the other surfaces' convention prose.
->
-> The handoff template path (`.claude/templates/agent-handoff.md`) resolves to
-> `~/.claude/templates/agent-handoff.md` when the core is installed globally — read whichever exists.
+> agent's rules — skip them), plus §Testing. You have no memory; re-read your slice every dispatch —
+> but never load the other surfaces' convention prose.
 
 ## You own
 
@@ -34,13 +31,16 @@ shared surface is the frozen contract and the spec.
 
 ## Your inputs (supplied at dispatch — you have no memory)
 
-1. The spec path `specs/<id>.md` — on a **first build**, read it fully (contract §5, your surface's
-   tasks, acceptance §9). On a **fix loop**, read §5 (the contract shapes) + your surface's tasks and
-   only the **open** `- [ ]` items under `## Remediation` — skip the already-fixed `- [x]` history.
+1. The spec path `specs/<id>.md` — on a **first build** (your dispatch's Remediation slot says
+   `none`), read it fully (contract §5, your surface's tasks, acceptance §9). On a **fix loop**, do
+   NOT re-read the spec: your dispatch carries your open Remediation items verbatim, and the contract
+   file (input 2) is your only source of shapes — open the spec only if a finding explicitly cites a
+   spec section, or if `contract.enabled` is false in `PIPELINE.md` (then spec §5 prose IS the contract).
 2. The frozen contract for this feature (`<contract.path>/<id>.<contract.ext>`) — the shapes you build against.
-3. On a fix loop: the review findings are **self-contained** (`file:line` · concrete fix). Work from the
-   open `## Remediation` items + the current diff; read only the files those findings name — don't
-   re-explore your whole tree or re-read spec sections that didn't change. Fix exactly what's flagged.
+3. On a fix loop: the findings in your dispatch are **self-contained** (`file:line` · concrete fix).
+   Read only the files they name — don't re-explore your whole tree. Need the current state of your
+   work? Compute it yourself: `git diff <default_branch> -- <your surface path>` (never expect a diff
+   in your dispatch). Fix exactly what's flagged.
    <SURFACE_DESIGN_INPUT>
 
 ## How you read code — retrieval first
@@ -68,7 +68,30 @@ tools are unavailable or come up empty.
 Your surface's `test_cmd` green, `lint_cmd` clean, `typecheck_cmd` clean for your code, and every part
 of the contract your surface implements matches the spec exactly. User-facing copy in `ui_language`.
 
-## Your return — use `.claude/templates/agent-handoff.md`
+## Your return — the HANDOFF, exactly this shape
 
-Report: files touched, migrations added (if any), how to run your tests, any contract mismatch or
-assumption, and remaining TODOs. Your final message **is** the handoff (read by the lead, not a human chat).
+Your final message **is** the handoff (read by the lead, not a human chat). Keep it tight — the lead
+only acts on mismatches, test failures, remediation ticks, and TODOs; never list files one by one
+(the lead has `git diff --stat`):
+
+```
+# HANDOFF — <surface> · <feature_id>
+
+## Summary
+<2–4 lines: what you built and the approach>
+
+## Migrations / schema (only if any)
+- <name> — <additive change>
+
+## Tests
+- Run: <your test_cmd> · result: <pass/fail + counts>
+
+## Contract mismatches / assumptions
+<none, or describe — NEVER edit the contract; report here instead>
+
+## Remediation addressed (fix loops only)
+- <items fixed, by file:line>
+
+## TODO / not done
+- <deferred, blocked, or out of scope — or "none">
+```

package/core/agents/release.md

@@ -35,7 +35,7 @@ committing, pushing, and opening the PR. You do **not** write features.
    branch). Confirm no `.env`/secret files staged.
 2. Stage the feature changes and write **conventional commit(s)**: `feat(<scope>): …` / `fix(<scope>): …`,
    body summarizing what shipped, referencing `feature_id`. Scope from the domain. End the commit body with:
-   `Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>`
+   `Co-Authored-By: Claude <noreply@anthropic.com>`
 3. `git push -u origin <branch>` (plain push, no force).
 4. Open the PR against `vcs.default_branch`:
    - `vcs.host: github` and `gh` available → `gh pr create --base <default_branch> --head <branch>` with a

package/core/agents/review.md

@@ -2,6 +2,7 @@
 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.
 tools: Read, Grep, Glob, mcp__serena
+model: sonnet
 ---
 
 You are the **review** agent for one feature. You are **read-only by construction** — no Write, Edit,
@@ -16,18 +17,19 @@ be precise and self-contained.
 ## Your inputs (supplied at dispatch — you have no memory)
 
 1. The spec path `specs/<id>.md` — the source of truth (contract §5, tasks, acceptance §9).
-2. The diff to review — **your dispatch names your scope**: the whole branch diff, or (on
-   multi-surface diffs, where `/review` runs one reviewer per surface in parallel) a single
-   surface's changed files + the lead's contract file. Stay in scope; the lead merges the
-   per-surface reports and derives the global verdict. Contract conformance is checked per side
-   against the same frozen contract file, so you never need the other surfaces' code.
-3. `PIPELINE.md` (conventions) and `CLAUDE.md` (any project notes).
-
-## How you read — diff hunks first, retrieval second
-
-- Review the **diff hunks + their immediate context**, not whole files. Open a full file only when
-  a finding demands it (tracing a call path, checking an auth middleware chain, verifying an
-  import boundary) — never as a default.
+2. The diff to review — **your dispatch names your scope** and points at a **staged diff file**
+   (`specs/reports/<id>.<surface>.diff`) holding exactly your surface's hunks (plus any shared
+   remainder the lead attached). Stay in scope; the lead merges the per-surface reports and derives
+   the global verdict. Contract conformance is checked per side against the same frozen contract
+   file, so you never need the other surfaces' code.
+3. `PIPELINE.md` (conventions) — nothing else; project rules live in its §Conventions.
+
+## How you read — the staged diff first, retrieval second
+
+- **Read the staged diff file from your dispatch FIRST** — it is the review target. Review the hunks
+  + their immediate context, not whole files. Open a full source file only when a finding demands it
+  (tracing a call path, checking an auth middleware chain, verifying an import boundary) — never as
+  a default.
 - If `retrieval.provider` in `PIPELINE.md` is not `none`, its MCP tools are in your toolset —
   prefer them over Grep/Glob + whole-file Reads: locate code by symbol, read only the definitions
   you need. Fall back to Grep/Read when they are unavailable or come up empty.
@@ -68,8 +70,9 @@ Concrete, high-signal traps to grep for per language. A surface's language comes
 
 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
-entry point / module with **no test**), and the lint/format/type debt the lead pasted in. Emit a
-**prioritized refactor backlog grouped by domain** instead of a SHIP/REVISE/BLOCK verdict.
+entry point / module with **no test**), and the lint/format/type debt staged at the file your
+dispatch names (`specs/reports/audit-gates.txt`). Emit a **prioritized refactor backlog grouped by
+domain** (same finding-line shape) instead of a SHIP/REVISE/BLOCK verdict.
 
 ## Severity & verdict
 
@@ -78,8 +81,31 @@ entry point / module with **no test**), and the lint/format/type debt the lead p
 - Any **security vulnerability** ⇒ verdict **BLOCK**.
 - No CRITICAL and no security issue ⇒ verdict **SHIP**.
 
-## Your return — fill `.claude/templates/review-feedback.md` EXACTLY
+## Your return — the REVIEW REPORT, exactly this shape
 
 Every finding must be **self-sufficient for a stateless agent**: `file:line` · severity ·
-`spec-violation | quality | security` · one concrete suggested fix. The human pastes your report into
-`/spec`, which appends it to the spec's `## Remediation`. Your final message **is** the report.
+`spec-violation | quality | security` · one concrete suggested fix — it gets appended verbatim to the
+spec's `## Remediation`. Your final message **is** the report. Emit nothing outside this shape — no
+restated rules, no "verified clean" lists:
+
+```
+# REVIEW REPORT
+feature_id: <feature_id> · scope: <surface.key>
+
+| Severity | Count |
+| -------- | ----- |
+| CRITICAL | 0     |
+| HIGH     | 0     |
+| MEDIUM   | 0     |
+| LOW      | 0     |
+
+Verdict: <SHIP | REVISE | BLOCK>
+
+## Findings
+
+- **[<SEVERITY>]** `<file>:<line>` · <spec-violation|quality|security> · <problem> → **Fix:** <concrete change>
+(order by severity; "None." if none)
+
+## Notes
+(ONLY the RBAC / mobile-first assessment when the profile enables them; omit the section otherwise)
+```

package/core/agents/smoke.md

@@ -0,0 +1,61 @@
+---
+name: smoke
+description: Executes the end-to-end smoke run for one feature in its worktree — infra up, migrations, contract endpoints, key UI flows, visual check vs design — then stages the SMOKE REPORT. Dispatched by /smoke. Observes honestly, never fixes anything.
+tools: Read, Write, Grep, Glob, Bash, DesignSync
+model: sonnet
+---
+
+You are the **smoke** agent for one feature. You actually run the built feature — `/review` audits
+code read-only; nobody has executed it yet. You verify it *works*; you never fix it (failures go
+through `/fix`). Observe honestly: report what happened, not what should have happened.
+
+> **First action, always:** read `PIPELINE.md` §`pipeline-profile`: `commands` (migrate/dev),
+> `isolation` (worktree, slot ports, db), `contract`, `design`, `surfaces` — then the spec
+> `specs/<id>.md` (§5 contract, §8 flows, §9 acceptance).
+
+## Your inputs (supplied at dispatch — you have no memory)
+
+1. The feature id and spec path `specs/<id>.md`.
+2. The contract path `<contract.path>/<id>.<ext>`.
+3. The checkout to work in: the worktree path + slot ports/db, or the main checkout on the feature branch.
+
+## Keep your own context lean
+
+Redirect every bulky output to a file and inspect it with `grep`/`jq` — never print full curl bodies,
+server logs, or poll loops into your transcript. `curl -s … -o /tmp/resp.json -w '%{http_code}'` then
+assert on the pieces you need.
+
+## 1. Bring the feature up
+
+- Work in the checkout your dispatch names. Infra as needed: the compose stack if one is declared
+  (the gate will ask — that's expected), then `commands.migrate`, then `commands.dev` **in the
+  background**. Wait for ready (poll the ports), don't assume.
+
+## 2. Exercise the contract (the real server, not the tests)
+
+- Hit a representative set of spec §5 endpoints with `curl`: every route domain, every auth level,
+  at least one error case per class (validation `422`, unauthenticated `401`, wrong-role `403`,
+  conflict `409`). Compare status + response envelope against the contract.
+- If `rbac.enabled`: verify at least one denial per role boundary the spec declares.
+- A mismatch is a FAIL entry with the exact command, expected, and actual — precise enough for a
+  stateless `/fix` agent.
+
+## 3. Exercise the UI (only if a touched surface has `uses_design`)
+
+- Drive the spec §8 flows against the running app, **mobile viewport first** (375px), then desktop.
+- If a browser/screenshot tool is available (a project driver, playwright, an agent browser), capture
+  each §8 screen and compare against the feature's design pages: each `design_files` entry is a full
+  `https://claude.ai/design/p/<projectId>?file=<file>` link — extract its `<projectId>` (the `/p/…`
+  segment) + `<file>` (the `?file=` query) and fetch read-only via `DesignSync get_file(<projectId>,
+  <file>)`. Compare layout, states (empty/loading/error/suppressed…), copy language. Note deviations.
+- No browser tooling available ⇒ **say so and skip the visual diff** — never claim a visual check
+  you didn't perform.
+
+## 4. Stage the SMOKE REPORT, tear down, return
+
+- One line per check: ✅/❌ · what was exercised · (on ❌) command → expected vs actual.
+- **Write the full report to `specs/reports/<id>.md`** (overwrite) — the same gitignored buffer
+  `/review` uses, so a `/fix` after a `/clear` still has the failures.
+- Tear down what you started (kill the dev server); leave shared infra as you found it.
+- **Your return to the lead is ONLY:** the verdict line (`PASS` / `FAIL`), the ❌ lines verbatim (if
+  any), and `Full report: specs/reports/<id>.md`. No logs, no bodies, no screenshots.

package/core/commands/align-ds.md

@@ -1,4 +1,5 @@
 ---
+model: sonnet
 description: Align the code UI kit to the design system (design → code). Diffs the live design system against the committed snapshot and applies the deltas. No-op if the project has no design system.
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, DesignSync
 ---

package/core/commands/audit.md

@@ -1,4 +1,5 @@
 ---
+model: sonnet
 description: Audit the existing codebase (or a domain) against PIPELINE.md conventions + TDD coverage; produce a prioritized refactor backlog.
 argument-hint: [path or domain, default = whole repo]
 ---
@@ -10,17 +11,20 @@ analyze only — no fixes (those go through `/refactor`).
 
 ## 1. Mechanical gates (you run these — Bash)
 
-Run the profile's repo-wide checks and capture the `file:line` of every failure:
-`commands.format` in check mode (e.g. `prettier --check .` / `ruff format --check`), `commands.lint`,
-`commands.typecheck`, `commands.test`.
+Run the profile's checks **scoped to `$ARGUMENTS`** when a path/domain is given (lint/format/typecheck
+on that path, tests via that surface's `test_cmd`); repo-wide only for the default whole-repo audit.
+Redirect each command's output into `specs/reports/audit-gates.txt` in the same call
+(`cmd > specs/reports/audit-gates.txt 2>&1`) so the bulk never sits in your history, then grep it for
+the `file:line` of every failure: `commands.format` in check mode (e.g. `prettier --check .` /
+`ruff format --check`), `commands.lint`, `commands.typecheck`, `commands.test`.
 
 ## 2. Convention + TDD audit (dispatch `review` in audit mode)
 
 Dispatch `review` (read-only): "Audit `$ARGUMENTS` against `PIPELINE.md` (no spec — **audit mode**).
 Check conventions (§Conventions per surface), TDD coverage (untested entry points / modules per surface),
 and — if the profile enables them — mobile-first + design-system usage. Mechanical findings from the
-gates: «paste §1 output». Emit a prioritized refactor backlog (review-feedback format), grouped by
-domain (one group per surface + shared)."
+gates: read `specs/reports/audit-gates.txt`. Emit a prioritized refactor backlog (finding-line format
+from your instructions), grouped by domain (one group per surface + shared)."
 
 ## 3. Write the backlog
 

package/core/commands/brainstorm.md

@@ -4,8 +4,9 @@ argument-hint: [one-line idea (optional)]
 ---
 
 You are facilitating an **interactive brainstorm** for a new feature. This runs in the main thread — a
-back-and-forth with the human, NOT a one-shot. Do not write any files — the ONE exception is moving this
-feature's kanban card at Finish, when a board is configured.
+back-and-forth with the human, NOT a one-shot. Do not write any files — the TWO exceptions are staging
+the return at Finish (`specs/reports/<feature_id>-brainstorm.md`) and moving this feature's kanban card
+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.
@@ -39,8 +40,10 @@ screens, risks, and what's explicitly out.
 ## Finish
 
 When the human is satisfied, produce the **brainstorm return** by filling
-`.claude/templates/brainstorm-return.md` and printing it in a copy-paste block. Tell them to paste it
-into `/spec`.
+`.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`
+— **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
 downstream. If a board is configured, **move** the card into the **Brainstorm** column tagged

package/core/commands/build.md

@@ -1,4 +1,5 @@
 ---
+model: sonnet
 description: Author the contract from the frozen spec, then dispatch one implementer agent per surface in parallel.
 argument-hint: <feature_id>
 ---
@@ -6,18 +7,23 @@ argument-hint: <feature_id>
 You are the **lead**. Build feature **$ARGUMENTS** from its frozen spec.
 
 > Read `PIPELINE.md` §`pipeline-profile` first: the `surfaces` list (how many implementers to
-> dispatch + their agent names), `contract` (mechanism + path), and the `design` flag.
->
-> Template paths below (`.claude/templates/…`) resolve to `~/.claude/templates/…` when the core is
-> installed globally — read whichever exists.
+> dispatch + their agent names), `contract` (mechanism + path), and the `design` flag. _Skip the
+> re-read if it's already in your context this session and unmodified since._
 >
 > **Kanban** (SCHEMA.md §Kanban): once §1 confirms the frozen spec, move card `#$ARGUMENTS` →
 > **Building**. No-op silently if no board is configured.
 
 ## 1. Load & check
 
-- Read `specs/$ARGUMENTS.md`. If missing or `status` not `frozen`/`in-review`, stop — tell the human to
-  run `/spec` first.
+- 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
+  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
+  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).
 - **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
@@ -26,7 +32,8 @@ You are the **lead**. Build feature **$ARGUMENTS** from its frozen spec.
   survives a design-system rebuild (a new DS ⇒ just paste the new links, no profile change). _Legacy bare
   file names still resolve against the optional `design.design_project` fallback, but new specs use links._
   Skip if the feature is backend-only / no UI.
-- If this is a fix loop (`## Remediation` has unchecked items), note them — they go to every agent.
+- If this is a fix loop (`## Remediation` has unchecked items), map each open item to a surface by its
+  `file:line` path — each agent gets ONLY its own surface's items, inlined in its dispatch (§3).
 
 ## 1.5 Reconcile surfaces — auto-grow / specialize agents
 
@@ -56,8 +63,9 @@ _Only if `contract.enabled`._ From §5 of the spec, write/update the feature's c
 types for `shared-types-zod`). Export it from `contract.index` if set. This is the ONLY file the agents
 share; they import it read-only and must not edit it. If `contract.enabled` is false, the spec prose is
 the sync channel — say so and skip. **Postcondition (if `contract.enabled`):**
-`test -f <contract.path>/$ARGUMENTS.<contract.ext>` — the contract file must exist before you dispatch
-§3, or the stateless agents have nothing to build against.
+`test -f <contract.path>/$ARGUMENTS.<contract.ext> && date +%s` — the contract file must exist before
+you dispatch §3, or the stateless agents have nothing to build against (the epoch output is §4's
+wall-clock start — no separate timing call).
 
 ## 3. Dispatch one implementer per surface — IN PARALLEL
 
@@ -65,27 +73,35 @@ Spawn every surface's agent in a **single message** (one Task call each) so they
 NEVER serially: build wall-clock must be the slowest surface, not the sum. Use
 the reconciled `surfaces` list from §1.5 (existing + any just-rendered). Give EACH only what a stateless
 agent needs — re-supply everything every time, as **exact file paths** (spec, contract, the surface's
-tree), never "find the relevant files". Keep the dispatch prompt **structurally identical across
-dispatches and fix loops** (same template below, only the variable parts change) so repeated dispatches
-hit the prompt cache. Note the epoch (`date +%s`) just before dispatching — §4's metrics line needs
-the batch wall-clock. For each surface in `surfaces`:
+tree), never "find the relevant files". Keep the dispatch prompt **byte-identical across dispatches
+and fix loops** except the two variable slots, which sit at the END of the prompt so every repeat hits
+the prompt-cache prefix. Never paste a diff into a dispatch — the agent computes its own, scoped to its
+tree. For each surface in `surfaces`:
 
 > `subagent_type: <surface.agent>` — "Implement the **<surface.key>** surface for feature `$ARGUMENTS`.
 > Read `PIPELINE.md` first. Spec: `specs/$ARGUMENTS.md`. Contract: `<contract.path>/$ARGUMENTS.<ext>`
-> (import read-only). Work test-first. Touch only `<surface.path>`. [If a `uses_design` surface: design
-> > files = the spec's `design_files` links — each `https://claude.ai/design/p/<projectId>?file=<file>`
-> > carries its own project + page, fetch read-only via `DesignSync get_file(<projectId>, <file>)`;
-> > build mobile-first.] [If fix loop: address the
-> > `## Remediation` items; current diff: …]. Return the handoff per `.claude/templates/agent-handoff.md`."
+> (import read-only). Work test-first. Touch only `<surface.path>`. Need the current state of your
+> tree? Compute it yourself: `git diff <default_branch> -- <surface.path>`. Return the handoff in the
+> format your agent instructions define. Design files: <the spec's `design_files` links — each
+> `https://claude.ai/design/p/<projectId>?file=<file>` carries its own project + page, fetch read-only
+> 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`>."
 
 ## 4. Integrate
 
-When all return, summarize their handoffs and flag any contract mismatch reported. Append **one line
-per dispatched agent** to `.claude/pipeline-metrics.jsonl` (create it if absent; it must be
-gitignored):
-`{"ts":"<ISO date>","feature":"$ARGUMENTS","phase":"build","surface":"<key>","seconds":<batch wall-clock>,"result":"ok|error"}`
+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.
+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",…}}`
 — this is the evidence SCHEMA.md §Specialization asks for before splitting a surface.
 Then tell the human: run `/smoke $ARGUMENTS` to exercise the feature end-to-end (or test by hand),
 then `/review $ARGUMENTS`. Do not run the app or migrations yourself here — `/smoke` is the
-sanctioned path for that. _The spec, contract and diff are all on disk — `/clear` before `/smoke`
-is safe._
+sanctioned path for that. **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

@@ -1,4 +1,5 @@
 ---
+model: sonnet
 description: Diagnose the pipeline installation — core version, pointer, agents↔surfaces, hooks, gate, retrieval, design, isolation — and print the exact fix for each failure.
 ---
 
@@ -22,7 +23,17 @@ fix only with the human's go-ahead (or hand them the command).
    `surfaces[].agent` has its `.claude/agents/<agent>.md` and every agent file has its `surfaces[]`
    entry — **no orphans either way** (SCHEMA.md rule). Each rendered agent's frontmatter `tools`
    matches its surface's `tools` (incl. `DesignSync` iff `uses_design`, retrieval MCP tools iff
-   `retrieval.provider` ≠ `none`).
+   `retrieval.provider` ≠ `none`). **Model pins:** each rendered agent's frontmatter `model` matches
+   its `surfaces[].model` — ❌ if missing, mismatched, or a literal `<SURFACE_MODEL>` placeholder
+   (all three silently fall back to inheriting the lead session's model — often Opus — on every
+   dispatch); ⚠️ any `inherit` with the note that it bills at the lead's tier. The generic agents
+   (`review.md`, `release.md`, `smoke.md` — repo or `~/.claude/agents/`) must each carry their
+   `model:` line too (sonnet/haiku/sonnet). **Command pins:** every mechanical command file
+   (`build`, `review`, `fix`, `smoke`, `ship`, `audit`, `refactor`, `doctor`, `align-ds`,
+   `update-pipeline` — in `.claude/commands/` or `~/.claude/commands/`) carries `model: sonnet` in
+   its frontmatter — ⚠️ if missing (the lead's orchestration turn then bills at the session model,
+   e.g. Opus/Fable). `brainstorm`, `spec`, and `init-pipeline` are intentionally unpinned
+   (interactive — they inherit the session model).
 3. **Hooks & gate.** `.claude/gate-config.json` exists and mirrors the profile's `gate` block
    (regenerate if drifted). The PreToolUse gate hook is registered **once** for the install mode
    (bundled: repo `settings.json`; global: `~/.claude/settings.json` — flag double registration,
@@ -39,9 +50,15 @@ fix only with the human's go-ahead (or hand them the command).
    rendered (no `__TOKEN__` placeholders left). `.worktrees/slots.tsv` coherent with
    `git worktree list` — flag **stale slots** (registered but no worktree) and **zombie worktrees**
    (worktree but no slot / spec already `shipped`) ⇒ suggest `scripts/remove-feature.sh <id>`.
+   When ≥2 slots are live, print the parallel-feature table (feature · worktree · ports · db ·
+   branch behind main by N commits) — a worktree far behind main means its next review will diff
+   against stale code ⇒ suggest rebasing it.
 7. **Specs & metrics.** Every `specs/*.md` front-matter `status` is a valid stage; `shipped` specs
    with a live worktree flagged (see 6). `.claude/pipeline-metrics.jsonl` and `specs/reports/` (the
-   `/review`·`/smoke` report buffer that lets a `/fix` survive a `/clear`) are gitignored.
+   `/review`·`/smoke` report buffer that lets a `/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.
 
 ## Report
 

package/core/commands/fix.md

@@ -1,4 +1,5 @@
 ---
+model: sonnet
 description: Apply a REVIEW REPORT (or SMOKE failures) — append it to the spec's Remediation, then re-dispatch ONLY the surfaces that have findings.
 argument-hint: <feature_id> [paste REVIEW REPORT]
 ---
@@ -8,9 +9,7 @@ You are the **lead**. Run the fix loop for feature **$ARGUMENTS** — the scoped
 that change the *contract*; `/fix` is for everything else.
 
 > Read `PIPELINE.md` §`pipeline-profile` first: `surfaces` (paths + agent names) and `contract`.
->
-> Template paths below (`.claude/templates/…`) resolve to `~/.claude/templates/…` when the core is
-> installed globally — read whichever exists.
+> _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.
@@ -23,7 +22,9 @@ that change the *contract*; `/fix` is for everything else.
   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
   dated/numbered subheading): `- [ ] <severity> · <file:line> · <type> · <concrete fix>`. Set
-  `status: in-review`.
+  `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
@@ -36,8 +37,12 @@ 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
-  fix-loop dispatch template from `/build` §3 (spec, contract read-only, "address the `## Remediation`
-  items", current diff). Surfaces without findings are NOT re-dispatched — that is the point.
+  dispatch template from `/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
+  non-visual (no DesignSync re-fetch for a type fix). Surfaces without findings are NOT re-dispatched —
+  that is the point.
 
 ## 3. Integrate & check off what's fixed
 
@@ -54,9 +59,10 @@ When the agents return:
   fixed`) — the audit fact survives, but the per-item bulk stops growing the spec that every agent
   re-reads each loop. Keep any round with ≥1 still-open `- [ ]` item fully expanded (§2's skip logic
   needs those checkboxes).
-- Summarize the handoffs and append one metrics line per dispatched agent to
-  `.claude/pipeline-metrics.jsonl` (see `/build` §4).
+- 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"`).
 - Tell the human: re-run `/smoke` if the failures were runtime ones, and `/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). _All state (spec, checkboxes, staged report) is on
-  disk, so `/clear` before the next command is safe._
+  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.