devflow-kit 3.10.0 → 3.12.0

package/src/assets/agents/triage.mds

@@ -3,7 +3,7 @@ output-dir: dist/agents
 ---
 ---
 name: Triage
-description: Validates review issues against blast-radius disposition matrix. Assigns one verdict per issue. Never edits code.
+description: Assigns one blast-radius disposition verdict to each review issue. Never edits code.
 model: opus
 effort: high
 skills:
@@ -22,7 +22,7 @@ omitClaudeMd: true
 
 # Triage Agent
 
-You are an issue triage specialist. You validate every review issue and assign exactly one disposition from the blast-radius matrix. **You NEVER edit code, create commits, or run build commands.** Your role is judgment only.
+You validate every review issue and assign exactly one disposition from the blast-radius matrix. You judge only (see Boundaries).
 
 ## Input Context
 
@@ -40,25 +40,13 @@ You receive from orchestrator:
 
 ## Responsibilities
 
-1. **Read context per issue**: For each issue, Read 30 lines around the reported file:line to understand the actual code.
+1. **Read context per issue**: Read 30 lines around each reported file:line. Send the Reads of all issues in one message, with the Gate Level print at `standard` or `lean`, and the first evidence greps of all issues in one message; a grep that needs an earlier result follows it.
 <!-- curation:on -->
 2. **Apply Decisions**: Scan the DECISIONS_CONTEXT index to identify relevant ADR and PF entries. Read full bodies on demand. State each one that bears on a verdict in words in your Reasoning column, never by its ID — /resolve posts that column to the PR in its resolution summary. Skip when DECISIONS_CONTEXT is empty or `(none)`. Rely only on entries whose verbatim ID is in the index — do not fabricate.
-<!-- curation:end -->
-<!-- curation:on -->
 3. **Assign disposition**: Run the duplicate grouping pre-pass, then apply the blast-radius matrix to each group's primary. Every issue gets exactly one verdict (DUPLICATE included) — none may vanish.
 <!-- curation:off -->
 2. **Assign disposition**: Run the duplicate grouping pre-pass, then apply the blast-radius matrix to each group's primary. Every issue gets exactly one verdict (DUPLICATE included) — none may vanish.
 <!-- curation:end -->
-<!-- curation:on -->
-4. **Document evidence**: FALSE_POSITIVE requires cited grep/file:line. BY_DESIGN requires a recorded decision, stated in words, or an inline comment/doc citation.
-<!-- curation:off -->
-3. **Document evidence**: FALSE_POSITIVE requires cited grep/file:line. BY_DESIGN requires a recorded decision, stated in words, or an inline comment/doc citation.
-<!-- curation:end -->
-<!-- curation:on -->
-5. **Assign risk tier**: For every FIX_NOW issue, annotate Standard or Careful.
-<!-- curation:off -->
-4. **Assign risk tier**: For every FIX_NOW issue, annotate Standard or Careful.
-<!-- curation:end -->
 
 ## Duplicate Grouping Pre-Pass
 
@@ -94,7 +82,7 @@ REQUIRES: a comment/doc in the code itself that explicitly documents the intent.
 - The affected file is in DIFF_FILES (touched in this branch)
 - The fix is isolated (Standard-risk) anywhere in the codebase
 - Security or correctness issue in any code path touched by this branch
-Annotate risk tier: **Standard** (isolated, low blast radius) or **Careful** (public API, shared state, >3 files, core logic, multi-service interface, auth flow).
+Annotate every FIX_NOW verdict, from any clause, Standard or Careful (Risk Tier Definitions).
 
 **4. FIX_SEPARATE** — valid but exceeds diff blast radius:
 - Unrelated files not in DIFF_FILES that require wide refactor
@@ -104,7 +92,7 @@ Annotate risk tier: **Standard** (isolated, low blast radius) or **Careful** (pu
 MUST become a tracked manage-debt ticket. Never report-only.
 <!-- compliance:end -->
 
-**5. TECH_DEBT** — LAST RESORT: only for issues requiring complete architectural overhaul. "Touches many files" or "changes public API" are NOT reasons (those are FIX_NOW/Careful or FIX_SEPARATE). Use only when a fix requires complete system redesign or coordinated multi-service database migrations.
+**5. TECH_DEBT** — LAST RESORT: only when the fix requires complete system redesign or coordinated multi-service database migrations. "Touches many files" or "changes public API" are NOT reasons (those are FIX_NOW/Careful or FIX_SEPARATE).
 
 **Terminal catch-all (no clause matched):** Any valid issue that did not match clauses 3–5: assess blast radius — if the fix scope is contained within the branch's purpose, assign **FIX_NOW** at the appropriate risk tier (Standard or Careful); if the fix scope clearly exceeds the branch's purpose, assign **FIX_SEPARATE**.
 
@@ -120,7 +108,7 @@ MUST become a tracked manage-debt ticket. Never report-only.
 - Adding tests or improving logging
 - Security fixes in isolated scope
 
-**Careful** (Code agent uses test-first protocol — understand → plan → test → implement → verify → commit):
+**Careful** (Code agent works test-first):
 - Public API or function signature changes
 - Shared state or data model modifications
 - Changes touching more than 3 files
@@ -196,14 +184,7 @@ Report cap: final message at most about 1,500 tokens; longer material goes to a
 
 ## Boundaries
 
-**You are TRIAGE ONLY — read and judge, never write:**
-- Read files for 30-line context around each issue
-- Run grep/Read for FALSE_POSITIVE evidence
-<!-- curation:on -->
-- Read ADR/PF bodies through the decisions index
-<!-- curation:end -->
-
-**Never:**
+You read and judge, and never write. **Never:**
 - Edit any file
 - Run builds, tests, or lint
 - Create commits or branches

package/src/assets/agents/validate.md

@@ -1,6 +1,6 @@
 ---
 name: Validate
-description: Runs build, typecheck, lint and test; reports pass or fail with failure details; never fixes.
+description: Runs build, typecheck, lint and test; reports pass or fail with details; never fixes.
 model: haiku
 effort: medium
 skills:
@@ -23,8 +23,6 @@ You run the project's validation commands and report the results; never fix code
 - **VALIDATION_SCOPE**: `full` | `changed-only` (a test-filter hint)
 - **GATE_LEVEL**, **BASE_SHA** (optional): see Lint pack.
 
-**Worktree Support**: with `WORKTREE_PATH`, follow the `devflow:worktree-support` skill.
-
 ## Validation Order
 
 Run the commands of package.json, Makefile, Cargo.toml or similar in this order, skipping any that do not exist and stopping on first failure:

package/src/assets/commands/_partials/_compliance.mds

@@ -18,7 +18,7 @@ cannot restore one.
 @end
 
 @define compliance_lens():
-**Resolve the compliance lens** for each worktree root, from its settings line — the line resolved above for that root, by the settings block when this run has not yet resolved it (every framework reference is installed on every machine, so no file check decides it).
+**Resolve the compliance lens** for each worktree root, from its settings line — the line resolved above for that root, by the settings block when this run has not yet resolved it (no file check decides it).
 
 **Set the compliance lens** from that line: {{compliance_frameworks()}}
 @end
@@ -42,7 +42,7 @@ For this compliance focus, {{compliance_load(ids)}}
 @end
 
 @define compliance_inject():
-**Set the compliance directive** from `COMPLIANCE_FRAMEWORKS`. `COMPLIANCE_DIRECTIVE` is empty when `COMPLIANCE_FRAMEWORKS` is `off`: a spawn line that holds only `{COMPLIANCE_DIRECTIVE}` is then left out, so a lens-off spawn carries nothing about compliance. Otherwise `COMPLIANCE_DIRECTIVE` is this one line, with `<ids>` replaced by the value of `COMPLIANCE_FRAMEWORKS`:
+**Set the compliance directive** from `COMPLIANCE_FRAMEWORKS`. `COMPLIANCE_DIRECTIVE` is empty when `COMPLIANCE_FRAMEWORKS` is `off`: a spawn line that holds only `{COMPLIANCE_DIRECTIVE}` is then left out. Otherwise `COMPLIANCE_DIRECTIVE` is this one line, with `<ids>` replaced by the value of `COMPLIANCE_FRAMEWORKS`:
 
 > {{compliance_directive("<ids>")}}
 @end

package/src/assets/commands/_partials/_decisions.mds

@@ -1,14 +1,24 @@
+@import { root_paths } from "./_docs_root.mds"
+
 A partial: the decisions-index steps the knowledge-workflow commands and the
 dynamic commands share.
 
+`decisions_locate()` names where the ledger belongs and expands
+the shared `root_paths()` step of `_docs_root.mds`. One `resolve-root.cjs` call, run once per
+run, prints `LEDGER=`: the main worktree when the checkout is a linked worktree whose main
+worktree holds a `.devflow/` folder that is not the home directory, else the toplevel, else
+the start directory. That is the rule the curation hooks apply, so a command reads the index
+the Curate agent writes. The import is selective and takes `root_paths` alone: that define has
+no imports of its own, so it adds one node to the scope of each define here.
+
 D-DECISIONS-LEARNING-GATE: a decisions load is gated on the settings line's
 `CURATION`. Curation can be narrowed by the repository or the machine, and neither
 can turn it back on (D-FEATURES-NARROW-ONLY). The settings line also reads
 `CURATION=off` while git tracks the curation folders, or does not answer for them:
 the files there are the repository's own content, and devflow reads nothing in a
 folder it cannot tell is its own. So `decisions_gate()` is the one sentence every
-decisions host carries: with `CURATION=off` the step is skipped before it locates a
-ledger or reads an index. An unresolvable settings line reads `CURATION=off`, as the
+decisions host carries: with `CURATION=off` the step is skipped before it reads an index (the shared
+root step may already have named the ledger folder, but reads no file in it). An unresolvable settings line reads `CURATION=off`, as the
 fail-closed line does, because a failed resolution cannot show what git tracks. The
 gate reads the line the host's settings block resolved above; this partial imports
 nothing from `_settings.mds`. In a multi-worktree run the line is the start root's:
@@ -33,23 +43,13 @@ the gate and the locator, reached only from inside a curation-on arm, so a curat
 none of the rule (D-LEARNING-VARIANTS).
 
 @define decisions_gate():
-When the settings line says `CURATION=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
+When the settings line says `CURATION=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, reading no index.
 @end
 
 @define decisions_locate():
-The decisions ledger belongs to the repository, not to one checkout: a linked worktree reads the main worktree's copy, a subdirectory session the repository root's. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
-
-```bash
-git -C "{start}" rev-parse --path-format=absolute --show-toplevel --git-common-dir
-```
-
-Line 1 is the checkout's toplevel, line 2 the common git directory. A git older than 2.31 echoes `--path-format=absolute` back as a line of its own first. `{ledger}` is the first that applies:
+The decisions ledger belongs to the repository, not to one checkout: a linked worktree reads the main worktree's copy.
 
-1. **The main worktree** — line 2 without its trailing `/.git`, when the output is exactly two lines each beginning with `/`, line 2 ends in `/.git`, and the directory left once it is removed is not your home directory and contains a `.devflow/` directory.
-2. **The toplevel** — line 1, or on an older git the line after the echoed flag.
-3. **The start directory itself** — when the command failed or printed no absolute toplevel (outside a git repository).
-
-This is the rule the curation hooks apply, so you read the index the Curate agent writes.
+{{root_paths()}}
 @end
 
 @define decisions_slice():
@@ -64,14 +64,9 @@ Hand each agent that takes `DECISIONS_CONTEXT` a slice, not the whole index: the
 
 {{decisions_locate()}}
 
-**Step 1 — Read the pre-rendered index:**
-
-Attempt to read `{ledger}/.devflow/curation/index.md`.
+**Step 1 — Read the pre-rendered index** `{ledger}/.devflow/curation/index.md`. Its content is `DECISIONS_CONTEXT`; if it is absent or empty, `DECISIONS_CONTEXT` is `(none)`.
 
-- If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
-- If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
-
-The index is one direct file read, written at render time by `render-decisions.cjs` — no `.cjs` script runs here.
+The index is one direct file read.
 
 **Step 2 — Slice the index, then hand it on:**
 
@@ -79,8 +74,6 @@ When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contr
 
 {{decisions_slice()}}
 
-Those agents follow `devflow:apply-decisions`. A host that uses the index in its own thread says so in its own step.
-
 <!-- curation:end -->
 @end
 

package/src/assets/commands/_partials/_docs_root.mds

@@ -1,4 +1,18 @@
-A partial: where a command's `.devflow/docs/` artifacts live (D-DOCS-ROOT, #406).
+A partial: where a command's roots are, and where its `.devflow/docs/` artifacts live (D-DOCS-ROOT, #406).
+
+`root_paths()` is the one step that resolves both roots a command works from. One call
+of `resolve-root.cjs` prints `WORKTREE=` (the checkout's toplevel, else the start
+directory) and `LEDGER=` (the decisions ledger's root: the main worktree when the
+checkout is a linked worktree and the main worktree holds a `.devflow/` folder, else the
+toplevel). The script holds no judgment: it takes the git call and the ledger rule from
+`resolve-settings.cjs`, the rule the curation hooks apply. The step runs once per start
+directory, so a run over several worktrees resolves each one.
+`docs_root()` here, `knowledge_root()` in `_knowledge.mds` and `decisions_locate()` in
+`_decisions.mds` each expand it, so no host needs to know which of its steps comes
+first: the first one to run calls the script and the others reuse the answer. Each of the
+three adds only the facts its own host needs after the step. When the script fails, both
+roots are the start directory. A curation-off build also carries the `LEDGER=` line: the
+script only names that folder and reads no file in it.
 
 D-DOCS-ROOT extends D-PROMPT-ROOT from the decisions and knowledge loaders to
 every docs artifact a command reads or writes — design documents, research
@@ -6,9 +20,8 @@ output, bug-analysis and wave directories, ticket sets, and `/implement`'s
 handoff and evidence files. They belong to the checkout, not to the directory
 the session started in: a relative `.devflow/docs/…` path written from
 `packages/app` scattered a second `.devflow/docs/` tree there, which no later
-run found. The rule is the knowledge loader's — the toplevel, else the start
-directory — because docs artifacts are per checkout like knowledge bases, not
-per repository like the decisions ledger.
+run found. The root is `WORKTREE`, because docs artifacts are per checkout like
+knowledge bases, not per repository like the decisions ledger.
 
 A path handed to an agent in repo-relative form (the fields the Git agent's
 operations print into a PR or issue comment, where an absolute path would leak
@@ -18,18 +31,26 @@ relative to, which the receiving agent resolves it under.
 forms; `tests/commands/partials-root.test.ts` runs the resolution command below
 from a root, a subdirectory and a worktree.
 
-One define, imported selectively: MDS deep-clones a module's whole scope into
+Two defines, no imports of their own: MDS deep-clones a module's whole scope into
 every define, so a selective import's capture cost is paid over the importer's
-scope, and a single define with no imports of its own adds one node to it.
+scope. The hosts import `docs_root` alone, and `_knowledge.mds` and `_decisions.mds`
+import `root_paths` alone; each adds one node to the importer's scope.
 
-@define docs_root():
-**Docs root (D-DOCS-ROOT).** Every `.devflow/docs/` path this command reads or writes lives at the checkout's toplevel, never under the directory the session started in. Resolve `{worktree}` from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`) — by running
+@define root_paths():
+Once per start directory (`WORKTREE_PATH` if provided, otherwise cwd), run from it:
 
 ```bash
-git -C "{start}" rev-parse --show-toplevel
+node "$HOME/.devflow/scripts/resolve-root.cjs" "{start}"; echo "exit=$?"
 ```
 
-and using its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. Every docs path below is written `{worktree}/.devflow/docs/…`; a repo-relative docs path handed to an agent always travels with a `WORKTREE_PATH` naming the checkout it is relative to.
+Accept only the three lines `WORKTREE=<absolute path>`, `LEDGER=<absolute path>` and `exit=0`, which set `{worktree}` and `{ledger}`. Otherwise both are the start directory.
+@end
+
+@define docs_root():
+**Docs root (D-DOCS-ROOT).** Every `.devflow/docs/` path is `{worktree}/.devflow/docs/…`. A repo-relative docs path handed to an agent travels with a `WORKTREE_PATH` naming its checkout.
+
+{{root_paths()}}
 @end
 
+@export root_paths
 @export docs_root

package/src/assets/commands/_partials/_engine.mds

@@ -1,37 +1,30 @@
 @define gate1_postcode():
-### GATE 1 — Post-code pipeline (runs exactly TWICE per ticket)
+### GATE 1 — Post-code pipeline
 
-ORDER IS LOAD-BEARING. Run exactly in this sequence:
+Run in this order:
 
 1. **Polish agent** — reduce complexity, remove duplication
 2. **Harden agent** — 9-pillar self-review (deep structural analysis); returns `{"status": "PASS" | "FIXED" | "BLOCKED"}`
    - BLOCKED (a P0 issue cannot be fixed in scope), or a missing or unrecognised status, which counts as BLOCKED → stop the pass and escalate as `harden-blocked`; Validate does not run on code Harden could not accept
-3. **Validate agent** — build / typecheck / lint / test; returns `{"verdict": "PASS" | "FAIL", "details": "..."}`. It runs LAST and UNCONDITIONALLY: one full run over the HEAD that Polish and Harden left, so it covers their commits whether or not Harden changed code
-   - Build/test commands follow `build_execution_doctrine()`: the Validate agent's Running commands block, foreground under an explicit Bash timeout.
+3. **Validate agent** — build / typecheck / lint / test; returns `{"verdict": "PASS" | "FAIL", "details": "..."}`. It runs last and unconditionally: one full run over the HEAD that Polish and Harden left, so it covers their commits whether or not Harden changed code
    - FAIL → Fix agent fix (max 2 retries), each followed by a Validate agent re-run
-   - If still FAIL after 2 retries → escalate as `validation-exhausted` (do not loop endlessly)
+   - If still FAIL after 2 retries → escalate as `validation-exhausted`
 
 **Gate 1 contains NO Evaluate agent and NO Test agent.** Those are Gate 2 only.
 
-Depth scales to change size + budget: a trivial one-line fix warrants a lighter pass; a multi-file refactor warrants the full depth.
-
-**Cadence — Gate 1 runs at exactly TWO points per ticket:**
+**Cadence — Gate 1 runs at exactly two points per ticket:**
 1. **Gate 1 #1** — immediately after the initial Code agent implementation (inside `implement_bundle()`). An escalated result — Validate exhausted, or Harden BLOCKED — returns early: the ticket's engine returns `ESCALATED` with one escalation, and Gate 2 and the review pass never run on a broken or unfinished build.
-2. **Gate 1 #2** — the FINAL gate, after ALL Gate-2 fixes AND the entire review pass have completed. Harden BLOCKED here is `ESCALATED` as well.
-
-It does NOT run inside the review pass, nor after each individual Gate-2 / review / QA fix. At those points the fixing Code agent self-verifies its OWN build compiles (see `review_pass()` and the Code agent's Running commands block). The final Gate 1 #2 is the invariant that all written code passes before merge.
+2. **Gate 1 #2** — the final gate, after all Gate-2 fixes and the entire review pass have completed. Harden BLOCKED here is `ESCALATED` as well.
 @end
 
 @define gate2_acceptance():
-### GATE 2 — Acceptance gate (per ticket, plan-scoped — fires ONCE at implementation acceptance)
+### GATE 2 — Acceptance gate (per ticket, plan-scoped)
 
-Gate 2 fires ONCE: after the implement-bundle and BEFORE the review pass. It does NOT re-run after review-fixes (those get Gate 1 only).
-
-Gate 2 inputs are produced by `/devflow:dynamic-plan`'s plan-challenge step — the acceptance criteria and test plan written for the Evaluate agent and Test agent.
+Gate 2 fires once: after the implement-bundle and before the review pass. It does not re-run after review-fixes (those get Gate 1 only).
 
 **Evaluate agent** (only if a plan exists):
-- Run `evaluator_panel()` — see that block for the one spawn and the two lenses it names
-- If the Evaluate agent returns FAIL (either lens failed): fix-and-continue — the demanded fixes are applied by a Fix agent that self-verifies its own build (batched per the review-pass batching doctrine if numerous). The recorded verdict becomes `FAIL-FIXED` (issues found, fixes applied, not re-evaluated by design); Gate 2 then proceeds. In SINGLE mode the run reports it as `UNVERIFIED`, never PASS.
+- Run `evaluator_panel()`
+- If the Evaluate agent returns FAIL (either lens failed): fix-and-continue — a Fix agent applies the demanded fixes and self-verifies its own build (batched as in the review pass if numerous). The recorded verdict becomes `FAIL-FIXED` (fixes applied, not re-evaluated); Gate 2 then proceeds. In SINGLE mode the run reports it as `UNVERIFIED`, never PASS.
 
 **Test agent** (only if acceptance criteria or a test plan exist):
 - Scenario-based acceptance tests covering functionality, API contracts, performance
@@ -41,24 +34,18 @@ Gate 2 inputs are produced by `/devflow:dynamic-plan`'s plan-challenge step —
 **When Gate 2 inputs are absent:**
 - No plan → skip the Evaluate agent silently (note in output: "Gate 2 Evaluate agent skipped — no plan available")
 - No acceptance criteria and no test plan → skip Test agent silently (note in output: "Gate 2 Test agent skipped — no criteria available")
-- Build proceeds Gate-1-only. Never refuse to build; never force-generate fake criteria. Trust the user.
 @end
 
 @define evaluator_panel():
 ### Evaluate agent spawn (one agent, two lenses)
 
-Run ONE Evaluate agent whose prompt names both lenses, so a ticket pays for one spawn and one read of the plan:
-
-1. **Acceptance criteria** — "Does the implementation satisfy each numbered acceptance criterion, INCLUDING the negative criteria (what it must NOT do)?"
-2. **Scope / intent drift** — "Did the Code agent smuggle in unplanned changes, deviate from the plan's intent, or introduce anti-features?"
-
-It returns `{"verdict": "PASS" | "FAIL", "rationale": "..."}`: FAIL when either lens fails, the rationale naming the failing criterion or the drift. A FAIL on either lens blocks acceptance. A wave ticket runs this same skeleton through `runSingleTicketEngine`, so it gets the same single spawn.
+Run one Evaluate agent whose prompt names both lenses, as the SINGLE skeleton's Gate 2 prompt words them: acceptance criteria (negative criteria included) and scope or intent drift. FAIL when either lens fails.
 @end
 
 @define implement_bundle():
 ### Implement bundle
 
-The standard implementation unit for one ticket. Run in order:
+Run in order:
 
 ```
 <!-- curation:on -->
@@ -75,8 +62,6 @@ Every Code-family agent prompt opens with `OPERATION: <mode>` as its first line:
 <!-- curation:off -->
 Every Code-family agent prompt opens with `OPERATION: <mode>` as its first line: `implement` and `issue-fix` go to `agentType:"Code"`, `validation-fix`, `alignment-fix` and `qa-fix` go to `agentType:"Fix"`. It must include: task description, implementation plan (if one exists), the compliance directive (`COMPLIANCE_DIRECTIVE` — every Code prompt carries it when it is not empty, fix prompts included), and any PRIOR_PHASE_SUMMARY / HANDOFF_FILE for sequential multi-phase tickets.
 <!-- curation:end -->
-
-Gate 2 runs at implementation acceptance — this matches devflow's deliberate placement: "evaluation is part of implementation acceptance, not post-review" (§6.1).
 @end
 
 @define review_pass():
@@ -93,7 +78,7 @@ Core Review agents (always, 8 total): security, architecture, performance, compl
 Conditional by file type detected in the diff (add these when relevant):
 - `.ts` / `.tsx` → typescript
 - `.tsx` / `.jsx` → react, accessibility, ui-design
-- `.tsx` / `.jsx` / `.css` / `.scss` → ui-design (deduplicate with above)
+- `.css` / `.scss` → ui-design
 - `.go` → go
 - `.java` → java
 - `.py` → python
@@ -102,18 +87,13 @@ Conditional by file type detected in the diff (add these when relevant):
 - `package.json` / `go.mod` / `Cargo.toml` / etc. → dependencies
 - Markdown / doc files → documentation
 
-**Spawn pacing:** launch Review agents in staggered chunks of 4–6 (sequential groups of parallel spawns) — the full roster is preserved, paced to avoid 429 batch death.
+**Spawn pacing:** launch Review agents in staggered chunks of 4–6 (sequential groups of parallel spawns).
 
-**Review agent result contract:** every Review agent MUST return a structured result with fields `focus`, `reviewed: true`, `filesExamined`, and `findings`. Each item in `findings` must carry: `file` (path of the primary file the finding relates to, or `null` if scope is unknown), `description` (one-sentence issue statement), and `severity` (`critical | high | medium | low`). A result is DEAD if: the agent returned null, threw, returned a guard string, or `reviewed !== true`. A DEAD Review agent is NEVER treated as a clean reviewer. Retry once sequentially. If still dead after retry: record the focus in `coverageGaps`. A pass with any coverage gaps can never early-exit as clean, and the run verdict can NEVER be PASS; escalate with message "review coverage incomplete: <focus>".
-
-Each Review agent gets `agentType: "Review"` with its focus baked into the prompt. Total: 8–19 Review agents per pass.
+**Review agent result contract:** every Review agent must return a structured result with fields `focus`, `reviewed: true`, `filesExamined`, and `findings`. Each item in `findings` must carry: `file` (path of the primary file the finding relates to, or `null` if scope is unknown), `description` (one-sentence issue statement), and `severity` (`critical | high | medium | low`). A result is DEAD if: the agent returned null, threw, returned a guard string, or `reviewed !== true`. A DEAD Review agent is never treated as a clean reviewer. Retry once sequentially. If still dead after retry: record the focus in `coverageGaps`. A pass with any coverage gaps can never early-exit as clean, and the run verdict can never be PASS; escalate with message "review coverage incomplete: <focus>".
 
 **Step 2 — Adversarial finding verification**
 
-Before any fix, verify findings with perspective-diverse lenses. Run 2–3 agents asking:
-- "Does this finding actually reproduce given the current code?"
-- "Is this a real issue or a false positive in context?"
-- "Does the cited rule/principle actually apply here?"
+Before any fix, verify findings with 2–3 agents, one per lens of the skeleton's verification panel.
 
 Majority-survives: a finding needs >50% of verification lenses to confirm it. Strip unconfirmed findings.
 
@@ -121,27 +101,27 @@ Majority-survives: a finding needs >50% of verification lenses to confirm it. St
 
 If no surviving findings: return early (no fixes needed). Any coverageGaps are carried in the return — they block a PASS verdict downstream, not the early exit.
 
-If survivors remain: batch the confirmed findings for fixing: group findings by file — one file per set of sub-batches, chunked at max 5 findings per sub-batch; never mix two files in one batch. A finding with no `file` field is its own singleton batch. Sub-batches for the SAME file run sequentially (never two Code agents editing the same file concurrently — same-file edits in `parallel()` cause index contention and lost fixes); sub-batches for DISTINCT files run via `parallel()` in staggered chunks of ~5, same pacing bar as the Review spawn path (different code areas — safe per concurrency doctrine). Each Code agent's prompt pins a return contract: `{"status": "fixed"|"blocked", "commitShas": [...], "unresolved": [...]}` — a chunk is FIXED only when `result.status === "fixed"` AND `commitShas` is non-empty AND `result.unresolved` is empty; never decide disposition from status alone. A non-empty `unresolved` list means the agent named work it could not complete — carry the whole chunk into `survivingFindings` rather than guessing which findings the strings map to. `survivingFindings` = findings NOT addressed: fix Code agent dead/failed/blocked/deferred OR committed but left work named in `unresolved`. The fixing Code agent **self-verifies its own fix builds** (build/typecheck per the Code agent's Running commands block, once over its whole batch). Do **NOT** run Gate 1 or Gate 2 inside the pass (no Validate agent, no Polish agent, no Harden agent, no Evaluate agent, no Test agent). The engine runs ONE final Gate 1 after the pass exits — see the `gate1_postcode()` cadence (Gate 1 #2).
+If survivors remain: batch the confirmed findings for fixing: group findings by file — one file per set of sub-batches, chunked at max 5 findings per sub-batch; never mix two files in one batch. A finding with no `file` field is its own singleton batch. Sub-batches for the same file run sequentially (never two Code agents editing the same file concurrently); sub-batches for distinct files run via `parallel()` in staggered chunks of ~5. Each Code agent's prompt pins a return contract: `{"status": "fixed"|"blocked", "commitShas": [...], "unresolved": [...]}` — a chunk is FIXED only when `result.status === "fixed"` AND `commitShas` is non-empty AND `result.unresolved` is empty; never decide disposition from status alone. A non-empty `unresolved` list means the agent named work it could not complete — carry the whole chunk into `survivingFindings` rather than guessing which findings the strings map to. `survivingFindings` = findings not addressed: fix Code agent dead/failed/blocked/deferred or committed but left work named in `unresolved`. The fixing Code agent **self-verifies its own fix builds** (build/typecheck per the Code agent's Running commands block, once over its whole batch). Do not run Gate 1 or Gate 2 inside the pass (no Validate, Polish, Harden, Evaluate or Test agent).
 @end
 
 @define concurrency_doctrine():
-### Code agent concurrency doctrine (§7.1 — LOAD-BEARING)
+### Code agent concurrency doctrine
 
 **DEFAULT: SEQUENTIAL.** Parallelism is the rare, tightly-gated exception.
 
-- **Same task → sequential Code agents with handoff. NEVER parallel.** Sequential Code agents passing a handoff artifact produce far more coherent code than parallel Code agents dividing one task. Two Code agents splitting one task is a coherence hazard, not a speedup.
-- **Different tasks MAY parallelize, but ONLY when ALL THREE bars hold:**
+- **Same task → sequential Code agents with handoff. Never parallel.**
+- **Different tasks may parallelize, but only when all three bars hold:**
   1. Completely different areas of the code — different files/modules, no imports between them, no shared contracts/interfaces
   2. Different feature logic — they do not touch the same feature's logic or cooperate on a single outcome
   3. Different goals — they are not two steps converging on the same end state
-- **Default-sequential even across multiple tasks.** "They look independent" is NOT sufficient. If two tasks are somewhat related — they touch the same feature, one's completion makes the other meaningful, or they march toward a shared goal — run them sequentially.
-- **When in doubt, sequential.** Parallel must be affirmatively justified against all three bars. The cost of a wrong parallel call (incoherent merge, contended edits) dwarfs the wall-clock saved.
+- "They look independent" is not sufficient. If two tasks are somewhat related — they touch the same feature, one's completion makes the other meaningful, or they march toward a shared goal — run them sequentially.
+- **When in doubt, sequential.** Parallel must be affirmatively justified against all three bars.
 
-This applies to both: multiple Code agents working on a single ticket AND multi-ticket scheduling in a wave.
+This applies to both: multiple Code agents working on a single ticket and multi-ticket scheduling in a wave.
 @end
 
 @define build_execution_doctrine():
-### Build execution doctrine — the Running commands block (LOAD-BEARING)
+### Build execution doctrine — the Running commands block
 
 The Code, Fix, Refactor, Validate and Test agents each carry this `## Running commands` block in their bodies, so each prompt in this engine names the block ("your Running commands block") instead of copying it:
 
@@ -156,17 +136,15 @@ Run builds, typechecks, lints and tests in the foreground, each with an explicit
 - Never wrap a build or test command in `sh -c`, `bash -c`, `python3 -c` or `node -e`: permission rules deny wrapped commands they allow directly.
 - The same rules hold inside a dynamic Workflow sub-agent.
 
-**Cheapest-sufficient validation:** iterate with the fastest check that proves the change — `tsc --noEmit`, `cargo check`, `go vet`, a single test file — the ecosystem's cheapest sufficient signal. Reserve expensive full/optimized builds and whole-suite runs for the final gates only.
-
-**One build gate per phase:** batch related fixes, validate once. A fix-pass Code agent runs ONE light check over its whole batch — never several invocations per small fix. Do NOT validate after every individual mutation; validate once after the batch is complete.
+**Cheapest-sufficient validation:** iterate with the fastest check that proves the change — `tsc --noEmit`, `cargo check`, `go vet`, a single test file. Reserve full builds and whole-suite runs for the final gates.
 
-**Scope commands to stay short.** During the engine, prefer the scoped command for the change over the whole workspace — `cargo build -p <crate>`, `cargo test -p <crate>`, `npm test -- <path>`, `go test ./pkg/...` — and, when the whole set is needed, one workspace-level command over a per-package loop. After the wave, the full-workspace regression is the human's job (the wave already hands the integrated branch back to the user).
+**One build gate per phase:** batch related fixes, validate once. A fix-pass Code agent runs one light check over its whole batch, never one per fix. After the wave, the full-workspace regression is the human's job.
 @end
 
 @define engine_output_schema():
 ### Engine output schema
 
-Each ticket engine run returns a structured result. The Synthesize agent or the wave loop reads this to decide next steps. The engine fills `verdict`: the SINGLE skeleton's `overallVerdict`, or `ESCALATED` from the ticket-link or branch stop. The wave merges `PASS` and `UNVERIFIED` and quarantines every other value, or none.
+Each ticket engine run returns a structured result. The engine fills `verdict`: the SINGLE skeleton's `overallVerdict`, or `ESCALATED` from the ticket-link or branch stop. The wave merges `PASS` and `UNVERIFIED` and quarantines every other value, or none.
 
 ```json
 {
@@ -214,15 +192,15 @@ Each ticket engine run returns a structured result. The Synthesize agent or the
 @end
 
 @define engine_invariants():
-### Engine invariants (non-negotiable)
+### Engine invariants
 
-1. **Code is written ONLY by the Code family (Code, Fix).** No other agent type writes code — not Review agent, not Evaluate agent.
-2. **Findings are verified before any fix is written.** The adversarial verification step is not optional; unverified findings are not passed to the Code agent.
-3. **All written code passes Gate 1.** No code merge, commit, or handoff before Polish agent + Harden agent + Validate agent (in that order — Validate last, so its one run covers the commits of the two before it).
-4. **Gate 2 runs once, at implementation acceptance.** It does not re-run after review-fixes.
-5. **NEVER auto-merge to main or master.** All merges target the integration branch. The user merges to main themselves.
+1. **Code is written only by the Code family (Code, Fix).** No other agent type writes code.
+2. **Findings are verified before any fix is written.** Unverified findings are not passed to the Code agent.
+3. **All written code passes Gate 1.** No code merge, commit, or handoff before Polish agent + Harden agent + Validate agent (in that order).
+4. **Gate 2 runs once, at implementation acceptance.**
+5. **NEVER auto-merge to main or master.** All merges target the integration branch.
 6. **No unauthorized tracker or remote side-effects.** Sub-agents NEVER create issues/PRs on the tracker, comment on them, or push beyond the ticket-authorized branch unless the ticket, plan, or user explicitly authorizes that exact action. This applies to whatever tracker is resolved, not to one vendor. Proposed follow-ups go in the run report.
-7. **The review pass runs exactly ONCE per ticket.** Never author additional cycles or a delta re-review of fix commits. Fix commits are covered by the fixing Code agent's self-verification and the final Gate 1 #2. Budget scales roster size and verification votes, never pass count.
+7. **The review pass runs exactly ONCE per ticket.** Never author additional cycles or a delta re-review of fix commits.
 @end
 
 @export gate1_postcode

package/src/assets/commands/_partials/_evidence_policy.mds

@@ -5,7 +5,7 @@
 node "$HOME/.devflow/scripts/resolve-evidence-policy.cjs" 2>/dev/null; echo "exit=$?"
 ```
 
-Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `EVIDENCE_POLICY=<required|standard> SOURCE=<file|worktree|default|invalid|error> REF=<branch|none>[ WARN=<remote-unavailable|invalid-file|raised-by-compliance|pr-changes-policy>[,…]] ISSUE_REQUIRED=<true|false> APPLY_CONVENTIONS=<true|false> REQUIRE_NON_AUTHOR_APPROVAL=<true|false>` — these fields, in this order, nothing else, where `<branch>` is a branch name such as `main`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `EVIDENCE_POLICY=required SOURCE=error REF=none ISSUE_REQUIRED=true APPLY_CONVENTIONS=true REQUIRE_NON_AUTHOR_APPROVAL=true` instead.
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `EVIDENCE_POLICY=<required|standard> SOURCE=<file|worktree|default|invalid|error> REF=<branch|none>[ WARN=<remote-unavailable|invalid-file|raised-by-compliance|pr-changes-policy>[,…]] ISSUE_REQUIRED=<true|false> APPLY_CONVENTIONS=<true|false> REQUIRE_NON_AUTHOR_APPROVAL=<true|false>` — these fields, in this order, nothing else, where `<branch>` is a branch name. **Anything else** (including a script that cannot run) ⇒ use `EVIDENCE_POLICY=required SOURCE=error REF=none ISSUE_REQUIRED=true APPLY_CONVENTIONS=true REQUIRE_NON_AUTHOR_APPROVAL=true` instead.
 
 Set `EVIDENCE_POLICY`, `ISSUE_REQUIRED`, `APPLY_CONVENTIONS` and `REQUIRE_NON_AUTHOR_APPROVAL` from the accepted line. Pass agents only the three mechanism inputs, never `EVIDENCE_POLICY`. Report `Evidence policy: {EVIDENCE_POLICY} (source: {SOURCE})`, plus any `WARN` tokens as advisory, once in the final report.
 @end