devflow-kit 3.11.0 → 3.12.0

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

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

@@ -1,27 +1,11 @@
 @define factory_shape():
 ### Ticket-factory pipeline shape (generalized)
 
-This is the standard shape for converting an initiative or spec into a reviewed, amended, self-consistent set of tickets plus a tracking issue. It generalises the `l3-ticket-factory` reference (`draft → [2-lens review in parallel] → revise → whole-set critic → per-ticket amend → tracking-issue`).
-
-The candidate ticket slate is **proposed by the model** (you, reading the initiative/spec), then **user-editable** before the pipeline runs. Never hardcode ticket identities — let the user confirm the slate first.
-
 ---
 
 #### Stage 1 — Draft (one agent per ticket, parallelisable)
 
-Spawn one Design agent or Synthesize agent per candidate ticket:
-
-```js
-// Parallel per-ticket drafters — each is fully independent at draft time
-const drafts = await parallel(candidates.map(c => () =>
-  agent(`Draft ticket for: ${c.title}\nInitiative: ${initiative}\n${constraints}`, {
-    agentType: "Design",
-    schema: DRAFT_SCHEMA
-  })
-));
-```
-
-DRAFT_SCHEMA (in fenced block — braces are raw):
+Spawn one Design agent or Synthesize agent per candidate ticket. DRAFT_SCHEMA:
 
 ```json
 {
@@ -45,29 +29,9 @@ DRAFT_SCHEMA (in fenced block — braces are raw):
 
 #### Stage 2 — Two-lens review (parallel per ticket)
 
-For each draft, run TWO independent Review agents **in parallel** — one per lens:
-
-**Lens A — Planner-readiness (cold read):** Could a planner build from this ticket alone, with no other context? Hunt: missing information; untestable or missing negative acceptance criteria; ambiguous constraints; scope holes (things the feature obviously needs that neither In nor Out mentions); undefined terms a cold reader cannot resolve. Severity: critical = planner would be blocked or misled; major = planner would guess; minor = polish.
-
-**Lens B — Accuracy / scope-discipline audit:** Every claim is sourced from the initiative or spec. No smuggled anti-features (scope items the initiative explicitly excludes). Constraints are honored. Dependency placeholders are consistent with the candidate slate. Severity: critical = invented fact / anti-feature / leak; major = unsourced claim or stance contradiction; minor = citation polish.
-
-```js
-// Two Review agents per ticket, parallel across both lens and all tickets
-const reviews = await parallel(drafts.map((draft, i) => () =>
-  parallel([
-    () => agent(`Planner-readiness cold read of ticket: ${JSON.stringify(draft)}`, {
-      agentType: "Review",
-      schema: REVIEW_SCHEMA
-    }),
-    () => agent(`Accuracy/scope-discipline audit of ticket: ${JSON.stringify(draft)}`, {
-      agentType: "Review",
-      schema: REVIEW_SCHEMA
-    }),
-  ])
-));
-```
+For each draft, run two independent Review agents **in parallel**, one per lens, with the checks and severities the skeleton's review prompts state: Lens A, planner-readiness (a cold read), and Lens B, accuracy and scope discipline. A scope hole is a thing the feature obviously needs that neither In nor Out names. A smuggled anti-feature is a scope item the initiative explicitly excludes.
 
-REVIEW_SCHEMA (in fenced block — braces are raw):
+REVIEW_SCHEMA:
 
 ```json
 {
@@ -92,22 +56,7 @@ REVIEW_SCHEMA (in fenced block — braces are raw):
 
 #### Stage 3 — Revise (one agent per ticket, per review findings)
 
-For each ticket, spawn one Synthesize agent or Design agent to apply review findings:
-
-```js
-// Sequential per ticket (shared file state); parallelisable across tickets only if separate files
-const revised = await parallel(drafts.map((draft, i) => () =>
-  agent(`Revise ticket per review findings. Fix all critical + major findings; apply minor only where they clarify.
-Ticket: ${JSON.stringify(draft)}
-Reviews: ${JSON.stringify(reviews[i])}
-Rules: if a finding asks for information that does not exist in the source initiative, add it to Open Questions — never invent. If a finding contradicts the stated initiative scope, the initiative wins; note the decline.`, {
-    agentType: "Synthesize",
-    schema: REVISE_SCHEMA
-  })
-));
-```
-
-REVISE_SCHEMA (in fenced block — braces are raw):
+For each ticket, spawn one Synthesize agent or Design agent to apply review findings. REVISE_SCHEMA:
 
 ```json
 {
@@ -125,25 +74,9 @@ REVISE_SCHEMA (in fenced block — braces are raw):
 
 #### Stage 4 — Whole-set cross-critic (single agent, sees all revised tickets)
 
-One Design agent reviews the FULL revised set for set-level issues — not individual prose quality:
-
-1. **Coverage:** does the union of tickets cover every item the initiative mandates? Anything the initiative mandates that no ticket owns?
-2. **Overlaps / contradictions:** same responsibility claimed by two tickets; contradictory constraints between tickets; inconsistent terminology for the same concept.
-3. **Dependency graph:** placeholders used consistently; wave assignment matches stated dependencies; anything that should be a dependency but isn't declared.
-4. **Acceptance-criteria coherence:** no criterion in one ticket contradicts a criterion in another.
-
-```js
-const critic = await agent(`Whole-set completeness & coherence audit.
-Revised tickets: ${JSON.stringify(revised)}
-Initiative: ${initiative}
-Audit: coverage · overlaps/contradictions · dependency graph · acceptance-criteria coherence.
-Return: setVerdict + perTicketAmendments + trackingGuidance.`, {
-  agentType: "Design",
-  schema: CRITIC_SCHEMA
-});
-```
+One Design agent reviews the full revised set for set-level issues, not individual prose quality, on the four axes the skeleton's cross-critic prompt names: coverage, overlaps and contradictions, the dependency graph, and acceptance-criteria coherence. The dependency-graph check also flags a dependency that a ticket needs but does not declare.
 
-CRITIC_SCHEMA (in fenced block — braces are raw):
+CRITIC_SCHEMA:
 
 ```json
 {
@@ -168,48 +101,21 @@ CRITIC_SCHEMA (in fenced block — braces are raw):
 
 #### Stage 5 — Per-ticket amend (parallel, only tickets with amendments)
 
-Apply cross-set amendments to the tickets that need them:
-
-```js
-const toAmend = (critic.perTicketAmendments || []).filter(a => a.amendments.length > 0);
-if (toAmend.length) {
-  await parallel(toAmend.map(a => () =>
-    agent(`Apply cross-set amendments to ticket "${a.title}":
-Amendments: ${JSON.stringify(a.amendments)}
-Rules: same as revise — never invent; unresolvable items go to Open Questions; initiative scope wins over any amendment that contradicts it.`, {
-      agentType: "Synthesize"
-    })
-  ));
-}
-```
-
 ---
 
 #### Stage 6 — Assemble tracking issue
 
-One Synthesize agent writes the tracking-issue document from the final ticket set + critic guidance:
-
-```js
-const tracker = await agent(`Write a tracking-issue document for the initiative.
-Guidance from cross-set critic: ${JSON.stringify(critic.trackingGuidance)}
-Final tickets: ${JSON.stringify(revised)}
-Structure: initiative context (1–2 paragraphs) + wave-structured execution checklist + ticket index (one line per ticket, user-facing) + explicitly-excluded items (decisions, not oversights) + invariants that bind every ticket.
-Output: write to the artifact path and return { path, title }.`, {
-  agentType: "Synthesize",
-  schema: { type: "object", required: ["path", "title"],
-    properties: { path: { type: "string" }, title: { type: "string" } } }
-});
-```
+One Synthesize agent writes the tracking-issue document from the final ticket set + critic guidance.
 
 ---
 
-#### Usage notes for commands that import this partial
+#### Usage notes
 
+- Each schema is its stage's return shape, passed as `schema:`: `{ agentType: "Design", schema: DRAFT_SCHEMA }`, `{ agentType: "Review", schema: REVIEW_SCHEMA }`, `{ agentType: "Synthesize", schema: REVISE_SCHEMA }`, `{ agentType: "Design", schema: CRITIC_SCHEMA }`. A field that the host script's `Return:` line adds joins the schema.
 - The `candidates` array is **what the model proposed + user confirmed** — never hardcoded.
 - The `initiative` variable is the raw user input (a description, a spec doc path, or inline text) — read it and distill before passing to agents.
 - The `constraints` variable is optional: any cross-cutting rules (naming discipline, scope filters, authority order) the user supplied.
-- Emit artifact files using the `ticket_body_template()` shape (from `_ticket_template.mds`) for each ticket — write inside agents, since the script body has no filesystem access.
-- Tracking-issue doc goes to `${ROOT}/.devflow/docs/tickets/{slug}/{ts}/tracking-issue.md`, `ROOT` being the workflow's `root` argument (agents do the writing).
+- Write each ticket's artifact file inside an agent, with the ticket body template above.
 - For large initiatives (more than ~8 tickets), chunk the `parallel(map())` fan-outs into batches (e.g. `for` loop over slices, `await`-ing each batch) so agent concurrency stays bounded and provider rate limits are respected.
 @end