cohorte 2.0.2 → 2.2.0

package/CHANGELOG.md

@@ -7,6 +7,154 @@ short, user-facing, most recent first. One `## <version> — <YYYY-MM-DD>` secti
 > They are history and are deliberately not rewritten — every command gained a `cohorte-` prefix
 > in 2.0.0.
 
+## 2.2.0 — 2026-08-12
+
+- **The pipeline was Claude Code or nothing.** The doctrine — frozen spec, stateless surfaces, a
+  gate you cannot talk your way past — is not Claude-specific, but every artefact that carried it
+  was: `.claude/commands/*.md` with Claude frontmatter, `Task` dispatches, a PreToolUse hook. A
+  Codex or Cursor user could read the ideas and reimplement nothing.
+
+  `core/commands/` and `core/agents/` are now **runtime-neutral sources**, and the installer renders
+  them per coding agent — as slash commands, TOML commands, or **Codex skills**
+  (`.agents/skills/<name>/SKILL.md`, committed with the repo: custom prompts are deprecated *and*
+  user-scoped, so a teammate cloning the repo would have got the profile and none of the commands) —
+  for **Claude Code, Codex CLI, Cursor, Gemini CLI, OpenCode**
+  (`npx cohorte install --runtime=codex,cursor`, or `--all-runtimes`, or nothing and it detects and
+  asks). Rendering rewrites the surface — markdown + the frontmatter keys that runtime understands,
+  or TOML for Gemini — resolves every path through the tokens `<core>` / `<state>` / `<agents>` /
+  `<config>` / `<memory>`, and swaps the argument placeholder (`$ARGUMENTS`, `{{args}}`, or an
+  explicit note where the runtime substitutes nothing, as Cursor does).
+
+  The part that is not cosmetic: the prompts **branch on what the runtime can enforce**, and say so
+  in their own text rather than pretending.
+
+  **The gate really runs on four of the five.** `gate.py` is registered as a blocking hook in each
+  runtime's own format — `PreToolUse` in `settings.json` (Claude) and `.codex/hooks.json` (Codex),
+  `beforeShellExecution` in `.cursor/hooks.json`, `BeforeTool` in `.gemini/settings.json` — and
+  emits that runtime's envelope, selected by `--runtime <id>`. A verdict in the wrong shape is read
+  as *allow* by every one of them, so each dialect is covered by `scripts/test-gate.mjs` rather than
+  trusted. **Codex and Gemini have no confirmation tier**, so an `ask` verdict is escalated to
+  `deny` with the reason attached: the point of that tier is that a human sees the command first,
+  and a runtime that cannot ask cannot deliver it — the same rule unattended headless runs already
+  used. The phase gate also learned Gemini's shape, where a subagent arrives as a tool of its own
+  name rather than as `Task` + `subagent_type`. OpenCode extends via plugins, not hooks, so there
+  the commands call `gate.py --check` themselves: same verdicts, but advisory, and
+  `/cohorte-doctor` says so instead of reporting ✅.
+
+  **Subagents are real everywhere**, in four different file formats — markdown + frontmatter for
+  Claude, Cursor, Gemini and OpenCode, TOML with the body under `developer_instructions` for Codex.
+  Read-only enforcement for the reviewer is derived from the source agent's tool list and re-emitted
+  as each runtime spells it (`readonly: true`, `sandbox_mode = "read-only"`); where there is no
+  equivalent, the rendered reviewer carries an explicit instruction that read-only is on it, and
+  why. Model pins do **not** travel: the profile names Anthropic aliases, which are meaningless
+  elsewhere, so agents inherit the runtime's own model selection.
+
+  **Real subagents are a requirement, not a capability to degrade around.** A sequential-persona
+  fallback shipped mid-development and was removed before release: it asked the lead to simulate the
+  isolation boundary by discipline — adopt one agent file, do that surface, drop it — which is not
+  the same guarantee, and no supported runtime ever took the branch. A runtime declaring
+  `subagents: false` is now refused at install with a named error rather than rendered into a
+  pipeline whose central promise is silently absent.
+
+- **`/cohorte-loop` is removed, on every runtime including Claude Code.** The autonomous
+  build→review→fix driver was the one part of the pipeline tied to a single vendor's headless CLI —
+  it spawned `claude -p` children through two shell scripts, a detached `screen` session, a
+  `caffeinate` assertion and a resume protocol stamped into spec front-matter. That is a lot of
+  surface, on the platform-specific end of the codebase, for a phase the human-driven cycle already
+  covers at a cost the loop was mostly there to hide.
+
+  Gone with it: `scripts/loop.sh`, `scripts/loop-detach.sh`, their test suite, and the
+  `loop_pass`/`loop_phase` front-matter fields (dropped from the spec template; still *read* by the
+  dashboard so a spec left mid-flight by an older core still explains itself). The installer scrubs
+  the command and both scripts on upgrade, in every runtime's layout — copy-over never deletes, and
+  a surviving command file is a decoy the model can still fire against a core that no longer ships
+  its driver.
+
+  **The file contract stays.** `verdict.json`, `readiness.json` and `build.json` are still written
+  on every run, and the `in-progress`/`blocked` spec statuses stay valid: they are what anything
+  automating the cycle from outside reads and writes. Removing the built-in driver does not remove
+  the ability to drive it — it removes cohorte's opinion about how.
+
+  Layout: each runtime gets its own rendered core (`.cohorte/<id>/`), because the same template
+  resolves differently per capability — but the **project state is shared** (`.cohorte/`:
+  gate-config, preflight stamp, metrics), so a repo driven from two agents cannot disagree with
+  itself about what is gated or what has been verified. The user config is shared too; the shipped
+  scripts probe `~/.claude` then `~/.cohorte`, so one kanban board and one telemetry consent.
+
+  **Claude Code is unchanged** — same paths, same frontmatter, same hook, and `scripts/test-adapter.mjs`
+  asserts that as a regression test alongside the per-runtime output. `install.sh` / `install.ps1`
+  now delegate to the Node CLI: there is no shell renderer, and a raw copy would install prompts
+  full of unresolved markers that look installed and instruct the model wrongly.
+
+- **A config dir with a space in it broke every tool call in the session.** The gate-hook
+  registration quoted the script path only on Windows, so a `CLAUDE_CONFIG_DIR` under
+  `~/Library/Application Support/…` — where a desktop host naturally puts it — produced
+  `python3 /Users/x/Library/Application Support/…/gate.py`. The shell split that, python reported
+  `can't open file '/Users/x/Library/Application'`, and *every* Bash and Task call failed —
+  including the ones needed to undo it. Quoted on every platform now, in both the global
+  registration and the per-runtime one, with a test that installs into a path containing a space
+  and asserts the quoting plus that a re-install still reconciles its own entry instead of
+  stacking a second.
+
+- **`CLAUDE_CONFIG_DIR` was only half honoured.** The runtime registry declares Claude's paths as
+  `~/.claude`, and the adapter resolved them from the homedir — so with the variable set, the core
+  was written to the real `~/.claude` while the hook was registered in the overridden dir. A
+  scratch or CI install silently wrote into the user's actual global core. `resolvePaths` now
+  takes a re-rooting override, and the test asserts the core, the commands and the hook all land
+  in the override with nothing written to the home default.
+
+- **The dashboard reported a healthy non-Claude install as broken.** Every path it checked was
+  `.claude/…`, so a repo driven from Cursor came back "no pipeline core installed", "surface with
+  no rendered agent", "artifacts not gitignored", "gate.py not registered" — four findings, all
+  false. A false red is worse than no check: it sends someone fixing what is not broken. The
+  server now resolves paths from `runtimes.json` (`dashboard/server/runtime.js`), reads the gate
+  registration in each runtime's own envelope, names artifacts against the right state dir, reads
+  the metrics sink from every state dir in play, skips workflows where there is no engine instead
+  of reporting them missing, and the reset action backs up every runtime's directory rather than
+  leaving the others behind for the fresh install to land beside.
+
+- **`SCHEMA.md` is the agents' rulebook, read at run time — and it still hardcoded `.claude`.**
+  It ships to `<core>/pipeline/`, so on a non-Claude install it was telling agents to write
+  rendered agents and read the gate config in a directory that runtime never looks at. It and
+  `PIPELINE.template.md` now use the same `<core>`/`<state>`/`<agents>`/`<config>` tokens as the
+  commands, and the installer resolves their capability conditionals like any other prompt.
+
+- **The preflight stamp could green code that had changed.** Both sides of the content digest seed
+  a throwaway git index from the real one, for its stat cache — but the copy is stamped `now`, and
+  git trusts an entry's cached stat data whenever the entry predates the index file. A file edited
+  in the same second as the preflight, at an unchanged size, therefore read as clean: the gate let
+  a `review` dispatch through onto code the preflight never verified. Both `gate.py` and
+  `preflight.sh` now backdate the copy by 5 s, which forces a content check for anything touched
+  inside that window and leaves the fast path intact for every older file.
+
+## 2.1.0 — 2026-08-09
+
+- **A repo that gates merges on a per-feature release note shipped red PRs, and the flow reported
+  success.** Changesets' `changeset` job fails any PR that touches product code without a
+  `.changeset/*.md`, but that requirement lives in the project's `CLAUDE.md` — which the ship flow
+  never reads. So `/cohorte-ship` committed, pushed, opened the PR and moved the kanban card to
+  **Shipped** while the PR was unmergeable, red on a job nobody was watching.
+
+  The profile gains a `release_notes` block (`enabled`, `tool`, `dir`/`filename`,
+  `anchor_package`, `language`, `forbid_levels`, `empty_cmd`, `ci_job`, `guidance` — SCHEMA.md
+  §Release notes), and `/cohorte-ship` gains **§2b**: the lead writes the note itself, next to the
+  `status: shipped` flip, so it lands *inside* the release commit rather than in a second one after
+  the PR is already open. The bump level is project policy, not a git ritual — the release agent is
+  now explicitly forbidden from authoring or editing a note, and only stages the one it is handed.
+  §4 verifies the note is in the commit; §5 routes a red `ci_job` back to §2b instead of through
+  `/cohorte-fix`, which would treat a missing note as a code finding.
+
+  Two things the block encodes that the tool itself does not: `forbid_levels`, for the `0.x` repo
+  where a `major` changeset silently jumps to `1.0.0` with no human deciding it, and the rule to
+  **ask** rather than guess between two defensible levels — a wrong bump is a published version
+  number, not a fixable draft. `empty_cmd` covers the honest no-op, for a PR that must move no
+  version at all.
+
+- **Existing projects are asked, not defaulted.** `/cohorte-init-pipeline` detects a versioning tool
+  or note-enforcing CI job in Phase 1 and asks the anchor package, language and bump policy in Phase
+  2; `/cohorte-update-pipeline` treats `release_notes` as a genuine human decision during reconcile
+  rather than topping it up blind. No tool found ⇒ `enabled: false`, and §2b is a silent no-op.
+
 ## 2.0.2 — 2026-08-08
 
 - **Kanban cards stopped moving mid-pipeline, and every stage still reported success.** The

package/README.md

@@ -13,8 +13,9 @@
 
 </div>
 
-A **portable, stack-agnostic multi-agent pipeline** for Claude Code. Install it once globally,
-then one command per project (`/cohorte-init-pipeline`) adapts it to that project's stack.
+A **portable, stack-agnostic multi-agent pipeline** for your coding agent — Claude Code, Codex CLI,
+Cursor, Gemini CLI or OpenCode. Install it once globally, 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:
@@ -39,6 +40,44 @@ The core never hardcodes stack facts. Two mechanisms keep it generic:
 2. **Render-at-init** — things that must be in agent frontmatter (name, `tools:`, surface ownership)
    are rendered per **surface** by `/cohorte-init-pipeline` from `implementer.template.md`.
 
+## Which coding agent — [full matrix →](https://thebidouilleagency.github.io/cohorte/reference/runtimes)
+
+The doctrine is one set of source prompts. The installer renders them into whatever your agent
+actually reads, and branches the instructions on what it can actually do:
+
+```sh
+npx cohorte install --runtime=codex,cursor     # pick explicitly
+npx cohorte install --all-runtimes             # every supported one
+npx cohorte install                            # detects what you have and asks
+```
+
+| | Commands | Subagents | Gate | Workflows |
+| --- | --- | --- | --- | --- |
+| **Claude Code** | `.claude/commands/*.md` | ✅ `.claude/agents` | ✅ blocking hook, deny + **ask** | ✅ |
+| **Codex CLI** | `.agents/skills/*/SKILL.md` | ✅ `.codex/agents` (TOML) | ✅ blocking hook, deny only | — |
+| **Cursor** | `.cursor/commands/*.md` | ✅ `.cursor/agents` | ✅ blocking hook, deny + **ask** | — |
+| **Gemini CLI** | `.gemini/commands/*.toml` | ✅ `.gemini/agents` | ✅ blocking hook, deny only | — |
+| **OpenCode** | `.opencode/commands/*.md` | ✅ `.opencode/agents` | advisory `--check` | — |
+
+The same `gate.py` is registered as a real blocking hook on four of the five — it speaks each
+runtime's envelope (`PreToolUse`, `beforeShellExecution`, `BeforeTool`). Codex and Gemini have **no
+confirmation tier**, so a pattern that would be queried elsewhere is **denied** there rather than
+falling through; the rendered prompts say so. OpenCode extends via plugins rather than hooks, so
+there the commands call `gate.py --check` themselves — same config and verdicts, but advisory.
+
+**Real subagents are a requirement, not a capability to degrade around** — the pipeline's isolation
+guarantee is that boundary, so a runtime without them is refused at install rather than rendered
+into a pipeline whose central promise is absent. All five have them.
+`/cohorte-doctor` reports what the runtime you are in can actually enforce.
+
+On Codex the commands ship as **skills** (`$cohorte-build`) rather than custom prompts: prompts are
+deprecated and user-scoped, so a teammate cloning the repo would get the profile but none of the
+commands — `.agents/skills/` is committed with it instead.
+
+One thing does not travel: model pins. The profile names Anthropic aliases, meaningless elsewhere,
+so agents inherit the runtime's own model. Claude Code remains the reference implementation and its
+install is unchanged.
+
 ## Prerequisites
 
 Only one hard requirement — the rest is optional and independent:
@@ -220,7 +259,6 @@ it in `.claude/pipeline/VERSION` and bundled repos in their committed `pipeline.
 | `/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.                                         |
@@ -244,35 +282,6 @@ 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 — `/cohorte-loop`
-
-```
-/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 `/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
-`specs/reports/<id>.loop.log`, which the command is forbidden to read back. Your session sees one
-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 `/cohorte-review` now writes on every run; no
-prose is ever parsed.
 
 ### Run features in parallel — one session per feature