cohorte 2.1.0 → 2.3.0

package/core/commands/cohorte-build.md

@@ -11,8 +11,7 @@ You are the **lead**. Build feature **$ARGUMENTS** from its frozen spec.
 > re-read if it's already in your context this session and unmodified since._
 >
 > **Kanban** (SCHEMA.md §Kanban): once §1 confirms the frozen spec, run
-> `<core>/pipeline/scripts/kanban-move.sh auto $ARGUMENTS building` (`<core>` = `.claude` bundled /
-> `~/.claude` global — probe with `test -x`). `auto` resolves the board from the config itself and
+> `<core>/pipeline/scripts/kanban-move.sh auto $ARGUMENTS building`. `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**. That inference, not a missing board, is what used to freeze
 > cards mid-pipeline.
@@ -20,13 +19,18 @@ You are the **lead**. Build feature **$ARGUMENTS** from its frozen spec.
 ## 1. Load & check
 
 - Check the spec front-matter FIRST — `grep '^status:' specs/$ARGUMENTS.md` (or Read with a ~15-line
-  limit) — before any full read. Buildable statuses are `frozen`, `in-review` and `in-progress` (the
-  last one means a `/cohorte-loop` is or was driving this spec — SCHEMA.md §Spec status). `blocked` means a
-  loop gave up here: say so, and route by the spec's `## Remediation` — open items ⇒ `/cohorte-fix`, none ⇒
+  limit) — before any full read. Buildable statuses are `frozen`, `in-review` and `in-progress`
+  (SCHEMA.md §Spec status). `blocked` means a previous round gave up here: say so, and route by the
+  spec's `## Remediation` — open items ⇒ `/cohorte-fix`, none ⇒
   continue this build. Anything else (`draft`, missing, `shipped`) ⇒ stop and tell the human to run
   `/cohorte-spec` first. Only then read the body, selectively: front-matter, §5 contract, the surface
   task sections, and `## Remediation` (fall back to a full read if the spec doesn't follow the
   template's headings).
+- **`kind: patch` in the front-matter ⇒ this is a bug fix** frozen by `/cohorte-patch`, and it is
+  built by this command like any other spec, with two differences called out where they apply: §1.6
+  judges it against its regression test instead of a contract, and §2 authors no contract unless §5
+  carries a delta. Everything else — surface mapping, parallel dispatch, roll call, metrics — is
+  identical, and `kind` absent means feature, so nothing changes for existing specs.
 - **Route check** — if `## Remediation` has open `- [ ]` items and none requires a contract change,
   stop and tell the human to run `/cohorte-fix $ARGUMENTS` instead: it re-dispatches only the surfaces with
   findings. A full build with open items is only right when the contract change ripples into clean
@@ -58,13 +62,13 @@ Map every area the spec touches (§5 contract + each surface's tasks + touched p
 For each surface to add: infer its `key`, `path`, `label`, `agent`, `tools`, `model`, `*_cmd`s, and
 `uses_design` (mirror a sibling surface), show the human a one-line proposal, and on go-ahead **render it now** per
 SCHEMA.md §"Rendering / reconciling a surface agent" — write the `surfaces[]` entry + §Conventions/§Testing
-stanza into `PIPELINE.md`, render `.claude/agents/<agent>.md` from the implementer template, applying the
+stanza into `PIPELINE.md`, render `<agents>/<agent>.md` from the implementer template, applying the
 shared-code rule (shared trees get a single-owner surface; cross-slice shapes go through the contract).
 This is the automatic path: you don't send the human back to `/cohorte-init-pipeline`. If nothing new is needed,
 say so and continue. Dispatch (§3) then covers the reconciled surface list.
 
 **Adding or splitting a surface is an architectural decision** — append ONE line for it to
-`specs/_decisions.md` §Live (SCHEMA.md §Decisions; create from `.claude/templates/decisions.template.md`
+`specs/_decisions.md` §Live (SCHEMA.md §Decisions; create from `<core>/templates/decisions.template.md`
 if absent), area `surfaces`, e.g.
 `- <date> · surfaces · <key> owns <path>, single owner of <what> — because <the boundary reason> · $ARGUMENTS`.
 One `>>` in the Bash call you're already making. Nothing added ⇒ nothing to append.
@@ -80,6 +84,13 @@ good idea (that was `/cohorte-brainstorm`), never by re-reading files you don't
    request fields with types + validation, the success shape, and its error cases. A missing
    **request or success shape** ⇒ `NOT-READY` (an implementer would invent it, and the other surface
    would invent a different one). A missing **error case** ⇒ `RESERVATIONS`.
+   **On a `kind: patch` spec this check is replaced, not skipped** — a patch has no contract to be
+   complete, so judge §1 Symptom & repro + §4 Regression test instead: no stated expected behaviour,
+   or a §4 that names no test and no reason the fix would be verifiable ⇒ `NOT-READY` (an implementer
+   would fix whatever it guessed the bug was, and nothing would catch a wrong guess). A repro
+   explicitly frozen as a hypothesis, or a cause left to the implementer to find, is
+   `RESERVATIONS` — normal for a patch, never a blocker. Then judge §5 as above **only** if it
+   carries a delta rather than `none`.
 2. **Surface coverage** — every §6 task maps to a surface in the reconciled list, and every contract
    entry has an owner **on each side it names** (producer and consumer). A contract entry no surface
    owns ⇒ `NOT-READY`.
@@ -94,8 +105,8 @@ good idea (that was `/cohorte-brainstorm`), never by re-reading files you don't
 
 Write the machine-readable verdict to `specs/reports/$ARGUMENTS.readiness.json` (overwrite,
 `mkdir -p specs/reports` first — the same gitignored buffer dir `/cohorte-review` stages into, which may not
-exist yet on a first build) — on **every** build, including `READY`. It is the only channel between this gate and a driver (`/cohorte-loop`),
-which parses no prose:
+exist yet on a first build) — on **every** build, including `READY`. It is the only channel between
+this gate and any automated driver, which parses no prose:
 
 ```json
 { "id": "$ARGUMENTS", "phase": "readiness", "ts": "<ISO>", "verdict": "RESERVATIONS",
@@ -104,7 +115,8 @@ which parses no prose:
 ```
 
 - **`gaps`** — one normalized string per gap, `<check>|<where>|<what is missing>`: `<check>` is
-  `contract` · `coverage` · `dependency` · `ambiguity` · `design`; `<where>` is the contract entry,
+  `contract` · `coverage` · `dependency` · `ambiguity` · `design` — plus `repro` on a `kind: patch`
+  spec, for a gap check 1 raised against §1/§4; `<where>` is the contract entry,
   surface key or dependency name (no `:line` — it shifts on every edit); `<what>` is the gap, not the
   fix. `READY` ⇒ `[]`.
 - **`NOT-READY` ⇒ STOP: author no contract and spawn NO agent.** Print the gaps and send the human to
@@ -118,6 +130,15 @@ which parses no prose:
 
 ## 2. Author the contract (lead-only — the single sync channel)
 
+_Skipped entirely on a `kind: patch` spec whose §5 Contract delta is `none`_ — which is the usual
+case: a bug fix corrects behaviour behind a shape that already exists, and re-authoring that shape
+would put the contract file in the diff for nothing. Say you skipped it and why, in one line. A patch
+whose §5 **does** carry a delta is authored exactly as below, from the delta, against the existing
+file — never rewritten from scratch. (A patch needing *new* contract surface area never reaches here:
+`/cohorte-patch` §3 routes it to `/cohorte-spec`.) When you skip, still run `date +%s` on its own —
+the skipped postcondition is where §4's wall-clock start comes from, and a build with no start epoch
+writes a metrics line with no duration.
+
 _Only if `contract.enabled`._ From §5 of the spec, write/update the feature's contract file at
 `<contract.path>/$ARGUMENTS.<contract.ext>` in the profile's `mechanism` (e.g. Zod v4 schemas + inferred
 types for `shared-types-zod`). Export it from `contract.index` if set. This is the ONLY file the agents
@@ -129,7 +150,7 @@ wall-clock start — no separate timing call).
 
 ## 3. Dispatch one implementer per surface — IN PARALLEL
 
-Spawn every surface's agent in a **single message** (one Task call each) so they run concurrently —
+Spawn every surface's agent in a **single message** (one dispatch each) so they run concurrently —
 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
@@ -153,11 +174,11 @@ tree. For each surface in `surfaces`:
 
 ## 3.5 Roll call — account for EVERY dispatch before integrating
 
-A subagent can die: a rate limit mid-run, a transport error after retries, its own context exhausted.
+A surface's work can die: a rate limit mid-run, a transport error after retries, context exhausted.
 When it does, it returns **nothing** — and nothing is byte-identical to "a clean surface with nothing
 to report". Silence is not a green light; treat it as the failure it is (SCHEMA.md §Dead agents).
 
-- **Roll call.** Every surface you dispatched in §3 must come back with a handoff in the format its
+- **Roll call.** Every surface handled in §3 must come back with a handoff in the format its
   agent instructions define. Missing, empty, or truncated mid-sentence ⇒ that surface is **dead**.
 - **Never infer success from silence,** and never speak for a dead agent — you did not see its work.
 - **Retry that surface ONCE, alone.** Re-dispatch it with the byte-identical §3 prompt. The other
@@ -174,9 +195,9 @@ to report". Silence is not a green light; treat it as the failure it is (SCHEMA.
 When all return, flag any contract mismatch or failing test from the handoffs; otherwise print one
 status line per surface (`<key> · tests pass/fail · <n> TODOs`) — do not restate handoff content.
 A dead surface (§3.5) prints `<key> · DEAD — unverified` and **the batch is never reported as ok**.
-Append **ONE line for the batch** to the **main checkout's** `.claude/pipeline-metrics.jsonl` —
+Append **ONE line for the batch** to the **main checkout's** `<state>/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`
+it from anywhere: `$(dirname "$(git rev-parse --git-common-dir)")/<state>/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>)),...}" >> …`):
@@ -187,14 +208,7 @@ anything went wrong. In the same call write the machine-readable batch result to
 `specs/reports/$ARGUMENTS.build.json` (overwrite) — the channel an automated driver reads, since it
 never sees your chat:
 `{"id":"$ARGUMENTS","phase":"build","ts":"<ISO>","surfaces":{"<key>":"ok|error|dead",…},"dead":["<key>",…]}`
-— this is the evidence SCHEMA.md §Specialization asks for before splitting a surface. In the same
-Bash call, chain the opt-in usage ping — **the shared form every phase command reuses**:
-`<core>/pipeline/scripts/telemetry-send.sh <phase> "$ARGUMENTS" <seconds> "<results>" || true`
-(`<core>` = `~/.claude` global / `.claude` bundled; here `<phase>` = `build`, `<results>` =
-`<ok,ok|error,…>`) — a silent no-op unless the human explicitly consented (SCHEMA.md §Telemetry);
-never ask about consent here. `/cohorte-review` and `/cohorte-fix` chain the same line with their own
-phase + results. The `|| true` swallows a **missing** script too, so a half-copied core goes
-silent rather than loud — `/cohorte-doctor` check 1 is what catches that.
+— this is the evidence SCHEMA.md §Specialization asks for before splitting a surface.
 Then tell the human: exercise the feature by hand if it's worth it, then run `/cohorte-review $ARGUMENTS` —
 unless a surface is dead, in which case say so first and let them decide whether to re-run `/cohorte-build`
 (a dead surface has no findings, so `/cohorte-fix` has nothing to re-dispatch).

package/core/commands/cohorte-doctor.md

@@ -12,8 +12,17 @@ fix only with the human's go-ahead (or hand them the command).
 
 ## Checks, in order
 
-1. **Core & pointer.** A core exists (`~/.claude/pipeline/VERSION` global, and/or
-   `.claude/pipeline/VERSION` bundled); `.claude/pipeline.json` names a mode + `core_version`
+0. **Runtime.** Say which coding agent you are running as and what it can enforce — every check
+   below is read through it. **You already know which one**: the Runtime preamble at the top of
+   this file names it. Read `<core>/pipeline/runtimes.json` for the details — a map of every
+   runtime installed against this core, since they share one core. Report one line:
+   `runtime: <label> · scope <global|project> · hooks <yes|no> · workflows <yes|no>`,
+   and name the other installed runtimes if there are any (they share `<state>` and `<config>`, so
+   a board or a gate config wired from one is seen by all — that is intended, and worth stating).
+   File absent ⇒ a core installed before the adapter existed ⇒ ⚠️, fix by re-running the installer.
+   A runtime without hooks makes check 3's gate **advisory** — say so there rather than
+   reporting a false ✅.
+1. **Core & pointer.** A core exists (`<core>/pipeline/VERSION`); `<state>/pipeline.json` names a mode + `core_version`
    coherent with the VERSION file. A **global**-mode pointer lagging the VERSION file is ⚠️, not ❌:
    nothing bumped that field before 1.2.5, so the core itself is fine and only the pointer is stale
    ⇒ fix by running `/cohorte-update-pipeline` (§3 syncs it now), or by editing the one field. Compare
@@ -21,40 +30,57 @@ fix only with the human's go-ahead (or hand them the command).
    commands' step files are present — `templates/steps/init-pipeline/` non-empty (a router whose
    `templates/steps/<cmd>/` dir is missing is a partial/stale install ⇒
    re-run install/update). **Shipped scripts present and executable** in `<core>/pipeline/scripts/`:
-   `kanban-move.sh`, `telemetry-send.sh`, `preflight.sh`, `loop.sh`, `loop-detach.sh`,
+   `kanban-move.sh`, `preflight.sh`,
    `new-feature.sh.template`, `remove-feature.sh.template` — ❌ any missing one.
-   `loop-detach.sh` absent is what silently turns `/cohorte-loop` back into a foreground run
-   that dies at the 600 s tool ceiling, so name it explicitly rather than folding it into
-   "some script is missing". Every caller chains these with `|| true`, so an absent script is a **silent**
-   no-op (no kanban card moves, no telemetry ping, no error anywhere) — this check is the only thing
+   Every caller chains these with `|| true`, so an absent script is a **silent**
+   no-op (no kanban card moves, no error anywhere) — this check is the only thing
    that sees it. Also flag ❌ a `VERSION` **newer than** the other `pipeline/` files (compare mtimes):
    a version bumped without a full re-copy is a half-done update ⇒ re-run install/update.
 2. **Profile.** `PIPELINE.md` exists and its `yaml pipeline-profile` block parses. Every
-   `surfaces[].agent` has its `.claude/agents/<agent>.md` and every agent file has its `surfaces[]`
+   `surfaces[].agent` has its `<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`). **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`, `profile-reader.md` — repo or `~/.claude/agents/`) must
-   each carry their `model:` line too (sonnet/haiku/haiku). **Command pins:** every mechanical command file
-   (`build`, `review`, `fix`, `loop`, `ship`, `audit`, `refactor`, `doctor`, `align-ds`,
-   `update-pipeline` — in `.claude/commands/` or `~/.claude/commands/`) carries `model: sonnet` in
+   (`review.md`, `release.md`, `profile-reader.md` in `<agents>/`) must
+   each carry their `model:` line too (sonnet/haiku/haiku).
+<!-- cohorte:if runtime:claude -->
+   **Command pins:** every mechanical command file
+   (`build`, `review`, `fix`, `ship`, `audit`, `refactor`, `doctor`, `align-ds`,
+   `update-pipeline` — in `<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
+   e.g. Opus/Fable). `brainstorm`, `spec`, `patch`, 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,
-   it double-prompts) **with a matcher covering both `Bash` and `Task`** — a `Bash`-only matcher
-   leaves the preflight phase gate dead (the 1.3.0–1.3.1 regression). Hook files exist at the
-   registered paths.
+<!-- cohorte:endif -->
+
+3. **Hooks & gate.** `<state>/gate-config.json` exists and mirrors the profile's `gate` block
+   (regenerate if drifted).
+<!-- cohorte:if hooks -->
+   The gate hook is registered **once** in the config file the Runtime preamble names — flag a
+   double registration, it double-prompts — and its `command` points at a `gate.py` that exists.
+   Check the **matcher** actually covers what it must: on Claude Code that means both `Bash` and
+   `Task`, since the preflight phase gate keys off `Task` dispatches and a `Bash`-only matcher
+   leaves it silently dead (the 1.3.0–1.3.1 regression). Prove the wiring end to end rather than
+   trusting the file: `python3 <core>/hooks/gate.py --check "<a pattern from the ask list>"` must
+   return a non-`allow` verdict. If the Runtime preamble said this runtime has **no confirmation
+   tier**, state it here too: every `ask` pattern behaves as a `deny`, which is safe but stricter
+   than the profile reads, and a human who expects a prompt will read the refusal as a bug.
+<!-- cohorte:endif -->
+<!-- cohorte:if !hooks -->
+   This runtime has **no blocking hook**, so the gate is **advisory**: it only fires when the agent
+   calls it. Say that in one line rather than reporting ✅ — the enforcement property genuinely is
+   weaker here, and a human who thinks otherwise will approve less carefully. Verify what CAN be
+   verified: `<core>/hooks/gate.py` exists and `python3 <core>/hooks/gate.py --check "git push"`
+   returns a verdict line (a non-`allow` on a gated pattern proves config + script are wired). ❌ if
+   the script is missing or errors; ℹ️ "advisory (this runtime has no hooks)" otherwise.
+<!-- cohorte:endif -->
    Then the **preflight stamp is local, never versioned**: `git ls-files --error-unmatch
-   .claude/preflight.ok` must miss, and `.gitignore` must cover it. A tracked stamp is a ❌ (not a
+   <state>/preflight.ok` must miss, and `.gitignore` must cover it. A tracked stamp is a ❌ (not a
    ⚠️) — it records the tree it verified, the commit that carries it moves HEAD past that tree, and
    the committed copy lands in every clone and new worktree; the gate then blocks clean trees and
-   greens unchecked ones. fix: `git rm --cached .claude/preflight.ok` + add it to `.gitignore`.
+   greens unchecked ones. fix: `git rm --cached <state>/preflight.ok` + add it to `.gitignore`.
 4. **Retrieval** (if `retrieval.provider` ≠ `none`). Run the SCHEMA.md §Code retrieval health
    check: CLI resolvable from PATH, `.mcp.json` entry present in PATH-proof launcher form,
    `.serena/` gitignored, server actually connects.
@@ -70,13 +96,7 @@ fix only with the human's go-ahead (or hand them the command).
    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. **Telemetry** (consent hygiene — read `~/.claude/cohorte.config.yaml` §`telemetry`). Report the
-   status in one line: `disabled` / `enabled since <consent_date> · install_id <id> · endpoint <url>`
-   (the install_id is the human's GDPR erasure key — see SCHEMA.md §Telemetry). Flag ❌ any
-   incoherent state: `enabled: true` with no `install_id` or no `consent_date` (sending without
-   recorded consent — fix: set `enabled: false` until the consent question is re-run), or a
-   `telemetry:` block missing entirely on a current core (top up via `/cohorte-update-pipeline`).
-7b. **Kanban** (the board mirror — SCHEMA.md §Kanban). Run
+7. **Kanban** (the board mirror — SCHEMA.md §Kanban). Run
    `<core>/pipeline/scripts/kanban-move.sh --check` and report its one line verbatim: the resolved
    board path, or the exact link that is missing. A board mirror is optional, so "not configured" is
    ℹ️, never ❌ — but it must be **stated**, because the whole class of bug here is a card that
@@ -85,6 +105,7 @@ fix only with the human's go-ahead (or hand them the command).
    other key whose board file exists (a **rename** orphaned the link — re-key it via
    `/cohorte-update-pipeline`), and an entry whose board file no longer exists at
    `vault_path`-relative `board` (moved or renamed in the vault).
+<!-- cohorte:if workflows -->
 8. **Workflows** (the opt-in execution path — SCHEMA.md §Workflows; the conversational commands
    stay the default, so failures here are ⚠️ at most, never ❌). Report which path this machine will
    take and why:
@@ -92,8 +113,7 @@ fix only with the human's go-ahead (or hand them the command).
      on PATH ⇒ conversational only.
    - **Scripts present:** `<core>/workflows/review.js` + `audit.js` + `refactor.js` —
      missing on a current core ⇒ half-done install, re-run install/update.
-   - **Phase-0 agent present:** `<agents dir>/profile-reader.md` (repo `.claude/agents/` bundled or
-     `~/.claude/agents/` global) — the workflows abort without it.
+   - **Phase-0 agent present:** `<agents>/profile-reader.md` — the workflows abort without it.
    - **Workflows enabled in this session** — the `Workflow` tool is in your own toolset right now;
      absent ⇒ disabled for this session (a setting or an old client), conversational path.
    - **Preflight wiring** (used by both paths): `pipeline/scripts/preflight.sh` executable and
@@ -101,15 +121,20 @@ fix only with the human's go-ahead (or hand them the command).
    End the check with ONE summary line, e.g.
    `workflows: available (opt-in — ask to "run the review workflow")` or
    `workflows: unavailable (<first failing prerequisite>) — conversational commands (the default)`.
+<!-- cohorte:else -->
+8. **Preflight wiring.** `<core>/pipeline/scripts/preflight.sh` is executable and
+   `gate-config.json` carries the `preflight` block — mismatch ⇒ regenerate from the profile.
+   (The workflow execution path does not exist on this runtime; the conversational commands are
+   the only path, which is also the default everywhere else. Not a defect — state it and move on.)
+<!-- cohorte:endif -->
 9. **Specs & metrics.** Every `specs/*.md` front-matter `status` is a valid stage — one of
-   `draft · frozen · in-progress · in-review · shipped · blocked` (SCHEMA.md §Spec status; the last two
-   are written by the `/cohorte-loop` driver, so flagging them would report the pipeline's own state as a
-   defect) — excluding
+   `draft · frozen · in-progress · in-review · shipped · blocked` (SCHEMA.md §Spec status) — excluding
    `_`-prefixed files (the spec template and `specs/_decisions.md`, the decision journal) and
    `specs/refactor-backlog.md`, which `/cohorte-audit` writes as a backlog, not a
-   spec, and which has no front-matter to check. A spec left `in-progress`/`blocked` with
-   `loop_pass` > 0 is a loop that never finished ⇒ say so and name `/cohorte-loop <id> --resume`. `shipped` specs
-   with a live worktree flagged (see 6). `.claude/pipeline-metrics.jsonl` and `specs/reports/` (the
+   spec, and which has no front-matter to check. A spec left `in-progress` or `blocked` is a round
+   that never finished ⇒ say so and route it: open `## Remediation` items ⇒ `/cohorte-fix`, none ⇒
+   `/cohorte-build`. `shipped` specs
+   with a live worktree flagged (see 6). `<state>/pipeline-metrics.jsonl` and `specs/reports/` (the
    `/cohorte-review` report buffer that lets a `/cohorte-fix` survive a `/clear`) are gitignored. Metrics
    belong to the **main checkout** — a `pipeline-metrics.jsonl` inside a live feature worktree is a
    stale-core sign (its lines die at teardown) ⇒ suggest appending its lines to the main checkout's

package/core/commands/cohorte-fix.md

@@ -12,8 +12,7 @@ that change the *contract*; `/cohorte-fix` is for everything else.
 > _Skip the re-read if it's already in your context this session and unmodified since._
 >
 > **Kanban** (SCHEMA.md §Kanban): on ingest, run
-> `<core>/pipeline/scripts/kanban-move.sh auto $ARGUMENTS fix` (`<core>` = `.claude` bundled /
-> `~/.claude` global — probe with `test -x`); the card returns to **Review** when `/cohorte-review`
+> `<core>/pipeline/scripts/kanban-move.sh auto $ARGUMENTS fix`; the card returns to **Review** when `/cohorte-review`
 > re-runs. `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**.
 
@@ -71,10 +70,9 @@ When the agents return:
   needs those checkboxes).
 - Print one status line per surface (`<key> · items fixed <n>/<m> · tests pass/fail`) — do not restate
   handoff content — and append ONE metrics line for the batch to the **main checkout's**
-  `$(dirname "$(git rev-parse --git-common-dir)")/.claude/pipeline-metrics.jsonl` (never a bare
+  `$(dirname "$(git rev-parse --git-common-dir)")/<state>/pipeline-metrics.jsonl` (never a bare
   relative path: from a feature worktree that writes a stray sink whose lines die at teardown)
-  (rules in `/cohorte-build` §4, `phase: "fix"`), chaining the opt-in usage ping in the same Bash call
-  (results = items fixed over items found across surfaces, e.g. `"5/6"`).
+  (rules in `/cohorte-build` §4, `phase: "fix"`).
 - Tell the human: re-test by hand if the failures were runtime ones, and `/cohorte-review $ARGUMENTS` for the
   re-verdict — the re-review is what *verifies* the ticked items actually hold (a regression simply
   reappears as a new finding in the next round). **Recommend a `/clear`** — all state (spec,

package/core/commands/cohorte-init-pipeline.md

@@ -9,13 +9,12 @@ agents. Interactive — confirm inferences with the human.
 
 > **Bootstrap (applies to every step):**
 >
-> **Where the core lives (bundled vs global).** The stack-agnostic source files (`pipeline/`,
-> `templates/`) live in EITHER this repo's `.claude/` (per-project install) OR `~/.claude/`
-> (global install). **Resolve every source path below as: prefer `.claude/<path>`; if it isn't
-> there, use `~/.claude/<path>`.** Detect the mode once at the start (`.claude/pipeline/VERSION`
-> present ⇒ `bundled`; else `~/.claude/pipeline/VERSION` ⇒ `global`) and remember it — Phase 4
-> branches on it. **Everything you GENERATE is always written into THIS repo** (`PIPELINE.md` at the
-> root, agents/config under this repo's `.claude/`), never into `~/.claude/`.
+> **Where the core lives (bundled vs global).** `<core>` above already names it — the adapter
+> resolved the scope at install time, so nothing here probes. Read it once to learn WHICH mode you
+> are in (`<core>` inside this repo ⇒ `bundled`; `<core>` under your home ⇒ `global`) and remember
+> it — Phase 4 branches on it. **Everything you GENERATE is always written into THIS repo**
+> (`PIPELINE.md` at the root, agents under `<agents>/`, config under `<state>/`), never into the
+> global core.
 >
 > Work in phases. Do not write any file until Phase 4.
 
@@ -29,4 +28,4 @@ agents. Interactive — confirm inferences with the human.
 | 04 | `04-write-render` | Write files & render surface agents | after go-ahead |
 | 05 | `05-report` | Print install mode, files, mapping | always |
 
-**Before running a step, read its file** in `.claude/templates/steps/init-pipeline/` (resolves to `~/.claude/templates/steps/init-pipeline/` when the core is installed globally — read whichever exists). This table is a map, not the instructions.
+**Before running a step, read its file** in `<core>/templates/steps/init-pipeline/`. This table is a map, not the instructions.

package/core/commands/cohorte-patch.md

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

@@ -8,10 +8,12 @@ You are the **lead**. Refactor domain **$ARGUMENTS** to match `PIPELINE.md`, usi
 
 > 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
 
@@ -22,11 +24,12 @@ You are the **lead**. Refactor domain **$ARGUMENTS** to match `PIPELINE.md`, usi
 
 ## 2. Dispatch the surface's implementer agent — TDD-first, stateless
 
-Spawn the matching `<surface.agent>` with the template below. Keep it **byte-identical across loop
+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:
 
-> `subagent_type: <surface.agent>` — "Refactor pass on your surface (no feature spec). Read
+> "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?

package/core/commands/cohorte-review.md

@@ -10,20 +10,21 @@ You are the **lead**. Dispatch the review for feature **$ARGUMENTS**.
 > _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` (`<core>` = `.claude` bundled /
-> `~/.claude` global — probe with `test -x`). `auto` resolves the board from the config itself and
+> `<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**.
 >
+<!-- 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 -->
 
 ## 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`, `<core>` = `.claude` bundled / `~/.claude` global — probe
-with `test -x`); note the epoch (`date +%s`) in the same call — §3's metrics line needs it:
+(`<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 \
@@ -37,8 +38,14 @@ with `test -x`); note the epoch (`date +%s`) in the same call — §3's metrics
   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.
-- **Zero exit** ⇒ it stamped `.claude/preflight.ok`, which the gate hook checks before letting
+<!-- 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.
 
@@ -61,7 +68,7 @@ with `test -x`); note the epoch (`date +%s`) in the same call — §3's metrics
 
 ## 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 Task call
+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.
 
@@ -70,12 +77,12 @@ changed lines), touches no contract file, and every open finding it addresses is
 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
-dispatched surface:
+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` — "Review one feature surface against its frozen spec. Read `PIPELINE.md`
+> `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
@@ -109,16 +116,14 @@ re-ordered by severity, counts summed, duplicates collapsed, verdict = the worst
 (`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)")/.claude/pipeline-metrics.jsonl` (rules in
+`$(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>",…}}`.
-In the same Bash call, chain the opt-in usage ping (`/cohorte-build` §4, `phase: "review"`, results = the
-merged verdict + total finding count, e.g. `"REVISE:3"`).
 **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 an automated driver (`/cohorte-loop`), which parses no prose:
+between the pipeline and any automated driver, which parses no prose:
 
 ```json
 { "id": "$ARGUMENTS", "phase": "review", "ts": "<ISO>", "verdict": "REVISE",
@@ -163,8 +168,8 @@ exactly the leak this step closes. Append each merged `## Deferred` item to
 - [ ] <SEVERITY> · <file:line> · <quality|security|rule> · <concrete fix> · deferred:$ARGUMENTS
 ```
 
-- **Never into the spec's `## Remediation`** — that list is what `/cohorte-fix` re-dispatches and what `/cohorte-loop`
-  waits on, so a deferred item there would re-trigger the very loop it was deferred out of.
+- **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.
@@ -197,10 +202,7 @@ would sit in this session's history, re-sent every turn). Then:
   re-trigger the fix loop), keep the SHIP verdict and the freshness stamp, and let the human ship.
 - **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. (If they'd rather automate the rounds, the autonomous driver is
-  `disable-model-invocation: true` on purpose: **you cannot start it, they must type it**. Name the
-  exact line for them to type rather than attempting it — an attempt that silently fails reads as a
-  loop that is running when nothing is.) The full path (`/cohorte-spec` Mode B then `/cohorte-build`) remains for findings that
+  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._