cohorte 1.5.0 → 2.0.0

package/CHANGELOG.md

@@ -1,7 +1,172 @@
 # Changelog
 
-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.
+Entries are shown by `/cohorte-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.
+
+> Sections below 2.0.0 name commands **as they were at the time** (`/build`, `/drive`, `/loop`).
+> They are history and are deliberately not rewritten — every command gained a `cohorte-` prefix
+> in 2.0.0.
+
+## 2.0.0 — 2026-08-03
+
+> **Breaking: every command is renamed.** `/build` → `/cohorte-build`, `/review` →
+> `/cohorte-review`, and so on for all 13. The driver, `/loop` → `/drive` in 1.6.0, is now
+> **`/cohorte-loop`**. Re-run `npx cohorte@latest update --global` (or `update`): the update
+> **deletes** the 13 unprefixed command files from your install rather than leaving them as
+> decoys. Nothing inside your repo needs editing — `/build` in a spec or PIPELINE.md is prose,
+> not a call site. Muscle memory is the only migration cost.
+
+- **Every command now carries a `cohorte-` prefix, ending command shadowing for good.** A command
+  whose name collides with a Claude Code built-in is not overridden, it is **shadowed**: the
+  built-in answers the slash, our file is never read, and the session confidently reports on a run
+  that never happened. `/loop` did exactly that and went unnoticed until a user found the driver had
+  never started; `/doctor` was sitting on a watchlist waiting to do the same. 1.6.0 renamed one
+  name; this replaces the whole approach. `validate-core` now enforces the prefix structurally
+  instead of maintaining a blocklist that could only ever forbid the collisions we already knew
+  about. Telemetry **phase** names (`build`, `review`, `fix`, …) stay unprefixed — they are a wire
+  contract with the collector, and the retired bare command names are kept in the metrics
+  collector's retired list so months of existing transcripts stay attributed instead of silently
+  reclassifying to `(chat)`.
+
+- **`/cohorte-loop` can now run for hours.** It previously ran the driver as one foreground Bash
+  call, which cannot work: a single call is capped at **600 s** and a build is 25–40 min, so it was
+  killed mid-`/cohorte-build`. Backgrounding it was worse — a backgrounded Bash call is **not
+  detached**, so the driver stayed in the calling session's process group and every Claude Code
+  restart, crash or laptop sleep took `loop.sh` and its `claude -p` children down with it, mid-write.
+  Observed on a real run: four teardowns in 45 minutes, each aborting both surface implementers and
+  leaving a half-built tree that read as `dead`. New `loop-detach.sh` puts the driver in its own
+  `screen` session so it outlives the launching process entirely, and `/cohorte-loop` polls a small
+  status file in ~9-minute waits. The driver's exit code — which the report table is keyed on —
+  survives as `__EXIT__ <code>` in that file.
+
+- **`loop.sh` holds the machine awake for its whole run.** It re-execs itself under
+  `caffeinate -ims` on macOS, `systemd-inhibit` on Linux, because system sleep aborts every
+  in-flight `claude -p` request and the abort is byte-identical to "the agent returned nothing" —
+  the `dead` family the driver exists to catch. The inhibitor is **probed before the `exec`**, since
+  `exec` replaces the shell: one that exists but is refused (`systemd-inhibit` answers `Failed to
+  inhibit: Access denied` in a container, in CI, or in any seatless session) would otherwise make its
+  own failure the driver's exit code and the run would never start — GitHub's Linux runners turned
+  all 24 loop tests red exactly that way. Absent or refused both fall through to a no-op; an unheld
+  power assertion is a degraded run, not a failed one, and `test-loop.mjs` now pins both directions.
+  **This cannot prevent lid-close sleep** — no userspace assertion can on any platform; keep the
+  lid open or use clamshell mode.
+
+- **Platform tiers, stated rather than assumed.** Detaching uses `screen` (macOS + Linux), else
+  `setsid` (Linux) — both escape the caller's process group, which is what actually matters. Git
+  Bash on Windows has neither, so it falls back to `nohup`, which ignores `SIGHUP` but does **not**
+  survive a teardown; `loop-detach.sh` prints that warning rather than degrading silently, and
+  points at running `loop.sh` from your own terminal instead. See the platform table in
+  `docs/reference/scripts.md`.
+
+- **Fixed — the preflight stamp is keyed on the code, not on HEAD, and is never versioned.** The
+  stamp recorded the HEAD sha, which is the wrong key in both directions: the reviewed tree is
+  normally *dirty*, so committing the very code the preflight verified made the gate ask on a clean
+  tree, while an implementer editing files between preflight and dispatch invalidated nothing. Worse,
+  `.claude/preflight.ok` was never gitignored — once a release agent staged `.claude/`, the stamp
+  went into git describing the tree *before* its own commit, so it could never match again: every
+  review dispatch in that repo asked "HEAD moved" forever, and every new clone or worktree inherited
+  a green it never earned. The stamp is now `<epoch> <sha> <tree digest>`, where the digest is the
+  git tree id of the working tree (`.claude` and `specs` excluded, so the pipeline's own report,
+  metrics and DoD writes don't invalidate it), computed in a throwaway index that never touches
+  yours. Pre-2.0.0 two-field stamps still fall back to the HEAD comparison. `/cohorte-doctor` check 3
+  now fails hard on a tracked stamp, `/cohorte-update-pipeline` untracks it and fixes `.gitignore`
+  (§Reconcile step 8), and `test-gate.mjs` pins all of it — including "commit the verified code ⇒
+  still green" and "one edit ⇒ red".
+
+- **`/cohorte-review` and `/cohorte-fix` now spell out the metrics path instead of delegating it.**
+  Both said "append a line to `pipeline-metrics.jsonl`" and pointed at `/cohorte-build` §4 for where
+  that file lives — a lead running from a feature worktree resolves the bare name against its own
+  cwd and strands the batch in a sink that dies at teardown. Both now carry the resolved
+  `$(dirname "$(git rev-parse --git-common-dir)")` form inline.
+
+- **Fixed — the dashboard's command allowlist had drifted from its own error message.** The
+  server accepted the bare `/audit`/`/init-pipeline`/`/update-pipeline` while the UI sent (and the
+  error text advertised) the prefixed names, so the run button would have 400'd on the only
+  commands that exist. The test suite checked *rejection* only, which is why it passed; it now pins
+  both directions.
+
+## 1.6.0 — 2026-08-01
+
+> **Re-run `npx cohorte@latest update --global` (or `update`)** to pick up the readiness gate, the
+> deferred-findings route, the resumable driver and the decision journal — the update *deletes* the
+> shadowed `/loop` command and the long-dead `/cycle` from your install, it does not just stop
+> shipping them. Existing specs keep working: the new front-matter fields are written on demand, and a
+> spec without them simply isn't resumable yet. **`/loop <id>` is now `/drive <id>`.**
+
+- **New — the readiness gate between `/spec` and `/build`.** `/build` §1.6 now scores the frozen spec
+  on **implementability** before authoring the contract and before dispatching anything: contract
+  shapes complete · every area owned by a surface · named dependencies actually exist · no ambiguity a
+  surface would have to guess at · design links present. The verdict goes to
+  `specs/reports/<id>.readiness.json` (`READY` · `RESERVATIONS` · `NOT-READY` + `gaps[]`).
+  **`NOT-READY` stops the build with zero agents spawned** — a spec that can't be built doesn't get
+  cheaper by being built on N surfaces in parallel — and sends you to `/spec`. `RESERVATIONS` never
+  blocks: each gap is inlined into the affected surface's dispatch as an assumption the implementer
+  applies *and* flags in its handoff. It costs **no extra agent**: the lead already holds the spec,
+  the profile and the reconciled surface list.
+- **New — deferred findings: `/review` stops throwing away what isn't blocking.** The review agent
+  now returns a separate `## Deferred` section (max 10) for what is real but **out of this feature's
+  scope** — pre-existing code the diff never touched, adjacent debt the spec never claims to fix —
+  each line carrying its own out-of-scope reason. Deferred items count in no severity row, move no
+  verdict, are never cross-checked, and on **every** verdict get routed into
+  `specs/refactor-backlog.md` under the owning surface's `## <domain>` heading, tagged
+  `deferred:<id>`. So `/review` feeds `/refactor` for free instead of dropping everything
+  non-blocking on the floor. Never into `## Remediation`, which is what `/fix` re-dispatches. Not
+  deferrable, ever: anything the diff touched, any spec violation, any security issue on a path this
+  feature adds or calls. `/audit` now **carries open `deferred:` items over** when it rewrites the
+  backlog. The verdict JSON gains `deferred: <n>` (informational, outside `blocking`).
+- **BREAKING — `/loop` is renamed `/drive`, because Claude Code shadowed it.** Claude Code ships its
+  own built-in `/loop` (run a prompt on a recurring interval), which won the name: typing
+  `/loop <id>` started the *interval runner* with the feature id as its prompt, so cohorte's driver
+  never ran — and the session, having never seen `loop.md`, reported a loop that did not exist. Same
+  command, same flags, same script (`pipeline/scripts/loop.sh` keeps its name — nothing about your
+  install paths changes): type **`/drive <id>`**. The update scrubs the old `commands/loop.md`, so a
+  stale shadowed copy can't linger.
+- **`/drive` is resumable — the spec's status is the state machine.** The lifecycle is now
+  `draft → frozen → in-progress → in-review → shipped` plus `blocked`. Before every phase the driver
+  stamps `status: in-progress` + `loop_pass` + `loop_phase` into the spec's front-matter — plain
+  `awk`, a temp file and `mv`, **zero tokens** — and on exit a terminal `in-review` (clean) or
+  `blocked`. **`/drive <id> --resume`** then continues at the pass it reached instead of re-paying the
+  ones already made, whether the session died, the ceiling hit, or the fix stopped converging.
+  `--max` stays a ceiling on the *total* passes. New **exit 4** (`not implementable`) relays the
+  readiness gate's `NOT-READY`: the one loop outcome more passes cannot fix. The dashboard's specs
+  board gains In-progress and Blocked columns and shows `↻ pass 3 · /review` on the card; `/doctor`
+  names any spec left mid-loop.
+- **Fixed — a dead subagent no longer reads as a clean one on the conversational path.** The
+  "a dead agent is never a clean result" doctrine existed since 1.3.4 — but only inside the
+  **workflows**. `/build`, `/review` and `/fix` had nothing: a subagent that dies (rate limit,
+  transport error, exhausted context) returns *nothing*, and nothing was indistinguishable from
+  "finished, nothing to report". Concretely, a dead **reviewer** produced zero findings ⇒
+  `blocking: 0` ⇒ verdict `SHIP` ⇒ `/drive` exit 0 ⇒ the human sent to `/ship` — a clean bill of
+  health on code no agent ever read. Now every fan-out phase does a **roll call** before integrating:
+  a silent surface is retried **once** alone (byte-identical prompt, so recovery costs one agent, not
+  a rebuild), then `/build` marks it `dead` and verifies the tree with that surface's own quiet
+  commands instead of speaking for the agent, `/review` lists it in the verdict's new `unreviewed[]`
+  and **refuses to score `SHIP`**, and `/fix` leaves every one of its items `- [ ]` (a dead agent
+  never ticks a box). `/build` also writes `specs/reports/<id>.build.json` with `dead[]`, and
+  `loop.sh` aborts on either signal with **exit 2** *before* reading `blocking` — because a dead
+  reviewer makes `blocking == 0` a statement about unread code. `unreviewed` is deliberately kept
+  out of `blocking`: faking a count there would corrupt the one field the driver contract rests on.
+  The metrics line is now written even when a surface died (`"<key>":"dead"`) — an incomplete batch
+  is exactly the batch worth recording.
+- **Fixed — `/cycle` and its workflow were removed in 1.4.0 but no installer ever scrubbed them.**
+  Every install since has kept `commands/cycle.md` + `workflows/cycle.js` on disk, so a dead command
+  stayed listed and invokable — dispatching a workflow whose phases 1.5.0 then deleted. All three
+  installers now remove them (as they already did for `/smoke`), and CI **plants the orphans before
+  re-installing** instead of asserting their absence on a fresh scratch home, which is exactly the
+  blind spot that let this survive four releases.
+- **Reconcile now tops up `specs/_template.md`.** It was seeded once at install and never refreshed,
+  so every repo kept the front-matter its core shipped with. `/update-pipeline` adds the missing
+  front-matter fields (never the body — the section list is yours).
+- **New — `specs/_decisions.md`, the transverse decision journal.** `PIPELINE.md` is a *stack* profile;
+  it says nothing about what the project has **decided**, so every `/spec` re-discovered or
+  contradicted the same choices. The journal is deliberately tiny: **append-only, one line per
+  decision** (`- <date> · <area> · <decision> — because <reason> · <feature_id>`), reversal by a
+  superseding line rather than an edit. Written by `/spec` at freeze (typically 0–3 lines; zero is
+  normal) and by `/build` when it adds or splits a surface. Read by the **deciding** stages only —
+  `/brainstorm`, `/spec`, `/audit`. **Implementers and reviewers never load it:** they have the frozen
+  contract, and shipping them the rationale would cost `surfaces × dispatches` tokens per feature for
+  a fact they can't act on. That exclusion is what keeps it cheap enough to be worth having. The `_`
+  prefix means `/doctor`, the dashboard scanner and the kanban backfill already skip it.
 
 ## 1.5.0 — 2026-08-01
 
@@ -9,7 +174,8 @@ user-facing, most recent first. One `## <version> — <YYYY-MM-DD>` section per
 > `/smoke` removal — the update *deletes* the command and its agent from your install, it does not
 > just stop shipping them. The new dashboard panel comes with `npx cohorte dashboard`.
 
-- **New — `/loop <id>`: the review ⇄ fix cycle, run for you.** `/build` → `/review` → `/fix` →
+- **New — `/loop <id>`: the review ⇄ fix cycle, run for you.** _(renamed `/drive` in 1.6.0 — see
+  there.)_ `/build` → `/review` → `/fix` →
   `/review` … until a review reports **zero blocking findings** (a CRITICAL or a security issue —
   a LOW nit never costs a pass), or the pass ceiling (`--max=N`, default 5), or two consecutive
   reviews returning the *same* blocking findings, which means the fix is treading water and more

package/README.md

@@ -14,13 +14,13 @@
 </div>
 
 A **portable, stack-agnostic multi-agent pipeline** for Claude Code. Install it once globally,
-then one command per project (`/init-pipeline`) adapts it to that project's stack.
+then one command per project (`/cohorte-init-pipeline`) adapts it to that project's stack.
 
 - **The dev pipeline** — a human **lead** drives feature work through gated commands, dispatching
   **stateless agents** that only communicate through a frozen contract:
 
   ```
-  /brainstorm → /spec → (design) → /build <id> → /review → (/fix) → /ship
+  /cohorte-brainstorm → /cohorte-spec → (design) → /cohorte-build <id> → /cohorte-review → (/cohorte-fix) → /cohorte-ship
   ```
 
 ## How it works — three layers
@@ -28,7 +28,7 @@ then one command per project (`/init-pipeline`) adapts it to that project's stac
 | Layer | What it holds | Lives in | Scope |
 | --- | --- | --- | --- |
 | **Generic core** | the workflow doctrine: commands, fixed agents, templates, hooks — zero project facts | `~/.claude` (global) — or vendored in a repo's `.claude/` (bundled) | identical everywhere, installed once |
-| **Project profile** | stack, surfaces, commands, conventions, gates | `PIPELINE.md` + rendered surface agents + `gate-config.json`, **committed in each repo** | generated per project by `/init-pipeline` |
+| **Project profile** | stack, surfaces, commands, conventions, gates | `PIPELINE.md` + rendered surface agents + `gate-config.json`, **committed in each repo** | generated per project by `/cohorte-init-pipeline` |
 | **User config** | kanban board links + shared Obsidian vault path | `~/.claude/cohorte.config.yaml` | personal, project-independent |
 
 The core never hardcodes stack facts. Two mechanisms keep it generic:
@@ -37,7 +37,7 @@ The core never hardcodes stack facts. Two mechanisms keep it generic:
    `~/.claude/cohorte.config.yaml` (kanban board links + shared vault) at run time — an agent's
    _first action_ is to read its config.
 2. **Render-at-init** — things that must be in agent frontmatter (name, `tools:`, surface ownership)
-   are rendered per **surface** by `/init-pipeline` from `implementer.template.md`.
+   are rendered per **surface** by `/cohorte-init-pipeline` from `implementer.template.md`.
 
 ## Prerequisites
 
@@ -48,10 +48,10 @@ Only one hard requirement — the rest is optional and independent:
   provider. Install it separately (`uv tool install -p 3.13 serena-agent && uv tool update-shell`); the
   `npx` install neither needs nor touches it, so the order between the two is irrelevant. Without Serena
   the pipeline still runs — agents just fall back to Grep/Read. Having it installed **before**
-  `/init-pipeline` lets init wire it in one pass (otherwise `/update-pipeline` wires it later).
+  `/cohorte-init-pipeline` lets init wire it in one pass (otherwise `/cohorte-update-pipeline` wires it later).
 - **On a new machine cloning a repo that's already pipeline-ised:** the Serena registration is committed
   in the repo's `.mcp.json` (project scope, portable) — you don't re-wire. Just install the Serena CLI,
-  restart the session, and run `/doctor` to confirm it connects.
+  restart the session, and run `/cohorte-doctor` to confirm it connects.
 
 ## Install
 
@@ -66,11 +66,11 @@ own `gate-config.json`:
 npx cohorte install --global
 ```
 
-The per-project part is NOT the core — it's the **profile** `/init-pipeline` generates and you
+The per-project part is NOT the core — it's the **profile** `/cohorte-init-pipeline` generates and you
 commit: `PIPELINE.md`, the rendered surface agents, `gate-config.json`, `settings.json`, `specs/`.
 **That's what makes team work possible in global mode**: everything project-specific travels with the
 repo; each teammate just runs the same global one-liner once, guided by the committed
-`.claude/pipeline.json` pointer (core version + install command) that `/init-pipeline` writes.
+`.claude/pipeline.json` pointer (core version + install command) that `/cohorte-init-pipeline` writes.
 
 <details>
 <summary><strong>Alternative: per-project (bundled)</strong> — vendor the core into the repo itself.</summary>
@@ -109,13 +109,13 @@ published semver. Both land in `.claude/pipeline/VERSION` and the `pipeline.json
 </details>
 
 > **After installing (or updating): restart Claude Code / start a new session.** Slash commands and
-> agents are scanned at session start — in an already-open session the new `/init-pipeline`,
-> `/build`, etc. won't appear until you reload. This is the #1 "the install didn't work" trap.
+> agents are scanned at session start — in an already-open session the new `/cohorte-init-pipeline`,
+> `/cohorte-build`, etc. won't appear until you reload. This is the #1 "the install didn't work" trap.
 
 Then, in Claude Code (from any repo, once the core is installed either way):
 
 ```
-/init-pipeline
+/cohorte-init-pipeline
 ```
 
 It **detects** your stack (package manager, workspaces, frameworks, test runners, linters, git remote,
@@ -131,9 +131,10 @@ design system), **interviews** you for the gaps, and **generates**:
   symbols instead of grep-and-reading whole files; `graphify` or `none` also available via the
   profile's `retrieval.provider`)
 - `scripts/new-feature.sh` + `remove-feature.sh` — parallel worktree isolation (if you enable it)
-- `specs/_template.md`
+- `specs/_template.md` (and, on first decision, `specs/_decisions.md` — the project's one-line-per-decision
+  journal, read by `/cohorte-brainstorm`, `/cohorte-spec` and `/cohorte-audit` so features stop re-litigating settled ground)
 
-Sanity-check `PIPELINE.md`, commit it, and run `/brainstorm`.
+Sanity-check `PIPELINE.md`, commit it, and run `/cohorte-brainstorm`.
 
 ## Update
 
@@ -148,12 +149,12 @@ The installer refreshes the generic core (commands, hook, templates) **without**
 `PIPELINE.md`, rendered agents, `gate-config.json`, `settings.json`, or your filled
 `~/.claude/cohorte.config.yaml`.
 
-From inside Claude Code, prefer **`/update-pipeline`**: it runs the right update invocation for your
+From inside Claude Code, prefer **`/cohorte-update-pipeline`**: it runs the right update invocation for your
 install scope, reports `old → new` — and then **reconciles the repo's generated files to the new
 core**: new profile fields are added at their defaults (you're only asked for genuinely new
 decisions), surface agents are re-rendered, settings are patched additively, new capabilities get
-wired. **`/init-pipeline` is one-time per project** — after init, `/update-pipeline` is the only
-maintenance command you ever run (`/build` auto-grows surfaces as specs need them).
+wired. **`/cohorte-init-pipeline` is one-time per project** — after init, `/cohorte-update-pipeline` is the only
+maintenance command you ever run (`/cohorte-build` auto-grows surfaces as specs need them).
 
 ## Dashboard — a local web cockpit
 
@@ -166,7 +167,7 @@ npx cohorte dashboard --port=4400 --open   # custom port, open the browser
 ```
 
 **Bound to `127.0.0.1` by default** — the dashboard's actions execute code (install/update/reset,
-and `/init-pipeline`·`/update-pipeline`·`/audit` via headless Claude), so it must stay on loopback. Each user
+and `/cohorte-init-pipeline`·`/cohorte-update-pipeline`·`/cohorte-audit` via headless Claude), so it must stay on loopback. Each user
 runs their own agent and drives only their own machine. `--host=0.0.0.0` exposes it to the network
 (it prints a security warning) — only on a trusted network, since anyone who reaches the port can run
 those actions.
@@ -174,7 +175,7 @@ those actions.
 - **Fleet overview** — the global core version vs npm latest, plus every tracked project's freshness
   and health at a glance. Add a project by absolute path or with the **folder picker** (Browse…); the
   set is remembered in `~/.claude/cohorte-dashboard.json`.
-- **Per-project drill-down** — Freshness (installed core vs npm), `/doctor` rendered as a live
+- **Per-project drill-down** — Freshness (installed core vs npm), `/cohorte-doctor` rendered as a live
   ✅/⚠️/❌ checklist (each failure with its fix), the **Surfaces ↔ agents** map from `PIPELINE.md`,
   and one board: a **Kanban** if the project has a linked Obsidian board (columns + cards from the
   vault, with clickable PR links + live open/merged/closed status and a ship-date-sorted Shipped
@@ -190,7 +191,7 @@ those actions.
   **workflows** state (scripts + profile-reader installed, which path a session will take).
 
 Runtime is **dependency-free** — node's built-in `http` server serves a prebuilt React app (the app
-source lives in `dashboard/app/`, built to `dashboard/dist/` at publish time). The `/doctor` checks
+source lives in `dashboard/app/`, built to `dashboard/dist/` at publish time). The `/cohorte-doctor` checks
 are reimplemented in JS, so the dashboard needs no Claude session to compute state. See
 [`dashboard/README.md`](dashboard/README.md) for the architecture.
 
@@ -213,29 +214,29 @@ it in `.claude/pipeline/VERSION` and bundled repos in their committed `pipeline.
 
 | Command              | Role                                                                                  |
 | -------------------- | ------------------------------------------------------------------------------------- |
-| `/init-pipeline`     | Detect stack → interview → generate the profile + agents. Run once per project.       |
-| `/brainstorm`        | Interactive persona panel that pressure-tests a feature idea.                         |
-| `/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. |
-| `/build <id>`        | Lead authors the contract, then dispatches one implementer per surface in parallel.   |
-| `/review <id>`       | Read-only review agents (one per touched surface, parallel) audit the diff vs the spec. |
-| `/fix <id>`          | Apply a review report: remediation into the spec, re-dispatch only the surfaces with findings. |
-| `/loop <id>`         | Autonomous `/build → /review → /fix → /review …` until no blocking finding is left (see below). |
-| `/ship <id>`         | Release agent commits, pushes, opens the PR; watches CI; proposes worktree teardown.  |
-| `/audit [path]`      | Prioritized refactor backlog for existing code.                                       |
-| `/refactor <domain>` | Apply the backlog for one surface, TDD-first.                                         |
-| `/align-ds`          | Align the code UI kit to the design system (no-op if none configured).                |
-| `/update-pipeline`   | Refresh the installed core (global or bundled) to the latest published version.       |
-| `/doctor`            | Diagnose the installation (core, agents↔surfaces, hooks, gate, retrieval, worktrees). |
+| `/cohorte-init-pipeline`     | Detect stack → interview → generate the profile + agents. Run once per project.       |
+| `/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-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-fix <id>`          | Apply a review report: remediation into the spec, re-dispatch only the surfaces with findings. |
+| `/cohorte-loop <id>`         | Autonomous `/cohorte-build → /cohorte-review → /cohorte-fix → /cohorte-review …` until no blocking finding is left (see below). |
+| `/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-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). |
 
 ### Run the loop cheaply — `/clear` between stages
 
 Every command reloads all the state it needs **from disk** — the frozen spec, the contract, the diff, the
-Remediation checkboxes, the freshness stamp, and the last `/review` report (staged to a gitignored
+Remediation checkboxes, the freshness stamp, and the last `/cohorte-review` report (staged to a gitignored
 `specs/reports/<id>.md`). Nothing essential lives in the conversation. So the loop is **`/clear`-safe at
 every boundary**:
 
 ```
-/spec → /clear → /build → /clear → /review → /clear → /fix → /clear → /review → /ship
+/cohorte-spec → /clear → /cohorte-build → /clear → /cohorte-review → /clear → /cohorte-fix → /clear → /cohorte-review → /cohorte-ship
 ```
 
 `/clear`-ing between stages sheds the accumulated main-thread context, which is the single biggest token
@@ -243,19 +244,26 @@ 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.)
 
-### Let it run itself — `/loop`
+### Let it run itself — `/cohorte-loop`
 
 ```
-/loop feat-x              # /build, then /review ⇄ /fix until clean (max 5 passes)
-/loop feat-x --no-build   # already built — just re-run the /review ⇄ /fix loop
-/loop feat-x --max=8
+/cohorte-loop feat-x              # /cohorte-build, then /cohorte-review ⇄ /cohorte-fix until clean (max 5 passes)
+/cohorte-loop feat-x --no-build   # already built — just re-run the /cohorte-review ⇄ /cohorte-fix loop
+/cohorte-loop feat-x --max=8
+/cohorte-loop feat-x --resume     # continue a run that died / hit the ceiling, at the pass it reached
 ```
 
-It stops when `/review` reports **zero blocking findings** (a CRITICAL or a security issue — a LOW
-nit never costs a pass), at the pass ceiling, or as soon as two consecutive reviews return the same
-blocking findings, which means the fix is treading water and more passes won't help. **Each fix pass
-is committed** (`loop(<id>): fix pass <i>`) — that's your way back after N autonomous passes — and
-**no fix runs on the last pass**, since fixing without a review behind it leaves unaudited code.
+It stops when `/cohorte-review` reports **zero blocking findings** (a CRITICAL or a security issue — a LOW
+nit never costs a pass), at the pass ceiling, as soon as two consecutive reviews return the same
+blocking findings (the fix is treading water and more passes won't help), or immediately if `/cohorte-build`'s
+readiness gate says the frozen spec **cannot be built** — that one needs `/cohorte-spec`, not passes. **Each
+fix pass is committed** (`loop(<id>): fix pass <i>`) — that's your way back after N autonomous passes —
+and **no fix runs on the last pass**, since fixing without a review behind it leaves unaudited code.
+
+**It's resumable.** Before each phase the driver stamps `status: in-progress` + `loop_pass` +
+`loop_phase` into the spec's front-matter (plain `awk`, zero tokens), and a terminal `in-review` or
+`blocked` on exit. So `--resume` continues at pass 3 instead of re-paying passes 1 and 2 — and the spec
+itself tells you, `/cohorte-doctor` and the dashboard where the loop got to.
 
 **The loop does not run in your session.** Each phase is a separate `claude -p` child with its own
 fresh context, driven by `pipeline/scripts/loop.sh`; all of their output goes to
@@ -263,7 +271,7 @@ fresh context, driven by `pipeline/scripts/loop.sh`; all of their output goes to
 line per phase and a three-line summary. That's the whole design: a slash command can't `/clear`
 itself, so a conversational loop would pile the diff plus N review reports plus N contracts into a
 history that is re-sent at input price every turn — it would cost more than the loop saves. The
-machine contract is `specs/reports/<id>.verdict.json`, which `/review` now writes on every run; no
+machine contract is `specs/reports/<id>.verdict.json`, which `/cohorte-review` now writes on every run; no
 prose is ever parsed.
 
 ### Run features in parallel — one session per feature
@@ -271,16 +279,16 @@ prose is ever parsed.
 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.
+while feature A's `/cohorte-build` runs its agents (minutes of wall-clock you'd otherwise spend waiting), a
+second Claude Code session can `/cohorte-spec` or `/cohorte-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:                   /review feat-a → /ship feat-a
-session 2:                   /review feat-b → …
+session 1 (main checkout):   /cohorte-spec feat-a → /cohorte-build feat-a  (agents run…)
+session 2 (main checkout):   /cohorte-spec feat-b → /cohorte-build feat-b  (agents run…)
+session 1:                   /cohorte-review feat-a → /cohorte-ship feat-a
+session 2:                   /cohorte-review feat-b → …
 ```
 
 Rules that make it safe:
@@ -293,10 +301,10 @@ Rules that make it safe:
 - **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
+- `/cohorte-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.
+- `/cohorte-doctor` check 6 shows the live slot table (feature ↔ worktree ↔ ports) when you lose track.
 
 ### Workflows — deterministic multi-agent runs (opt-in)
 
@@ -315,7 +323,7 @@ The essentials:
 - **The conversational commands stay the default path** — and the fallback when workflows are
   disabled or the client is too old. A workflow runs only when you explicitly ask for it
   ("run the review workflow").
-- **Prerequisite: Claude Code ≥ 2.1.154** with workflows enabled. `/doctor` (check 8) tells you
+- **Prerequisite: Claude Code ≥ 2.1.154** with workflows enabled. `/cohorte-doctor` (check 8) tells you
   which path your session will take and why.
 - **No input mid-run — questions at the edges.** A workflow runs to completion without asking
   anything: whatever would have been a mid-run question lands in the result at the end. The
@@ -331,9 +339,9 @@ Details: `profile/SCHEMA.md` §Workflows.
 
 Cohorte can send **anonymous** usage pings (core version, OS, phase name, duration, per-surface
 result counts, and a *hash* of the feature id — never repo names, paths, code, or IPs). It is
-**strictly opt-in**: `/init-pipeline` asks once per machine, the default is No, and both answers are
+**strictly opt-in**: `/cohorte-init-pipeline` asks once per machine, the default is No, and both answers are
 recorded so you're never re-asked. Withdraw anytime (`telemetry.enabled: false` in
-`~/.claude/cohorte.config.yaml`); erase your history anytime (`/doctor` prints your `install_id`,
+`~/.claude/cohorte.config.yaml`); erase your history anytime (`/cohorte-doctor` prints your `install_id`,
 the collector's `DELETE /v1/install/<id>` drops it). Full spec + GDPR details:
 `profile/SCHEMA.md` §Telemetry (including the collector API contract).
 
@@ -355,12 +363,12 @@ install.sh              # script installer (fresh + --update) for no-Node enviro
 install.ps1             # same installer for Windows PowerShell (fresh + -Update)
 core/                   # copied verbatim into ~/.claude (global) or <project>/.claude (bundled)
   agents/               # implementer.template.md (rendered per surface) + review / release / profile-reader
-  commands/             # init-pipeline + the pipeline commands + /update-pipeline
+  commands/             # init-pipeline + the pipeline commands + /cohorte-update-pipeline
   hooks/                # gate.py (destructive-command gate; branch-aware; preflight phase gate)
   templates/            # handoff / brainstorm-return / design-brief / review-feedback / pr-body / spec
   workflows/            # opt-in Workflow-runtime scripts: review.js / audit.js / refactor.js
 profile/
-  PIPELINE.template.md  # the profile skeleton /init-pipeline fills
+  PIPELINE.template.md  # the profile skeleton /cohorte-init-pipeline fills
   SCHEMA.md             # field reference
   cohorte.config.template.yaml   # seeds ~/.claude/cohorte.config.yaml (kanban)
 scripts/                # worktree-isolation templates + shipped preflight/kanban/telemetry scripts

package/bin/cli.js

@@ -45,7 +45,7 @@ Commands:
   update    Refresh the stack-agnostic core only. PIPELINE.md, rendered surface
             agents, gate-config.json, settings.json and your filled
             ~/.claude/cohorte.config.yaml are never touched.
-  dashboard Serve a local web cockpit for the pipeline (freshness, /doctor
+  dashboard Serve a local web cockpit for the pipeline (freshness, /cohorte-doctor
             health, specs board, install/update actions). Binds 127.0.0.1:4317
             by default (loopback only — its actions execute code). --host=ADDR
             to expose (e.g. --host=0.0.0.0, prints a security warning). --open
@@ -163,7 +163,7 @@ function copyCore() {
   // every caller chains them with `|| true`, the result was silent: no kanban card
   // moves, no telemetry pings, no error. The shell installers named them explicitly
   // and this port drifted. The rule below needs no list to keep in sync: a `<x>.sh`
-  // with an `<x>.sh.template` sibling is rendered per-project by /init-pipeline, so
+  // with an `<x>.sh.template` sibling is rendered per-project by /cohorte-init-pipeline, so
   // only the template ships; every other `.sh` is a shipped executable.
   const scriptFiles = fs.readdirSync(path.join(src, 'scripts'));
   for (const f of scriptFiles) {
@@ -178,7 +178,7 @@ function copyCore() {
   }
   fs.copyFileSync(path.join(src, 'core', 'agents', 'implementer.template.md'),
                   path.join(pipelineDir, 'implementer.template.md'));
-  // /doctor reads this to tell the human what they're missing; the shell installers
+  // /cohorte-doctor reads this to tell the human what they're missing; the shell installers
   // have always copied it, this port never did.
   const changelog = path.join(src, 'CHANGELOG.md');
   if (fs.existsSync(changelog)) fs.copyFileSync(changelog, path.join(pipelineDir, 'CHANGELOG.md'));
@@ -211,7 +211,7 @@ function scrubTddGate() {
 // the fixed (non-rendered) agents: the dev review/release pipeline agents
 function copyFixedAgents() {
   fs.mkdirSync(path.join(dest, 'agents'), { recursive: true });
-  // Every agent in core/agents/ EXCEPT the *.template.md ones, which /init-pipeline renders
+  // Every agent in core/agents/ EXCEPT the *.template.md ones, which /cohorte-init-pipeline renders
   // per-surface. Until 1.2.6 this was a hardcoded ['review.md', 'release.md'] that never grew
   // the agents the shell installers copy, so `npx cohorte install` shipped a command with no
   // agent to dispatch — the run reported the command as not installed.
@@ -227,6 +227,22 @@ function copyFixedAgents() {
   // 1.5.0 removed the /smoke phase; copy-over never deletes, so scrub the orphan agent+command.
   fs.rmSync(path.join(dest, 'agents', 'smoke.md'), { force: true });
   fs.rmSync(path.join(dest, 'commands', 'smoke.md'), { force: true });
+  // 1.4.0 removed /cycle and its workflow — and no installer ever scrubbed them, so every
+  // install since has kept offering a command that dispatches a workflow whose phases were
+  // later deleted. A dead command is worse than a missing one: the model can still fire it.
+  fs.rmSync(path.join(dest, 'commands', 'cycle.md'), { force: true });
+  fs.rmSync(path.join(dest, 'workflows', 'cycle.js'), { force: true });
+  // 1.6.0 renamed /loop → /drive: Claude Code's own built-in /loop shadowed ours, so a leftover
+  // commands/loop.md is a command the user can never reach — scrub it rather than leave a decoy.
+  fs.rmSync(path.join(dest, 'commands', 'loop.md'), { force: true });
+  // 2.0.0 prefixed every command with `cohorte-`, which ends the shadowing problem for good.
+  // Copy-over never deletes, so all 13 bare names would survive an upgrade as decoys — and a
+  // stale /build is the worst kind: it still dispatches implementers, from a 1.x command file
+  // that knows nothing of this core's contract. /drive goes too (it became /cohorte-loop).
+  for (const c of ['align-ds', 'audit', 'brainstorm', 'build', 'doctor', 'drive', 'fix',
+                   'init-pipeline', 'refactor', 'review', 'ship', 'spec', 'update-pipeline']) {
+    fs.rmSync(path.join(dest, 'commands', `${c}.md`), { force: true });
+  }
   scrubResearchQuestionnaire();
 }
 
@@ -271,10 +287,10 @@ function setCfg(text, cfgKey, value) {
 }
 
 // Fill the seeded config from a short TTY interview (shared Obsidian vault for the kanban mirror).
-// Kanban is per-project, so it is wired later by /init-pipeline — not asked here.
+// Kanban is per-project, so it is wired later by /cohorte-init-pipeline — not asked here.
 async function promptConfig(text) {
   console.log('\n  Quick setup (Enter to skip — you can also wire this later via');
-  console.log('  /init-pipeline or /update-pipeline):');
+  console.log('  /cohorte-init-pipeline or /cohorte-update-pipeline):');
   const vault = await ask('    · absolute path to your shared Obsidian vault (for the kanban mirror): ');
   if (vault) text = setCfg(text, 'vault_path', `"${vault}"`);
   return text;
@@ -291,7 +307,7 @@ async function seedConfig() {
   if (fs.existsSync(cfg)) { console.log(`  · kept your existing ${cfg}`); return; }
   if (legacy) {
     console.log(`  · found legacy ${legacy} — kept as-is (still read as a fallback).`);
-    console.log('    Run /update-pipeline to migrate it into cohorte.config.yaml + wire the kanban.');
+    console.log('    Run /cohorte-update-pipeline to migrate it into cohorte.config.yaml + wire the kanban.');
     return;
   }
   fs.mkdirSync(path.dirname(cfg), { recursive: true });
@@ -302,7 +318,7 @@ async function seedConfig() {
     console.log(`  · seeded ${cfg} from your answers`);
   } else {
     fs.writeFileSync(cfg, text);
-    console.log(`  · seeded ${cfg} (disabled defaults — enable via /init-pipeline or /update-pipeline)`);
+    console.log(`  · seeded ${cfg} (disabled defaults — enable via /cohorte-init-pipeline or /cohorte-update-pipeline)`);
   }
 }
 
@@ -383,21 +399,21 @@ if (scope === 'global') {
 ✓ pipeline core installed globally into ${dest}  (version ${VERSION})
   gate hook: ${hookState}  (reads each repo's .claude/gate-config.json; silent where absent)
 
-The commands (/init-pipeline, /brainstorm, /build …) and the review/release agents are now
+The commands (/cohorte-init-pipeline, /cohorte-brainstorm, /cohorte-build …) and the review/release agents are now
 available in EVERY project on this machine — nothing is copied per repo.
 
 Per repo:
   1. Open the project in Claude Code.
-  2. Run  /init-pipeline  — it generates PIPELINE.md, renders the surface agents, writes
+  2. Run  /cohorte-init-pipeline  — it generates PIPELINE.md, renders the surface agents, writes
      .claude/gate-config.json, and drops a committed .claude/pipeline.json pointer so
      teammates know to install the global core (${REPO_URL}).
-  3. Commit PIPELINE.md + .claude/, then  /brainstorm  to start a feature.
+  3. Commit PIPELINE.md + .claude/, then  /cohorte-brainstorm  to start a feature.
 
 Update later with:  npx cohorte@latest update --global
 
 Global kanban config, user-scoped — optional:
   · One consolidated file: ${path.join(globalDir, 'cohorte.config.yaml')}
-  · Don't hand-edit it — /init-pipeline (new project) and /update-pipeline (existing) wire it
+  · Don't hand-edit it — /cohorte-init-pipeline (new project) and /cohorte-update-pipeline (existing) wire it
     for you: creating + syncing an Obsidian kanban board of the pipeline in your shared vault.`);
 } else if (mode === 'install') {
   console.log(`→ installing pipeline core into ${dest}`);
@@ -414,9 +430,9 @@ Global kanban config, user-scoped — optional:
 
 Next:
   1. Open the project in Claude Code.
-  2. Run  /init-pipeline   — it detects your stack, asks the gaps, and generates
+  2. Run  /cohorte-init-pipeline   — it detects your stack, asks the gaps, and generates
      PIPELINE.md + renders one implementer agent per surface.
-  3. Commit PIPELINE.md, then  /brainstorm  to start a feature.
+  3. Commit PIPELINE.md, then  /cohorte-brainstorm  to start a feature.
 
 Update later with:  npx cohorte@latest update
 Prefer one shared core across all your repos?  Re-run with  --global.`);
@@ -428,6 +444,6 @@ Prefer one shared core across all your repos?  Re-run with  --global.`);
   bumpPointerVersion(path.join(dest, 'pipeline.json'));
   console.log(`
 ✓ core refreshed to ${VERSION}. Your PIPELINE.md, rendered surface agents, gate-config.json and
-  settings.json were left as-is. Re-run /init-pipeline if your stack changed.`);
+  settings.json were left as-is. Re-run /cohorte-init-pipeline if your stack changed.`);
 }
 })();