devflow-kit 3.1.0 → 3.3.0

package/src/assets/agents/simplify.md

@@ -2,9 +2,29 @@
 name: Simplify
 description: Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. Focuses on recently modified code unless instructed otherwise.
 model: sonnet
+effort: medium
 skills:
   - devflow:software-design
   - devflow:worktree-support
+disallowedTools:
+  - Agent
+  - SendMessage
+  - NotebookEdit
+  - EnterWorktree
+  - ExitWorktree
+  - ArtifactComments
+  - ArtifactData
+  - TodoWrite
+  - AskUserQuestion
+  - TaskOutput
+  - ScheduleWakeup
+  - CronCreate
+  - CronDelete
+  - CronList
+  - RemoteTrigger
+  - PushNotification
+  - DesignSync
+  - Skill
 ---
 
 # Simplify Agent
@@ -76,6 +96,8 @@ Your refinement process:
 
 You operate autonomously and proactively, refining code immediately after it's written or modified without requiring explicit requests. Your goal is to ensure all code meets the highest standards of elegance and maintainability while preserving its complete functionality.
 
+**Gate ownership:** Run no build, test or lint command. Reading files and git diffs is not verification. Only Validate runs the full suite.
+
 ## Output
 
 Return structured completion status:
@@ -93,6 +115,8 @@ Return structured completion status:
 - {file} ({change description})
 ```
 
+Report cap: final message at most about 1,500 tokens; longer material goes to a `mktemp` file (via Bash or Write) and the message gives its path. Exempt, inline in full: the completion status, `### Files Modified` and your commits.
+
 ## Boundaries
 
 **Escalate to orchestrator:**

package/src/assets/agents/skim.md

@@ -1,10 +1,12 @@
 ---
 name: Skim
 description: Codebase orientation using rskim to identify relevant files, functions, and patterns for a feature or task
-model: sonnet
+model: haiku
+effort: medium
 tools: ["Bash", "Read"]
 skills:
   - devflow:worktree-support
+omitClaudeMd: true
 ---
 
 # Skim Agent
@@ -70,7 +72,7 @@ If you already know a file needs content, go straight to Read — don't skim it
 
 ### Step 6: Project Knowledge
 
-If `.devflow/learning/decisions.md` exists, Read its `<!-- TL;DR: ... -->` first-line comment and include active decision count under "### Active Decisions". Only the TL;DR — intentional for token efficiency.
+Read the decisions TL;DR at the repository's main worktree, where the ledger lives. Run `git -C "{start}" rev-parse --path-format=absolute --show-toplevel --git-common-dir`, `{start}` being `WORKTREE_PATH` if provided, otherwise cwd. `{ledger}` is the first that applies: the main worktree — when the output is two absolute lines and line 2 ends in `/.git`, its parent, provided that directory contains `.devflow/` and is not your home directory; else the toplevel, line 1 (on a git older than 2.31, the line after the echoed flag); else `{start}`, when the command failed. If `{ledger}/.devflow/learning/decisions.md` exists, Read its first line, `<!-- TL;DR: N decisions -->`, and report N under "### Active Decisions". Only the TL;DR — intentional for token efficiency.
 
 ### Step 7: Generate Summary
 
@@ -127,6 +129,8 @@ skim also handles prose/config files (`.md`, `.json`, `.yaml`, `.toml`) — the
 {Brief recommendation based on codebase structure}
 ```
 
+Report cap: final message at most about 1,500 tokens; longer material goes to a `mktemp` file via Bash and the message gives its path. Exempt, inline in full: the `### Relevant Files for Task` table.
+
 ## Principles
 
 1. **Speed and focus** — Get oriented quickly on what's relevant; task-focused exploration only

package/src/assets/agents/synthesize.md

@@ -2,10 +2,20 @@
 name: Synthesize
 description: "Combines outputs from multiple agents into actionable summaries (modes: exploration, planning, review, bug-analysis, design, research)"
 model: haiku
+effort: medium
 skills:
   - devflow:review-methodology
   - devflow:docs-framework
   - devflow:worktree-support
+tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - StructuredOutput
+omitClaudeMd: true
 ---
 
 # Synthesize Agent
@@ -24,6 +34,8 @@ The orchestrator provides:
 
 **Worktree Support**: If `WORKTREE_PATH` is provided, follow the `devflow:worktree-support` skill for path resolution. If omitted, use cwd.
 
+**Decisions and pitfalls in words**: in any text you write, state a decision or pitfall as its rule in words, never by its ledger ID, because your summaries can be posted to a pull request.
+
 ---
 
 ## Mode: Exploration
@@ -378,6 +390,12 @@ If CYCLE_NUMBER >= 3 and prior FP ratio > 70%: append "Note: High false-positive
 
 ---
 
+## Output
+
+Each mode's template above is its output.
+
+Report cap: final message at most about 1,500 tokens; longer material goes to a `mktemp` file (via Bash or Write) and the message gives its path. Exempt, inline in full: the synthesis in exploration, planning and design modes. Review, bug-analysis and research modes write the summary to disk and return its path.
+
 ## Principles
 
 1. **No new research** - Only synthesize what agents found

package/src/assets/agents/test.md

@@ -2,10 +2,10 @@
 name: Test
 description: Scenario-based QA agent. Designs and executes acceptance tests from criteria and implementation. Reports pass/fail with evidence — never fixes code.
 model: sonnet
+effort: medium
 tools: ["Read", "Grep", "Glob", "Bash", "mcp__claude-in-chrome__tabs_context_mcp", "mcp__claude-in-chrome__tabs_create_mcp", "mcp__claude-in-chrome__navigate", "mcp__claude-in-chrome__get_page_text", "mcp__claude-in-chrome__read_page", "mcp__claude-in-chrome__find", "mcp__claude-in-chrome__form_input", "mcp__claude-in-chrome__javascript_tool", "mcp__claude-in-chrome__read_console_messages"]
 skills:
   - devflow:qa
-  - devflow:testing
   - devflow:worktree-support
 ---
 
@@ -72,18 +72,24 @@ For each scenario:
 
 If a previous run failed (PREVIOUS_FAILURES provided), prioritize re-testing those scenarios first.
 
-## Long-running commands (test/build commands that may run >120s)
+**Gate ownership:** Run the scenario commands. Never the full suite. Only Validate runs the full suite.
 
-A plain `Bash` call defaults to a 120s timeout, and inside a dynamic Workflow a sub-agent that emits no output for 180s is KILLED ("agent stalled"). For any scenario whose command may run silent longer than ~120s (a full `cargo test` / `go test ./...`, a build step, a slow integration suite), do NOT run it as one silent foreground command. Instead:
+## Running commands
 
-1. Run it in the BACKGROUND with the Bash tool (`run_in_background: true`), capturing output + exit code under a unique `<slug>` reused in step 2:
-   `<command> > /tmp/df-test-<slug>.log 2>&1; echo "EXIT=$?" > /tmp/df-test-<slug>.done`
-2. Poll with the `Monitor` tool (load it via ToolSearch `select:Monitor` if it is not available): set `persistent: false`, `timeout_ms` above the expected run time (e.g. 600000), and
-   `command: until [ -f /tmp/df-test-<slug>.done ]; do echo running; sleep 25; done; echo DONE; cat /tmp/df-test-<slug>.done`
-   The 25s heartbeat (≪ 180s) is delivered as a notification that keeps you alive past the watchdog.
-3. When the monitor reports `DONE`: the scenario's command PASSED iff the `.done` file contains `EXIT=0`. Read the `.log` for evidence.
+Run builds, typechecks, lints and tests in the foreground, each with an explicit Bash `timeout` above its expected run time. The ceiling is 600000 ms, or `BASH_MAX_TIMEOUT_MS` when set (`echo ${BASH_MAX_TIMEOUT_MS:-600000}`).
 
-For a foreground command that exceeds the 120s default but stays under 180s, pass an explicit higher `timeout` to the Bash tool (up to 600000ms). Prefer scoping to the changed package/path where possible.
+- Capture, then tail, in one Bash call (shell state does not persist): `LOG=$(mktemp); echo "LOG=$LOG"; <command> >"$LOG" 2>&1; rc=$?; tail -n 40 "$LOG"; echo "EXIT=$rc"`. The printed `EXIT=` value is the result; never decide one from a grep count.
+- Never background a command and wait on it, and never poll across turns: no `sleep` or `true` turns, no sentinel-file checks, no Monitor.
+- Prefer the scoped command for the change (a package, a path or a test file); for the whole set, one workspace-level command over a per-package loop.
+- A run that exceeds its timeout is BLOCKED: report its duration and log path. Do not wait on it, poll it or re-run it.
+- A run expected to exceed the ceiling is split into parts, each under about 90% of it, run in sequence. If it cannot be split, report BLOCKED with the remedy `devflow flags --set bash-max-timeout-ms=<ms>`.
+- Never re-run a command when nothing it reads has changed.
+- Never wrap a build or test command in `sh -c`, `bash -c`, `python3 -c` or `node -e`: permission rules deny wrapped commands they would allow directly.
+- The same rules hold inside a dynamic Workflow sub-agent.
+
+## Dev server (test.md only)
+
+When a scenario needs the dev server, follow the lifecycle in `devflow:qa/references/browser-testing.md`: start the server in the background, check readiness with one bounded loop inside a single Bash call, and kill the server before you finish. Never end the turn while it runs.
 
 ## Output
 
@@ -139,9 +145,11 @@ One row per TP line, in TP order. PASS only when every scenario covering the TP
 - **Remediation**: {what Code agent should fix}
 
 ### Evidence Log
-{Raw command outputs for traceability}
+{Each command run's `LOG=` path, for traceability}
 ```
 
+Report cap: final message at most about 1,500 tokens; longer material goes to a `mktemp` file via Bash and the message gives its path. Exempt, inline in full: `### Test Plan Evidence` (HEAD line and TP table), the Scenario Results table (`| ID | TP | Type |`) and `### Failed Scenarios`. `### Evidence Log` lists each run's `LOG=` path, never raw output.
+
 ## Principles
 
 1. **User perspective** - Test what the user asked for, not implementation internals

package/src/assets/agents/triage.md

@@ -2,11 +2,17 @@
 name: Triage
 description: Validates review issues against blast-radius disposition matrix. Assigns one verdict per issue. Never edits code.
 model: opus
+effort: high
 skills:
   - devflow:security
   - devflow:worktree-support
   - devflow:apply-decisions
   - devflow:apply-feature-knowledge
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
 ---
 
 # Triage Agent
@@ -145,6 +151,8 @@ Return the verdict ledger grouped by disposition:
 - DUPLICATE: {n}
 ```
 
+Report cap: final message at most about 1,500 tokens; longer material goes to a `mktemp` file via Bash and the message gives its path. Exempt, inline in full: the whole ledger, since `/resolve` checks that every issue id appears in it.
+
 ## Boundaries
 
 **You are TRIAGE ONLY — read and judge, never write:**

package/src/assets/agents/validate.md

@@ -2,9 +2,14 @@
 name: Validate
 description: Dedicated agent for running validation commands (build, typecheck, lint, test). Reports pass/fail with structured failure details - never fixes.
 model: haiku
+effort: medium
 skills:
-  - devflow:testing
   - devflow:worktree-support
+tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
 ---
 
 # Validate Agent
@@ -38,18 +43,20 @@ Execute in this order, stopping on first failure:
 | 3 | Lint | `npm run lint`, `cargo clippy`, `make lint` |
 | 4 | Test | `npm test`, `cargo test`, `make test` |
 
-## Long-running commands (builds/tests that may run >120s)
+**Gate ownership:** Run the full suite once per HEAD. You are the only agent that does.
 
-A plain `Bash` call defaults to a 120s timeout, and inside a dynamic Workflow a sub-agent that emits no output for 180s is KILLED ("agent stalled"). For any build/test that may run silent longer than ~120s (cold `cargo build`/`cargo test`, large `tsc`, `gradle`, `go build ./...`), do NOT run it as one silent foreground command. Instead:
+## Running commands
 
-1. Run it in the BACKGROUND, capturing output + exit code. With the Bash tool set `run_in_background: true` and pick a unique `<slug>` (reuse the same paths in step 2):
-   `<command> > /tmp/df-val-<slug>.log 2>&1; echo "EXIT=$?" > /tmp/df-val-<slug>.done`
-2. Poll with the `Monitor` tool (load it via ToolSearch `select:Monitor` if it is not available): set `persistent: false`, `timeout_ms` above the expected run time (e.g. 600000), and
-   `command: until [ -f /tmp/df-val-<slug>.done ]; do echo running; sleep 25; done; echo DONE; cat /tmp/df-val-<slug>.done`
-   The 25s heartbeat (≪ 180s) is delivered as a notification that keeps you alive past the watchdog.
-3. When the monitor reports `DONE`: the command PASSED iff the `.done` file contains `EXIT=0`. Read the `.log` for failure details to parse.
+Run builds, typechecks, lints and tests in the foreground, each with an explicit Bash `timeout` above its expected run time. The ceiling is 600000 ms, or `BASH_MAX_TIMEOUT_MS` when set (`echo ${BASH_MAX_TIMEOUT_MS:-600000}`).
 
-For a foreground command that merely exceeds the 120s default but stays well under 180s, simply pass an explicit higher `timeout` to the Bash tool (up to 600000ms). Prefer package-scoped commands (`cargo build -p <crate>`, `cargo test -p <crate>`) when the project supports them.
+- Capture, then tail, in one Bash call (shell state does not persist): `LOG=$(mktemp); echo "LOG=$LOG"; <command> >"$LOG" 2>&1; rc=$?; tail -n 40 "$LOG"; echo "EXIT=$rc"`. The printed `EXIT=` value is the result; never decide one from a grep count.
+- Never background a command and wait on it, and never poll across turns: no `sleep` or `true` turns, no sentinel-file checks, no Monitor.
+- Prefer the scoped command for the change (a package, a path or a test file); for the whole set, one workspace-level command over a per-package loop.
+- A run that exceeds its timeout is BLOCKED: report its duration and log path. Do not wait on it, poll it or re-run it.
+- A run expected to exceed the ceiling is split into parts, each under about 90% of it, run in sequence. If it cannot be split, report BLOCKED with the remedy `devflow flags --set bash-max-timeout-ms=<ms>`.
+- Never re-run a command when nothing it reads has changed.
+- Never wrap a build or test command in `sh -c`, `bash -c`, `python3 -c` or `node -e`: permission rules deny wrapped commands they would allow directly.
+- The same rules hold inside a dynamic Workflow sub-agent.
 
 ## Principles
 
@@ -78,7 +85,7 @@ HEAD: {the 40-hex `git rev-parse HEAD`, read before the first command}
 
 ### Failures (if FAIL)
 
-#### typecheck
+#### typecheck (first 30 lines; full output at {log path})
 ```
 src/auth/login.ts:42:15 - error TS2339: Property 'email' does not exist on type 'User'.
 src/auth/login.ts:58:3 - error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
@@ -92,6 +99,8 @@ src/auth/login.ts:58:3 - error TS2345: Argument of type 'string' is not assignab
 {Description of why validation couldn't run - e.g., missing dependencies, broken config}
 ```
 
+Report cap: final message at most about 1,500 tokens; longer material goes to a `mktemp` file via Bash and the message gives its path. Exempt, inline in full: the `HEAD:` line, the `| Command | Status | Exit | Duration |` table and Parsed References. Failure output: at most 30 lines per failing command, then its log path.
+
 ## Boundaries
 
 **Escalate to orchestrator (BLOCKED):**

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

@@ -3,23 +3,23 @@
 
 ORDER IS LOAD-BEARING. Run exactly in this sequence:
 
-1. **Validate agent** — build / typecheck / lint / test
-   - Build/test commands that may run silent for >~120s MUST follow `build_execution_doctrine()` (background Bash + Monitor poll), or they trip the 180s workflow watchdog.
-   - FAIL → Code agent fix (max 2 retries) → re-run Validate agent
-   - If still FAIL after 2 retries → escalate (do not loop endlessly)
-2. **Simplify agent** — reduce complexity, remove duplication
-3. **Scrutinize agent** — 9-pillar self-review (deep structural analysis)
-   - If Scrutinize agent changed code → re-run Validate agent (verify the Scrutinize agent's edits compile/pass)
+1. **Simplify agent** — reduce complexity, remove duplication
+2. **Scrutinize 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 `scrutiny-blocked`; Validate does not run on code Scrutinize 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 Simplify and Scrutinize left, so it covers their commits whether or not Scrutinize changed code
+   - Build/test commands follow `build_execution_doctrine()`: the Validate agent's Running commands block, foreground under an explicit Bash timeout.
+   - FAIL → Code 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)
 
 **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:**
-1. **Gate 1 #1** — immediately after the initial Code agent implementation (inside `implement_bundle()`).
-2. **Gate 1 #2** — the FINAL gate, after ALL Gate-2 fixes AND the entire review pass have completed.
+1. **Gate 1 #1** — immediately after the initial Code agent implementation (inside `implement_bundle()`). An escalated result — Validate exhausted, or Scrutinize 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. Scrutinize 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 "Long-running commands" discipline). The final Gate 1 #2 is the invariant that all written code passes before merge.
+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.
 @end
 
 @define gate2_acceptance():
@@ -29,32 +29,29 @@ Gate 2 fires ONCE: after the implement-bundle and BEFORE the review pass. It doe
 
 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.
 
-**Evaluate agent panel** (only if a plan exists):
-- Run `evaluator_panel()` — see that block for the panel composition
-- If any critical lens returns MISALIGNED: fix-and-continue — the demanded fixes are applied by a Code 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.
+**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 Code 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.
 
 **Test agent** (only if acceptance criteria or a test plan exist):
 - Scenario-based acceptance tests covering functionality, API contracts, performance
 - FAIL → fix-and-continue — a Code agent applies the demanded fixes and self-verifies its own build. The recorded verdict becomes `FAIL-FIXED`; Gate 2 then proceeds. In SINGLE mode the run reports it as `UNVERIFIED`, never PASS.
 
 **When Gate 2 inputs are absent:**
-- No plan → skip Evaluate agent panel silently (note in output: "Gate 2 Evaluate agent skipped — no plan available")
+- 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 panel (§12 — diverse-lens verification)
+### Evaluate agent spawn (one agent, two lenses)
 
-Run 2–3 Evaluate agents with DISTINCT lenses. Diversity not redundancy — each agent asks a different question:
+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 evaluator** — "Does the implementation satisfy each numbered acceptance criterion, INCLUDING the negative criteria (what it must NOT do)?"
-2. **Scope / intent-drift evaluator** — "Did the Code agent smuggle in unplanned changes, deviate from the plan's intent, or introduce anti-features?"
-3. **Cross-ticket-consistency evaluator** — (wave-only; skip for single-ticket runs) "Does this ticket honor the API contracts and invariants that other wave tickets depend on?"
+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?"
 
-Gate = **all-critical-must-pass**: a single critical FAIL from any lens blocks acceptance.
-
-Keep the panel to 2–3 agents. Do not spawn redundant agents asking the same question — that is cost with no diversity benefit.
+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.
 @end
 
 @define implement_bundle():
@@ -63,12 +60,12 @@ Keep the panel to 2–3 agents. Do not spawn redundant agents asking the same qu
 The standard implementation unit for one ticket. Run in order:
 
 ```
-Code(agentType:"Code", prompt: full task + plan + DECISIONS_CONTEXT + handoff if sequential)
+Code(agentType:"Code", prompt: "OPERATION: implement" first line, then full task + plan + DECISIONS_CONTEXT + handoff if sequential)
   → gate1_postcode()
   → gate2_acceptance()   ← Gate 2 runs HERE — before the review pass, not after
 ```
 
-The Code agent prompt must include: task description, implementation plan (if one exists), relevant DECISIONS_CONTEXT (the index you loaded before authoring), the compliance lens (`COMPLIANCE_FRAMEWORKS` — every Code prompt carries it, fix prompts included), and any PRIOR_PHASE_SUMMARY / HANDOFF_FILE for sequential multi-phase tickets.
+Every Code agent prompt opens with `OPERATION: <mode>` as its first line (`implement`, `issue-fix`, `validation-fix`, `alignment-fix` or `qa-fix`). It must include: task description, implementation plan (if one exists), relevant DECISIONS_CONTEXT (the index you loaded before authoring), the compliance lens (`COMPLIANCE_FRAMEWORKS` — every Code prompt carries it, fix prompts included), and any PRIOR_PHASE_SUMMARY / HANDOFF_FILE for sequential multi-phase tickets.
 
 Gate 2 runs at implementation acceptance — this matches devflow's deliberate placement: "evaluation is part of implementation acceptance, not post-review" (§6.1).
 @end
@@ -115,7 +112,7 @@ 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 "Long-running commands" discipline). Do **NOT** run Gate 1 or Gate 2 inside the pass (no Validate agent, no Simplify agent, no Scrutinize 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 — 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 Simplify agent, no Scrutinize 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).
 @end
 
 @define concurrency_doctrine():
@@ -135,42 +132,26 @@ This applies to both: multiple Code agents working on a single ticket AND multi-
 @end
 
 @define build_execution_doctrine():
-### Build execution doctrine — long-running commands (LOAD-BEARING)
-
-The Workflow runtime KILLS any sub-agent that emits no output for 180 seconds. A cold `cargo build`, `cargo test`, a large `tsc`, `gradle build`, `go build ./...`, etc. routinely runs silent far longer and trips this watchdog (the failure reads `agent stalled on all N attempts`). Plain foreground `Bash` also defaults to a 120s timeout.
-
-**RULE: any agent (Validate agent, Code agent, Test agent) running a build / test / compile / install that may run silent for more than ~120s MUST run it in the BACKGROUND and POLL — never as a single silent foreground command.**
-
-Build commands are NEVER wrapped in `sh -c`, `bash -c`, or inline interpreters (`python3 -c`, `node -e`). Invoke commands directly with the step-1 redirect form — permission systems deny wrapper-invoked commands that would be allowed directly.
+### Build execution doctrine — the Running commands block (LOAD-BEARING)
 
-Mechanical procedure (spike-verified — a workflow sub-agent survived a 253s job this way):
+The Validate, Code 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:
 
-0. **Pre-load Monitor:** before launching any background task, load the `Monitor` tool via ToolSearch (`select:Monitor`).
-1. Choose ONE unique base path for this run and reuse it verbatim in steps 1–3, e.g. `BASE=/tmp/df-build-<ticket-slug>`. Launch the command with the Bash tool using `run_in_background: true`:
-   ```
-   <build/test command> > <BASE>.log 2>&1; echo "EXIT=$?" > <BASE>.done
-   ```
-   This returns immediately with a background task id — do NOT block on it.
-2. Arm ONE Monitor that emits a heartbeat well under 180s AND exits when the job finishes:
-   - description: short, e.g. `await <build cmd>`
-   - persistent: false
-   - timeout_ms: comfortably ABOVE the expected job time (e.g. 600000)
-   - command: `until [ -f <BASE>.done ]; do echo building; sleep 25; done; echo BUILD_DONE; cat <BASE>.done`
+Run builds, typechecks, lints and tests in the foreground, each with an explicit Bash `timeout` above its expected run time. The ceiling is 600000 ms, or `BASH_MAX_TIMEOUT_MS` when set (`echo ${BASH_MAX_TIMEOUT_MS:-600000}`).
 
-   The `building` heartbeat every 25s (≪ 180s) is delivered as a notification that re-invokes you, so the watchdog never sees a >180s gap. `BUILD_DONE` + the `EXIT=` line signal completion.
-
-   **Exit-code honesty:** the background task's own exit status is meaningless (the trailing `echo` always exits 0). ALWAYS read the `EXIT=` value written inside `<BASE>.done` — that is the authoritative result.
-
-   **Bounded polling:** arm ONE Monitor then stop acting. On Monitor timeout, re-arm at most 2× (never more than 3 total Monitor calls per build). If the build has not finished after 3 Monitor calls: record the state and escalate — never babysit. A Code agent burned 241k tokens polling one build.
-3. When the monitor reports `BUILD_DONE`: the job PASSES iff `<BASE>.done` contains `EXIT=0`. Read `<BASE>.log` for output/failure detail.
+- Capture, then tail, in one Bash call (shell state does not persist): `LOG=$(mktemp); echo "LOG=$LOG"; <command> >"$LOG" 2>&1; rc=$?; tail -n 40 "$LOG"; echo "EXIT=$rc"`. The printed `EXIT=` value is the result; never decide one from a grep count.
+- Never background a command and wait on it, and never poll across turns: no `sleep` or `true` turns, no sentinel-file checks, no Monitor.
+- Prefer the scoped command for the change (a package, a path or a test file); for the whole set, one workspace-level command over a per-package loop.
+- A run that exceeds its timeout is BLOCKED: report its duration and log path. Do not wait on it, poll it or re-run it.
+- A run expected to exceed the ceiling is split into parts, each under about 90% of it, run in sequence. If it cannot be split, report BLOCKED with the remedy `devflow flags --set bash-max-timeout-ms=<ms>`.
+- Never re-run a command when nothing it reads has changed.
+- Never wrap a build or test command in `sh -c`, `bash -c`, `python3 -c` or `node -e`: permission rules deny wrapped commands they would 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.
 
-**Scope commands to stay short.** During the engine, PREFER crate/package-scoped builds and tests — `cargo build -p <crate>`, `cargo test -p <crate>`, `npm test -- <path>`, `go test ./pkg/...` — over the whole workspace. The full-workspace regression is the human's job after the wave (the wave already hands the integrated branch back to the user). Scoping keeps most commands under the watchdog window and under budget.
-
-**Invariants:** heartbeat interval MUST stay well under 180s (25–30s is the tested value); Monitor `timeout_ms` MUST exceed the expected job duration (a too-short timeout kills the poll, not the build). Never substitute a single silent long command for this procedure.
+**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).
 @end
 
 @define engine_output_schema():
@@ -210,7 +191,7 @@ Each ticket engine run returns a structured result. The Synthesize agent or the
   },
   "escalations": [
     {
-      "type": "merge-conflict | gate2-fail | validation-exhausted | ambiguous-resolution | review-coverage-incomplete | dependency-blocked | engine-crash | ticket-link-missing | branch-missing",
+      "type": "merge-conflict | gate2-fail | validation-exhausted | scrutiny-blocked | ambiguous-resolution | review-coverage-incomplete | dependency-blocked | engine-crash | ticket-link-missing | branch-missing",
       "description": "string"
     }
   ],
@@ -228,7 +209,7 @@ Each ticket engine run returns a structured result. The Synthesize agent or the
 
 1. **Code is written ONLY by Code agents.** 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 Validate agent + Simplify agent + Scrutinize agent (in that order).
+3. **All written code passes Gate 1.** No code merge, commit, or handoff before Simplify agent + Scrutinize 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.
 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.

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

@@ -69,7 +69,7 @@ If the settings line says `KNOWLEDGE=off`, skip write-back entirely. The machine
 **Step 2 — Evaluate whether write-back is warranted:**
 
 Only proceed if **at least one** of these is true:
-- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed).
+- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed). Knowledge bases are written through at that point, never on a background schedule.
 - This workflow surfaced durable, cross-cutting knowledge about a codebase area that would help future agents working in the same area — patterns, anti-patterns, integration points, gotchas not visible from a single file read.
 
 **Never spawn unconditionally.** If neither condition is met, skip write-back silently.
@@ -86,8 +86,6 @@ DIRECTORIES: {list of primary directories touched by this workflow}
 FILES_CHANGED: {list of files changed}
 DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
 
-Load the devflow:feature-knowledge skill and follow its authoring process.
-
 Write the knowledge base to:
   {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
 

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

@@ -46,7 +46,7 @@ Every line of a `## Test Plan` section, or of a PR's test-plan block, follows th
 
 #### Consumption by Gate 2
 
-The Evaluate agent panel receives: the per-ticket plan + the numbered acceptance criteria (positive and negative).
+The Evaluate agent receives: the per-ticket plan + the numbered acceptance criteria (positive and negative).
 
 The Test agent receives: the test plan's TP lines, once `check tp` has admitted them.
 

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

@@ -1,5 +1,5 @@
 @define issue_ref_grammar():
-**Issue-reference grammar (L1 — command layer, permissive and provider-blind):** scan `$ARGUMENTS` for candidate issue references — a `#`-prefixed token and a bare digit run are both candidates — and collect them in source order as the raw token list `ISSUE_REFS`. Forward that list to the Git agent **verbatim**: the command never renders, normalises, pads, strips or coerces a token, and never rules a candidate out. Under `github` a token matching `^#?[1-9][0-9]{0,8}$` **is** a reference and the Git agent renders it as `#{n}`.
+**Issue-reference grammar (L1 — command layer, permissive and provider-blind):** scan `COMMAND_INPUT` for candidate issue references — a `#`-prefixed token and a bare digit run are both candidates — and collect them in source order as the raw token list `ISSUE_REFS`. Forward that list to the Git agent **verbatim**: the command never renders, normalises, pads, strips or coerces a token, and never rules a candidate out. Under `github` a token matching `^#?[1-9][0-9]{0,8}$` **is** a reference and the Git agent renders it as `#{n}`.
 
 **A token of any other shape is neither coerced nor dropped silently — and no producer-side grammar check rejects it before the fetch.** Adjudication belongs to the operation that runs, and each one answers in its own Output block: `fetch-issue` strips a leading `#` and takes the text branch, so a non-numeric token is used as a **search term** and the operation returns the first open match or nothing; `fetch-issues-batch` resolves each token to an issue number, drops the ones it cannot resolve, and names them in `NOT_FOUND ({refs})` beside the issues it did fetch. Read the outcome from the operation that ran — a token's shape is a verdict nowhere, and there is nothing upstream holding it back.
 

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

@@ -40,8 +40,8 @@ For each ready ticket (sequentially by default; parallel only past the §7.1 bar
 - Branch setup: the engine's setup-task creates the ticket's branch off integration HEAD at ready-time (so it already contains merged deps); every later phase, and the merge, uses the branch setup-task created, and a setup-task that reports none stops the ticket before implementing
 - Run the single-ticket engine inside a try/catch — one ticket's crash/stall never kills the wave; catch the exception, quarantine that ticket, and continue with the remaining ready set
 - The engine gets the ticket's own reference, the one the pre-fetch printed, as its setup-task input — never the wave's tracking issue
-- On engine PASS or UNVERIFIED: merge to integration branch, run Validate agent (build + test)
-  - Merge FAIL (build red after merge): quarantine ticket, mark as escalated, continue
+- On engine PASS or UNVERIFIED: merge to the integration branch locally through Git (no push, no build or test), then the workflow spawns the Validate agent (build + test) over the merge. The merge counts as kept only when that Validate returns PASS
+  - Validate FAIL or no PASS (build red after merge): the workflow spawns Git to undo the merge, quarantines the ticket, marks it as escalated, and continues. If the undo is refused, the wave stops taking merges and rounds
 - On any other verdict (PARTIAL, FAIL, ESCALATED) or none: quarantine ticket, do not block independent siblings
 
 **Cascade quarantine:** when a ticket is quarantined for any reason (Gate-1 exhausted, engine crash/stall, build-red after merge, review coverage incomplete after retry), the quarantine cascades to its direct and transitive dependents — each is marked blocked with the named reason, naming the blocker by its `{ISSUE_REF}` (e.g. "blocked: depends on {ISSUE_REF} which failed Gate-1"). Independent siblings are never affected. The quarantined list is injected into every subsequent Design agent reader prompt so the reader never schedules dependents of failed tickets.
@@ -70,7 +70,9 @@ MAX_ROUNDS = LLM judgment based on ticket count (heuristic: ticket_count * 2 + 5
 
 **Parallel independent tickets:** each gets its own `git worktree add` + durable branch managed by the Git agent. Use explicit `git worktree add` — NOT the Workflow tool's ephemeral `isolation:'worktree'`. The branch must persist across implement → review → resolve → merge stages; ephemeral worktrees are gone when the agent call ends.
 
-**Post-merge validation:** after EVERY merge into the integration branch, run Validate agent (build + test). A red build immediately after merge is the cheapest possible conflict detector. Red → quarantine the merged result + escalate.
+**Post-merge validation:** after EVERY merge into the integration branch, the workflow itself spawns the Validate agent (build + test) over the integration branch; Git runs no build or test. A red build immediately after merge is the cheapest possible conflict detector. It always runs — the merge reports `treeEqual` (whether the merge commit's tree equals the ticket branch head's tree) and the wave row records it, but a true value never skips the Validate.
+
+**Undo of a red merge:** on FAIL or no PASS verdict the workflow spawns Git to undo the merge. The undo runs only when no remote branch contains the merge commit and the integration HEAD still equals it, as `git reset --keep {mergeSha}^1` on the integration branch — never `--hard`, never a push. It returns `{"undone": true}` or `{"undone": false, "reason": "..."}`. Undone → the row reads `merged: false` and the ticket is quarantined ("post-merge build red; merge undone"). Not undone → the wave stops taking merges and rounds, and its report names the red integration HEAD.
 
 **Commit discipline:** Git agent creates atomic commits per logical change, conventional-commit format, on the ticket branch before merge.
 @end
@@ -83,13 +85,13 @@ Two parallel sibling tickets can produce real git conflicts. The resolution is *
 **Resolution procedure:**
 
 1. Git agent detects the conflict and reports the conflicting files + sections
-2. Spawn a Code agent with FULL intent context:
+2. Spawn a Code agent whose prompt opens with `OPERATION: implement` and carries `COMPLIANCE_FRAMEWORKS`, with FULL intent context:
    - Both ticket descriptions and plans
    - The conflicting diff sections (both sides)
    - Relevant ADRs from DECISIONS_CONTEXT (loaded by main model before authoring)
 3. Code agent resolves to PRESERVE BOTH INTENTS — the resolution must honor what both tickets were trying to achieve
 4. If the correct resolution is NOT UNAMBIGUOUS from the intent context: **do NOT guess** → quarantine + escalate
-5. After any resolution: Validate agent (build + test) immediately
+5. After any resolution: the post-merge Validate covers it — the workflow spawns it after the merge, and no Validate is requested from Git
 
 **Conservative-or-escalate is absolute.** An LLM silently guessing a wrong merge is the highest-danger failure mode in the whole design. When in doubt: quarantine + surface in report. The user re-runs (resume) with the escalated context.
 
@@ -106,7 +108,7 @@ A workflow cannot pause mid-run (F4). "Escalate" means: quarantine-and-continue
 - Ticket engine FAIL after max retries (Gate 1 exhausted)
 - Gate 2 FAIL after max retries (Evaluate agent/Test agent not satisfied)
 - Circular dependency detected (all remaining tickets blocked on each other)
-- Build red after merge (Validate agent fails post-merge)
+- Build red after merge (the post-merge Validate agent fails: the merge is undone and the ticket quarantined; a refused undo halts the wave)
 - Review coverage incomplete after retry (a focus area failed to produce a live Review agent result after the retry)
 - Ticket engine crash/stall (unrecoverable exception or watchdog kill — quarantine cascades to dependents)
 - No ticket link while issues are required (the engine stops before implementing)

package/src/assets/commands/code-review.mds

@@ -30,7 +30,7 @@ Run a comprehensive code review of the current branch by spawning parallel revie
 
 1. **Discover reviewable worktrees** using the `devflow:worktree-support` skill discovery algorithm:
    - Run `git worktree list --porcelain` → parse, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
-   - See the `devflow:worktree-support` skill for the full 7-step algorithm and canonical protected branch list
+   - Invoke the `devflow:worktree-support` skill, then Read its `references/discovery.md` from the skill's base directory for the full 7-step algorithm; the canonical protected branch list stays in the skill
 2. **If `--path` flag provided:** use only that worktree, skip discovery
    **`--path` validation**: Before proceeding, verify the path exists as a directory and appears in `git worktree list` output. If not: report error and stop.
 3. **If only 1 reviewable worktree** (the common case): proceed as single-worktree flow — zero behavior change
@@ -198,8 +198,6 @@ Only `exit=0` means the skill is installed. On any other result, do NOT add that
 
 **Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, COMPLIANCE_FRAMEWORKS (carried from Step 0b)
 
-**Load Companion Skills** — Load via Skill tool: `devflow:quality-gates`, `devflow:software-design`. If a skill fails to load, continue without it.
-
 {{decisions_load()}}
 
 This produces a compact index of active ADR/PF entries. Pass `DECISIONS_CONTEXT` to all Review agents. Review agents use `devflow:apply-decisions` to Read full entry bodies on demand.