cohorte 1.3.3 → 1.4.0

package/CHANGELOG.md

@@ -3,6 +3,139 @@
 Entries are shown by `/update-pipeline` ("What's new") after a core refresh. Keep them short,
 user-facing, most recent first. One `## <version> — <YYYY-MM-DD>` section per release.
 
+## 1.4.0 — 2026-08-01
+
+> **Re-run `npx cohorte@latest update --global` (or `update`)** — the workflow fixes only apply
+> once the installed core is refreshed. Both the workflow scripts and the `profile-reader` agent
+> are replaced by the update.
+
+- **BREAKING — `/cycle` and `cycle.js` are removed.** The full-cycle workflow is gone: the command
+  file, the script, its tests and its documentation. The conversational path it wrapped is
+  unchanged and remains the way to run a feature — `/build` → `/smoke` → `/review` → `/fix` →
+  `/ship`, with `/clear` safe between each. `review.js`, `audit.js` and `refactor.js` are
+  untouched. Nothing else in the pipeline depended on it; a `/cycle` in an old habit will simply
+  report an unknown command. Metrics files and dashboards that already carry `phase: "cycle"`
+  lines keep rendering them.
+- **A workflow could dispatch zero agents and still report a verdict.** Phase 0's `profile-reader`
+  (haiku) intermittently returned the profile as a JSON *string* nested under a wrapper field
+  (`{"output": "{\"surfaces\": …}"}`) instead of at the top level. The schema was
+  `{type: 'object', additionalProperties: true}` — no declared properties, no required keys — so
+  the wrapper validated cleanly and every field then read as `undefined`: `surfaces` fell back to
+  `[]`, `parallel([])` dispatched **nothing**, and because every later guard compares against
+  `surfaces`, an empty list made them all vacuously pass. The run finished with a verdict, no code
+  written, and no complaint — indistinguishable from a clean run with an empty diff. Fixed in three
+  places: `profile-reader.md` now states that the profile's keys go at the top level of the
+  structured-output tool (with the wrong shapes shown), the schema declares what it expects, and a
+  profile with no surfaces **aborts loudly** instead of proceeding. All three workflows.
+- **`args` given as a JSON string became the feature id.** A caller that JSON-encoded its arguments
+  got that whole blob used as the id — which is how a report was written to
+  `specs/reports/{"feature": "x"}.md` — and the other options (`maxRounds`, `smoke`) silently read
+  as `undefined` on the same run, so a run could skip smoke without saying so. `args` is now parsed
+  back into an object (a bare slug is still valid shorthand), and a feature id that is not a slug
+  throws with an actionable message **before** anything touches the filesystem — so no junk file
+  can be written, and a path-shaped id is rejected.
+- **`/doctor` warned about a file cohorte itself had written.** `/audit` writes
+  `specs/refactor-backlog.md` by design; the spec scanner globbed `specs/*.md` and flagged it for
+  having no valid front-matter `status`. It fired in every project that had ever run `/audit`. Both
+  the conversational `/doctor` and the dashboard port now exclude it.
+- **New: `cohorte metrics` — real cost and runtime per command.** Reconstructs tokens, USD,
+  wall/active time and subagent counts from Claude Code's own transcripts, so it needs nothing
+  enabled and works retroactively on runs that already happened. It is worktree-aware (a feature
+  built across worktrees adds up instead of being dropped), attributes subagent spend back to the
+  command that spawned it, and de-duplicates the repeated `usage` blocks a single API response
+  writes across several transcript lines — summing those naively inflates tokens ~1.8×.
+  `--json`, `--runs`, `--days=N`, `--since=ISO`. Prices live in `scripts/metrics/prices.json`.
+
+## 1.3.4 — 2026-07-31
+
+> **Re-run `npx cohorte@latest update --global` (or `update`)** — the workflow and script
+> fixes only apply once the installed core is refreshed.
+
+- **The dashboard server now has tests.** `dashboard/server/*.js` is shipped runtime code — a
+  hand-rolled YAML parser every `/doctor` check derives from, the metrics aggregator, the JS port
+  of `/doctor`, the board parser, the fleet registry, and the HTTP guards — with no coverage at
+  all. `scripts/test-dashboard.mjs` (83 assertions, in CI) pins each module, including every
+  `/doctor` check both green and deliberately broken.
+- **The gate hook now has tests.** `hooks/gate.py` is the one component that can block a command,
+  and CI only ever checked that it *parsed* — every one of its shipped regressions reached users
+  first. `scripts/test-gate.mjs` drives its real stdin→stdout contract (42 assertions: deny/ask
+  tiers, chained-command splitting, branch-conditional gating at the payload's cwd, the
+  `bypassPermissions` ask⇒deny escalation, config robustness, the preflight phase gate, worktree
+  HEAD matching) and runs in CI. No new defect was found in the gate itself — the behaviour is
+  now pinned.
+- **A crashed reviewer scored as a clean surface.** `agent()` returns `null` when a subagent dies,
+  and a dead reviewer returns zero findings — byte-identical to a surface with nothing wrong. Both
+  `review.js` and `cycle.js` read that as `SHIP`: the review workflow answered "`/ship`" when
+  *every* reviewer had crashed, and the cycle workflow exited **SHIP-READY**, ticked the DoD and
+  stamped the freshness gate over code nobody had read. Unreviewed surfaces are now named in
+  `unreviewedSurfaces` + `questions`, can never score `SHIP`, and the cycle re-reviews instead of
+  dispatching an empty fix round. `scripts/test-workflows.mjs` (new, run in CI) pins this.
+- **Swept the whole "dead agent read as success" family across all four workflows** — the same
+  root cause as the two above, found at eight more call sites by auditing every `agent()` result
+  in `cycle.js` · `review.js` · `audit.js` · `refactor.js`. The worst: a dead **diff-staging**
+  agent in `review.js` returned `verdict: SHIP` ("no diff — nothing to review") for a feature
+  nobody had looked at; and a dead **close/staging** agent let both `/cycle` and the review
+  workflow report `SHIP-READY` + a report path + "ship is a straight shot" when the report, the
+  DoD ticks, the freshness stamp and the metrics had never been written (and `/ship`'s freshness
+  gate skips silently when those fields are absent, so the human would have shipped on it). Also:
+  a dead auditor made a domain look **clean** instead of unaudited; a dead backlog writer/reader
+  and a dead item-ticker were each reported as success. Every one of these now distinguishes
+  "died" from "succeeded with nothing to say", and `scripts/test-workflows.mjs` pins all of them.
+- **A dead contract agent was reported as a successful re-authoring.** Same failure shape as the
+  crashed reviewer: when the lead-equivalent agent that re-authors spec §5 + the contract file
+  died, `/cycle` still pushed a `contractChanges` entry and handed **every** consuming surface a
+  CRITICAL "the contract was RE-AUTHORED — re-read it and realign" item, pointing at a file
+  nobody had touched. It now reports the contract as UNCHANGED and ripples nothing.
+- **A red preflight nobody owns burned every remaining round.** When no surface path appeared in
+  the failure tail and no implementer had survived the build, the fix round dispatched *zero*
+  agents, the next round found the same red gates, and the loop spun to the cap doing literally
+  nothing before reporting a stale verdict. It now stops immediately with the failure tail.
+- **Findings belonging to no surface were dropped silently.** A finding whose file sits outside
+  every surface tree — reachable when the diff-staging agent names a key the profile lacks —
+  stayed in the open set (so the loop could never exit clean) while nobody was ever dispatched to
+  fix it. They are now named, with their `file:line`, in `questions`.
+- **`/cycle` build telemetry hid dead implementers**: results were mapped over the *survivors*, so
+  two of three surfaces reported `ok,ok` and the dead one vanished from the funnel entirely.
+- **The review workflow sent HIGH findings straight to `/ship`.** A `SHIP` verdict can legitimately
+  carry HIGH/MEDIUM findings (only CRITICAL and security force a fix), but the conversational
+  `/review` routes any surviving HIGH to `/fix` — the workflow said `/ship`. It now only recommends
+  shipping when nothing above LOW survived, and stamps the freshness gate on that same condition.
+- **Smoke is now opt-in in the cycle workflow** — `/cycle <id> smoke` (or `args.smoke: true`).
+  Booting the app every round is expensive and a library project has nothing to smoke. Without it
+  the run reports `smoke: "SKIPPED"`, leaves the runtime-flow DoD boxes unticked, and says so.
+- **The dashboard reset could move the shared global core.** Nothing stopped a project path of
+  `~` — reset would then rename `~/.claude` into a backup dir and break every repo on the machine,
+  while the UI promised the global core is never touched. It now refuses that path outright.
+- **The cycle workflow polluted the metrics with phantom surfaces.** It wrote `rounds` / `verdict` /
+  `smoke` inside the metrics line's `surfaces` map, so the dashboard rendered them as three surface
+  rows and scored `rounds: "1"` as a failing surface. Run-level facts now sit outside `surfaces`,
+  and the dashboard knows the `cycle` phase.
+- **Telemetry from bundled installs reported no core version.** `telemetry-send.sh` read `VERSION`
+  only from the *global* core; it now resolves the core that ships it. Payloads are also hardened —
+  a quote or newline in the results string used to produce JSON the collector dropped.
+- **Every kanban card move added a blank line.** Ten moves of one card padded a board with fifteen
+  of them, and every phase command moves cards. Runs of blank lines are now collapsed; a board is
+  byte-stable across moves. Sub-notes of a duplicate card are no longer duplicated either.
+- **Python bytecode could reach the published package and users' `.claude`.** `.npmignore` is inert
+  under an explicit `files` allowlist, so its `__pycache__/` rule never fired, and all three
+  installers copied the directory verbatim. Excluded at both ends, asserted in CI.
+- **Every non-design surface agent rendered with a blank first TDD step.** `<SURFACE_TDD_STEP1>`
+  sat as numbered item 1 of the TDD list but is filled only for `uses_design` surfaces, so every
+  other agent got an empty "1." above its real first step. It is now a lead-in paragraph.
+- Doc/template corrections found by reading the whole core against the code: the spec template's
+  `## 6+. Surface tasks` could collide with the `§8`/`§9` sections the pipeline references by
+  number; `/init-pipeline` step 04 forgot `smoke.md` in its "leave the fixed agents as-is" list;
+  the getting-started page placed `implementer.template.md` in `agents/` (it ships in `pipeline/`);
+  the dashboard docs never documented the CSRF/DNS-rebinding guard; `dashboard/README.md` was
+  missing `metrics.js`, `/api/metrics` and `/audit`; the two reference-only templates
+  (`agent-handoff.md`, `review-feedback.md`) are unreferenced copies of shapes that live in the
+  agents — `review-feedback.md` had drifted and is re-synced, and both now say so.
+- Smaller: the dashboard no longer stalls for 13 s per project when npm is unreachable (failed
+  lookups are cached and de-duplicated); `--port=` rejects a non-numeric value instead of listening
+  on a random port; a missing hashed asset 404s instead of being served `index.html`; a project
+  card is now keyboard-activatable; long headless logs are trimmed instead of growing unbounded;
+  `install.sh --help` exists; the preflight stamp is written once per distinct directory.
+
 ## 1.3.3 — 2026-07-30
 
 > **Re-run `npx cohorte@latest update --global` (or `update`)** — the gate fixes only apply once

package/README.md

@@ -217,7 +217,6 @@ it in `.claude/pipeline/VERSION` and bundled repos in their committed `pipeline.
 | `/brainstorm`        | Interactive persona panel that pressure-tests a feature idea.                         |
 | `/spec`              | Freeze the feature spec + contract into `specs/<id>.md` (UI features also get a standalone design brief at `specs/design/<id>.md`). Also applies review returns. |
 | `/build <id>`        | Lead authors the contract, then dispatches one implementer per surface in parallel.   |
-| `/cycle <id>`        | Launch the full dev-cycle **workflow** on a frozen spec: build → smoke ∥ review → fix until zero findings; deferred questions in the output. Needs workflows enabled (falls back to the conversational path). |
 | `/smoke <id>`        | Run the feature for real: infra up, contract endpoints, UI flows, design conformance. |
 | `/review <id>`       | Read-only review agents (one per touched surface, parallel) audit the diff vs the spec. |
 | `/fix <id>`          | Apply a review/smoke report: remediation into the spec, re-dispatch only the surfaces with findings. |
@@ -278,13 +277,12 @@ Rules that make it safe:
 
 ### Workflows — deterministic multi-agent runs (opt-in)
 
-Three phases also ship as **workflow scripts** for the Claude Code Workflow runtime — the same
+Four phases also ship as **workflow scripts** for the Claude Code Workflow runtime — the same
 fan-out the commands orchestrate, but driven by a deterministic script instead of the lead reasoning
 it out turn by turn:
 
 | Script                  | What it runs                                                                              |
 | ----------------------- | ----------------------------------------------------------------------------------------- |
-| `workflows/cycle.js`    | **The full dev cycle on a frozen spec**: contract → parallel build → smoke ∥ review(+cross-check) → fix, looping until zero findings + PASS (contract changes handled in-loop by a lead-equivalent agent). Human decisions come back in a `questions` array at the END — empty when `/brainstorm`+`/spec` did their job. Exits SHIP-ready (DoD ticked, freshness stamped) so `/ship` is a straight shot. |
 | `workflows/review.js`   | Preflight gate (aborts while red — zero agents), one reviewer per touched surface, adversarial cross-check of CRITICAL/security findings, merged verdict only. |
 | `workflows/audit.js`    | One auditor per domain (every surface + shared) concurrently, prioritized `specs/refactor-backlog.md`. |
 | `workflows/refactor.js` | Big domains only: `shared` first and alone, then parallel surface implementers, per-domain verify + one retry. |
@@ -297,10 +295,9 @@ The essentials:
 - **Prerequisite: Claude Code ≥ 2.1.154** with workflows enabled. `/doctor` (check 8) tells you
   which path your session will take and why.
 - **No input mid-run — questions at the edges.** A workflow runs to completion without asking
-  anything. `cycle.js` moves the decisions to its boundaries: a readiness gate refuses a non-frozen
-  spec up front, and whatever would have been a mid-run question lands in the result's `questions`
-  array at the end (spec gaps, hit round-cap) — answer them, rerun the cycle. The destructive-
-  command gate still fires inside workflow subagents; in unattended runs its confirms become denies.
+  anything: whatever would have been a mid-run question lands in the result at the end. The
+  destructive-command gate still fires inside workflow subagents; in unattended runs its confirms
+  become denies.
 - Phase 0 of every script is the `profile-reader` agent (haiku) — it reads `PIPELINE.md` and hands
   the script the profile as JSON, since workflow scripts have no filesystem access. Mechanical
   phases run on haiku; judgment phases use the same pinned agents as the commands.

package/bin/cli.js

@@ -35,6 +35,7 @@ Usage:
   cohorte install   [target] [--global]
   cohorte update    [target] [--global]
   cohorte dashboard [target] [--port=N] [--host=ADDR] [--open]
+  cohorte metrics   [target] [--days=N] [--since=ISO] [--runs] [--json]
   cohorte version
 
 Commands:
@@ -49,6 +50,11 @@ Commands:
             by default (loopback only — its actions execute code). --host=ADDR
             to expose (e.g. --host=0.0.0.0, prints a security warning). --open
             to launch the browser.
+  metrics   Cost and runtime per command, reconstructed from Claude Code's own
+            transcripts (tokens, USD, wall/active time, subagent count). Reads
+            ~/.claude/projects — nothing to enable, and it covers runs that
+            already happened. Worktree-aware, so a feature adds up. --json for
+            the raw rollup, --runs to include every individual invocation.
   version   Print the installed CLI version.`);
   process.exit(code);
 }
@@ -64,12 +70,30 @@ let port = parseInt(process.env.COHORTE_DASHBOARD_PORT, 10) || 4317;
 let host = process.env.COHORTE_DASHBOARD_HOST || '127.0.0.1';
 let openBrowser = false;
 
+// Flags that belong to `metrics` and are forwarded verbatim to the collector. They are
+// listed here rather than parsed, so the collector stays the single source of truth for
+// its own options — but the generic "unknown flag" guard below must not reject them.
+const metricsFlags = [];
+const isMetricsFlag = (a) =>
+  a === '--json' || a === '--runs' || a.startsWith('--days=') || a.startsWith('--since=');
+
 for (const a of args) {
-  if (a === 'install' || a === 'update' || a === 'dashboard') mode = a;
+  if (a === 'install' || a === 'update' || a === 'dashboard' || a === 'metrics') mode = a;
+  else if (isMetricsFlag(a)) metricsFlags.push(a);
   else if (a === 'version' || a === '--version' || a === '-v') { console.log(VERSION); process.exit(0); }
   else if (a === '--global' || a === '-g') scope = 'global';
-  else if (a.startsWith('--port=')) { port = parseInt(a.slice(7), 10); }
-  else if (a.startsWith('--host=')) { host = a.slice(7); }
+  else if (a.startsWith('--port=')) {
+    // A bad value used to land as NaN, which http.listen() silently treats as
+    // "any free port" — the banner then printed `localhost:NaN` and nothing worked.
+    port = parseInt(a.slice(7), 10);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      console.error(`error: --port must be an integer 1-65535 (got "${a.slice(7)}")`);
+      process.exit(2);
+    }
+  } else if (a.startsWith('--host=')) {
+    host = a.slice(7).trim();
+    if (!host) { console.error('error: --host= needs an address (e.g. --host=0.0.0.0)'); process.exit(2); }
+  }
   else if (a === '--open') { openBrowser = true; }
   else if (a === 'help' || a === '--help' || a === '-h') usage(0);
   else if (a.startsWith('-')) { console.error(`error: unknown flag: ${a}`); usage(2); }
@@ -86,6 +110,19 @@ if (mode === 'dashboard') {
   return;
 }
 
+// --- metrics: cost + runtime per command ------------------------------------
+// The collector is ESM and this CLI is CommonJS, so it runs as a child process rather
+// than being required. stdio is inherited so --json stays pipeable.
+if (mode === 'metrics') {
+  const script = path.join(pkgRoot, 'scripts', 'metrics', 'collect.mjs');
+  if (!fs.existsSync(script)) {
+    console.error(`error: metrics collector not found at ${script}`);
+    process.exit(1);
+  }
+  const r = spawnSync(process.execPath, [script, target, ...metricsFlags], { stdio: 'inherit' });
+  process.exit(r.status == null ? 1 : r.status);
+}
+
 // --- paths -------------------------------------------------------------------
 const globalDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
 const dest = scope === 'global' ? globalDir : path.join(target, '.claude');
@@ -103,8 +140,16 @@ function copyCore() {
   // Workflow runtime resolves from .claude/workflows (bundled) or ~/.claude/workflows
   // (global) — same copy rule in both modes, like commands.
   for (const d of ['commands', 'hooks', 'templates', 'workflows']) {
-    fs.cpSync(path.join(src, 'core', d), path.join(dest, d), { recursive: true, force: true });
+    fs.cpSync(path.join(src, 'core', d), path.join(dest, d), {
+      recursive: true,
+      force: true,
+      // Never carry a Python bytecode cache into a user's .claude. It appears in a
+      // source checkout the moment anyone compiles or imports gate.py (CI does), it
+      // is machine- and interpreter-specific, and copy-over never deletes it later.
+      filter: s => !s.split(/[\\/]/).includes('__pycache__') && !s.endsWith('.pyc'),
+    });
   }
+  fs.rmSync(path.join(dest, 'hooks', '__pycache__'), { recursive: true, force: true });
   // 0.1.19 renamed questionnaire-domain-brief.md → research-brief.md; drop the stale copy.
   fs.rmSync(path.join(dest, 'templates', 'questionnaire-domain-brief.md'), { force: true });
   const pipelineDir = path.join(dest, 'pipeline');

package/core/agents/implementer.template.md

@@ -61,12 +61,17 @@ tools are unavailable or come up empty.
 
 ## How you work — strict TDD (red → green → refactor)
 
-1. <SURFACE_TDD_STEP1>
-2. **Write the failing test(s) first** from the frozen contract. Cover exactly what your baked
+<!-- <SURFACE_TDD_STEP1> is a LEAD-IN paragraph, not a numbered item: it is filled only for a
+     `uses_design` surface (the design-pull step) and renders as nothing otherwise. As a numbered
+     item it left every non-design agent with a blank "1." above the real first step. -->
+
+<SURFACE_TDD_STEP1>
+
+1. **Write the failing test(s) first** from the frozen contract. Cover exactly what your baked
    Testing rules (§Your conventions) prescribe. Run the test command and watch it fail (red).
-3. Implement until green, following your baked conventions.
-4. Refactor to the conventions. Keep tests green.
-5. **Lint + format before handoff:** run your surface's lint and fix every issue. If the project
+2. Implement until green, following your baked conventions.
+3. Refactor to the conventions. Keep tests green.
+4. **Lint + format before handoff:** run your surface's lint and fix every issue. If the project
    registers a PostToolUse format hook (see `.claude/settings.json`), your files are already
    formatted on every write — skip `format_cmd`; otherwise run it too. Code you hand off must be
    lint-clean and formatted.

package/core/agents/profile-reader.md

@@ -21,6 +21,28 @@ nothing only when something is wrong.
 3. Return **only** the JSON object — no fences, no commentary, no markdown. Your final message is
    parsed by a script.
 
+## Returning through a structured-output tool
+
+When you are given a tool to return structured output, the profile's own keys go at the **top
+level** of that tool's input — `surfaces`, `commands`, `vcs`, `contract`, and the rest, as real
+JSON values.
+
+Do **not** serialize the profile to a string and nest it under a wrapper field. These are wrong:
+
+```json
+{"output": "{\"surfaces\": [ … ]}"}      ← the profile as text under a wrapper
+{"profile": {"surfaces": [ … ]}}         ← the profile nested one level down
+```
+
+This is right:
+
+```json
+{"surfaces": [ … ], "commands": { … }, "vcs": { … }}
+```
+
+A wrapped return costs the caller everything: the script reads `surfaces` as absent, builds
+nothing, and reports success anyway.
+
 ## Failure shape
 
 If `PIPELINE.md` is missing, or the `yaml pipeline-profile` fence is absent or unparseable, return

package/core/commands/doctor.md

@@ -37,14 +37,16 @@ fix only with the human's go-ahead (or hand them the command).
    (`review.md`, `release.md`, `smoke.md`, `profile-reader.md` — repo or `~/.claude/agents/`) must
    each carry their `model:` line too (sonnet/haiku/sonnet/haiku). **Command pins:** every mechanical command file
    (`build`, `review`, `fix`, `smoke`, `ship`, `audit`, `refactor`, `doctor`, `align-ds`,
-   `update-pipeline`, `cycle` — in `.claude/commands/` or `~/.claude/commands/`) carries `model: sonnet` in
+   `update-pipeline` — in `.claude/commands/` or `~/.claude/commands/`) carries `model: sonnet` in
    its frontmatter — ⚠️ if missing (the lead's orchestration turn then bills at the session model,
    e.g. Opus/Fable). `brainstorm`, `spec`, and `init-pipeline` are intentionally unpinned
    (interactive — they inherit the session model).
 3. **Hooks & gate.** `.claude/gate-config.json` exists and mirrors the profile's `gate` block
    (regenerate if drifted). The PreToolUse gate hook is registered **once** for the install mode
    (bundled: repo `settings.json`; global: `~/.claude/settings.json` — flag double registration,
-   it double-prompts). Hook files exist at the registered paths.
+   it double-prompts) **with a matcher covering both `Bash` and `Task`** — a `Bash`-only matcher
+   leaves the preflight phase gate dead (the 1.3.0–1.3.1 regression). Hook files exist at the
+   registered paths.
 4. **Retrieval** (if `retrieval.provider` ≠ `none`). Run the SCHEMA.md §Code retrieval health
    check: CLI resolvable from PATH, `.mcp.json` entry present in PATH-proof launcher form,
    `.serena/` gitignored, server actually connects.
@@ -71,7 +73,7 @@ fix only with the human's go-ahead (or hand them the command).
    take and why:
    - **Claude Code version** ≥ 2.1.154 (`claude --version 2>/dev/null | head -1`) — older or no CLI
      on PATH ⇒ conversational only.
-   - **Scripts present:** `<core>/workflows/review.js` + `audit.js` + `refactor.js` + `cycle.js` —
+   - **Scripts present:** `<core>/workflows/review.js` + `audit.js` + `refactor.js` —
      missing on a current core ⇒ half-done install, re-run install/update.
    - **Phase-0 agent present:** `<agents dir>/profile-reader.md` (repo `.claude/agents/` bundled or
      `~/.claude/agents/` global) — the workflows abort without it.
@@ -82,7 +84,9 @@ fix only with the human's go-ahead (or hand them the command).
    End the check with ONE summary line, e.g.
    `workflows: available (opt-in — ask to "run the review workflow")` or
    `workflows: unavailable (<first failing prerequisite>) — conversational commands (the default)`.
-9. **Specs & metrics.** Every `specs/*.md` front-matter `status` is a valid stage; `shipped` specs
+9. **Specs & metrics.** Every `specs/*.md` front-matter `status` is a valid stage — excluding
+   `_`-prefixed files and `specs/refactor-backlog.md`, which `/audit` writes as a backlog, not a
+   spec, and which has no front-matter to check; `shipped` specs
    with a live worktree flagged (see 6). `.claude/pipeline-metrics.jsonl` and `specs/reports/` (the
    `/review`·`/smoke` report buffer that lets a `/fix` survive a `/clear`) are gitignored. Metrics
    belong to the **main checkout** — a `pipeline-metrics.jsonl` inside a live feature worktree is a

package/core/hooks/gate.py

@@ -100,18 +100,33 @@ def current_branch(cwd: str):
     return None
 
 
-def current_head(cwd: str):
-    """HEAD sha at `cwd`, or None."""
+def known_heads(cwd: str):
+    """Every HEAD sha this repo currently has checked out: `cwd`'s plus each
+    linked worktree's. The preflight may legitimately have run in a feature
+    worktree while the Task dispatch fires from the main checkout (or vice
+    versa) — comparing against a single HEAD flags those runs as stale."""
+    heads = set()
     try:
         out = subprocess.run(
             ["git", "rev-parse", "HEAD"],
             cwd=cwd, capture_output=True, text=True, timeout=3,
         )
+        if out.returncode == 0 and out.stdout.strip():
+            heads.add(out.stdout.strip())
+    except Exception:
+        pass
+    try:
+        out = subprocess.run(
+            ["git", "worktree", "list", "--porcelain"],
+            cwd=cwd, capture_output=True, text=True, timeout=3,
+        )
         if out.returncode == 0:
-            return out.stdout.strip() or None
+            for line in out.stdout.splitlines():
+                if line.startswith("HEAD "):
+                    heads.add(line.split(" ", 1)[1].strip())
     except Exception:
         pass
-    return None
+    return heads
 
 
 def check_preflight(payload: dict, cfg: dict) -> int:
@@ -140,8 +155,8 @@ def check_preflight(payload: dict, cfg: dict) -> int:
             if age_min > max_age:
                 why = f"the preflight stamp is {age_min:.0f} min old (max {max_age:.0f})"
             else:
-                head = current_head(session_cwd(payload))
-                if head and sha not in ("", "none") and head != sha:
+                heads = known_heads(session_cwd(payload))
+                if heads and sha not in ("", "none") and sha not in heads:
                     why = "HEAD moved since the preflight ran"
         except Exception:
             why = "the preflight stamp is unreadable (expected `<epoch> <sha>`)"

package/core/templates/agent-handoff.md

@@ -1,6 +1,11 @@
-# HANDOFF — <surface> · `<feature_id>`
+# HANDOFF — <surface> · <feature_id>
 
-<!-- Keep it tight: the lead only acts on mismatches, test failures, remediation ticks, and TODOs.
+<!-- REFERENCE COPY — not read at runtime. The AUTHORITATIVE shape is inlined in
+     core/agents/implementer.template.md (§"Your return"), because a rendered agent must
+     not need a second file read to know its own output format. This file exists for humans
+     reading the core; keep it byte-aligned with the template, or delete both together.
+
+     Keep it tight: the lead only acts on mismatches, test failures, remediation ticks, and TODOs.
      Never list files one by one — the lead has `git diff --stat`. Never paste code excerpts —
      a file:line reference is enough, the code is on disk. One line per item. -->
 

package/core/templates/review-feedback.md

@@ -1,15 +1,18 @@
 # REVIEW REPORT
 
-<!-- Emitted-report shape. Everything in an HTML comment is guidance — do NOT emit it.
+<!-- REFERENCE COPY — not read at runtime. The AUTHORITATIVE shape is inlined in
+     core/agents/review.md (§"Your return"), because an agent must not need a second
+     file read to know its own output format. This file exists for humans reading the
+     core; keep it byte-aligned with the agent, or delete both together.
+
+     Everything in an HTML comment is guidance — do NOT emit it.
      Verdict rules live in the review agent's instructions (SHIP = no CRITICAL/security;
      REVISE = ≥1 CRITICAL; BLOCK = security vulnerability).
      CAPPED: max 20 findings, ONE line each (severity · file:line · type · concrete fix),
      ZERO code excerpts — file:line is enough, the source is on disk. Overflow ⇒ keep all
      CRITICAL/HIGH/security, fill by severity, close with one `+<n> more …` line. -->
 
-feature_id: <feature_id>
-Feature branch: <feature_branch_prefix><feature_id>
-Commit SHA: <first 12 chars>
+feature_id: <feature_id> · scope: <surface.key>
 
 | Severity | Count |
 | -------- | ----- |

package/core/templates/spec.template.md

@@ -49,9 +49,12 @@ design_files: [] # design page links — full URLs of the form https://claude.ai
 
 - `<slug>...Request` / `<slug>...Response` / `<slug>Base` … (sketch the schemas here)
 
-## 6+. Surface tasks
+## 6. Surface tasks
 
-> One subsection per surface in `PIPELINE.md` §surfaces (e.g. backend, frontend), each TDD.
+> 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 (`/smoke` drives "§8 flows", `/review` checks "§9 acceptance"), so a
+> third surface must not become a §8 of its own.
 
 ### <surface.key>
 

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

@@ -14,7 +14,8 @@
    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 `review.md` + `release.md` + `profile-reader.md` as-is (generic).
+   Leave the fixed agents as-is (generic, shipped by the installer): `review.md`, `release.md`,
+   `smoke.md`, `profile-reader.md`.
 4. **Generate `.claude/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>}}`

package/core/workflows/audit.js

@@ -21,9 +21,67 @@ export const meta = {
   ],
 }
 
-const target = (typeof args === 'string' ? args.trim() : args && args.target) || ''
+// 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 || ''
 
-const PROFILE = { type: 'object', additionalProperties: true }
+// 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,
@@ -64,15 +122,21 @@ const BACKLOG = {
 
 // ── Phase 0 — profile ────────────────────────────────────────────────────────
 phase('Profile')
-const profile = await agent(
+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 /doctor' }
+}
 const quiet = (q, full) => (q && !String(q).startsWith('<') ? q : full ? `${full} 2>&1 | tail -40` : '')
 const scope = target || 'the whole repo'
 
@@ -114,11 +178,20 @@ const audited = await parallel(domains.map(d => () => agent(
   { 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.')
+}
 let total = 0
 for (const d of perDomain) {
   const items = [...d.items].sort((a, b) => SEV[a.severity] - SEV[b.severity])
@@ -127,18 +200,26 @@ for (const d of perDomain) {
   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)`)
 }
-await agent(
+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 /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: 'specs/refactor-backlog.md',
+  backlog: backlogOk ? 'specs/refactor-backlog.md' : '(NOT written — the backlog writer died)',
+  notAudited: deadDomains,   // absence of findings here means "not looked at"
   mechanicalFailures: mech.length,
   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: 'refactor a domain with /refactor <domain> (or the refactor workflow for big domains)',
+  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 /refactor <domain>`
+      : 'refactor a domain with /refactor <domain> (or the refactor workflow for big domains)',
 }