cohorte 2.10.0 → 3.0.0-dev.0

package/core/templates/spec.template.md

@@ -1,87 +0,0 @@
----
-feature_id: <slug>
-title: <Feature title>
-status: draft # draft → frozen → in-progress → in-review → shipped · blocked (see SCHEMA.md §Spec status)
-branch: <feature_branch_prefix><slug>
-created: <YYYY-MM-DD>
-reviewed_base: # merge-base sha at the last SHIP verdict — freshness-gate anchor (written by /cohorte-review)
-reviewed_digest: # sha256 (16 hex) of the reviewed source diff vs reviewed_base, specs excluded — /cohorte-ship re-checks
-design_files: [] # design page links — full URLs of the form https://claude.ai/design/p/<projectId>?file=<file> (each carries its own project + page); blank until designed; omit if no UI
----
-
-# <Feature title>
-
-## 1. Goal & user story
-
-<one paragraph: what · who · why>
-
-## 2. Scope
-
-**In:** …
-**Out (non-goals):** …
-
-## 3. Roles & permissions
-
-> Only if `PIPELINE.md` §rbac is enabled — which roles can do what; note the lowest-privilege experience.
-
-## 4. Data model & migrations
-
-> Additive only (never gate.deny commands). Omit if the feature has no persistence.
-
-| table | column | type | null? | default | notes |
-| ----- | ------ | ---- | ----- | ------- | ----- |
-|       |        |      |       |         |       |
-
-## 5. CONTRACT (frozen)
-
-> The only sync channel. Complete enough to build every surface independently. Uses the profile's
-> `contract.mechanism`. If `contract.enabled` is false, capture the interface precisely in prose here.
-
-### `<METHOD> /<path>` · auth: `<middleware/role>`
-
-- **Request** — params / query / body: `field` · type · required? · nullable? · validation
-- **Success** — `<status>` · response shape
-- **Errors** — `<status>` · when (422 validation · 401 · 403 · 404 · 409 …)
-
-<repeat per endpoint/interface>
-
-### Contract types — lead authors `<contract.path>/<slug>.<ext>` before /cohorte-build
-
-- `<slug>...Request` / `<slug>...Response` / `<slug>Base` … (sketch the schemas here)
-
-## 6. Surface tasks
-
-> One `###` subsection per surface in `PIPELINE.md` §surfaces (e.g. backend, frontend), each TDD.
-> Surfaces are subsections of §6, never top-level sections — §8 and §9 are referenced by number
-> across the whole pipeline (`/cohorte-build` implements "§8 flows", `/cohorte-review` checks "§9 acceptance"), so a
-> third surface must not become a §8 of its own.
-
-### <surface.key>
-
-- …
-
-## 8. Design brief (the "spec return")
-
-> Only if the project has UI. Standalone; mirrors `<core>/templates/design-brief.md`.
-
-- **Screens / views:** …
-- **Flows:** …
-- **Responsive:** mobile (base) → `md:` → `lg:`
-- **States:** empty · loading · error · success
-
-## 9. Acceptance criteria / DoD
-
-- [ ] Every contract endpoint/interface implemented exactly
-- [ ] Each surface's tests (TDD) green
-- [ ] `PIPELINE.md` commands.lint · typecheck · test green
-- [ ] Mobile-first / responsive verified (if UI)
-- [ ] User-facing copy in `ui_language`
-
-## 10. Assumptions & open questions
-
-- …
-
-## Remediation
-
-> Filled by `/cohorte-spec` in review-return mode; empty otherwise. Each item:
-> `[ ] <SEVERITY> · <file:line> · <spec-violation|quality|security> · <concrete fix>`

package/core/templates/steps/init-pipeline/01-detect-stack.md

@@ -1,44 +0,0 @@
-# /cohorte-init-pipeline · 01 Detect the stack
-
-### Phase 1 — Detect the stack (read-only, no questions yet)
-
-Gather evidence, then summarize what you found. Look for:
-
-- **Package manager & workspaces:** root `package.json` (`packageManager`, `workspaces`),
-  `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`; lockfiles (`pnpm-lock.yaml`,
-  `package-lock.json`, `yarn.lock`, `bun.lockb`); or non-JS: `pyproject.toml`/`requirements.txt`,
-  `go.mod`, `Cargo.toml`, `Gemfile`, `composer.json`.
-- **Surfaces (independently-built areas):** `apps/*`, `packages/*`, `services/*`, `cmd/*`, or a single
-  root app. For each, detect its framework from its own `package.json`/config:
-  backend markers (`adonisrc.ts`, `@adonisjs/*`, `nestjs`, `express`, `fastify`, `django`, `fastapi`,
-  `rails`, `.go`), frontend markers (`vite.config.*`, `next.config.*`, `@tanstack/react-router`,
-  `angular.json`, `nuxt`, `svelte`), and its test runner (`@japa/*`, `vitest`, `jest`, `playwright`,
-  `pytest`, `go test`), linter/formatter (`eslint`, `prettier`, `biome`, `ruff`).
-- **Split candidates (sub-surface boundaries):** inside each surface, look for a clean internal partition
-  — feature modules (`src/features/*`, `src/modules/*`, `app/(group)/*`), or independent services
-  (`services/*`, domain folders). Note the surface's rough size (module/file count) so a *large* surface
-  with a *clean* boundary can be proposed as several specialized surfaces in Phase 2. See SCHEMA.md
-  §"Specialization — when to split one surface into more agents" for the heuristic. Don't split yet — just
-  flag candidates + their would-be shared-code tree.
-- **Per-surface commands:** derive `test`/`lint`/`format`/`typecheck`/`build` from each surface's
-  `package.json` scripts + the workspace filter syntax (e.g. `pnpm --filter <pkg> test`).
-- **Contract mechanism:** a shared types/schema package (`packages/shared-types`, Zod/`z.`),
-  an `openapi.*`/`swagger.*` file, `.proto` files, or none.
-- **Release notes / versioning:** a `.changeset/` directory (+ `config.json`, and whether it declares a
-  `fixed`/lockstep group — that names the anchor package), `changesets` in devDependencies, or a CI job
-  that fails a PR lacking a note (grep `.github/workflows/*` for `changeset`). Also note the root
-  `version`: a `0.y.z` product usually forbids `major`. None of these ⇒ `release_notes.enabled: false`.
-- **DB / migrations:** migration tooling (`node ace make:migration`, `knex`, `prisma`, `alembic`,
-  `golang-migrate`), a `docker-compose.yml`, DB service.
-- **Design system:** an existing `design-reference/` snapshot, `components/ui`, a DesignSync MCP
-  connection, Figma links, or none.
-- **Code retrieval:** is the `serena` CLI resolvable (`command -v serena`)? If not, does
-  `~/.local/bin/serena` exist anyway — installed but PATH-broken (see SCHEMA.md §Code retrieval)?
-  `graphify`? Is either already registered in this repo's `.mcp.json` or `claude mcp list`? (Feeds
-  the retrieval question + Phase 4 wiring — default provider is `serena`.)
-- **VCS:** `git remote -v` → host + `owner/repo`; the default branch (`git symbolic-ref refs/remotes/origin/HEAD` or `git branch`).
-- **Existing `<memory>`** — read it; it may already state stack/conventions to fold in. **Existing
-  `PIPELINE.md`** — if present, this is a re-run: load it as the starting draft and only reconcile deltas.
-
-Print a compact **Detection Report**: layout, surfaces (with framework + commands), contract, release
-notes, DB, design, vcs. Mark each field `detected` / `guessed` / `unknown`.

package/core/templates/steps/init-pipeline/02-interview-gaps.md

@@ -1,55 +0,0 @@
-# /cohorte-init-pipeline · 02 Interview the gaps
-
-### Phase 2 — Interview the gaps (AskUserQuestion)
-
-Ask ONLY what you couldn't confidently detect. Batch related questions. Cover:
-
-- **Surfaces & ownership** — confirm the surface list and each one's path + owning agent name. (If a
-  single-app repo, one surface.) Confirm the `tools` each agent needs (add `DesignSync` only to a
-  surface with `uses_design: true`), and each surface's `model` tier: `sonnet` (Recommended default —
-  implementers mostly apply a frozen contract, which Sonnet handles at a fraction of the Opus-lead
-  cost), `haiku` for purely mechanical surfaces (scaffolding), `inherit` only for surfaces with real
-  design decisions worth running on the lead's model.
-- **Specialization (only if Phase 1 flagged a large + cleanly-separable surface)** — offer to split it
-  into specialized sub-surfaces (e.g. `web-checkout`, `web-billing`) so `/cohorte-build` runs them in parallel,
-  per SCHEMA.md §Specialization. If the human accepts, apply the rules: **shared code (routing, global
-  state, DS kit/tokens) becomes its own single-owner surface**, and cross-slice shapes go through the
-  contract. Default to NOT splitting when boundaries are tangled or slices are tiny — coarse is fine.
-- **Quiet commands** (never store a bare `pnpm test` as what agents execute) — for each noisy command
-  (tests, lint; per surface AND repo-wide), propose the detected **bridled variant** as the
-  Recommended option: dot/failures-only reporter (`--reporter=dot` vitest/playwright, `--silent`
-  jest, `-q` pytest, `--quiet` eslint/ruff — whatever the detected runner supports). These land in
-  `test_quiet_cmd`/`lint_quiet_cmd` + `commands.test_quiet`/`lint_quiet` and are what agents and the
-  `/cohorte-review` pre-flight actually run (SCHEMA.md §Output discipline). If the human declines or
-  the runner has no such flag, leave `""` — consumers then fall back to `<cmd> 2>&1 | tail -40`.
-- **Contract** — mechanism (`shared-types-zod` / `openapi` / `protobuf` / `json-schema` / `none`) and
-  where feature contracts are authored. If `none`, surfaces sync by the spec prose alone.
-- **Release notes (only if Phase 1 found a versioning tool or a note-enforcing CI job)** — confirm the
-  anchor package (a `fixed`/lockstep group means ONE key propagates to all), the note's language, and the
-  **bump policy** the lead will apply at `/cohorte-ship`: what counts as major/minor/patch here, and
-  whether any level is forbidden (a `0.y.z` product normally forbids `major` — Changesets would jump it
-  to `1.0.0` with no human deciding). Policy prose lands in `release_notes.guidance`. Nothing detected ⇒
-  don't ask; leave `release_notes.enabled: false`.
-- **UI language** — language of all user-facing copy.
-- **RBAC** — is there a role hierarchy? If yes, list it highest→lowest.
-- **Design system** — enabled? provider (Claude Design / Figma / none) + project ids + kit/token paths.
-- **Code retrieval** — confirm the provider (see SCHEMA.md §Code retrieval): `serena` (Recommended
-  default — live LSP symbol navigation, no index to maintain), `graphify` (persistent knowledge graph
-  over code + docs — better on very large or mixed code+docs repos, but needs an index step + rescans),
-  or `none`. Only demote from `serena` if the human objects or the provider CLI can't be installed.
-- **Isolation** — build features in parallel git worktrees with per-feature DB + ports, or just in the
-  main checkout? If worktrees: DB-per-worktree? port bases? compose file?
-- **Gate** — confirm the destructive commands to hard-deny and the ones to confirm-first (seed from the
-  detected DB/migration tooling + always git commit/push/merge/rebase/reset).
-- **Personas** — keep the default `/cohorte-brainstorm` panel, or customize members for this domain?
-
-Prefer sensible defaults from Phase 1 as the first (Recommended) option in each question.
-
-- **Kanban** (optional) — mirror this project's pipeline (`/cohorte-brainstorm`…`/cohorte-ship`) onto an Obsidian
-  Kanban board? If the human says yes: confirm the shared vault path (`obsidian.vault_path` in
-  `<config>`; ask if empty) and the board's location inside it (default
-  `<ProjectName>/Tasks.md`). Phase 4 creates the board and records the link. Default: no.
-
-> The **kanban** link is user-scoped (it points at a personal vault, so it never goes in the committed
-> `PIPELINE.md`), but IS wired here because it is per-project — see Phase 4.
-

package/core/templates/steps/init-pipeline/03-draft-profile.md

@@ -1,10 +0,0 @@
-# /cohorte-init-pipeline · 03 Draft the profile
-
-### Phase 3 — Draft the profile (show, don't write yet)
-
-Assemble the full `PIPELINE.md` from the installer's `pipeline/PIPELINE.template.md` (resolve
-bundled-vs-global per the note above), filling the `yaml pipeline-profile`
-block and every prose section from Phases 1–2. **Keep it lean**: every stateless agent re-reads this
-file on every dispatch, so its length is a per-dispatch token+latency tax — terse rule-shaped
-conventions, no narration, no facts derivable from the code. **Show the human the drafted
-`PIPELINE.md` in a fenced block and get a go-ahead** before writing.

package/core/templates/steps/init-pipeline/04-write-render.md

@@ -1,115 +0,0 @@
-# /cohorte-init-pipeline · 04 Write & render
-
-### Phase 4 — Write & render (after go-ahead)
-
-1. **Write `PIPELINE.md`** at the repo root (source: the installer's `pipeline/PIPELINE.template.md`).
-2. **Wire it into `<memory>`:** if `<memory>` exists, ensure it references the profile (add a line
-   near the top: `> Project profile & pipeline facts: **@PIPELINE.md**`). If not, create a minimal
-   `<memory>` with that reference + a one-paragraph project intro.
-3. **Render one agent per surface** — for each surface, follow SCHEMA.md §"Rendering / reconciling a
-   surface agent" (steps 2–3): render `<agents>/<agent>.md` from the installer's
-   `pipeline/implementer.template.md`, substituting `<SURFACE_AGENT>`, `<SURFACE_LABEL>`, `<SURFACE_PATH>`,
-   `<SURFACE_TOOLS>`, `<SURFACE_MODEL>`, `<PROJECT_NAME>`, `<SURFACE_CONVENTIONS>` (the surface's
-   baked convention slice — §Shared + its `### Surface:` stanza + its §Testing lines from the
-   PIPELINE.md you just wrote), and the surface-specific blocks
-   (`<SURFACE_EXTRA_NEVER>`, `<SURFACE_DESIGN_INPUT>`, `<SURFACE_TDD_STEP1>` — fill design-related ones
-   only when `uses_design`).
-   Leave the fixed agents as-is (generic, shipped by the installer): `review.md`, `release.md`,
-   `profile-reader.md`.
-4. **Generate `<state>/gate-config.json`** from the `gate` block — copy all five keys verbatim:
-   `{"deny": [...], "ask": [...], "ask_on_default_branch": [...], "default_branch": "<vcs.default_branch>",
-   "preflight": {"enabled": <gate.preflight.enabled>, "agents": [...], "max_age_minutes": <n>}}`
-   (profile has no `preflight` block ⇒ omit the key — the hook then skips the phase gate).
-<!-- cohorte:if hooks -->
-5. **Write `.claude/settings.json`** permissions (`ask`/`deny` lists mirroring the gate, **plus an
-   `allow` list of the project's read-only / verification commands** so agents don't stall on
-   permission prompts — including mid-workflow, where nobody is watching a prompt: the detected
-   per-surface `test_cmd`/`lint_cmd`/`typecheck_cmd`/`build_cmd` **and their `*_quiet_cmd`
-   variants** and repo-wide `commands.*` equivalents as `Bash(<cmd>:*)` rules, plus read-only git —
-   `Bash(git status:*)`, `Bash(git diff:*)`, `Bash(git log:*)`, `Bash(git rev-parse:*)` — plus the
-   shipped pipeline scripts (`Bash(<core>/pipeline/scripts/:*)` — preflight, kanban-move;
-   a prefix rule matches a command *starting* with that path, so a `bash <path>`
-   invocation would need its own entry), and the
-   retrieval provider's MCP tools when wired (e.g. `mcp__serena`). Never allowlist anything matching
-   a `gate.ask`/`gate.deny` pattern. Mention the human can widen it later with
-   `/fewer-permission-prompts`) + the hooks, **conditioned on the install mode:**
-   - **bundled:** register the PreToolUse hook `<core>/hooks/gate.py` with matcher `Bash|Task`
-     (Task is required — the preflight phase gate keys off Task dispatches; a `Bash`-only matcher
-     leaves it dead) and the PostToolUse formatter (detected formatter). Before adding, drop any
-     existing PreToolUse entry whose command ends in `gate.py` (here AND in `~/.claude/settings.json`
-     if one points at this repo's copy) — exactly one registration must survive, or every gated
-     command prompts twice.
-   - **global:** the PreToolUse gate hook is
-     already in `~/.claude/settings.json` and reads this repo's `gate-config.json` — do **not** re-register
-     it here (double-registration double-prompts). It no-ops where its config is absent, so one
-     registration serves every repo; you only supply this repo's `gate-config.json`. Still write the
-     PostToolUse formatter hook + the permissions.
-   Preserve any existing custom keys.
-<!-- cohorte:else -->
-5. **No permissions or hook file to write.** This runtime has neither a PreToolUse hook nor a
-   settings.json permission model the pipeline can generate, so the gate is enforced by the
-   commands calling `<core>/hooks/gate.py --check` at the points the profile marks gated. That
-   means `<state>/gate-config.json` (step 4) is not decoration here — it is the ONLY place the
-   deny/ask patterns live, so fill it from the profile exactly and do not skip it. If this repo is
-   also driven from Claude Code, that install's hook reads the same file; nothing to duplicate.
-<!-- cohorte:endif -->
-6. **Wire the retrieval provider** (skip if `retrieval.provider: none`):
-   - **serena:** if the `serena` CLI is missing, have the human install it (`uv tool install -p 3.13
-     serena-agent`) — or set the provider to `none` if they decline, and say `/cohorte-update-pipeline` can wire
-     it later. If the binary exists (e.g. `~/.local/bin/serena`) but `command -v serena` fails,
-     recommend the PATH fix (`uv tool update-shell`, or add `~/.local/bin` to the shell profile) for
-     CLI use. Then register at **project scope** (committed `.mcp.json`, portable —
-     `--project-from-cwd` resolves the project at server start) using the **PATH-proof launcher**
-     from SCHEMA.md §Code retrieval (`sh -c 'exec "$(command -v serena || echo
-     "$HOME/.local/bin/serena")" start-mcp-server …'` — a bare `serena` entry dies with ENOENT when
-     Claude Code was launched from an environment without `~/.local/bin` on PATH; Windows-native
-     teams use the bare form + PATH instead). If `.mcp.json` already has a bare `serena` entry,
-     upgrade it to the launcher form rather than skipping. Add `.serena/` to the repo's `.gitignore`
-     (per-machine cache/config Serena creates on first launch). On a large repo, offer the one-off
-     `serena project index`. Finish with the **health check** from SCHEMA.md §Code retrieval and
-     report each result — if the static checks pass but the server isn't connected in this session,
-     say a session restart is needed; never report Serena wired on registration alone.
-   - **graphify:** have the human install it (`uv tool install graphify` then `graphify install`),
-     build the initial graph (`/graphify .`), and note it needs incremental rescans (`--update`) after
-     big changes.
-   - Either way the rendered agents already carry the provider's MCP tools in their `tools:` list
-     (step 3 / SCHEMA §Rendering); remind the human the new MCP server appears after a session restart.
-7. **Render the isolation scripts** (if `isolation.enabled`) from the installer's
-   `pipeline/scripts/*.template` to this repo's `scripts/new-feature.sh` and `scripts/remove-feature.sh`,
-   substituting the `__TOKENS__` (project
-   slug, DB pattern, port bases, compose file, branch prefix, install/dev/migrate commands, per-surface
-   env stanzas). `chmod +x` them. If isolation is disabled, skip and note features build in the main checkout.
-8. **Ensure `specs/_template.md`** exists (copy from the installer's `templates/spec.template.md` if missing).
-9. **Write the pointer** `<state>/pipeline.json` (committed — this is how a teammate who clones the repo
-   knows which core to install):
-   `{ "pipeline": "cohorte", "mode": "<bundled|global>", "core_version": "<contents of the
-   installer's pipeline/VERSION>", "install": "<per mode: bundled ⇒ \"npm i -g cohorte && cohorte install\"
-   note that the core is committed under .claude/; global ⇒ \"npm i -g cohorte && cohorte install --global\"
-   (or, without npm: curl -fsSL https://raw.githubusercontent.com/TheBidouilleAgency/cohorte/main/install.sh | sh -s -- --global;
-   Windows: install.ps1 -Global from the same repo)> " }`.
-   In **global** mode also add, near the top of `<memory>`, a one-liner:
-   `> Pipeline: global core — run the installer above if /cohorte-brainstorm etc. are missing.`
-10. **CI workflow** (if `vcs.host: github` and no existing workflow already runs the profile's
-    checks): with the human's go-ahead, generate `.github/workflows/pipeline-ci.yml` — on
-    `pull_request` to `<default_branch>`: checkout, set up the `package_manager` toolchain,
-    `commands.install`, then `commands.lint` · `commands.typecheck` · `commands.test` (+ per-surface
-    `build_cmd`s that are non-empty). Derive the setup steps from the detected stack — mirror what a
-    sibling workflow does if one exists. `/cohorte-ship` watches these checks before the merge.
-11. **Metrics sink, report buffer & preflight stamp:** add `<state>/pipeline-metrics.jsonl` to
-    `.gitignore` — `/cohorte-build`, `/cohorte-review` and `/cohorte-fix` append per-dispatch evidence
-    there (SCHEMA §Specialization reads it).
-    Also add `specs/reports/` — `/cohorte-review` stages its last report there so a `/cohorte-fix` (or
-    `/cohorte-spec` Mode B) survives a `/clear`; it's a derived buffer, not a versioned artifact.
-    And `<state>/preflight.ok` — a local, per-checkout freshness stamp. Versioning it breaks the phase
-    gate for good (a committed stamp describes the tree *before* its own commit, and it rides into every
-    new worktree as a green nobody earned). If it is already tracked: `git rm --cached <state>/preflight.ok`.
-12. **Design system:** if `design.enabled` with a snapshot dir, note that `/cohorte-align-ds` is active; else the
-    `/cohorte-align-ds` command will no-op with a clear message.
-13. **Kanban** (only if the human opted in at Phase 2): wire it per SCHEMA.md §Kanban, writing into the
-    **global** `<config>` (never into this repo — the board points at a
-    personal vault). Create the file from `pipeline/cohorte.config.template.yaml` if absent; set
-    `kanban.enabled: true` and `obsidian.vault_path` if it was empty. Add a `kanban.boards[<PIPELINE
-    name>]` entry with `board: <folder>/Tasks.md`. Then **create the board file**
-    `<vault>/<folder>/Tasks.md` (per §Kanban) if it doesn't exist — one column per `kanban.columns`
-    stage, in pipeline order. Finally run the §Kanban backfill so any spec already in `specs/` lands on
-    the board. Report the board path + the `obsidian://` URI. Skip silently if the human declined.

package/core/templates/steps/init-pipeline/05-report.md

@@ -1,12 +0,0 @@
-# /cohorte-init-pipeline · 05 Report
-
-### Phase 5 — Report
-
-Print: the install mode (bundled core under `.claude/` vs global core in `~/.claude/` + the committed
-`<state>/pipeline.json` pointer), the files written/rendered, the surface→agent mapping, and the
-tailored workflow line, e.g.
-`/cohorte-brainstorm → /cohorte-spec → (design) → /cohorte-build <id> → test → /cohorte-review → /cohorte-ship`. Tell the human to sanity-check
-`PIPELINE.md`, commit it, and run `/cohorte-brainstorm` to start a feature. Note that this was the one-time
-setup: from now on `/cohorte-update-pipeline` both refreshes the core AND reconciles the generated files
-(SCHEMA.md §Reconcile), and `/cohorte-build` auto-grows surfaces — re-running `/cohorte-init-pipeline` is only for deep
-stack changes (package manager, contract mechanism, surface overhaul).

package/core/workflows/audit.js

@@ -1,240 +0,0 @@
-// cohorte — /cohorte-audit as a deterministic workflow (opt-in; the conversational
-// /cohorte-audit command remains the default path and the fallback).
-//
-// Invoke with args = {target: "<path or domain>"} (optional — default whole repo).
-//
-// Shape (SCHEMA.md §Workflows): profile via profile-reader (phase 0), the
-// mechanical gates staged to disk by one haiku agent, then ONE auditor per
-// domain (each surface + `shared`) running concurrently — the runtime caps
-// concurrency at 20 (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS since 2026-08), extra
-// domains queue — and a merge phase that writes the
-// prioritized specs/refactor-backlog.md. Only the summary comes back.
-
-export const meta = {
-  name: 'cohorte-audit',
-  description: 'Audit the codebase against PIPELINE.md: mechanical gates, one auditor per domain in parallel, prioritized refactor backlog',
-  whenToUse: 'Only when the human explicitly asks for the audit workflow. args = {target: "<path or domain>"} — omit for the whole repo.',
-  phases: [
-    { title: 'Profile', detail: 'PIPELINE.md → JSON via profile-reader', model: 'haiku' },
-    { title: 'Gates', detail: 'format/lint/typecheck/tests → specs/reports/audit-gates.txt', model: 'haiku' },
-    { title: 'Audit', detail: 'one review-in-audit-mode agent per domain (concurrent, runtime-capped 20)' },
-    { title: 'Backlog', detail: 'merge + write specs/refactor-backlog.md', model: 'haiku' },
-  ],
-}
-
-// The Workflow runtime hands `args` to a script verbatim, so a caller that passes a
-// JSON-ENCODED STRING instead of a real object gets that string back here. The old
-// `typeof args === 'string' ? args.trim()` then took the whole blob as the value — which
-// is how a report landed on disk named `specs/reports/{"feature": "x"}.md`, and how
-// maxRounds/smoke were silently dropped on the same run. Parse it back into the object
-// it was meant to be; a bare slug stays valid shorthand.
-const ARGS = (() => {
-  if (typeof args === 'string') {
-    const t = args.trim()
-    if (t.startsWith('{')) {
-      try { const o = JSON.parse(t); if (o && typeof o === 'object' && !Array.isArray(o)) return o } catch {}
-    }
-    return { feature: t, target: t }
-  }
-  return args && typeof args === 'object' ? args : {}
-})()
-const target = ARGS.target || ''
-
-// The profile-reader returns through a StructuredOutput tool call, and a haiku agent
-// intermittently nests the whole profile as a JSON *string* under a single wrapper field
-// ({"output": "{\"surfaces\": …}"}) instead of putting the profile's keys at the top level.
-// The schema here used to be {type:'object', additionalProperties:true} — no declared
-// properties, no required keys — so that wrapper validated cleanly and every field then read
-// as undefined: `surfaces` fell back to [], parallel([]) dispatched zero agents, the
-// dead-agent guard had no surfaces to find missing, and the run reported a verdict having
-// done nothing. On the surface it is indistinguishable from a clean run with an empty diff.
-// Declaring the shape gives the tool layer something to validate and the agent something to
-// aim at; unwrapProfile() salvages a wrapped return that still gets through; and the
-// zero-surface abort below makes the silent-success path impossible either way.
-// See also the structured-output section of core/agents/profile-reader.md.
-const PROFILE = {
-  type: 'object', additionalProperties: true,
-  properties: {
-    error: { type: 'string', description: 'set ONLY when PIPELINE.md is missing or unparseable' },
-    surfaces: {
-      type: 'array',
-      description: "one entry per surface, at the TOP LEVEL of this object — never a JSON string",
-      items: {
-        type: 'object', required: ['key'], additionalProperties: true,
-        properties: { key: { type: 'string' }, path: { type: 'string' }, agent: { type: 'string' } },
-      },
-    },
-  },
-}
-
-// Salvage a profile handed back as JSON text rather than as an object — either the whole
-// return, or nested under a single wrapper field. Anything already shaped like a profile
-// (has `surfaces`, or is the documented `{error}` failure shape) passes through untouched.
-const unwrapProfile = p => {
-  if (typeof p === 'string') { try { return JSON.parse(p) } catch { return null } }
-  if (!p || typeof p !== 'object') return null
-  if (Array.isArray(p.surfaces) || p.error) return p
-  for (const v of Object.values(p)) {
-    if (typeof v !== 'string') continue
-    try {
-      const inner = JSON.parse(v)
-      if (inner && typeof inner === 'object' && !Array.isArray(inner)) return inner
-    } catch {}
-  }
-  return p
-}
-
-const GATES = {
-  type: 'object', required: ['failures'], additionalProperties: false,
-  properties: {
-    failures: {
-      type: 'array', maxItems: 40,
-      items: {
-        type: 'object', required: ['file', 'line', 'kind', 'summary'], additionalProperties: false,
-        properties: {
-          file: { type: 'string' }, line: { type: 'integer' },
-          kind: { enum: ['lint', 'format', 'type', 'test'] },
-          summary: { type: 'string', description: 'one line, no output excerpts' },
-        },
-      },
-    },
-    overflow: { type: 'integer', description: 'failures beyond the 40-item cap' },
-  },
-}
-
-const BACKLOG = {
-  type: 'object', required: ['items'], additionalProperties: false,
-  properties: {
-    items: {
-      type: 'array', maxItems: 30,
-      items: {
-        type: 'object', required: ['severity', 'file', 'line', 'kind', 'fix'], additionalProperties: false,
-        properties: {
-          severity: { enum: ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'] },
-          file: { type: 'string' }, line: { type: 'integer' },
-          kind: { enum: ['rule', 'tdd', 'lint', 'format', 'type', 'security'] },
-          fix: { type: 'string', description: 'one concrete change, one line, no code excerpts' },
-        },
-      },
-    },
-    overflow: { type: 'integer' },
-  },
-}
-
-// ── Phase 0 — profile ────────────────────────────────────────────────────────
-phase('Profile')
-const profile = unwrapProfile(await agent(
-  'Return this project\'s PIPELINE.md `yaml pipeline-profile` block as JSON, per your instructions.',
-  { agentType: 'profile-reader', label: 'profile', schema: PROFILE, effort: 'low' },
-))
-if (!profile || profile.error) {
-  return { error: `profile unreadable: ${(profile && profile.error) || 'profile-reader returned nothing'}` }
-}
-const cmds = profile.commands || {}
-const surfaces = Array.isArray(profile.surfaces) ? profile.surfaces : []
-// A profile with no surfaces cannot do this workflow's work, and every later
-// guard compares against `surfaces` — an empty list makes them all vacuously
-// pass. Fail loudly here instead of finishing with nothing done.
-if (!surfaces.length) {
-  return { error: 'profile has no surfaces — nothing would be audited. the `yaml pipeline-profile` block in PIPELINE.md is empty or unparseable, or the profile-reader mis-returned; run /cohorte-doctor' }
-}
-const quiet = (q, full) => (q && !String(q).startsWith('<') ? q : full ? `${full} 2>&1 | tail -40` : '')
-const scope = target || 'the whole repo'
-
-// ── Phase 1 — mechanical gates, staged to disk ───────────────────────────────
-phase('Gates')
-const gateCmds = [
-  cmds.format ? `${cmds.format} --check` : '',
-  quiet(cmds.lint_quiet, cmds.lint),
-  cmds.typecheck,
-  quiet(cmds.test_quiet, cmds.test),
-].filter(c => c && !String(c).startsWith('<'))
-const gates = await agent(
-  `Run the cohorte audit's mechanical gates, scoped to ${scope}. Commands (adapt the format one to the ` +
-  `project's check mode if --check is wrong): ${gateCmds.map(c => JSON.stringify(c)).join(' · ')}.\n` +
-  'Redirect EVERY command\'s output into specs/reports/audit-gates.txt (append, `cmd >> file 2>&1`) — ' +
-  'never print it — and keep going after failures (this is an inventory, not a gate to pass). Then grep ' +
-  'the file and return each failure as file/line/kind/one-line summary, capped at 40 (set overflow for the rest).',
-  { model: 'haiku', label: 'gates', schema: GATES, effort: 'low' },
-)
-// A dead gates agent is NOT "zero mechanical failures" — silence would read as the
-// cleanest possible inventory from a phase that never ran (SCHEMA.md §Dead agents).
-// The domain auditors still run (they read the staged gates file, which then simply
-// isn't there), but the run must say the mechanical sweep is uncovered.
-const gatesCovered = gates != null
-const mech = (gates && gates.failures) || []
-log(gatesCovered
-  ? `Mechanical failures: ${mech.length}${gates.overflow ? ` (+${gates.overflow} overflow)` : ''}`
-  : 'the gates agent died — mechanical checks NOT covered this run')
-
-// ── Phase 2 — one auditor per domain, concurrent ─────────────────────────────
-// Domains = every surface + `shared` (contract package + anything outside the
-// surface trees). The runtime caps concurrent agents at 20 by default; more domains
-// queue. Raising CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS raises the ceiling, it does not
-// change this script — the queue is the runtime's, and a queued domain is not a lost one.
-phase('Audit')
-const domains = surfaces.map(s => ({ key: s.key, path: s.path }))
-  .concat([{ key: 'shared', path: (profile.contract && profile.contract.path) || '(everything outside the surface trees)' }])
-  .filter(d => !target || target === d.key || String(d.path).startsWith(target) || target.startsWith(String(d.path)))
-if (!domains.length) return { error: `target "${target}" matches no surface/domain` }
-
-const audited = await parallel(domains.map(d => () => agent(
-  'Audit a target against PIPELINE.md (no spec — audit mode, per your agent instructions). Check ' +
-  'conventions for the domain\'s surface, TDD coverage (untested entry points / modules), and — if the ' +
-  'profile enables them — mobile-first + design-system usage. Mechanical findings are already staged: ' +
-  'read specs/reports/audit-gates.txt and fold the ones in your domain in. Return the prioritized items, ' +
-  'capped at 30, one line each, no code excerpts. — Variable slots: domain: ' +
-  `${d.key} · tree: ${d.path}${target ? ` · human-requested target: ${target}` : ''}`,
-  { agentType: 'review', label: `audit:${d.key}`, schema: BACKLOG },
-).then(r => r && { key: d.key, items: r.items, overflow: r.overflow || 0 })))
-const perDomain = audited.filter(Boolean)
-// A dead auditor returns null, and a domain with no result is indistinguishable
-// from a domain with nothing to report — the backlog would simply omit it and the
-// human would read that as "clean". Name them instead.
-const deadDomains = domains.filter(d => !perDomain.some(p => p.key === d.key)).map(d => d.key)
-if (deadDomains.length) log(`Auditor died on: ${deadDomains.join(', ')} — those domains are NOT audited`)
-
-// ── Phase 3 — merge + write the backlog ──────────────────────────────────────
-phase('Backlog')
-const SEV = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 }
-const body = ['# Refactor backlog', '', `> Generated by the cohorte-audit workflow (scope: ${scope}).`]
-if (deadDomains.length) {
-  body.push('', `> ⚠ NOT audited (the auditor died): ${deadDomains.join(', ')} — absence of items below`,
-    '> for those domains means "not looked at", not "clean". Re-run the audit for them.')
-}
-if (!gatesCovered) {
-  body.push('', '> ⚠ Mechanical gates NOT run (the gates agent died) — lint/typecheck/test failures',
-    '> are uncounted below. Re-run the audit for the mechanical sweep.')
-}
-let total = 0
-for (const d of perDomain) {
-  const items = [...d.items].sort((a, b) => SEV[a.severity] - SEV[b.severity])
-  total += items.length
-  body.push('', `## ${d.key}`, '')
-  for (const it of items) body.push(`- [ ] ${it.severity} · ${it.file}:${it.line} · ${it.kind} · ${it.fix}`)
-  if (d.overflow) body.push(`- [ ] (+${d.overflow} more beyond the cap — re-audit ${d.key} after this pass)`)
-}
-const written = await agent(
-  `Write EXACTLY this content to specs/refactor-backlog.md (overwrite), then return the single word done:\n<<<BACKLOG\n${body.join('\n')}\nBACKLOG`,
-  { model: 'haiku', label: 'write-backlog', effort: 'low' },
-)
-// Returning `backlog: <path>` when the writer died points /cohorte-refactor at a file
-// that does not exist (or, worse, at the PREVIOUS run's stale backlog).
-const backlogOk = written != null && /done/i.test(String(written))
-
-return {
-  backlog: backlogOk ? 'specs/refactor-backlog.md' : '(NOT written — the backlog writer died)',
-  notAudited: deadDomains,   // absence of findings here means "not looked at"
-  mechanicalFailures: gatesCovered ? mech.length : null,  // null = gates agent died, NOT zero
-  gatesCovered,
-  domains: Object.fromEntries(perDomain.map(d => [d.key, d.items.length + (d.overflow || 0)])),
-  total,
-  top: perDomain.flatMap(d => d.items.map(it => ({ ...it, domain: d.key })))
-    .sort((a, b) => SEV[a.severity] - SEV[b.severity]).slice(0, 10)
-    .map(it => `[${it.severity}] ${it.domain} · ${it.file}:${it.line} — ${it.fix}`),
-  next: !backlogOk
-    ? 'the backlog was NEVER written (writer died) — the counts above are real but nothing is on disk; re-run the audit'
-    : deadDomains.length
-      ? `re-audit ${deadDomains.join(', ')} (auditor died — not covered), then /cohorte-refactor <domain>`
-      : 'refactor a domain with /cohorte-refactor <domain> (or the refactor workflow for big domains)',
-}