cohorte 2.0.2 → 2.2.0

package/install.sh

@@ -71,6 +71,27 @@ else
 fi
 [ -d "$src/core" ] || { echo "error: pipeline source not found (no core/ in $src)" >&2; exit 1; }
 
+# --- delegate to the Node CLI ------------------------------------------------
+# Since 2.2.0 the commands in core/ are runtime-NEUTRAL sources: they carry capability
+# conditionals (`<!-- cohorte:if subagents -->`) and path tokens (`<core>`, `<state>`) that
+# the adapter resolves per coding agent. Copying them verbatim, as this script used to,
+# would install prompts full of unresolved markers — an install that looks successful and
+# instructs the model with text meant for a different runtime. There is no shell renderer,
+# so hand the whole job to bin/cli.js, which is the documented route anyway.
+if command -v node >/dev/null 2>&1; then
+  set -- install
+  [ "$mode" = "update" ] && set -- update
+  [ "$scope" = "global" ] && set -- "$@" --global
+  [ "$scope" = "project" ] && set -- "$@" "$target"
+  exec node "$src/bin/cli.js" "$@"
+fi
+echo "error: cohorte needs Node ≥ 18 to install." >&2
+echo "  The pipeline's commands are rendered per coding agent (Claude Code, Codex, Cursor," >&2
+echo "  Gemini CLI, OpenCode) at install time; there is no shell equivalent of that step," >&2
+echo "  and a raw copy would install prompts this runtime cannot follow." >&2
+echo "  Install Node, then:  npx cohorte install${scope:+ }$([ "$scope" = global ] && echo --global)" >&2
+exit 1
+
 # --- resolve the destination .claude dir ------------------------------------
 if [ "$scope" = "global" ]; then
   dest="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
@@ -107,11 +128,8 @@ copy_core() {
   cp "$src/scripts/kanban-move.sh"       "$dest/pipeline/scripts/"
   cp "$src/scripts/telemetry-send.sh"    "$dest/pipeline/scripts/"
   cp "$src/scripts/preflight.sh"         "$dest/pipeline/scripts/"
-  cp "$src/scripts/loop.sh"              "$dest/pipeline/scripts/"
-  cp "$src/scripts/loop-detach.sh"       "$dest/pipeline/scripts/"
   chmod +x "$dest/pipeline/scripts/kanban-move.sh" "$dest/pipeline/scripts/telemetry-send.sh" \
-           "$dest/pipeline/scripts/preflight.sh" "$dest/pipeline/scripts/loop.sh" \
-           "$dest/pipeline/scripts/loop-detach.sh" 2>/dev/null || true
+           "$dest/pipeline/scripts/preflight.sh" 2>/dev/null || true
   cp "$src/core/agents/implementer.template.md" "$dest/pipeline/"
   [ -f "$src/CHANGELOG.md" ] && cp "$src/CHANGELOG.md" "$dest/pipeline/"
   printf '%s\n' "$ver" > "$dest/pipeline/VERSION"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cohorte",
-  "version": "2.0.2",
-  "description": "Portable, stack-agnostic multi-agent development pipeline for Claude Code — install the core, run /cohorte-init-pipeline, and it adapts to your project's stack.",
+  "version": "2.2.0",
+  "description": "Portable, stack-agnostic multi-agent development pipeline for Claude Code, Codex CLI, Cursor, Gemini CLI and OpenCode \u2014 install the core, run /cohorte-init-pipeline, and it adapts to your project's stack.",
   "bin": {
     "cohorte": "bin/cli.js"
   },
@@ -38,6 +38,10 @@
   "keywords": [
     "claude",
     "claude-code",
+    "codex",
+    "cursor",
+    "gemini-cli",
+    "opencode",
     "agents",
     "pipeline",
     "multi-agent"

package/profile/PIPELINE.template.md

@@ -2,7 +2,7 @@
 
 > **Generated by `/cohorte-init-pipeline`.** This is the project profile: the single place the
 > portable multi-agent pipeline reads for everything stack-specific. The pipeline core
-> under `.claude/` is generic and references THIS file by section — keep project facts
+> in the pipeline core is generic and references THIS file by section — keep project facts
 > here, never hardcoded into agent prompts. Kept current by `/cohorte-update-pipeline` (reconcile:
 > new fields are topped up, your values never overwritten). Rendered agent files are
 > regenerated from this profile on every reconcile — customize agents through §Conventions
@@ -52,7 +52,7 @@ surfaces:
   - key: backend                              # short id, used as agent name + scope
     path: apps/api                            # the ONLY tree this surface's agent may touch
     label: backend (AdonisJS)
-    agent: backend                            # rendered agent file: .claude/agents/backend.md
+    agent: backend                            # rendered as backend.md in this runtime's agents dir
     tools: [Read, Write, Edit, Bash, Grep, Glob, mcp__serena]   # mcp__<provider> mirrors retrieval.provider
     model: sonnet                             # frontmatter model tier: sonnet | haiku | inherit
                                               #   sonnet = default (applies the frozen contract — cheap
@@ -97,6 +97,26 @@ contract:
   index: packages/shared-types/src/index.ts   # barrel to export from, or "" if none
   authored_by: lead                           # NEVER the implementer agents
 
+# ── release notes (optional) ────────────────────────────────────────────────
+# A per-feature release note the project's versioning tool consumes. When
+# enabled, /cohorte-ship authors it BEFORE dispatching the release agent, so it
+# ships inside the release commit. Repos whose CI fails a PR that lacks one
+# (Changesets' `changeset` job) MUST set this — otherwise every ship goes red.
+release_notes:
+  enabled: <true | false>                     # false ⇒ /cohorte-ship §2b is a no-op
+  tool: <changesets | none>                   # what consumes the file
+  dir: .changeset                             # where the note is authored
+  filename: "<feature_id>.md"                 # one file per feature
+  anchor_package: shared-types                # sole key in the front-matter; a lockstep/fixed group propagates the bump
+  language: <ui_language | English>           # language of the note's prose
+  forbid_levels: []                           # bumps project policy refuses, e.g. [major] while 0.x
+  empty_cmd: "pnpm changeset --empty"         # when no version should move; "" if the tool has no such escape hatch
+  ci_job: changeset                           # CI job that fails when the note is missing (name it so /cohorte-ship §5 recognizes the red)
+  guidance: |                                 # rules the lead follows when writing the note (project policy)
+    major = the deploy needs an operator action; minor = a user-visible capability;
+    patch = fix/perf/refactor with no change of use. No client names, no internal
+    paths, no exploitable attack vector.
+
 # ── repo-wide commands (root unless noted) ──────────────────────────────────
 commands:
   install: pnpm install
@@ -138,7 +158,7 @@ isolation:
   compose_file: docker-compose.yml
   registry: .worktrees/slots.tsv
 
-# ── gate (drives .claude/hooks/gate.py + settings.json) ─────────────────────
+# ── gate (drives the pipeline gate hook + permissions) ─────────────────────
 # Confirm-first or hard-deny on dangerous Bash, inspecting the FULL command
 # string (so chained `cd x && …` forms are caught).
 gate:
@@ -164,10 +184,10 @@ gate:
     - "git rebase"
     - "git reset"
     - "docker compose"
-  # Phase gate: review dispatches require a fresh `.claude/preflight.ok` stamp,
+  # Phase gate: review dispatches require a fresh `preflight.ok` stamp,
   # written by pipeline/scripts/preflight.sh when typecheck+lint+tests are green —
   # gate.py "ask"s the dispatch when the stamp is missing, stale, or the code changed since.
-  # The stamp is local: keep `.claude/preflight.ok` gitignored, never committed.
+  # The stamp is local: keep `preflight.ok` gitignored, never committed.
   preflight:
     enabled: true
     agents: [review]                          # subagent_types the stamp gates
@@ -176,7 +196,8 @@ gate:
 ```
 
 > **Note.** The **kanban** board link is **user-scoped** — NOT configured here. Its facts live in the
-> consolidated `~/.claude/cohorte.config.yaml`, read at runtime (the kanban board is keyed by this
+> consolidated user config (`~/.claude/cohorte.config.yaml`, or `~/.cohorte/cohorte.config.yaml` on
+> a non-Claude runtime), read at runtime (the kanban board is keyed by this
 > profile's `name`). This project profile only governs the dev pipeline (`/cohorte-brainstorm…/cohorte-ship`).
 
 ---

package/profile/SCHEMA.md

@@ -33,6 +33,15 @@ generic pipeline uses it, so a stateless agent can read/regenerate the profile c
 | `contract.mechanism`                 | enum         | build, lead                       | `shared-types-zod`/`openapi`/`protobuf`/`json-schema`/`none`. |
 | `contract.path` `.ext` `.index`      | string       | build                             | Where `<feature_id>` contract is authored + barrel.           |
 | `contract.authored_by`               | const `lead` | build                             | Implementers import it read-only, never edit.                 |
+| `release_notes.enabled`              | bool         | ship                              | `false` ⇒ skip note authoring (§2b of /cohorte-ship). See §Release notes. |
+| `release_notes.tool`                 | enum         | ship                              | `changesets`/`none` — what consumes the file.                 |
+| `release_notes.dir` `.filename`      | string       | ship                              | Where the per-feature note is authored, e.g. `.changeset/<feature_id>.md`. |
+| `release_notes.anchor_package`       | string       | ship                              | Sole key in the note's front-matter; a lockstep/`fixed` group propagates the bump. |
+| `release_notes.language`             | string       | ship                              | Language of the note's prose — usually `ui_language`.         |
+| `release_notes.forbid_levels`        | list         | ship                              | Bump levels project policy refuses, e.g. `[major]` while `0.x`. |
+| `release_notes.empty_cmd`            | string       | ship                              | Escape hatch when no version should move; `""` if none.       |
+| `release_notes.ci_job`               | string       | ship                              | CI job that fails on a missing note — lets §5 name the red check. |
+| `release_notes.guidance`             | string       | ship                              | Project policy the lead follows when picking the bump + writing the prose. |
 | `commands.*`                         | string       | all                               | Repo-wide install/dev/lint/format/typecheck/test + migrate.   |
 | `commands.test_quiet` `.lint_quiet`  | string       | review, audit, workflows          | Repo-wide bridled variants — what the `/cohorte-review` pre-flight runs. Same fallback as the per-surface ones. |
 | `rbac.enabled`                       | bool         | brainstorm, review                | Toggle RBAC personas + authz audit.                           |
@@ -70,7 +79,7 @@ generic pipeline uses it, so a stateless agent can read/regenerate the profile c
 - **Commands** (`/cohorte-build`, `/cohorte-review`, …) parse the `yaml pipeline-profile` block to know how
   many surfaces to dispatch, the contract mechanism, the commands, and the capability flags.
 - **Hook** (`gate.py`) reads `gate.deny`/`gate.ask`/`gate.ask_on_default_branch`/`gate.default_branch`
-  from a generated `.claude/gate-config.json`. The last two make git + docker free on feature branches
+  from a generated `<state>/gate-config.json`. The last two make git + docker free on feature branches
   but confirm-gated on the default branch (branch resolved at run time via `git rev-parse`).
 - **Scripts** (`new-feature.sh`) read the `isolation` block (rendered in at init).
 
@@ -160,7 +169,7 @@ the frozen contract as the only cross-surface channel**. So specialization means
 
 Coarse first, specialize on evidence: start with one `frontend` / `backend` surface each; split only a
 surface that's proven slow and cleanly separable. The evidence lives in
-the **main checkout's** `.claude/pipeline-metrics.jsonl` (gitignored) — one JSONL line per phase batch
+the **main checkout's** `<state>/pipeline-metrics.jsonl` (gitignored) — one JSONL line per phase batch
 (`ts`/`feature`/`phase`/`seconds`/`surfaces:{key: result}`), appended by `/cohorte-build`, `/cohorte-review`
 and `/cohorte-fix`.
 **`surfaces` keys are surface keys, nothing else** — run-level facts go in their own top-level
@@ -168,7 +177,7 @@ fields. Anything put inside `surfaces` is read
 as a surface: the dashboard renders it as a row in the per-surface table and scores a non-`ok`
 value as that surface failing. Always the main checkout, never the feature worktree (which dies at teardown while
 metrics must accumulate across features) — resolve from anywhere with
-`$(dirname "$(git rev-parse --git-common-dir)")/.claude/pipeline-metrics.jsonl`. Read it before
+`$(dirname "$(git rev-parse --git-common-dir)")/<state>/pipeline-metrics.jsonl`. Read it before
 proposing a split: split the surface that actually dominates wall-clock, not the one that feels big.
 
 ## Measuring cost — what's slow vs what's expensive
@@ -181,7 +190,7 @@ to log it. For what's EXPENSIVE, use Claude Code's own accounting:
   over the last 24 h / 7 d (e.g. _"Top subagents: frontend 7 %, backend 4 % · Top skills: /cohorte-build 1 %,
   /cohorte-review 1 %"_). That IS the per-phase ledger — approximate (share-of-total, machine-local, not exact
   tokens). Read it to see which surface/command actually dominates the bill before you tune a `model` tier.
-- **OpenTelemetry** (exact numbers + dashboards) — add an `env` block to `~/.claude/settings.json`:
+- **OpenTelemetry** (exact numbers + dashboards) — add an `env` block to `this runtime's settings file`:
   `{"env":{"CLAUDE_CODE_ENABLE_TELEMETRY":"1","OTEL_METRICS_EXPORTER":"otlp","OTEL_EXPORTER_OTLP_PROTOCOL":"http/protobuf","OTEL_EXPORTER_OTLP_ENDPOINT":"http://localhost:4318"}}`
   and point it at a collector. Metrics `claude_code.token.usage` + `claude_code.cost.usage` carry
   `session.id` + model + type (input/output/cacheRead). Subagent tokens roll into the session total;
@@ -217,28 +226,25 @@ Rules for every consumer (implementers, preflight, `/cohorte-audit` gates, workf
 `/cohorte-init-pipeline` **asks** for these variants (detected defaults offered first) instead of silently
 storing a bare `pnpm test` as the thing agents execute; `/cohorte-update-pipeline` tops up older profiles.
 
-## Spec status — the lifecycle state machine (and the loop's resume state)
+## Spec status — the lifecycle state machine
 
 A spec's front-matter `status` is not a label, it is the pipeline's **state**: every command routes on
-it, the dashboard boards on it, the kanban backfill maps it to a column, and `/cohorte-loop --resume` reads it
-back to continue an interrupted autonomous run. Six states, and exactly one writer each:
+it, the dashboard boards on it, and the kanban backfill maps it to a column. Six states:
 
 | status | meaning | written by | who may build it |
 | --- | --- | --- | --- |
 | `draft` | the interview is open, nothing is frozen | `/cohorte-spec` Mode A | no |
 | `frozen` | the contract is frozen — the handoff to `/cohorte-build` | `/cohorte-spec` Mode A freeze | yes |
-| `in-progress` | a `/cohorte-loop` is driving this spec right now (or died doing it) | `scripts/loop.sh`, before each phase | yes |
-| `in-review` | reviewed / awaiting the next round or `/cohorte-ship` | `/cohorte-spec` Mode B, `/cohorte-fix`, `loop.sh` on a clean exit | yes |
-| `blocked` | a loop gave up here (ceiling, non-convergent, no verdict, not implementable) | `loop.sh` on any non-zero exit | yes, with the reason named |
+| `in-progress` | a round is under way on this spec (or died mid-way) | an automated driver, if any | yes |
+| `in-review` | reviewed / awaiting the next round or `/cohorte-ship` | `/cohorte-spec` Mode B, `/cohorte-fix` | yes |
+| `blocked` | a round gave up here (non-convergent, no verdict, not implementable) | an automated driver, if any | yes, with the reason named |
 | `shipped` | the PR is open; the status flip is part of the release commit | `/cohorte-ship` | no |
 
-**The resume contract.** Before every phase, `loop.sh` stamps `status: in-progress` plus `loop_pass`
-(the review pass it is on) and `loop_phase` (`build`/`review`/`fix`) into the spec — deterministically,
-with `awk`, spending **no tokens** on state it will need later. On exit it stamps a terminal status:
-`in-review` + `loop_phase: done` when clean, `blocked` otherwise. `/cohorte-loop <id> --resume` then continues
-at the recorded pass instead of pass 1, so a session killed at pass 3 of 5 does not re-pay passes 1–2.
-The build is still skipped or redone by the build stamp alone (`specs/reports/<id>.built`, written only
-after a build that finished), so an interrupted *build* correctly rebuilds.
+**`in-progress` and `blocked` are for external drivers.** No shipped command writes them: the
+built-in autonomous driver (`/cohorte-loop`) was retired in 2.2.0, and the human-driven cycle moves
+`frozen` → `in-review` → `shipped`. They stay valid states because specs in existing repos carry
+them, and because anything automating the cycle from outside needs somewhere to record "a round is
+under way" and "a round gave up". Every reader still routes on them; nothing produces them.
 
 Corollaries worth knowing:
 
@@ -270,8 +276,8 @@ Non-negotiables, in every phase:
 - **Never speak for a dead agent.** You did not see its work: report what the *tree* says (quiet
   commands, redirected to a file, grepped), not what a handoff would have said.
 - **Never let it reach a driver as clean.** `/cohorte-build` writes `dead[]` into
-  `specs/reports/<id>.build.json`, `/cohorte-review` writes `unreviewed[]` into the verdict; `scripts/loop.sh`
-  aborts on either with **exit 2** *before* it reads `blocking`, since a dead reviewer makes
+  `specs/reports/<id>.build.json`, `/cohorte-review` writes `unreviewed[]` into the verdict; a driver
+  must abort on either *before* it reads `blocking`, since a dead reviewer makes
   `blocking == 0` a statement about code nobody read.
 - **`unreviewed` is separate from `blocking` on purpose.** Faking a count in `blocking` to force a
   driver's hand would corrupt the one field the whole contract rests on; a driver reads them as two
@@ -291,8 +297,8 @@ of the step: a spec that cannot be built does not get cheaper by being built on
   the design gate. Each maps to `NOT-READY` (a surface would have to invent the answer) or
   `RESERVATIONS` (a surface can proceed on a stated assumption).
 - **`NOT-READY` aborts the build with no agent spawned** and sends the human to `/cohorte-spec`.
-  `scripts/loop.sh` reads the same file and exits **4** (`not implementable`) — the one loop outcome
-  that more passes cannot fix.
+  A driver reads the same file and must stop rather than retry — it is the one outcome more passes
+  cannot fix.
 - **`RESERVATIONS` never blocks.** Each gap is inlined verbatim into the dispatch of the surface it
   affects, as an assumption the implementer must apply *and* flag in its handoff. A gate that stalled a
   sound build on a missing error case would cost more human round-trips than it saves.
@@ -316,7 +322,7 @@ own out-of-scope reason.
   `## Remediation`, which is what `/cohorte-fix` re-dispatches.
 - `/cohorte-audit` **carries open `deferred:` items over** when it rewrites the backlog; overwriting them away
   is the one way they silently vanish.
-- The verdict JSON carries `deferred: <n>` (informational, outside `blocking`), so `/cohorte-loop` can name
+- The verdict JSON carries `deferred: <n>` (informational, outside `blocking`), so a driver can name
   them in its closing line without reading a report.
 
 ## Decisions — the transverse decision journal
@@ -350,14 +356,14 @@ variants) with all output redirected to `specs/reports/<id>.preflight.txt`:
   there: zero agents are spawned.** A reviewer dispatched onto code that doesn't compile burns its
   whole run rediscovering what `tsc` already printed for free — the failure goes straight to the
   human (or `/cohorte-fix`) instead.
-- **All green** ⇒ the script stamps `.claude/preflight.ok` (`<epoch> <HEAD sha> <tree digest>` —
+- **All green** ⇒ the script stamps `<state>/preflight.ok` (`<epoch> <HEAD sha> <tree digest>` —
   local and **gitignored**; a versioned stamp describes the tree *before* its own commit and rides
   into every clone and worktree, which breaks the gate both ways).
 
 `hooks/gate.py` enforces the stamp as a **phase gate** (the `preflight` block of `gate-config.json`,
 generated from `gate.preflight`): a Task dispatch of a listed `subagent_type` (default
 `review`) with a missing/stale stamp — older than `max_age_minutes`, or the digest no longer
-matches the working tree (`.claude` and `specs` excluded, so the pipeline's own writes and a
+matches the working tree (`.claude`, `.cohorte` and `specs` excluded, so the pipeline's own writes and a
 commit of already-verified code do not invalidate it) — gets an
 "ask", so a lead can't accidentally skip the gate but a human can consciously override it. The gate
 hook fires for **every** agent in the session, including subagents spawned by the Workflow runtime
@@ -378,8 +384,9 @@ this exact procedure so a surface is always defined the same way. To add surface
    scaffolding; `inherit` only when the surface makes real design decisions worth the lead's model),
    the five `*_cmd`s (derive from the surface's `package.json` / workspace
    filter, mirroring a sibling surface), and `uses_design`.
-2. **Render the agent file** `.claude/agents/<agent>.md` from `pipeline/implementer.template.md`
-   (resolve bundled `.claude/` vs global `~/.claude/`), substituting `<SURFACE_AGENT>`, `<SURFACE_LABEL>`,
+2. **Render the agent file** `<agents>/<agent>.md` from `<core>/pipeline/implementer.template.md`
+   — the template is already rendered for this runtime, so only the placeholders are yours to fill —
+   substituting `<SURFACE_AGENT>`, `<SURFACE_LABEL>`,
    `<SURFACE_PATH>`, `<SURFACE_TOOLS>`, `<SURFACE_MODEL>`, `<PROJECT_NAME>`, and the surface-specific
    blocks (`<SURFACE_EXTRA_NEVER>`, `<SURFACE_DESIGN_INPUT>`, `<SURFACE_TDD_STEP1>` — leave the design
    ones empty unless `uses_design`). Fill `<SURFACE_CONVENTIONS>` with the surface's convention slice
@@ -412,6 +419,36 @@ this exact procedure so a surface is always defined the same way. To add surface
 Removing/merging a surface is the reverse: drop the `surfaces[]` entry, delete its agent file, fold its
 conventions. Never leave an agent file with no matching `surfaces[]` entry (orphan) or vice-versa.
 
+## Release notes — the per-feature note the versioning tool consumes
+
+Many repos gate merges on a **per-feature release note**: Changesets' `changeset` CI job fails any PR
+that touches product code without a `.changeset/*.md`. That file is **not** something the release
+agent can invent — picking the bump level is project policy (semver over an API vs. over a product,
+a `0.x` rule forbidding `major`, what counts as user-visible), and the prose is outward-facing copy.
+It is the **lead's** to write, exactly like the contract.
+
+The failure mode this block exists to prevent is silent and reproducible: the requirement lives in the
+project's `CLAUDE.md`, which the ship flow never reads, so `/cohorte-ship` completes, opens the PR,
+moves the kanban card to **Shipped** — and CI goes red on a job nobody looked at. The feature reads as
+shipped while being unmergeable. Encoding it in the profile is what makes the step survive a stateless
+lead.
+
+- **Authored before the dispatch**, next to the `status: shipped` flip (`/cohorte-ship` §2b), so the note
+  lands **inside** the release commit. Written after the fact it needs a second commit, and the PR is
+  already open and red.
+- **One key in the front-matter** — `anchor_package`. Lockstep/`fixed` version groups propagate the bump
+  from it to every other workspace; listing more is how a repo ends up with a package bumped twice.
+- **`forbid_levels`** encodes policy the tool itself may not enforce. The common one: while the product
+  is `0.y.z`, a `major` changeset makes Changesets jump to `1.0.0` with no human deciding it — so `0.x`
+  repos forbid `major` and declare a breaking change as `minor`.
+- **Ask, don't guess, on an ambiguous bump.** Between two defensible levels (a refactor that also changes
+  what the user sees), state the reading and let the human pick — a wrong bump is a published version
+  number, not a fixable draft.
+- **`empty_cmd`** covers the honest no-op: a PR that touches product code but must move no version.
+  Prefer it to skipping the step; the CI job wants a file, not a version.
+
+`enabled: false` (or `tool: none`) ⇒ §2b is a no-op and nothing below applies.
+
 ## Reconcile — bringing generated files up to the current core
 
 `/cohorte-init-pipeline` is **one-time per project**. Afterwards, `/cohorte-update-pipeline` runs this procedure so a
@@ -423,37 +460,40 @@ files automatically. It works because every generated artifact is a **determinis
    `pipeline/PIPELINE.template.md`: every block/field the template has and the profile lacks is added
    with its documented default (e.g. `surfaces[].model: sonnet`, `retrieval.provider: serena`).
    **Ask only when a new field is a genuine human decision** (batch into ONE question set); never
-   change a value the profile already sets; never rewrite the prose sections.
+   change a value the profile already sets; never rewrite the prose sections. `release_notes` is one
+   such decision and must not be defaulted blind: detect a versioning tool / note-enforcing CI job per
+   `/cohorte-init-pipeline` Phase 1, and if there is one, ask Phase 2's release-notes question (anchor
+   package, language, bump policy, forbidden levels). No tool found ⇒ top up with `enabled: false`.
 2. **Re-render agent frontmatter + body.** For each `surfaces[]` entry, re-render
-   `.claude/agents/<agent>.md` from the current `implementer.template.md` per §Rendering above. Safe by
+   `<agents>/<agent>.md` from the current `implementer.template.md` per §Rendering above. Safe by
    doctrine: rendered agents are regenerable artifacts — hand-written rules belong in `PIPELINE.md`
    §Conventions (which reconcile never touches), NOT in agent files, where they'd be clobbered here.
-3. **Additive settings patch.** Bring `.claude/settings.json` + `gate-config.json` up to the current
-   init spec (missing `allow` entries, hooks per install mode) — add what's missing, never remove or
-   rewrite existing/custom keys.
+3. **Additive settings patch.** Bring `<state>/gate-config.json` — and, on a runtime with a settings
+   file the pipeline generates, that too — up to the current init spec (missing `allow` entries,
+   hooks per install mode): add what's missing, never remove or rewrite existing/custom keys.
 4. **Capability wiring.** If a top-up added a capability needing external setup (e.g. a `retrieval`
    provider whose MCP server isn't registered yet), run its wiring step from `/cohorte-init-pipeline` Phase 4.
    Even when nothing new was added, re-run the provider's health check (§Code retrieval) — wiring
    rots (PATH changes, uninstalls, hand-edits) — and repair whatever fails.
-5. **Global config seed.** If `~/.claude/cohorte.config.yaml` is absent, seed it from the template
+5. **Global config seed.** If `<config>` is absent, seed it from the template
    (`profile/cohorte.config.template.yaml`) so the kanban + shared-vault config has a home. Never
    clobber an existing filled file; report what was seeded.
 6. **Kanban sync.** Run the §Kanban reconcile: link/create the project's board if configured, verify
    its columns, and backfill/sync cards from `specs/*.md`. See §Kanban.
 7. **Spec-template top-up.** `specs/_template.md` is seeded once at install and then **never**
    refreshed, so a repo keeps whatever front-matter the core shipped the day it was installed (a
-   pre-1.6 copy has no `loop_pass`/`loop_phase`, and its `status` comment still lists four states).
-   Top it up the same way as the profile: add the **front-matter fields** the current
-   `templates/spec.template.md` has and the repo's copy lacks, with their documented defaults, and
-   refresh the `status:` comment. Never rewrite its body — the section list is the human's to shape,
+   pre-1.6 copy's `status` comment still lists four states). Top it up the same way as the profile:
+   add the **front-matter fields** the current `templates/spec.template.md` has and the repo's copy
+   lacks, with their documented defaults, drop `loop_pass`/`loop_phase` (retired with
+   `/cohorte-loop` in 2.2.0), and refresh the `status:` comment. Never rewrite its body — the section list is the human's to shape,
    and some repos have deliberately trimmed it. Nothing breaks without this (the fields are written on
    demand when a driver needs them); it just keeps a new spec's front-matter honest about the states
    the pipeline can put it in.
 
 8. **Local-artifact hygiene.** The pipeline's own runtime files must stay out of git:
-   `.claude/preflight.ok`, `.claude/pipeline-metrics.jsonl`, `specs/reports/`. Add any missing entry to
+   `<state>/preflight.ok`, `<state>/pipeline-metrics.jsonl`, `specs/reports/`. Add any missing entry to
    `.gitignore`, and **untrack** what a pre-2.0.0 install let slip in —
-   `git rm --cached --ignore-unmatch .claude/preflight.ok` (repeat per stray path). The stamp is the
+   `git rm --cached --ignore-unmatch <state>/preflight.ok` (repeat per stray path). The stamp is the
    one that actively breaks: it records the tree it verified, the commit carrying it moves HEAD past
    that tree, and the committed copy lands in every clone and worktree — so the phase gate ends up
    blocking clean trees and greening unchecked ones. Report what was untracked; the human commits it.
@@ -465,8 +505,8 @@ itself changes in ways `/cohorte-build` §1.5 can't auto-grow (e.g. package mana
 
 Three phases have a **workflow variant** — a deterministic orchestration script the Claude Code
 Workflow runtime executes instead of the lead reasoning out the fan-out turn by turn:
-`<core>/workflows/review.js`, `audit.js`, `refactor.js` (installed to `.claude/workflows/` bundled or
-`~/.claude/workflows/` global). The conversational commands (`/cohorte-review`, `/cohorte-audit`, `/cohorte-refactor`)
+`<core>/workflows/review.js`, `audit.js`, `refactor.js` (installed to `<core>/workflows/` bundled or
+`<core>/workflows/` global). The conversational commands (`/cohorte-review`, `/cohorte-audit`, `/cohorte-refactor`)
 **remain the default path and the fallback** — a workflow runs only when the human explicitly asks
 for it ("run the review workflow"), and requires Claude Code ≥ **2.1.154** with workflows
 enabled.
@@ -515,7 +555,7 @@ Shared design, all four scripts:
 
 An **optional, user-scoped** mirror of the dev flow: each pipeline stage moves a card across an
 [Obsidian Kanban](https://github.com/mgmeyers/obsidian-kanban) board, one board per project. Config
-lives in the consolidated global config `~/.claude/cohorte.config.yaml` §`kanban` (NOT in
+lives in the consolidated global config `<config>` §`kanban` (NOT in
 `PIPELINE.md` — the board path points at the user's personal vault, so it is machine-specific and must
 not be committed). Everything below **no-ops silently** when the config is absent, `kanban.enabled` is
 false, no board is configured for the current project, or the board file is missing — the pipeline never
@@ -543,12 +583,12 @@ agent's context (find, dedupe, sub-notes carried along, settings block preserved
 <core>/pipeline/scripts/kanban-move.sh auto <id> <stage> [--pr <num>] [--title <title>]
 ```
 
-`<core>` is `~/.claude` (global install) or `.claude` (bundled) — probe with `test -x`. It creates
+It creates
 the card in the target column when none exists, keeps the first and drops duplicates, and appends
 ` — PR #<num>` with `--pr`.
 
 **`auto` is not a convenience, it is the contract.** It reads `name` from `PIPELINE.md`, then
-`kanban.enabled` / `obsidian.vault_path` / `boards[name]` from `~/.claude/cohorte.config.yaml`
+`kanban.enabled` / `obsidian.vault_path` / `boards[name]` from `<config>`
 (override with `COHORTE_CONFIG`, or skip the profile with `--project <name>`), and it maps the
 **stage key** (`ideas` · `brainstorm` · `spec` · `ready` · `building` · `review` · `fix` · `ship` ·
 `shipped`) to that board's heading through `boards[name].columns` → `kanban.columns` → the built-in
@@ -584,15 +624,14 @@ Ideas — so `/cohorte-brainstorm` appends the tag to the picked line before its
 | `/cohorte-build`                                | `building`      |
 | `/cohorte-review`                               | `review`        |
 | `/cohorte-fix`                                  | `fix`           |
-| a `/cohorte-loop` is driving it (`in-progress`) | the current phase's column |
-| a `/cohorte-loop` gave up (`blocked`)            | `fix`           |
+| a round is under way (`in-progress`)    | `building`      |
+| a round gave up (`blocked`)             | `fix`           |
 | `/cohorte-ship` starts                          | `ship`          |
 | PR opened (`status: shipped`)           | `shipped` (+ `PR #<num>` on the card) |
 
 **Backfill / sync from specs (reconcile).** `specs/*.md` is the source of truth. For each spec, read its
 `feature_id` (front-matter or filename) and `status`, map `status`→column — `frozen`→`ready`,
-`in-progress`→the `loop_phase`'s column (`build`→`building`, `review`→`review`, `fix`→`fix`; unset ⇒
-`building`), `in-review`→`review`, `blocked`→`fix`, `shipped`→`shipped`, anything else / a spec with no
+`in-progress`→`building`, `in-review`→`review`, `blocked`→`fix`, `shipped`→`shipped`, anything else / a spec with no
 status→`spec` — then **full
 sync**: card absent ⇒ add it in that column; card present ⇒ **move it** to that column so the board
 always reflects the specs (this repositions cards the human may have moved by hand). Report cards
@@ -608,7 +647,7 @@ per configured column in pipeline order, and the closing `%% kanban:settings %%`
 Cohorte can send the maintainers anonymous usage pings so the pipeline improves where it's actually
 slow. **Nothing is ever sent without explicit consent**: `/cohorte-init-pipeline` (and `/cohorte-update-pipeline` on
 pre-telemetry installs) ask ONE question, once per machine, default **No**, and record the answer in
-`~/.claude/cohorte.config.yaml` §`telemetry` (`enabled`, `install_id`, `consent_date`). The sender —
+`<config>` §`telemetry` (`enabled`, `install_id`, `consent_date`). The sender —
 `pipeline/scripts/telemetry-send.sh` — is a silent no-op unless `enabled: true` AND `install_id` AND
 `endpoint` are all set, times out at 2s, and never fails the pipeline. Callers chain it with
 `|| true`, so a **missing** script is equally silent: `/cohorte-doctor` check 1 verifies `pipeline/scripts/`
@@ -650,7 +689,7 @@ work without revealing what is being built.
 **GDPR rights, concretely:**
 
 - **Consent** — opt-in only, recorded with a date; "No" is also recorded so nothing re-asks.
-- **Withdrawal** — set `telemetry.enabled: false` in `~/.claude/cohorte.config.yaml`; effective on
+- **Withdrawal** — set `telemetry.enabled: false` in `<config>`; effective on
   the next phase, no restart.
 - **Erasure** — `/cohorte-doctor` prints your `install_id`; send
   `curl -X DELETE <endpoint-origin>/v1/install/<install_id>` and the collector drops every event

package/scripts/kanban-move.sh

@@ -54,7 +54,17 @@ while [ $# -gt 0 ]; do
 done
 
 TAB=$(printf '\t')
-CONFIG="${COHORTE_CONFIG:-$HOME/.claude/cohorte.config.yaml}"
+# One config per human, wherever the runtime that installed it put it: `~/.claude` for a
+# Claude Code install (historical, still authoritative), `~/.cohorte` for every other coding
+# agent. Probe both — a repo driven from two agents must resolve ONE board, not two.
+CONFIG="${COHORTE_CONFIG:-}"
+if [ -z "$CONFIG" ]; then
+  for c in "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/cohorte.config.yaml" \
+           "$HOME/.cohorte/cohorte.config.yaml"; do
+    [ -f "$c" ] && { CONFIG="$c"; break; }
+  done
+  CONFIG="${CONFIG:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/cohorte.config.yaml}"
+fi
 
 # The nine pipeline stages and their default headings. A stage key given as the
 # target column is mapped through the config (per-board `columns` first, then the

package/scripts/metrics/collect.mjs

@@ -62,7 +62,7 @@ function knownCommands() {
   if (!names.size) {
     for (const n of ['cohorte-brainstorm', 'cohorte-spec', 'cohorte-build', 'cohorte-review',
                      'cohorte-fix', 'cohorte-ship', 'cohorte-audit', 'cohorte-refactor',
-                     'cohorte-align-ds', 'cohorte-doctor', 'cohorte-loop',
+                     'cohorte-align-ds', 'cohorte-doctor',
                      'cohorte-init-pipeline', 'cohorte-update-pipeline']) names.add(n);
   }
   // Retired commands. The list above is read from the shipped core, so a command that is
@@ -73,8 +73,10 @@ function knownCommands() {
   // 2.0.0 prefixed every command with `cohorte-`, which retires all 13 bare names at once:
   // months of transcripts say `/build`, and without these they would all reclassify to (chat)
   // — the largest instance of exactly the bug this list exists to prevent. `drive`/`loop` are
-  // both here because the driver was `/loop` → `/drive` (1.6.0) → `/cohorte-loop` (2.0.0).
-  for (const n of ['cycle', 'smoke', 'drive', 'loop', 'brainstorm', 'spec', 'build', 'review',
+  // both here because the driver was `/loop` → `/drive` (1.6.0) → `/cohorte-loop` (2.0.0), and
+  // `cohorte-loop` joins them now that 2.2.0 retired the driver outright.
+  for (const n of ['cycle', 'smoke', 'drive', 'loop', 'cohorte-loop',
+                   'brainstorm', 'spec', 'build', 'review',
                    'fix', 'ship', 'audit', 'refactor', 'align-ds', 'doctor',
                    'init-pipeline', 'update-pipeline']) names.add(n);
   return names;

package/scripts/preflight.sh

@@ -58,7 +58,7 @@ sha=$(git rev-parse HEAD 2>/dev/null || echo none)
 # invalidates the stamp without changing a line of code, while an implementer's edit
 # changes every line without moving HEAD. A tree id is content-addressed: it survives a
 # commit of the same content and dies on any real edit (including new untracked files).
-# `.claude` (stamps, metrics) and `specs` (DoD ticks, report buffer) are excluded — the
+# `.claude`/`.cohorte` (stamps, metrics) and `specs` (DoD ticks, report buffer) are excluded — the
 # pipeline writes those itself between the preflight and the dispatch it must not invalidate.
 # gate.py recomputes this identically; any change here must land there too.
 digest=none
@@ -69,29 +69,48 @@ if [ -n "$tmpidx" ]; then
   idx=$(git rev-parse --git-path index 2>/dev/null || echo "")
   if [ -n "$idx" ] && [ -f "$idx" ]; then
     cp "$idx" "$tmpidx" 2>/dev/null || true
+    # Backdate the copy, for the reason spelled out in gate.py's tree_digest(): git trusts an
+    # entry's cached stat data only when its mtime predates the index file's, so a copy stamped
+    # `now` makes a file edited in this same second look clean. Both sides must age it by the
+    # same window or they compute different trees for the same content. `date -d` is GNU and
+    # `date -v` is BSD — try both, and if neither exists just skip the touch (the digest is
+    # still correct for anything not edited in the last few seconds).
+    stamp=$(date -u -d '5 seconds ago' +%Y%m%d%H%M.%S 2>/dev/null \
+         || date -u -v-5S +%Y%m%d%H%M.%S 2>/dev/null || echo "")
+    [ -n "$stamp" ] && touch -t "$stamp" "$tmpidx" 2>/dev/null || true
   else
     rm -f "$tmpidx"                       # a 0-byte index is a corrupt index
   fi
   # Drop the excluded paths from the throwaway index entirely: an `add` exclude only stops
   # them being *updated*, so anything already tracked there (a committed stamp, a spec)
   # would still land in the tree and shift the digest.
-  GIT_INDEX_FILE="$tmpidx" git rm --cached -r -q --ignore-unmatch -- .claude specs > /dev/null 2>&1 || true
-  if GIT_INDEX_FILE="$tmpidx" git add -A -- . ':(exclude).claude' ':(exclude)specs' > /dev/null 2>&1; then
+  GIT_INDEX_FILE="$tmpidx" git rm --cached -r -q --ignore-unmatch -- .claude .cohorte specs > /dev/null 2>&1 || true
+  if GIT_INDEX_FILE="$tmpidx" git add -A -- . ':(exclude).claude' ':(exclude).cohorte' ':(exclude)specs' > /dev/null 2>&1; then
     digest=$(GIT_INDEX_FILE="$tmpidx" git write-tree 2>/dev/null || echo none)
   fi
   rm -f "$tmpidx" "$tmpidx.lock" 2>/dev/null || true
 fi
 [ -n "$digest" ] || digest=none
-# Stamp BOTH the main checkout and the cwd: gate.py reads CLAUDE_PROJECT_DIR,
-# which is the worktree when the session was opened there and the main checkout
-# when it wasn't — the two disagree, and either layout is supported.
+# Stamp BOTH the main checkout and the cwd: gate.py reads COHORTE_PROJECT_DIR /
+# CLAUDE_PROJECT_DIR, which is the worktree when the session was opened there and the
+# main checkout when it wasn't — the two disagree, and either layout is supported.
+# Stamp every state dir that EXISTS (`.cohorte` on a non-Claude runtime, `.claude` on a
+# Claude one, both where a repo is driven from both), falling back to `.claude` when the
+# repo has neither yet — gate.py's state_path() probes in that same order.
 now=$(date +%s)
 last=""
 for d in "$proj" "$(pwd)"; do
   [ "$d" = "$last" ] && continue          # same dir twice in the main checkout
   last="$d"
-  mkdir -p "$d/.claude" 2>/dev/null || true
-  printf '%s %s %s\n' "$now" "$sha" "$digest" > "$d/.claude/preflight.ok" 2>/dev/null || true
+  wrote=0
+  for s in .cohorte .claude; do
+    [ -d "$d/$s" ] || continue
+    printf '%s %s %s\n' "$now" "$sha" "$digest" > "$d/$s/preflight.ok" 2>/dev/null && wrote=1
+  done
+  if [ "$wrote" -eq 0 ]; then
+    mkdir -p "$d/.claude" 2>/dev/null || true
+    printf '%s %s %s\n' "$now" "$sha" "$digest" > "$d/.claude/preflight.ok" 2>/dev/null || true
+  fi
 done
 
 echo "PREFLIGHT PASS ($n checks green) — full log: $report"

package/scripts/telemetry-send.sh

@@ -16,8 +16,14 @@
 #   - Never blocks or fails the pipeline: 2s timeout, all errors swallowed, exit 0 always.
 set -u
 
-cfg="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/cohorte.config.yaml"
-[ -f "$cfg" ] || exit 0
+# Same two-location probe as kanban-move.sh: consent is recorded once per human, in
+# whichever config the runtime that installed the pipeline created.
+cfg=""
+for c in "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/cohorte.config.yaml" \
+         "$HOME/.cohorte/cohorte.config.yaml"; do
+  [ -f "$c" ] && { cfg="$c"; break; }
+done
+[ -n "$cfg" ] || exit 0
 
 # read keys scoped to the `telemetry:` block only
 tval() {
@@ -62,7 +68,8 @@ fi
 # bundled repo report an empty core_version.
 here=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd 2>/dev/null) || here=""
 ver=""
-for v in "$here/../VERSION" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/pipeline/VERSION"; do
+for v in "$here/../VERSION" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/pipeline/VERSION" \
+         "$HOME/.cohorte/pipeline/VERSION"; do
   [ -n "$ver" ] && break
   ver=$(head -1 "$v" 2>/dev/null | tr -d '"\\')
 done