cohorte 1.3.2 → 1.3.4

package/CHANGELOG.md

@@ -3,6 +3,125 @@
 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.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
+> the installed `hooks/gate.py` is refreshed.
+
+- **The cycle workflow could exit SHIP-READY with open findings.** A round with only HIGH/MEDIUM
+  findings scored `SHIP`, broke the loop, ticked the DoD and stamped the freshness gate — making
+  `/ship` a straight shot over unfixed findings, against the workflow's own "zero open findings"
+  contract. The exit condition is now literally zero open findings + a smoke PASS.
+- **Dead implementers went undetected in the cycle workflow.** `agent()` returns `null` when a
+  subagent dies, but the build fan-out wrapped every result in a truthy object before the check —
+  so the "implementer(s) died" question never fired and build telemetry always said `ok`.
+- **`gate.py` gated worktree commands as if they ran on the default branch.** Branch and HEAD were
+  resolved in `CLAUDE_PROJECT_DIR` (the main checkout, usually on `main`) instead of where the
+  command actually runs — so in a feature worktree, every `ask_on_default_branch` pattern
+  prompted, and the preflight HEAD-moved check compared against the wrong checkout. Git state now
+  resolves at the hook payload's `cwd`.
+- **The preflight phase gate hung headless runs.** The bypassPermissions "nobody can answer an
+  ask ⇒ deny" escalation only covered Bash patterns; a review/smoke Task dispatch with a stale
+  stamp still emitted an unanswerable `ask`. The phase gate now escalates the same way.
+- **`/init-pipeline` bundled installs registered the gate with the dead `Bash`-only matcher** —
+  the exact bug 1.3.2 fixed in the installers lived on in the template — and never dropped an
+  existing registration, so a bundled repo later switched to global ran the gate twice per
+  command. The template now mandates `Bash|Task` and a reconcile.
+- Smaller cycle-workflow fixes: smoke telemetry reports the real failure count (was always 0 —
+  it filtered on a `kind` value that doesn't exist); a run whose last round ends on a red
+  preflight now flags that the reported findings are from the previous round; a malformed
+  preflight stamp says "unreadable" instead of "not found".
+
 ## 1.3.2 — 2026-07-30
 
 > **Re-run `npx cohorte@latest update --global` (or `update`).** This release repairs the gate

package/README.md

@@ -217,7 +217,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). |
+| `/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. |
@@ -278,13 +278,13 @@ 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/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. |
@@ -338,7 +338,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: review.js / audit.js / refactor.js
+  workflows/            # opt-in Workflow-runtime scripts: cycle.js / review.js / audit.js / refactor.js
 profile/
   PIPELINE.template.md  # the profile skeleton /init-pipeline fills
   SCHEMA.md             # field reference

package/bin/cli.js

@@ -68,8 +68,18 @@ for (const a of args) {
   if (a === 'install' || a === 'update' || a === 'dashboard') mode = 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); }
@@ -99,12 +109,20 @@ fs.mkdirSync(dest, { recursive: true });
 
 // --- helpers (mirror install.sh) --------------------------------------------
 function copyCore() {
-  // `workflows` = the deterministic orchestration scripts (review/audit/refactor) the
+  // `workflows` = the deterministic orchestration scripts (cycle/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 });
+    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/commands/cycle.md

@@ -1,7 +1,7 @@
 ---
 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]
+description: Launch the full dev-cycle workflow (contract → build → review → fix, until zero findings; add `smoke` to also run the app each round) for a frozen spec; relay its verdict + deferred questions.
+argument-hint: <feature_id> [max_rounds] [smoke]
 ---
 
 You are the **lead**. Launch the full dev-cycle **workflow** for feature **$ARGUMENTS** — the
@@ -14,8 +14,11 @@ start it and relay its result. Do NOT run the phases yourself here — that's th
 
 ## 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).
+- Parse `$ARGUMENTS`: the first token is `<feature_id>`, an optional numeric token is
+  `<max_rounds>` (the workflow defaults to 5), and an optional literal token `smoke` opts the
+  smoke agent INTO the verify rounds (default: review-only — smoke is expensive, it boots the
+  app every round; skipping it is the human's explicit risk, `/smoke <feature_id>` stays
+  available standalone before `/ship`).
 - 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.
@@ -29,10 +32,12 @@ start it and relay its result. Do NOT run the phases yourself here — that's th
 ## 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.
+`args: {"feature": "<feature_id>", "maxRounds": <max_rounds, omit if not given>, "smoke": <true
+only if the smoke token was given — omit otherwise>}`.
+It runs in the background — tell the human it's off and what it will do (build, then review → fix
+rounds until zero findings, with smoke alongside each round if opted in; 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)
 
@@ -43,6 +48,8 @@ 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.
+- `unreviewedSurfaces` if non-empty — **say it plainly**: a reviewer died, so those surfaces
+  carry NO verdict. The run's verdict covers the others only; the code there was never read.
 - **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

package/core/commands/doctor.md

@@ -44,7 +44,9 @@ fix only with the human's go-ahead (or hand them the command).
 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.

package/core/hooks/gate.py

@@ -48,9 +48,12 @@ SPLIT = re.compile(r"&&|\|\||[;|\n]")
 WS = re.compile(r"\s+")
 
 
+def project_root() -> str:
+    return os.environ.get("CLAUDE_PROJECT_DIR", ".")
+
+
 def load_config() -> dict:
-    root = os.environ.get("CLAUDE_PROJECT_DIR", ".")
-    path = os.path.join(root, ".claude", "gate-config.json")
+    path = os.path.join(project_root(), ".claude", "gate-config.json")
     empty = {"deny": [], "ask": [], "ask_on_default_branch": [], "default_branch": "main",
              "preflight": {}}
     try:
@@ -76,13 +79,19 @@ def norm(s: str) -> str:
     return WS.sub(" ", s.strip())
 
 
-def current_branch():
-    """The checked-out branch of CLAUDE_PROJECT_DIR, or None (not a repo / detached / git absent)."""
-    root = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+def session_cwd(payload: dict) -> str:
+    """Where the gated command actually runs. A feature worktree is its own
+    checkout — resolving git state in CLAUDE_PROJECT_DIR (the main checkout)
+    would gate every worktree command as if it ran on the default branch."""
+    return payload.get("cwd") or project_root()
+
+
+def current_branch(cwd: str):
+    """The checked-out branch at `cwd`, or None (not a repo / detached / git absent)."""
     try:
         out = subprocess.run(
             ["git", "rev-parse", "--abbrev-ref", "HEAD"],
-            cwd=root, capture_output=True, text=True, timeout=3,
+            cwd=cwd, capture_output=True, text=True, timeout=3,
         )
         if out.returncode == 0:
             return out.stdout.strip() or None
@@ -91,19 +100,33 @@ def current_branch():
     return None
 
 
-def current_head():
-    """HEAD sha of CLAUDE_PROJECT_DIR, or None."""
-    root = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+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=root, capture_output=True, text=True, timeout=3,
+            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:
@@ -116,29 +139,37 @@ def check_preflight(payload: dict, cfg: dict) -> int:
     if subagent not in agents:
         return 0
 
-    root = os.environ.get("CLAUDE_PROJECT_DIR", ".")
-    stamp = os.path.join(root, ".claude", "preflight.ok")
+    stamp = os.path.join(project_root(), ".claude", "preflight.ok")
     why = None
     try:
         with open(stamp, "r", encoding="utf-8") as fh:
-            epoch_s, _, sha = fh.read().strip().partition(" ")
-        age_min = (time.time() - float(epoch_s)) / 60
-        max_age = float(pf.get("max_age_minutes", 30) or 30)
-        if age_min > max_age:
-            why = f"the preflight stamp is {age_min:.0f} min old (max {max_age:.0f})"
-        else:
-            head = current_head()
-            if head and sha not in ("", "none") and head != sha:
-                why = "HEAD moved since the preflight ran"
+            raw = fh.read().strip()
     except Exception:
+        raw = None
         why = "no preflight stamp found"
+    if raw is not None:
+        try:
+            epoch_s, _, sha = raw.partition(" ")
+            age_min = (time.time() - float(epoch_s)) / 60
+            max_age = float(pf.get("max_age_minutes", 30) or 30)
+            if age_min > max_age:
+                why = f"the preflight stamp is {age_min:.0f} min old (max {max_age:.0f})"
+            else:
+                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>`)"
     if why is None:
         return 0
+    # Same rule as the Bash gate: unattended runs have nobody to answer an "ask".
+    unattended = payload.get("permission_mode") == "bypassPermissions"
     return decide(
-        "ask",
+        "deny" if unattended else "ask",
         f"Phase gate: dispatching `{subagent}` but {why}. Run the deterministic pre-flight first "
         f"(pipeline/scripts/preflight.sh — typecheck + lint + tests) so agents never review red code; "
-        f"or confirm to dispatch anyway (PIPELINE.md gate.preflight).",
+        f"or confirm to dispatch anyway (PIPELINE.md gate.preflight)."
+        + (" (denied outright: unattended run, nobody to confirm)" if unattended else ""),
     )
 
 
@@ -173,7 +204,7 @@ def main() -> int:
     # be conservative and gate. Resolve the branch once, lazily.
     on_default = False
     if branch_gated:
-        branch = current_branch()
+        branch = current_branch(session_cwd(payload))
         on_default = branch is None or branch == default
 
     for raw in SPLIT.split(command):

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>}}`
@@ -30,8 +31,12 @@
    retrieval provider's MCP tools when wired (e.g. `mcp__serena`). Never allowlist anything matching
    a `gate.ask`/`gate.deny` pattern. Mention the human can widen it later with
    `/fewer-permission-prompts`) + the hooks, **conditioned on the install mode:**
-   - **bundled:** register the PreToolUse `Bash` hook `.claude/hooks/gate.py` and the PostToolUse
-     formatter (detected formatter).
+   - **bundled:** register the PreToolUse hook `.claude/hooks/gate.py` with matcher `Bash|Task`
+     (Task is required — the preflight phase gate keys off Task dispatches; a `Bash`-only matcher
+     leaves it dead) and the PostToolUse formatter (detected formatter). Before adding, drop any
+     existing PreToolUse entry whose command ends in `gate.py` (here AND in `~/.claude/settings.json`
+     if one points at this repo's copy) — exactly one registration must survive, or every gated
+     command prompts twice.
    - **global:** the PreToolUse gate hook is
      already in `~/.claude/settings.json` and reads this repo's `gate-config.json` — do **not** re-register
      it here (double-registration double-prompts). It no-ops where its config is absent, so one

package/core/workflows/audit.js

@@ -114,11 +114,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 +136,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)',
 }