cohorte 1.2.6 → 1.3.1

package/CHANGELOG.md

@@ -3,6 +3,66 @@
 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.3.1 — 2026-07-30
+
+- **`/cycle <feature_id> [max_rounds]`** — a launcher command for the full dev-cycle workflow,
+  so you don't have to phrase the request in prose. It resolves `workflows/cycle.js`
+  (bundled or global), checks the runtime is available (missing ⇒ it hands you the
+  conversational `/build` → `/smoke` → `/review` path instead), sanity-checks the spec is
+  frozen, launches the workflow in the background, then relays the verdict: outcome,
+  contract re-authorings to eyeball, the `questions` array verbatim, and the next step
+  (`/ship` on SHIP-READY, rerun `/cycle` or `/fix` otherwise). Kanban card moves included.
+
+## 1.3.0 — 2026-07-30
+
+**Token economy — immediate wins, no workflow needed:**
+
+- **Deterministic pre-flight before `/review` and `/smoke`.** A shipped script
+  (`pipeline/scripts/preflight.sh`) runs typecheck + lint + tests first; red ⇒ the command
+  aborts with the raw last-40 lines and **spawns zero agents** — a reviewer no longer burns
+  its whole run rediscovering what `tsc` printed for free. Green runs stamp
+  `.claude/preflight.ok`, and `gate.py` enforces it as a **phase gate**: a review/smoke
+  dispatch with a missing/stale stamp gets a confirm (`gate.preflight` in the profile).
+- **Quiet commands.** New profile fields (`test_quiet_cmd`/`lint_quiet_cmd` per surface,
+  `commands.test_quiet`/`lint_quiet` repo-wide) hold the bridled forms agents actually run
+  (`--reporter=dot`, `--quiet`, failures-only); absent ⇒ `<cmd> 2>&1 | tail -40`.
+  `/init-pipeline` now asks for them instead of storing a bare `pnpm test`;
+  `/update-pipeline` tops up older profiles.
+- **`/review` computes the diff once.** One `git diff --stat`, then full patches staged to
+  disk only for the touched surfaces — reviewers read the artifact instead of each
+  re-running git.
+- **Conventions baked into rendered agents.** The implementer template gets a
+  `<SURFACE_CONVENTIONS>` slice rendered at init; at runtime agents read only the profile's
+  machine block. Edit conventions in `PIPELINE.md`, then `/update-pipeline` re-renders.
+- **Capped reports.** Review reports: max 20 findings, one line each, zero code excerpts;
+  smoke returns: max 10 ❌ lines. Dispatch prompts now keep every volatile slot (feature id,
+  paths, file lists) at the END so repeats hit the prompt-cache prefix.
+- `gate.py` also escalates every `ask` to a hard deny in unattended runs
+  (`bypassPermissions`) — nobody is there to answer a prompt.
+
+**Workflows (opt-in — conversational commands stay the default and the fallback):**
+
+- Four deterministic multi-agent scripts for the Claude Code Workflow runtime
+  (≥ 2.1.154, workflows enabled): **`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 returned in a `questions` array at the end; a clean exit ticks the DoD and
+  stamps the freshness gate so `/ship` follows directly), `workflows/review.js` (preflight
+  gate → one reviewer per touched surface → adversarial cross-check of CRITICAL/security
+  findings → verdict only), `workflows/audit.js` (one auditor per domain, concurrent,
+  prioritized backlog), `workflows/refactor.js` (big domains only: shared first, parallel
+  implementers, per-domain verify + one retry). Mechanical phases route to haiku.
+- New `profile-reader` agent (haiku) — phase 0 of every workflow: returns the
+  `PIPELINE.md` machine block as JSON, since workflow scripts have no filesystem access.
+- `/doctor` check 8 reports the workflow prerequisites and which path a session will take;
+  the generated `settings.json` allow-list now covers what workflow agents need (quiet
+  commands, shipped scripts, `git rev-parse`, retrieval MCP tools) so runs don't stall on
+  prompts nobody is watching.
+- Installers (npx CLI, install.sh, install.ps1) ship `core/workflows/` + `preflight.sh` +
+  the `profile-reader` agent in both global and bundled modes; CI dry-runs assert it.
+- Dashboard: new headless **Audit** action (`claude -p "/audit"` — starts without a prompt,
+  no resume if the session dies) and the workflows state in the project drill-down.
+
 ## 1.2.6 — 2026-07-30
 
 - **`npx cohorte install` never installed the `smoke` agent.** It copied only `review.md` and

package/README.md

@@ -163,7 +163,7 @@ npx cohorte dashboard --port=4400 --open   # custom port, open the browser
 ```
 
 **Bound to `127.0.0.1` by default** — the dashboard's actions execute code (install/update/reset,
-and `/init-pipeline`·`/update-pipeline` via headless Claude), so it must stay on loopback. Each user
+and `/init-pipeline`·`/update-pipeline`·`/audit` via headless Claude), so it must stay on loopback. Each user
 runs their own agent and drives only their own machine. `--host=0.0.0.0` exposes it to the network
 (it prints a security warning) — only on a trusted network, since anyone who reaches the port can run
 those actions.
@@ -178,10 +178,13 @@ those actions.
   column, via `gh`), otherwise a **Specs board** from `specs/*.md` (by `draft · frozen · in-review ·
   shipped`). The Kanban supersedes the Specs board when both would apply.
 - **Actions** (stream their output live) — **Update / Install core** (the shared global core, or a
-  repo's bundled core); **Init-pipeline / Update-pipeline**, which run those Claude Code commands
-  **headless** (`claude -p`, autonomous — Init skips the interactive interview, so review the result);
-  and **Reset pipeline**, which backs up then wipes a project's pipeline footprint and reinstalls a
-  fresh core. Buttons render only when they apply (e.g. Init only when there's no profile).
+  repo's bundled core); **Init-pipeline / Update-pipeline / Audit**, which run those Claude Code
+  commands **headless** (`claude -p`, autonomous — Init skips the interactive interview, so review
+  the result; Audit writes `specs/refactor-backlog.md`; headless runs start without any prompt and
+  have **no resume** if the session dies); and **Reset pipeline**, which backs up then wipes a
+  project's pipeline footprint and reinstalls a fresh core. Buttons render only when they apply
+  (e.g. Init only when there's no profile). The drill-down's health checklist also shows the
+  **workflows** state (scripts + profile-reader installed, which path a session will take).
 
 Runtime is **dependency-free** — node's built-in `http` server serves a prebuilt React app (the app
 source lives in `dashboard/app/`, built to `dashboard/dist/` at publish time). The `/doctor` checks
@@ -211,6 +214,7 @@ 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. |
@@ -269,6 +273,37 @@ Rules that make it safe:
   their eventual reviews diff against reality.
 - `/doctor` check 6 shows the live slot table (feature ↔ worktree ↔ ports) when you lose track.
 
+### Workflows — deterministic multi-agent runs (opt-in)
+
+Three 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. |
+
+The essentials:
+
+- **The conversational commands stay the default path** — and the fallback when workflows are
+  disabled or the client is too old. A workflow runs only when you explicitly ask for it
+  ("run the review workflow").
+- **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.
+- 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.
+
+Details: `profile/SCHEMA.md` §Workflows.
+
 ## Privacy — opt-in telemetry
 
 Cohorte can send **anonymous** usage pings (core version, OS, phase name, duration, per-surface
@@ -296,15 +331,16 @@ bin/cli.js              # the npm CLI: install / update / dashboard / version (c
 install.sh              # script installer (fresh + --update) for no-Node environments
 install.ps1             # same installer for Windows PowerShell (fresh + -Update)
 core/                   # copied verbatim into ~/.claude (global) or <project>/.claude (bundled)
-  agents/               # implementer.template.md (rendered per surface) + review.md + release.md
-  commands/             # init-pipeline + the workflow commands + /update-pipeline
-  hooks/                # gate.py (destructive-command gate; branch-aware — git/docker free off the default branch)
+  agents/               # implementer.template.md (rendered per surface) + review / release / smoke / profile-reader
+  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: review.js / audit.js / refactor.js
 profile/
   PIPELINE.template.md  # the profile skeleton /init-pipeline fills
   SCHEMA.md             # field reference
   cohorte.config.template.yaml   # seeds ~/.claude/cohorte.config.yaml (kanban)
-scripts/                # new-feature / remove-feature worktree-isolation templates
+scripts/                # worktree-isolation templates + shipped preflight/kanban/telemetry scripts
 dashboard/              # local web cockpit (npx … dashboard) — see dashboard/README.md
   server/               # dependency-free node runtime (serves the built app + JSON/stream API)
   app/                  # Vite + React source (built to dashboard/dist/ at publish time)

package/bin/cli.js

@@ -92,7 +92,10 @@ fs.mkdirSync(dest, { recursive: true });
 
 // --- helpers (mirror install.sh) --------------------------------------------
 function copyCore() {
-  for (const d of ['commands', 'hooks', 'templates']) {
+  // `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']) {
     fs.cpSync(path.join(src, 'core', d), path.join(dest, d), { recursive: true, force: true });
   }
   // 0.1.19 renamed questionnaire-domain-brief.md → research-brief.md; drop the stale copy.

package/core/agents/implementer.template.md

@@ -9,16 +9,25 @@ You are the **<SURFACE_AGENT>** engineer for one feature of **<PROJECT_NAME>**.
 statelessly, from the spec you are given. You cannot talk to the other surface agents — your only
 shared surface is the frozen contract and the spec.
 
-> **First action, always:** read `PIPELINE.md` — the whole machine block (§`pipeline-profile`; it is the
-> shared contract: surfaces, contract, gate). Then in §Conventions read ONLY the `### Shared` stanza and
-> your own `### Surface: <your key>` stanza (Grep for your key; the other surfaces' stanzas are another
-> agent's rules — skip them), plus §Testing. You have no memory; re-read your slice every dispatch —
-> but never load the other surfaces' convention prose.
+> **First action, always:** read `PIPELINE.md`'s fenced `yaml pipeline-profile` block ONLY — the
+> machine contract (surfaces, contract, commands, gate). Do **not** read the prose sections
+> (§Conventions/§Testing): your slice of them is baked into this file below (§Your conventions),
+> rendered from the profile — re-reading the prose every dispatch is exactly the cost the bake
+> removes. If the baked slice visibly contradicts `PIPELINE.md`, say so in your handoff: the profile
+> wins, and this agent file needs a re-render (`/update-pipeline`).
 
 ## You own
 
 `<SURFACE_PATH>/**` only. Everything under it — and nothing outside it.
 
+## Your conventions (baked from `PIPELINE.md` at render time)
+
+<!-- Rendered by /init-pipeline (and refreshed by /update-pipeline's reconcile) from
+     §Conventions `### Shared` + `### Surface: <your key>` + your §Testing lines.
+     Edit conventions in PIPELINE.md, never here — this block is regenerated. -->
+
+<SURFACE_CONVENTIONS>
+
 ## You must NEVER
 
 - Touch any other surface's tree (see the `surfaces` list in `PIPELINE.md`). That's another agent's.
@@ -53,15 +62,19 @@ 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 (your surface's test runner is
-   `surfaces[].test_cmd` in `PIPELINE.md`). Cover exactly what §Testing prescribes for your surface.
-   Run the test command and watch it fail (red).
-3. Implement until green, following §Conventions for your surface.
+2. **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_cmd` from `PIPELINE.md` 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.
+5. **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.
+
+**Run commands bridled — always.** Your surface's `test_quiet_cmd`/`lint_quiet_cmd` in `PIPELINE.md`
+are the forms you execute (dot reporter / failures-only); when a quiet variant is empty or absent,
+run `<full cmd> 2>&1 | tail -40`. Never print a full runner log into your context — redirect to a
+file and grep it if you need more than the tail.
 
 ## Definition of done
 
@@ -72,7 +85,7 @@ of the contract your surface implements matches the spec exactly. User-facing co
 
 Your final message **is** the handoff (read by the lead, not a human chat). 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`):
+(the lead has `git diff --stat`), never paste code excerpts (the code is on disk):
 
 ```
 # HANDOFF — <surface> · <feature_id>

package/core/agents/profile-reader.md

@@ -0,0 +1,28 @@
+---
+name: profile-reader
+description: Reads PIPELINE.md and returns its `yaml pipeline-profile` block as compact JSON. Phase 0 of every cohorte workflow — workflow scripts have no filesystem or shell access, so this agent is how a script learns the profile (surfaces, commands, flags). Mechanical, read-only, no judgment.
+tools: Read, Grep, Glob
+model: haiku
+---
+
+You are the **profile-reader**. One job, purely mechanical: load this project's `PIPELINE.md` and
+return the machine block as JSON. A workflow script (which cannot read files itself) parses your
+return and parameterizes every later phase from it — so fidelity beats brevity, and prose beats
+nothing only when something is wrong.
+
+## How
+
+1. Read `PIPELINE.md` at the repo root — specifically the fenced ` ```yaml pipeline-profile ` block.
+   It can be long; read the whole block, nothing after it (the prose sections are not your job).
+2. Convert the YAML to JSON **faithfully**: every key and value as written, comments dropped,
+   nothing invented, nothing "fixed". Keep types honest (`true`/`false` booleans, numbers as
+   numbers, `""` stays an empty string). Unfilled template placeholders (values still wrapped in
+   `<…>`) pass through as the literal string — the caller decides what to do with them.
+3. Return **only** the JSON object — no fences, no commentary, no markdown. Your final message is
+   parsed by a script.
+
+## Failure shape
+
+If `PIPELINE.md` is missing, or the `yaml pipeline-profile` fence is absent or unparseable, return
+exactly one JSON object instead: `{"error": "<one line: what is missing or broken>"}` — never a
+partial profile, never prose.

package/core/agents/review.md

@@ -85,8 +85,12 @@ domain** (same finding-line shape) instead of a SHIP/REVISE/BLOCK verdict.
 
 Every finding must be **self-sufficient for a stateless agent**: `file:line` · severity ·
 `spec-violation | quality | security` · one concrete suggested fix — it gets appended verbatim to the
-spec's `## Remediation`. Your final message **is** the report. Emit nothing outside this shape — no
-restated rules, no "verified clean" lists:
+spec's `## Remediation`. Your final message **is** the report. **The shape is capped:** at most
+**20 findings**, ONE line each, **zero code excerpts** (the diff and the source are on disk — a
+`file:line` is enough for a stateless fixer). More than 20? Keep every CRITICAL/HIGH/security
+finding, fill the rest by severity, and close the list with one line:
+`+<n> more MEDIUM/LOW — re-run after the fix loop`. Emit nothing outside this shape — no restated
+rules, no "verified clean" lists:
 
 ```
 # REVIEW REPORT
@@ -104,7 +108,7 @@ Verdict: <SHIP | REVISE | BLOCK>
 ## Findings
 
 - **[<SEVERITY>]** `<file>:<line>` · <spec-violation|quality|security> · <problem> → **Fix:** <concrete change>
-(order by severity; "None." if none)
+(order by severity; "None." if none; max 20 lines, one per finding, no code excerpts)
 
 ## Notes
 (ONLY the RBAC / mobile-first assessment when the profile enables them; omit the section otherwise)

package/core/agents/smoke.md

@@ -57,5 +57,7 @@ assert on the pieces you need.
 - **Write the full report to `specs/reports/<id>.md`** (overwrite) — the same gitignored buffer
   `/review` uses, so a `/fix` after a `/clear` still has the failures.
 - Tear down what you started (kill the dev server); leave shared infra as you found it.
-- **Your return to the lead is ONLY:** the verdict line (`PASS` / `FAIL`), the ❌ lines verbatim (if
-  any), and `Full report: specs/reports/<id>.md`. No logs, no bodies, no screenshots.
+- **Your return to the lead is ONLY:** the verdict line (`PASS` / `FAIL:<n>`), **at most 10 ❌
+  lines** — one line each (`❌ <flow/endpoint> · expected <x> got <y>`), no command output, no code
+  or body excerpts; more than 10 ⇒ keep the 10 most severe and add `+<n> more — see the report` —
+  and `Full report: specs/reports/<id>.md`. No logs, no bodies, no screenshots.

package/core/commands/audit.md

@@ -8,23 +8,31 @@ You are the **lead**. Audit **$ARGUMENTS** (default: whole repo) to drive it to
 analyze only — no fixes (those go through `/refactor`).
 
 > Read `PIPELINE.md` §`commands` (the mechanical gates), `surfaces`, and §Conventions.
+>
+> **Workflow variant** (opt-in — SCHEMA.md §Workflows): on Claude Code ≥ 2.1.154 with workflows
+> enabled, the human can ask to "run the audit workflow" (`<core>/workflows/audit.js` — one auditor
+> per domain, concurrent). This conversational path stays the default and the fallback.
 
 ## 1. Mechanical gates (you run these — Bash)
 
 Run the profile's checks **scoped to `$ARGUMENTS`** when a path/domain is given (lint/format/typecheck
 on that path, tests via that surface's `test_cmd`); repo-wide only for the default whole-repo audit.
-Redirect each command's output into `specs/reports/audit-gates.txt` in the same call
-(`cmd > specs/reports/audit-gates.txt 2>&1`) so the bulk never sits in your history, then grep it for
-the `file:line` of every failure: `commands.format` in check mode (e.g. `prettier --check .` /
-`ruff format --check`), `commands.lint`, `commands.typecheck`, `commands.test`.
+Use the quiet variants (`commands.lint_quiet`/`test_quiet`, else the `2>&1 | tail -40` fallback —
+SCHEMA.md §Output discipline) and redirect each command's output into
+`specs/reports/audit-gates.txt` in the same call (`cmd > specs/reports/audit-gates.txt 2>&1`) so the
+bulk never sits in your history, then grep it for the `file:line` of every failure:
+`commands.format` in check mode (e.g. `prettier --check .` / `ruff format --check`),
+`commands.lint`, `commands.typecheck`, `commands.test`.
 
 ## 2. Convention + TDD audit (dispatch `review` in audit mode)
 
-Dispatch `review` (read-only): "Audit `$ARGUMENTS` against `PIPELINE.md` (no spec — **audit mode**).
-Check conventions (§Conventions per surface), TDD coverage (untested entry points / modules per surface),
-and — if the profile enables them — mobile-first + design-system usage. Mechanical findings from the
-gates: read `specs/reports/audit-gates.txt`. Emit a prioritized refactor backlog (finding-line format
-from your instructions), grouped by domain (one group per surface + shared)."
+Dispatch `review` (read-only; static prompt first, variable slot last — prompt-cache prefix):
+"Audit a target against `PIPELINE.md` (no spec — **audit mode**). Check conventions (§Conventions
+per surface), TDD coverage (untested entry points / modules per surface), and — if the profile
+enables them — mobile-first + design-system usage. Mechanical findings from the gates: read
+`specs/reports/audit-gates.txt`. Emit a prioritized refactor backlog (capped finding-line format
+from your instructions), grouped by domain (one group per surface + shared). — Target: `$ARGUMENTS`
+(default: whole repo)."
 
 ## 3. Write the backlog
 

package/core/commands/cycle.md

@@ -0,0 +1,54 @@
+---
+model: sonnet
+description: Launch the full dev-cycle workflow (contract → build → smoke ∥ review → fix, until zero findings) for a frozen spec; relay its verdict + deferred questions.
+argument-hint: <feature_id> [max_rounds]
+---
+
+You are the **lead**. Launch the full dev-cycle **workflow** for feature **$ARGUMENTS** — the
+deterministic script does the orchestration (SCHEMA.md §Workflows, `cycle.js`); your job is only to
+start it and relay its result. Do NOT run the phases yourself here — that's the conversational path
+(`/build` → `/smoke` → `/review` → `/fix`), which remains the fallback below.
+
+> **Kanban** (SCHEMA.md §Kanban): move card `#<feature_id>` → **Building** at launch. No-op silently
+> if no board.
+
+## 1. Resolve & check (fail fast, before spending anything)
+
+- Parse `$ARGUMENTS`: the first token is `<feature_id>`, an optional second numeric token is
+  `<max_rounds>` (the workflow defaults to 5).
+- Resolve the script: `.claude/workflows/cycle.js` if it exists, else `~/.claude/workflows/cycle.js`
+  (`test -f`). **Missing both** ⇒ the core predates 1.3.0 or is half-copied: tell the human to run
+  `/update-pipeline`, and stop.
+- **Workflow runtime available?** If the `Workflow` tool is not in your toolset (Claude Code
+  < 2.1.154 or workflows disabled), say so and hand over the conversational path instead:
+  `/build <feature_id>` → `/smoke` → `/review` → `/fix` — same phases, interactive. Stop.
+- Quick spec sanity (the workflow re-checks properly — this just saves a doomed launch):
+  `grep '^status:' specs/<feature_id>.md` must say `frozen` or `in-review`; otherwise tell the human
+  to run `/spec` first, and stop.
+
+## 2. Launch
+
+Call the `Workflow` tool: `scriptPath: <resolved cycle.js path>`,
+`args: {"feature": "<feature_id>", "maxRounds": <max_rounds, omit if not given>}`.
+It runs in the background — tell the human it's off and what it will do (build, then smoke ∥ review
+→ fix rounds until zero findings + PASS; no questions mid-run), and that `/workflows` shows live
+progress. Then END YOUR TURN — never poll, never sleep; the completion notification re-wakes you.
+
+## 3. Relay the result (when the task notification arrives)
+
+The workflow returns only a verdict object — the bulk is already on disk
+(`specs/reports/<feature_id>.md`, spec `## Remediation`). Print, without re-reading any of it into
+context:
+
+- `outcome` · rounds used · review verdict · smoke result.
+- `contractChanges` if any — flag them explicitly: the loop re-authored the frozen contract
+  lead-style; the human should eyeball those hunks in the diff.
+- **The `questions` array, verbatim** — this is the human's inbox from the run (empty when the spec
+  pre-answered everything). Each one is a decision to make, usually by sharpening the spec.
+- The `next` line: **SHIP-READY** ⇒ `/ship <feature_id>` (DoD ticked + freshness stamped — ship is a
+  straight shot, its human confirmation stays). **STOPPED** ⇒ answer the questions, then rerun
+  `/cycle <feature_id>` (it picks up from the spec's Remediation) or finish conversationally with
+  `/fix <feature_id>` + `/review <feature_id>`.
+- **Kanban:** outcome SHIP-READY ⇒ move card → **Review** (the cycle's last verdict is a review);
+  otherwise → **Fix**. No-op silently if no board.
+- **Recommend a `/clear`** — everything the next command needs is on disk.

package/core/commands/doctor.md

@@ -21,8 +21,8 @@ fix only with the human's go-ahead (or hand them the command).
    commands' step files are present — `templates/steps/init-pipeline/` non-empty (a router whose
    `templates/steps/<cmd>/` dir is missing is a partial/stale install ⇒
    re-run install/update). **Shipped scripts present and executable** in `<core>/pipeline/scripts/`:
-   `kanban-move.sh`, `telemetry-send.sh`, `new-feature.sh.template`, `remove-feature.sh.template`
-   — ❌ any missing one. Every caller chains these with `|| true`, so an absent script is a **silent**
+   `kanban-move.sh`, `telemetry-send.sh`, `preflight.sh`, `new-feature.sh.template`,
+   `remove-feature.sh.template` — ❌ any missing one. Every caller chains these with `|| true`, so an absent script is a **silent**
    no-op (no kanban card moves, no telemetry ping, no error anywhere) — this check is the only thing
    that sees it. Also flag ❌ a `VERSION` **newer than** the other `pipeline/` files (compare mtimes):
    a version bumped without a full re-copy is a half-done update ⇒ re-run install/update.
@@ -34,10 +34,10 @@ fix only with the human's go-ahead (or hand them the command).
    its `surfaces[].model` — ❌ if missing, mismatched, or a literal `<SURFACE_MODEL>` placeholder
    (all three silently fall back to inheriting the lead session's model — often Opus — on every
    dispatch); ⚠️ any `inherit` with the note that it bills at the lead's tier. The generic agents
-   (`review.md`, `release.md`, `smoke.md` — repo or `~/.claude/agents/`) must each carry their
-   `model:` line too (sonnet/haiku/sonnet). **Command pins:** every mechanical command file
+   (`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` — in `.claude/commands/` or `~/.claude/commands/`) carries `model: sonnet` in
+   `update-pipeline`, `cycle` — 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).
@@ -66,7 +66,23 @@ fix only with the human's go-ahead (or hand them the command).
    incoherent state: `enabled: true` with no `install_id` or no `consent_date` (sending without
    recorded consent — fix: set `enabled: false` until the consent question is re-run), or a
    `telemetry:` block missing entirely on a current core (top up via `/update-pipeline`).
-8. **Specs & metrics.** Every `specs/*.md` front-matter `status` is a valid stage; `shipped` specs
+8. **Workflows** (the opt-in execution path — SCHEMA.md §Workflows; the conversational commands
+   stay the default, so failures here are ⚠️ at most, never ❌). Report which path this machine will
+   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` —
+     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.
+   - **Workflows enabled in this session** — the `Workflow` tool is in your own toolset right now;
+     absent ⇒ disabled for this session (a setting or an old client), conversational path.
+   - **Preflight wiring** (used by both paths): `pipeline/scripts/preflight.sh` executable and
+     `gate-config.json` carries the `preflight` block — mismatch ⇒ regenerate from the profile.
+   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
    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/commands/refactor.md

@@ -7,6 +7,11 @@ argument-hint: <domain…> (one or more surface keys, "shared", or "all")
 You are the **lead**. Refactor domain **$ARGUMENTS** to match `PIPELINE.md`, using the `/audit` backlog.
 
 > Read `PIPELINE.md` §`surfaces` (map the domain → a surface + its agent + commands) and §`contract`.
+>
+> **Workflow variant** (opt-in — SCHEMA.md §Workflows): for BIG domains (many open backlog items
+> across several surfaces), on Claude Code ≥ 2.1.154 with workflows enabled, the human can ask to
+> "run the refactor workflow" (`<core>/workflows/refactor.js`). For a handful of items this
+> conversational path is cheaper — and it stays the default and the fallback.
 
 ## 1. Gather
 
@@ -42,9 +47,9 @@ slices import it, so refactor it alone, first.
 
 ## 3. Verify & loop
 
-After each agent returns: its surface's `test_cmd`/`lint_cmd`, `commands.typecheck`,
-`commands.format --check` (redirect output to a file and grep it — don't print gate output into your
-context). Then verify each backlog item cleared by checking its `file:line` directly — do NOT re-run
+After each agent returns: its surface's `test_quiet_cmd`/`lint_quiet_cmd` (else the `tail -40`
+fallback — SCHEMA.md §Output discipline), `commands.typecheck`, `commands.format --check` (redirect
+output to a file and grep it — don't print gate output into your context). Then verify each backlog item cleared by checking its `file:line` directly — do NOT re-run
 `/audit` per round (that repeats the repo-wide gates + a review dispatch you don't need); one optional
 final `/audit` once ALL dispatched domains are clean is enough. Check cleared items off in
 `specs/refactor-backlog.md`. Loop until each dispatched domain is clean. Verification is per-domain

package/core/commands/review.md

@@ -6,22 +6,46 @@ argument-hint: <feature_id>
 
 You are the **lead**. Dispatch the review for feature **$ARGUMENTS**.
 
-> Read `PIPELINE.md` §`vcs.default_branch` (diff base) and the `surfaces`/`contract` fields.
+> Read `PIPELINE.md` §`vcs.default_branch` (diff base) and the `surfaces`/`contract`/`commands` fields.
 > _Skip the re-read if it's already in your context this session and unmodified since._
 >
 > **Kanban** (SCHEMA.md §Kanban): move card `#$ARGUMENTS` → **Review**. No-op silently if no board.
+>
+> **Workflow variant** (opt-in — SCHEMA.md §Workflows): on Claude Code ≥ 2.1.154 with workflows
+> enabled, the human can ask to "run the review workflow" (`<core>/workflows/review.js`) instead.
+> This conversational path stays the default and the fallback; `/doctor` shows which is available.
+
+## 0. Deterministic pre-flight — no agents while red
+
+Run the profile's mechanical gates in ONE Bash call via the shipped script
+(`<core>/pipeline/scripts/preflight.sh`, `<core>` = `.claude` bundled / `~/.claude` global — probe
+with `test -x`); note the epoch (`date +%s`) in the same call — §3's metrics line needs it:
+
+```
+<core>/pipeline/scripts/preflight.sh specs/reports/$ARGUMENTS.preflight.txt \
+  "<commands.typecheck>" "<commands.lint_quiet, else lint>" "<commands.test_quiet, else test>"
+```
+
+- **Non-zero exit** ⇒ the script already printed the raw last-40 lines. **STOP: relay them verbatim
+  and spawn NO agent** — a compiler/test failure needs `/fix` (or the human), not a review that
+  rediscovers it at agent prices. This abort is the whole point of the step.
+- **Zero exit** ⇒ it stamped `.claude/preflight.ok`, which the gate hook checks before letting
+  `review`/`smoke` dispatches through (SCHEMA.md §Preflight). Continue.
+- Script absent (older core) ⇒ run the three commands yourself, each redirected into
+  `specs/reports/$ARGUMENTS.preflight.txt`, aborting on the first failure the same way.
 
 ## 1. Gather the inputs for stateless reviewers
 
 - Confirm `specs/$ARGUMENTS.md` exists.
-- Compute the diff, and let **git do the grouping** (deterministic — don't reason it out file by file):
-  per surface, `git diff <default_branch> --name-only -- <surface.path>` is exactly that surface's changed
-  files; the **`shared` remainder** (contract file + anything outside every surface) is
-  `git diff <default_branch> --name-only -- . $(for p in <each surface.path>; do printf ':(exclude)%s ' "$p"; done)`.
-  Attach the remainder to the most relevant surface's reviewer and say so in its dispatch. A surface whose
-  `git diff` comes back empty gets no reviewer.
-- **Stage the hunks** (reviewers are read-only — no Bash — so a staged diff file is the ONLY way they
-  can review hunks instead of re-reading whole files). Per touched surface, regenerated every round:
+- **Compute the diff ONCE — `--stat` first, patches only for retained surfaces.** One call:
+  `git diff <default_branch> --stat > specs/reports/$ARGUMENTS.stat.txt`, then grep that file to
+  group the changed paths by `surfaces[].path` prefix (deterministic — don't reason it out file by
+  file). Paths under no surface (contract file, root config) are the **`shared` remainder**: attach
+  them to the most relevant surface's reviewer and say so in its dispatch. A surface with no changed
+  paths gets no reviewer — and no `.diff` is ever generated for it.
+- **Stage the hunks once per touched surface** (reviewers are read-only — no Bash — so the staged
+  diff file is the ONLY way they can review hunks instead of re-reading whole files, and staging it
+  here means N reviewers never re-run git N times). Regenerated every round:
   `git diff <default_branch> -- <surface.path> > specs/reports/$ARGUMENTS.<surface.key>.diff`
   (same gitignored buffer dir as the reports). For the surface that carries the shared remainder,
   append the remainder pathspecs to its command so its `.diff` includes them. Never print a diff into
@@ -40,16 +64,20 @@ prescribed fixes land? — NOT a de-novo audit) and write the same REVIEW REPORT
 First-round reviews, contract changes, and security findings always get a full reviewer. For each
 dispatched surface:
 
-> `subagent_type: review` — "Review feature `$ARGUMENTS` — **scope: the `<surface.key>` surface
-> only**. Read `PIPELINE.md` first (its flags + §Conventions/§Testing for `<surface.key>`). Spec:
-> `specs/$ARGUMENTS.md` (source of truth). Contract: `<contract.path>/$ARGUMENTS.<ext>`. Diff to
-> review: `specs/reports/$ARGUMENTS.<surface.key>.diff` (staged hunks — read it FIRST; open a full
-> source file only when a finding demands it). Check spec conformance first, then correctness,
-> security, conventions, RBAC/mobile-first _if the profile enables them_, and TDD coverage. Emit
-> the REVIEW REPORT in the format your agent instructions define — every finding self-sufficient
-> (`file:line` · severity · type · concrete fix). Changed files (`--stat`): <list>."
+Keep the dispatch prompt **byte-identical across features and rounds** except the variable block,
+which sits at the END so every repeat hits the prompt-cache prefix:
+
+> `subagent_type: review` — "Review one feature surface against its frozen spec. Read `PIPELINE.md`
+> first (flags + the §Conventions/§Testing slice for your scope). Check spec conformance first, then
+> correctness, security, conventions, RBAC/mobile-first _if the profile enables them_, and TDD
+> coverage. Your dispatch names a staged diff file — read it FIRST; open a full source file only when
+> a finding demands it. Emit the REVIEW REPORT in the capped format your agent instructions define —
+> every finding self-sufficient (`file:line` · severity · type · one-line concrete fix), no code
+> excerpts. — Variable slots: feature `$ARGUMENTS` · scope: the `<surface.key>` surface only · spec:
+> `specs/$ARGUMENTS.md` (source of truth) · contract: `<contract.path>/$ARGUMENTS.<ext>` · staged
+> diff: `specs/reports/$ARGUMENTS.<surface.key>.diff` · changed files (`--stat`): <list>."
 
-The staging command in §1 already gave you the wall-clock start (`date +%s` in the same call) — §3's
+§0's preflight call already gave you the wall-clock start (`date +%s` in the same call) — §3's
 metrics line needs it.
 
 ## 3. Merge & relay the verdict