cohorte 1.3.4 → 1.4.0

package/CHANGELOG.md

@@ -3,6 +3,49 @@
 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

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 → review → fix until zero findings (add `smoke` to run the app each round); 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. |
@@ -284,7 +283,6 @@ it out turn by turn:
 
 | Script                  | What it runs                                                                              |
 | ----------------------- | ----------------------------------------------------------------------------------------- |
-| `workflows/cycle.js`    | **The full dev cycle on a frozen spec**: contract → parallel build → review(+cross-check) → fix (∥ smoke each round if opted in via `args.smoke`), looping until zero findings (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.
@@ -338,7 +335,7 @@ core/                   # copied verbatim into ~/.claude (global) or <project>/.
   commands/             # init-pipeline + the pipeline commands + /update-pipeline
   hooks/                # gate.py (destructive-command gate; branch-aware; preflight phase gate)
   templates/            # handoff / brainstorm-return / design-brief / review-feedback / pr-body / spec
-  workflows/            # opt-in Workflow-runtime scripts: cycle.js / review.js / audit.js / refactor.js
+  workflows/            # opt-in Workflow-runtime scripts: review.js / audit.js / refactor.js
 profile/
   PIPELINE.template.md  # the profile skeleton /init-pipeline fills
   SCHEMA.md             # field reference

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,8 +70,16 @@ 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=')) {
@@ -96,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');
@@ -109,7 +136,7 @@ fs.mkdirSync(dest, { recursive: true });
 
 // --- helpers (mirror install.sh) --------------------------------------------
 function copyCore() {
-  // `workflows` = the deterministic orchestration scripts (cycle/review/audit/refactor) the
+  // `workflows` = the deterministic orchestration scripts (review/audit/refactor) the
   // 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']) {

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,7 +37,7 @@ 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).
@@ -73,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.
@@ -84,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/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'
 

package/core/workflows/refactor.js

@@ -29,13 +29,72 @@ export const meta = {
 // /refactor handles it with less overhead than a workflow run.
 const MIN_ITEMS = 5
 
+// 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 wanted = (() => {
-  const d = args && args.domains
+  const d = ARGS.domains
   if (!d || d === 'all') return 'all'
   return Array.isArray(d) ? d : [String(d)]
 })()
 
-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 OPEN = {
   type: 'object', required: ['domains'], additionalProperties: false,
@@ -65,14 +124,20 @@ const VERIFY = {
 
 // ── 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 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 refactored. the `yaml pipeline-profile` block in PIPELINE.md is empty or unparseable, or the profile-reader mis-returned; run /doctor' }
+}
 const byKey = Object.fromEntries(surfaces.map(s => [s.key, s]))
 const contractPath = (profile.contract && profile.contract.path) || ''
 const base = (profile.vcs && profile.vcs.default_branch) || 'main'

package/core/workflows/review.js

@@ -26,10 +26,73 @@ export const meta = {
   ],
 }
 
-const feature = typeof args === 'string' ? args.trim() : args && args.feature
+// 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 isSlug = s => typeof s === 'string' && /^[A-Za-z0-9._-]+$/.test(s)
+const feature = ARGS.feature
 if (!feature) throw new Error('cohorte-review needs args = {feature: "<feature_id>"}')
+if (!isSlug(feature)) {
+  throw new Error(`cohorte-review got a feature id that is not a slug: ${JSON.stringify(feature)}. ` +
+    'Pass args as a real object, e.g. {feature: "titlebar-project-switcher"} — not a JSON string.')
+}
+
+// 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' } },
+      },
+    },
+  },
+}
 
-const PROFILE = { type: 'object', additionalProperties: true }
+// 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 PREFLIGHT = {
   type: 'object', required: ['pass'], additionalProperties: false,
@@ -88,16 +151,22 @@ const VERDICT = {
 
 // ── 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 { verdict: 'ABORTED', reason: `profile unreadable: ${(profile && profile.error) || 'profile-reader returned nothing'}` }
 }
 const cmds = profile.commands || {}
 const base = (profile.vcs && profile.vcs.default_branch) || 'main'
 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 { verdict: 'ABORTED', reason: 'profile has no surfaces — nothing would be reviewed. 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 checks = [cmds.typecheck, quiet(cmds.lint_quiet, cmds.lint), quiet(cmds.test_quiet, cmds.test)]
   .filter(c => c && !String(c).startsWith('<'))

package/dashboard/server/doctor.js

@@ -18,6 +18,13 @@ const FIXED_AGENTS = new Set([
 
 const VALID_STATUS = ['draft', 'frozen', 'in-review', 'shipped'];
 
+// Artifacts the pipeline itself writes into specs/ that are NOT feature specs and have no
+// front-matter status. `/audit` writes specs/refactor-backlog.md by design, so scanning it
+// as a spec made /doctor warn about a file cohorte had just created — a false positive that
+// fired in every project that had ever run /audit. `_`-prefixed files (e.g. _template.md)
+// are already skipped by the reader below.
+const NON_SPEC_FILES = new Set(['refactor-backlog.md']);
+
 const exists = p => { try { return fs.existsSync(p); } catch { return false; } };
 const readText = p => { try { return fs.readFileSync(p, 'utf8'); } catch { return null; } };
 const readJson = p => { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; } };
@@ -226,7 +233,7 @@ function checkIsolation(profile, projectRoot) {
   return mk('isolation', 'Isolation', 'ok', 'feature scripts rendered (worktree state not checked here)');
 }
 
-// Workflow variants (cycle/review/audit/refactor as deterministic multi-agent runs) are opt-in;
+// Workflow variants (review/audit/refactor as deterministic multi-agent runs) are opt-in;
 // the conversational commands stay the default path, so nothing here is ever 'bad'.
 // Whether the session has workflows ENABLED needs a live Claude session — /doctor
 // in-session checks that; here we only check what's on disk.
@@ -238,7 +245,7 @@ function checkWorkflows(projectRoot, globalDir, installMode) {
   const agentsDir = installMode === 'bundled'
     ? path.join(projectRoot, '.claude', 'agents')
     : path.join(globalDir, 'agents');
-  const scripts = ['review.js', 'audit.js', 'refactor.js', 'cycle.js'];
+  const scripts = ['review.js', 'audit.js', 'refactor.js'];
   const missing = scripts.filter(s => !exists(path.join(dir, s)));
   if (missing.length === scripts.length) {
     return mk('workflows', 'Workflows', 'warn',
@@ -263,7 +270,7 @@ function scanSpecs(projectRoot) {
   const dir = path.join(projectRoot, 'specs');
   const specs = [];
   let files = [];
-  try { files = fs.readdirSync(dir).filter(f => f.endsWith('.md') && !f.startsWith('_')); }
+  try { files = fs.readdirSync(dir).filter(f => f.endsWith('.md') && !f.startsWith('_') && !NON_SPEC_FILES.has(f)); }
   catch { return specs; }
   for (const f of files) {
     const txt = readText(path.join(dir, f)) || '';

package/dashboard/server/metrics.js

@@ -11,9 +11,9 @@
 const fs = require('fs');
 const path = require('path');
 
-// `cycle` is the workflow variant's own batch (cycle.js §Close). Without it in this
-// list its per-surface results parse fine but render in no column — the surface table
-// showed rows with every cell empty.
+// `cycle` is a RETIRED phase, kept so metrics files written before its removal still render.
+// Without it in this list its per-surface results parse fine but land in no column — the
+// surface table showed rows with every cell empty.
 const PHASES = ['build', 'review', 'fix', 'smoke', 'cycle'];
 
 // Parse the raw JSONL into normalized batches ({ts, feature, phase, seconds, surfaces}),
@@ -74,7 +74,8 @@ function aggregate(batches) {
       };
       byFeature.set(b.feature, f);
     }
-    // cycle.js reports its round count outside `surfaces` (that map is for surfaces).
+    // The retired cycle phase reported its round count outside `surfaces` (that map is for
+    // surfaces); historical files still carry it.
     if (b.phase === 'cycle' && Number(b.rounds) > 0) f.cycleRounds = Number(b.rounds);
     if (b.ts && (!f.firstTs || b.ts < f.firstTs)) f.firstTs = b.ts;
     if (b.ts && b.ts > f.lastTs) f.lastTs = b.ts;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cohorte",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "description": "Portable, stack-agnostic multi-agent development pipeline for Claude Code — install the core, run /init-pipeline, and it adapts to your project's stack.",
   "bin": {
     "cohorte": "bin/cli.js"