devflow-kit 3.6.0 → 3.7.0

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

@@ -35,17 +35,17 @@ Run a comprehensive code review of the current branch by spawning parallel revie
    - **Exactly one listed:** load neither the skill nor the reference — that worktree is the only candidate, and Step 0c's Git agent validates its branch
 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
+3. **If only 1 reviewable worktree**: proceed as single-worktree flow — zero behavior change
 4. **If multiple reviewable worktrees:** report "Found N worktrees with reviewable branches: {list with paths and branches}" and proceed with multi-worktree flow
 
-#### Step 0b: Resolve the compliance lens
+#### Step 0b: Resolve the compliance lens and gate level
 
-**Produces:** COMPLIANCE_ACTIVE, COMPLIANCE_FRAMEWORKS
+**Produces:** COMPLIANCE_ACTIVE, COMPLIANCE_FRAMEWORKS, GATE_LEVEL
 
 {{settings.settings_resolve()}}
 
 {{compliance_gate()}}
-Keep each worktree's values for every downstream phase of that worktree.
+Keep each worktree's values for every downstream phase.
 
 #### Step 0b-ii: Resolve the evidence policy
 
@@ -87,7 +87,7 @@ Validate branch, commit if needed, push, create PR if needed.
 Return: branch, base_branch, branch-slug, PR#"
 ```
 
-In multi-worktree mode, spawn all pre-flight agents **in a single message** (parallel).
+In multi-worktree mode, spawn all pre-flight agents **in a single message**.
 
 **If BLOCKED:** In single-worktree mode, stop and report. In multi-worktree mode, report the failure but continue with other worktrees.
 
@@ -127,7 +127,7 @@ For each worktree, perform a single pass over timestamped directories:
 2. Iterate once: accumulate CYCLE_NUMBER count for each directory containing `resolution-summary.md`; capture the first (most-recent) such directory as PRIOR_DIR.
 3. If CYCLE_NUMBER = 0: set PRIOR_RESOLUTIONS=(none), CYCLE_NUMBER=1, proceed.
 4. Otherwise: set CYCLE_NUMBER = count + 1. Read `{PRIOR_DIR}/resolution-summary.md` as PRIOR_RESOLUTIONS.
-5. If `--full`: still load PRIOR_RESOLUTIONS (valuable for Review agent cross-cycle awareness).
+5. If `--full`: still load PRIOR_RESOLUTIONS.
 
 #### Step 0e-ii: Convergence Assessment
 
@@ -169,7 +169,7 @@ For each reviewable worktree, call:
 ### Phase 1: Analyze Changed Files
 
 **Produces:** REVIEW_FOCUS_LIST, DIFF_CLASS, DIFF_FILES
-**Requires:** DIFF_RANGE, REVIEW_DIR, COMPLIANCE_ACTIVE (from Step 0b)
+**Requires:** DIFF_RANGE, REVIEW_DIR, COMPLIANCE_ACTIVE, GATE_LEVEL (from Step 0b)
 
 Per worktree, in order. Each `git` command here writes to a file and prints nothing.
 
@@ -185,7 +185,7 @@ git -C "{WORKTREE_PATH}" diff --name-only --no-renames {DIFF_RANGE} > "{REVIEW_D
 wc -l < "{REVIEW_DIR}/paths.txt"
 ```
 
-Read `paths.txt` once when the count is about 40 or fewer, and in ranges of about 40 lines (Read with offset and limit) when it is more. `--no-renames` lists a moved file under its old path and its new one, so a move cannot take a file out of its own class.
+Read `paths.txt` once when the count is about 40 or fewer, and in ranges of about 40 lines (Read with offset and limit) when it is more.
 
 Set `DIFF_CLASS` by these rules, in order; the first that decides wins:
 
@@ -202,7 +202,7 @@ Each reduced class runs only its focus set, every member reading `diff.patch`:
 - `tests-only`: testing, reliability, consistency, security
 - `lockfile-only`: dependencies, security
 
-A mixed non-code diff runs the union of the sets of the classes it holds. Language and conditional triggers inside a reduced class are suppressed: they add no focus, and Step 1.2 applies to the `code` class only.
+A mixed non-code diff runs the union of the sets of the classes it holds. Language and conditional triggers inside a reduced class are suppressed.
 
 #### Step 1.2: Choose the focuses
 
@@ -226,13 +226,27 @@ When `DIFF_CLASS` is `code`, read the file types from the paths in `paths.txt` t
 | Docs or significant code | documentation |
 | COMPLIANCE_ACTIVE AND diff touches regulated surface | compliance |
 
-If `COMPLIANCE_ACTIVE` AND the diff touches regulated surface (data models, auth flows, logging/observability, payments, IaC, retention): add `compliance` to REVIEW_FOCUS_LIST for this worktree.
+If `COMPLIANCE_ACTIVE` AND the diff touches regulated surface (data models, auth flows, logging/observability, payments, IaC, retention): on a `code` diff, add `compliance`.
 
 **Language focus stamp.** The eight language focuses — `typescript`, `react`, `accessibility`, `ui-design`, `go`, `java`, `python`, `rust` — ship with optional plugins, and the installer stamps the ones installed on this machine onto this line, rewriting it on every install and on `uninstall --plugin`:
 
 Installed language focuses: (none)
 
-A language focus is spawned only when its file-type condition above fires AND its name appears in that stamped line. A focus missing from the line is never spawned, even when its trigger fires. The eight core focuses are unconditional and are never stamp-gated.
+A language focus is spawned only when its file-type condition above fires AND its name appears in that stamped line. A focus missing from the line is never spawned, even when its trigger fires. On a `code` diff, REVIEW_FOCUS_LIST starts with the eight core focuses. Step 1.2b may narrow them; they are never stamp-gated.
+
+#### Step 1.2b: Narrow by gate level
+
+**Produces:** REVIEW_FOCUS_LIST, GATE_LEVEL
+**Requires:** REVIEW_FOCUS_LIST, DIFF_CLASS, CHANGED_PATHS, GATE_LEVEL
+
+**Gate level.** Narrow REVIEW_FOCUS_LIST, for every class, by this worktree's `GATE_LEVEL`. `full` keeps it and reads nothing.
+
+At `standard` or `lean`, once per run, run `d="${CLAUDE_CONFIG_DIR:-}"; case "$d" in /*) ;; *) d="$HOME/.claude" ;; esac; printf '%s\n' "$d"` in Bash and Read `<that directory>/skills/devflow:agent-references/references/commands/code-review-levels.md` with the Read tool.
+
+- Apply each class's row to that class's own set, then take the union of the results. A row only removes focuses.
+- If the Read fails, or a row is missing or malformed, set `GATE_LEVEL` to `full` for every worktree of this run and say `level reference unreadable: full sets applied`.
+- Security runs at every level and in every class.
+- Compliance keeps the trigger above at every level.
 
 #### Step 1.3: Write the diff files
 
@@ -297,9 +311,9 @@ Pass `FEATURE_KNOWLEDGE` to all Review agents.
 **Requires:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP, FEATURE_KNOWLEDGE, PR_DESCRIPTION, PRIOR_RESOLUTIONS, REVIEW_FOCUS_LIST, DIFF_CLASS, DIFF_FILES
 <!-- learning:end -->
 
-Spawn Review agents **in a single message**, for the focus set `DIFF_CLASS` selects (max 20 per worktree):
+Spawn Review agents **in a single message**, one per focus in REVIEW_FOCUS_LIST (max 20 per worktree):
 
-- `code`: the 8 core reviews on the full `diff.patch`, plus the language and conditional focuses Phase 1 added.
+- `code`: the 8 core reviews on the full `diff.patch` (lean keeps 3), plus the language and conditional focuses Phase 1 added.
 - `docs-only`, `tests-only`, `lockfile-only`: only the reduced set Phase 1 names, each reading `diff.patch`; a mixed non-code diff runs the union. No language or conditional focus is spawned, whatever its trigger.
 
 | Focus | Runs | Pattern Skill | DIFF_FILE |
@@ -325,7 +339,7 @@ Spawn Review agents **in a single message**, for the focus set `DIFF_CLASS` sele
 | documentation | conditional | devflow:documentation | diff.patch |
 | compliance | diff-driven | devflow:compliance | diff.patch |
 
-Review agent count: `code` runs 8 core, +1-12 added by Phase 1 (max 20 total per worktree); a reduced class or a mix runs 2-6.
+Review agent count: at `full`, `code` runs 8 core +1-12; `standard` runs up to 2 fewer; lean `code` runs 3-4; a reduced class or a mix runs 2-6.
 
 {{compliance_focus_inject()}}
 
@@ -353,16 +367,16 @@ Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE — feature-specifi
 IMPORTANT: Write report to {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}/{focus}.md using Write tool"
 ```
 
-In multi-worktree mode, process worktrees **sequentially** (one worktree at a time). Complete Phases 1-4 for each worktree before starting the next. This prevents agent overload — spawning 8-20 Review agents per worktree across multiple worktrees simultaneously overwhelms the system.
+In multi-worktree mode, process worktrees **sequentially**: complete Phases 1-4 for one worktree before starting the next, so Review spawns never pile up.
 
 ### Phase 3: Synthesis → Review Comment (Sequential)
 
 **Produces:** REVIEW_SUMMARY, PR_COMMENT
-**Requires:** REVIEW_FOCUS_OUTPUTS, REVIEW_DIR, PR_INFO
+**Requires:** REVIEW_FOCUS_OUTPUTS, REVIEW_DIR, PR_INFO, GATE_LEVEL, REVIEW_FOCUS_LIST
 
 **WAIT** for Phase 2. For each worktree, run steps 3a and 3b in sequence:
 
-**Step 3a — Synthesize agent** per worktree (wait for completion before 3b):
+**Step 3a — Synthesize agent** per worktree:
 ```
 Agent(subagent_type="Synthesize", run_in_background=false):
 "Mode: review
@@ -370,6 +384,8 @@ WORKTREE_PATH: {worktree_path}  (omit if cwd)
 REVIEW_BASE_DIR: {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}
 TIMESTAMP: {timestamp}
 CYCLE_NUMBER: {cycle_number}
+GATE_LEVEL: {GATE_LEVEL}
+FOCUSES: {REVIEW_FOCUS_LIST}
 PRIOR_RESOLUTIONS: <prior-resolution-summary>{prior_resolutions}</prior-resolution-summary>
 Include Convergence Status section in review-summary.md.
 Aggregate findings, determine merge recommendation.
@@ -402,8 +418,6 @@ Per worktree, after successful completion:
    - Publication status: FULL (private repo) | FULL (config override) | STUB (public repository) | OFF (publication disabled by config) | STUB (visibility undeterminable) | STUB (evidence policy) (from Git agent)
    - Artifact paths
 
-In multi-worktree mode, report results per worktree.
-
 ## Architecture
 
 ```
@@ -411,29 +425,27 @@ In multi-worktree mode, report results per worktree.
 │
 ├─ Phase 0: Worktree Discovery & Pre-flight
 │  ├─ Step 0a: git worktree list → filter reviewable
-│  ├─ Step 0b: Resolve the compliance lens
+│  ├─ Step 0b: Resolve the compliance lens and gate level
 │  ├─ Step 0c: Git agent (ensure-pr-ready) per worktree [parallel]
 │  ├─ Step 0d: Incremental detection + timestamp setup per worktree
 │  ├─ Step 0e-i: Load prior resolution-summary.md
-│  ├─ Step 0e-ii: Convergence assessment (warn if FP ratio > 70%)
+│  ├─ Step 0e-ii: Convergence assessment (warn only)
 │  └─ Step 0f: Resolve REVIEW_PUBLICATION per worktree (publication gate)
 │
 ├─ Per worktree (SEQUENTIAL — one worktree at a time):
 │  │
 │  ├─ Phase 1: Analyze changed files
 │  │  ├─ Classify the diff (paths.txt → DIFF_CLASS)
-│  │  ├─ Choose the focuses (code class: file types + the language stamp)
+│  │  ├─ Choose the focuses (code: file types + the language stamp; all: the gate level)
 │  │  └─ Write diff.patch and diff-{focus}.patch, by redirect
 │  │
-│  ├─ Phase 2: Reviews (PARALLEL within worktree)
-│  │  ├─ code: Review agents security, architecture, performance, complexity,
-│  │  │        consistency, regression, testing, reliability (diff.patch)
-│  │  ├─ code: + language (diff-{focus}.patch) and conditional Review agents
+│  ├─ Phase 2: Reviews (PARALLEL within worktree), one per REVIEW_FOCUS_LIST focus
+│  │  ├─ code: core (diff.patch), language (diff-{focus}.patch), conditional
 │  │  └─ docs-only / tests-only / lockfile-only: the reduced set (diff.patch)
 │  │
 │  ├─ Phase 3: Synthesis → Review Comment (SEQUENTIAL within worktree)
 │  │  ├─ Step 3a: Synthesize agent (mode: review, writes review-summary.md)
-│  │  └─ Step 3b: Git agent (post-review-summary, D7 marker-dedup, REVIEW_PUBLICATION)
+│  │  └─ Step 3b: Git agent (post-review-summary)
 │  │
 │  └─ Phase 4: Write .last-review-head + display results
 ```
@@ -442,31 +454,27 @@ In multi-worktree mode, report results per worktree.
 
 | Case | Handling |
 |------|----------|
-| `--full` in multi-worktree mode | Applies to all worktrees (global modifier) |
+| `--full` in multi-worktree mode | Applies to all worktrees (global modifier). It sets the diff range, never the gate level |
 | Review comment already posted | Git agent matches its own marker on the `{cycle, timestamp}` pair → skip silently (D7); a re-review in the same cycle (different timestamp) posts its own comment. The marker's format belongs to the operation; this caller passes the pair and never restates the literal |
-| Concurrent sessions | Advisory only, each session computes independently |
-| Docs-only diff | `docs-only`: documentation, consistency, security on `diff.patch`; no language or conditional focus |
-| Tests-only diff | `tests-only`: testing, reliability, consistency, security on `diff.patch`; no language or conditional focus |
-| Lockfile-only diff | `lockfile-only`: dependencies, security on `diff.patch` |
-| Mixed non-code diff (docs with tests, tests with a lockfile) | The union of the matching sets, on `diff.patch` |
-| A path matching no class pattern, or an empty path list | `code` (fail-safe): the 8 core focuses on the full diff |
-| A file moved across classes | `--no-renames` lists the old and the new path, so a code path makes the diff `code` |
-| Path listing above about 40 lines | The count is printed; `paths.txt` is read in ranges of about 40 lines |
+| Docs-only diff | Its Step 1.1 set, narrowed by level |
+| Tests-only diff | Its Step 1.1 set, narrowed by level |
+| Lockfile-only diff | Its Step 1.1 set, narrowed by level |
+| Mixed non-code diff | The union of the matching sets |
+| A path matching no class pattern, or an empty path list | `code` (fail-safe) |
+| A file moved across classes | `--no-renames` lists both paths, so a code path makes the diff `code` |
+| Path listing above about 40 lines | Read in ranges (Step 1.1) |
 | Language files changed, plugin not installed | The focus is absent from the stamped line: not spawned |
 | Public repo (`auto` mode) | Git agent probes visibility, posts counts-only STUB comment; full report stays local |
 | `reviewPublication: off` | Git agent skips posting the review comment (OFF) — except that, only when `EVIDENCE_POLICY` is `required`, Step 0f passes `stub` and a counts-only STUB comment posts |
 
 ## Backwards Compatibility
 
-- **Single worktree**: Auto-discovery finds only one worktree → proceeds exactly as before. Zero behavior change.
-- **Legacy flat layout**: If `{worktree}/.devflow/docs/reviews/{branch-slug}/` contains flat `*.md` files (no timestamped subdirectories), new runs create timestamped subdirectories. Old flat files remain untouched.
+- **Gate level**: `full` runs the sets named here; the default `standard` and `lean` narrow them. `devflow gates --set full` keeps them.
 
 ## Principles
 
 1. **Orchestration only** - Command spawns agents, doesn't do git/review work itself. The exceptions are the read-only Phase 0 probes (`git worktree list`, `git -C ... branch --show-current`, `git -C ... cat-file -t`), the bounded Phase 1 path listing (a redirect into `paths.txt`, a `wc -l` count and ranged reads) and the redirect-only patch writes (`diff.patch`, `diff-{focus}.patch`). Redirect-only writes print nothing, so no diff content reaches this thread
 2. **Parallel, not background** - Multiple agents in one message, but `run_in_background=false` so phases complete before proceeding
 3. **Git agent for git work** - All git operations go through Git agent, except the exceptions named in Principle 1; redirect-only writes print nothing
-4. **Clear ownership** - Each agent owns its output completely
-5. **Honest reporting** - Display agent outputs directly
-6. **Incremental by default** - Only review new changes unless `--full` specified
-7. **Auto-discover worktrees** - One command handles all reviewable branches
+4. **Honest reporting** - Display agent outputs directly
+5. **Incremental by default** - Only review new changes unless `--full` specified

package/src/assets/commands/dynamic-build.mds

@@ -575,22 +575,49 @@ When WAVE mode is detected, author a workflow that wraps the single-ticket engin
 
 **Wave workflow structure (author after the SINGLE engine blocks above):**
 
-The wave workflow uses the same phases as SINGLE but wraps them in a wave loop. The integration branch is `wave/<initiative>` — the initiative slug, referenced below as `{slug}` — (or the user's current branch). Each ticket works on the branch setup-task created. The Git agent manages worktrees for parallel-eligible tickets. After every merge the workflow spawns the Validate agent (build + test) and undoes a red merge. Escalations accumulate in a list; the final report lists all of them.
+The wave workflow uses the same phases as SINGLE but wraps them in a wave loop. The integration branch is `wave/<initiative>` — the initiative slug, referenced below as `{slug}` — (or the user's current branch).
 
 Wave skeleton — compact reference (see `wave_loop()` doctrine for full semantics):
 
 ```js
-// Wave round loop: Design agent reader → per-ticket try/catch → cascade quarantine via next reader
 // runSingleTicketEngine(args) is the SINGLE skeleton above as a function of its OWN args: the wave's
 // args.issueNumber (the tracking issue, Pre-authoring step 5) is never in its scope.
 const WAVE_TICKETS = [...remainingTickets];  // the pre-fetch's refs, in input order — the wave block's row order
-const results = {};  // ticketId → its row of the workflow's return; a ticket with no entry never ran
+const results = {};  // ticketId → its row of the workflow's return
 // A row from an engine result: the fields step 3 after the workflow renders
 const rowOf = (ticketId, r, merged, treeEqual = null) => ({ ticket: ticketId, ran: true, verdict: r?.verdict || r?.overallVerdict || null, merged, treeEqual, issuePrLink: r?.issuePrLink || "(none)", evaluateVerdict: r?.gate2?.evaluateVerdict, testVerdict: r?.gate2?.testVerdict, surviving: r?.survivingFindings?.length, coverageComplete: r?.reviewCoverage?.complete });
 const MAX_ROUNDS = Math.max(10, remainingTickets.length * 2 + 5);  // heuristic; always finite
-const MERGE_SHA = /^[0-9a-f]{40}$/;  // a merge commit as git prints it: the only Git-reported value that reaches a later prompt
+const MERGE_SHA = /^[0-9a-f]{40}$/;  // a SHA as git prints it; with the checked branch, the only Git-reported values that reach a merge, Validate or undo prompt
+const BRANCH_NAME = /^(?![-#]|(?:@|(?:FETCH_|ORIG_|MERGE_)?HEAD)$)(?!.*\.\.)[A-Za-z0-9._/+@,#-]{1,200}$/;  // implement's ref allowlist; no leading - or #, no revision name, no ..: the name enters git lines
+// One ticket's merge, post-merge Validate and undo (D-WAVE-MERGE-VALIDATE: Git validates nothing).
+const mergeValidateUndo = async (ticketId, engineResult) => {
+  if (typeof engineResult.branch !== "string" || !BRANCH_NAME.test(engineResult.branch)) return { kept: false, reason: "ticket branch name refused: not a plain git ref name", halted: null, treeEqual: null };
+  const merge = await agent(`Merge ${engineResult.branch} to ${INTEGRATION_BRANCH} locally. Include ticket ID ${ticketId} in the merge commit message. Do not push, and run no build or test.
+Check out ${INTEGRATION_BRANCH}, run git rev-parse ${INTEGRATION_BRANCH} as baseSha, run git rev-parse --verify --quiet refs/heads/${engineResult.branch} (on a non-zero exit return merged false, reason "no such local branch"), then run git merge --no-ff refs/heads/${engineResult.branch}. If the merge stops after it began (git rev-parse -q --verify MERGE_HEAD succeeds), run git merge --abort; if that abort fails, return merged true with no mergeSha. A merge that did not begin returns merged false with the reason.
+Return: {"merged": true, "mergeSha": "<40-hex merge commit>", "treeEqual": <true when mergeSha^{tree} equals the tree of ${engineResult.branch}'s head>, "baseSha": "<40-hex integration HEAD before the merge>"} — or {"merged": false, "reason": "<why>"} when no merge is kept.`, { agentType: "Git" });
+  const treeEqual = merge?.merged === true && typeof merge.treeEqual === "boolean" ? merge.treeEqual : null;
+  const done = (kept, reason, halted = null) => ({ kept, reason, halted, treeEqual });
+  if (merge?.merged !== true) return done(false, merge?.reason || "merge failed");
+  const badSha = ![merge.mergeSha, merge.baseSha].every(v => MERGE_SHA.test(String(v)));
+  if (badSha || merge.mergeSha === merge.baseSha) {
+    // No usable SHA, or no commit added: stop taking merges. Fixed reasons; no rejected value is copied.
+    const reason = badSha ? "merge reported without a 40-hex mergeSha or baseSha; the integration branch may hold an unvalidated merge" : "merge added no commit, so the wave stopped: an unchanged HEAD cannot be checked. Check that the ticket branch holds its commits, then run the wave again.";
+    return done(false, reason, { ticket: ticketId, mergeSha: null, baseSha: null, reason, kind: badSha ? "bad-sha" : "unchanged" });
+  }
+  const post = await agent(`Run build, typecheck, lint, and tests on ${INTEGRATION_BRANCH} after merging ${engineResult.branch} (merge commit ${merge.mergeSha}).
+Follow your Running commands block for every build and test command.
+Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate" });
+  if (post?.verdict === "PASS") {
+    return done(true, "");
+  }
+  const undo = await agent(`Undo the merge ${merge.mergeSha} on ${INTEGRATION_BRANCH}, only when no remote branch contains ${merge.mergeSha}. Run these read-only checks in order; a non-zero exit or a different value means not undone: git symbolic-ref --short HEAD must print ${INTEGRATION_BRANCH}; git rev-parse refs/heads/${INTEGRATION_BRANCH} must print ${merge.mergeSha}; git rev-parse ${merge.mergeSha}^1 must print ${merge.baseSha}. Then run exactly this one command and no other that changes a branch or a remote: git reset --keep ${merge.baseSha}
+Return: {"undone": true, "head": "<40-hex from git rev-parse refs/heads/${INTEGRATION_BRANCH}>"} — or {"undone": false, "reason": "<why>"} when you did not undo it.`, { agentType: "Git" });
+  if (undo?.undone === true && undo.head === merge.baseSha) return done(false, "post-merge build red; merge undone");
+  const reason = `post-merge build red; merge not undone (${undo?.undone === true ? "undo reported a head other than the recorded pre-merge SHA" : undo?.reason || "no reason given"})`;
+  return done(false, reason, { ticket: ticketId, mergeSha: merge.mergeSha, baseSha: merge.baseSha, reason, kind: "red" });
+};
 const waveState = { quarantined: [], round: 0, halted: null };
-let reAskedThisDeadlock = false;  // re-ask guard: re-ask once on empty ready-set, then escalate
+let reAskedThisDeadlock = false;
 while (remainingTickets.length > 0 && waveState.round < MAX_ROUNDS && waveState.halted === null) {
   waveState.round++;
 
@@ -614,56 +641,28 @@ Return: {"ready": [...ticket-ids], "blocked": [{"ticket": "id", "namedBlocker":
     reAskedThisDeadlock = true;      // re-ask once with vacuous-truth rule quoted verbatim
     continue;
   }
-  reAskedThisDeadlock = false;  // reset on a non-empty ready set
+  reAskedThisDeadlock = false;
 
   for (const ticketId of ready) {
     try {
-      // ticketId is the ISSUE_REF the pre-fetch heading printed — this ticket's OWN reference: the engine's `ticket` (its TICKET)
-      // and its setup-task ISSUE_INPUT; the engine returns the branch that setup-task created, merged below; plans[ticketId] is its own plan, criteria and checked testPlan (Pre-authoring step 4)
+      // ticketId is this ticket's OWN ISSUE_REF (pre-fetch heading): the engine's `ticket` and setup-task ISSUE_INPUT; the engine returns the branch setup-task created, merged below; plans[ticketId] is its own plan (Pre-authoring step 4)
 <!-- learning:on -->
       const engineResult = await runSingleTicketEngine({ ticket: ticketId, baseBranch: INTEGRATION_BRANCH, ...(plans[ticketId] || {}), decisionsContext: DECISIONS_CONTEXT, issueRequired: ISSUE_REQUIRED, applyConventions: APPLY_CONVENTIONS, complianceFrameworks: COMPLIANCE_FRAMEWORKS, issueInput: ticketId });
 <!-- learning:off -->
       const engineResult = await runSingleTicketEngine({ ticket: ticketId, baseBranch: INTEGRATION_BRANCH, ...(plans[ticketId] || {}), issueRequired: ISSUE_REQUIRED, applyConventions: APPLY_CONVENTIONS, complianceFrameworks: COMPLIANCE_FRAMEWORKS, issueInput: ticketId });
 <!-- learning:end -->
-      // Check both verdict (engine_output_schema) and overallVerdict (SINGLE skeleton alias).
-      // PASS and UNVERIFIED merge; PARTIAL, FAIL, ESCALATED (the ticket-link and branch stops included) or no verdict quarantine.
+      // PASS and UNVERIFIED merge (verdict, or overallVerdict as the SINGLE alias); PARTIAL, FAIL, ESCALATED (the ticket-link and branch stops included) or no verdict quarantine.
       if (["PASS", "UNVERIFIED"].includes(engineResult.verdict || engineResult.overallVerdict)) {
-        // Git merges locally and validates nothing: the workflow owns the post-merge Validate (D-WAVE-MERGE-VALIDATE).
-        const merge = await agent(`Merge ${engineResult.branch} to ${INTEGRATION_BRANCH} locally. Include ticket ID ${ticketId} in the merge commit message. Do not push, and run no build or test.
-Return: {"merged": true, "mergeSha": "<40-hex merge commit>", "treeEqual": <true when mergeSha^{tree} equals the tree of ${engineResult.branch}'s head>} — or {"merged": false, "reason": "<why>"} when no merge is kept.`, { agentType: "Git" });
-        let kept = false;
-        let reason = merge?.reason || "merge failed";
-        if (merge?.merged === true && !MERGE_SHA.test(String(merge.mergeSha))) {
-          // A merge may sit on the integration branch with no SHA to validate or undo it by: stop taking merges.
-          waveState.halted = { ticket: ticketId, mergeSha: null, reason: "merge reported without a 40-hex mergeSha; the integration branch may hold an unvalidated merge" };
-          reason = waveState.halted.reason;
-        } else if (merge?.merged === true) {
-          // A merge counts as kept only when this Validate returns PASS. It always runs: treeEqual is recorded, never a reason to skip.
-          const post = await agent(`Run build, typecheck, lint, and tests on ${INTEGRATION_BRANCH} after merging ${engineResult.branch} (merge commit ${merge.mergeSha}).
-Follow your Running commands block for every build and test command.
-Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate" });
-          if (post?.verdict === "PASS") {
-            kept = true;
-          } else {
-            const undo = await agent(`Undo the merge ${merge.mergeSha} on ${INTEGRATION_BRANCH}, only when no remote branch contains ${merge.mergeSha} and the HEAD of ${INTEGRATION_BRANCH} still equals ${merge.mergeSha}. On the integration branch run exactly this one command and no other that changes a branch or a remote: git reset --keep ${merge.mergeSha}^1
-Return: {"undone": true} — or {"undone": false, "reason": "<why>"} when you did not undo it.`, { agentType: "Git" });
-            if (undo?.undone === true) {
-              reason = "post-merge build red; merge undone";
-            } else {
-              // A merge that stays red would poison every later ticket: stop taking merges and rounds, and name the red HEAD.
-              reason = `post-merge build red; merge not undone (${undo?.reason || "no reason given"})`;
-              waveState.halted = { ticket: ticketId, mergeSha: merge.mergeSha, reason };
-            }
-          }
-        }
-        results[ticketId] = rowOf(ticketId, engineResult, kept, merge?.merged === true && typeof merge.treeEqual === "boolean" ? merge.treeEqual : null);
+        const { kept, reason, halted, treeEqual } = await mergeValidateUndo(ticketId, engineResult);
+        if (halted !== null) waveState.halted = halted;
+        results[ticketId] = rowOf(ticketId, engineResult, kept, treeEqual);
         if (!kept) waveState.quarantined.push({ ticket: ticketId, reason });
       } else {
         results[ticketId] = rowOf(ticketId, engineResult, false);
         waveState.quarantined.push({ ticket: ticketId, reason: engineResult.escalations?.[0]?.description || "engine fail/escalated" });
       }
     } catch (err) {
-      // One ticket's crash/stall never kills the wave — quarantine it; cascade propagates to dependents via the next reader round
+      // Quarantine the ticket: the cascade reaches its dependents via the next reader round
       results[ticketId] = rowOf(ticketId, null, false);
       waveState.quarantined.push({ ticket: ticketId, reason: `engine crash: ${String(err)}` });
     }
@@ -697,7 +696,7 @@ A workflow cannot pause mid-run. After the build/wave workflow returns, you (the
    In WAVE mode, if no tracking-issue number was resolved in Pre-authoring step 5: state `TRACEABILITY: DEGRADED (no tracking issue for this run)` in the run summary and skip — never skip silently.
 3. **Compose the wave PR inputs** (WAVE mode only — skip this step entirely in SINGLE mode). The workflow returned `tickets`: one entry per wave ticket, in its input order, each `{ticket, ran, verdict, merged, issuePrLink, evaluateVerdict, testVerdict, surviving, coverageComplete}`. Every value in it is agent-reported and treated as untrusted: nothing below is repaired, and no reference is ever composed from a number.
    - **Branch check.** Run `git -C "{integration worktree root}" branch --show-current`. Only a name matching `^wave/[a-z0-9][a-z0-9-]{0,59}$` opens a wave PR, and its part after `wave/` is the `{slug}` below. Any other name: record `TRACEABILITY: DEGRADED (not a wave branch)` and go to step 4 with no wave PR.
-   - **Halted** (the workflow returned a non-null `halted`: a post-merge build it could not undo, or a merge reported with no SHA): the integration HEAD may be red. Record `Wave PR: skipped (integration HEAD red, wave halted at <halted.ticket>)`, name `halted.mergeSha` (or `none reported`) and `halted.reason` as the red integration HEAD in the run summary, and go to step 4 with no wave PR.
+   - **Halted** (a non-null `halted`, whose `kind` is `red`, `bad-sha` or `unchanged`): record `Wave PR: skipped (<text>, wave halted at <halted.ticket>)` and go to step 4 with no wave PR. `<text>` is fixed by `kind`, and no other `halted` field is shown. `red` (a post-merge build it could not undo): `integration HEAD red at <halted.mergeSha>`. `bad-sha` (a merge without a usable SHA): `integration branch may hold an unvalidated merge`. `unchanged` (a merge that added no commit): `merge added no commit`, with the remedy to check that the ticket branch holds its commits, then run the wave again.
    - **Nothing merged** (no entry has `merged: true`): record `Wave PR: skipped (nothing merged)` and go to step 4.
    - Otherwise compose (a) and then (b).
 
@@ -807,4 +806,4 @@ cd "{integration worktree root}" && node "$HOME/.devflow/scripts/verify-evidence
 
 ### Maintenance note
 
-This recipe encodes the current `/implement` + `/code-review` + `/resolve` orchestration shape as of the authoring date (2026-06-12). When those base commands change their orchestration, update this recipe to match. No tooling detects drift — by design (the LLM-vs-plumbing Iron Rule). The reminder lives in the design doc §16.
+This recipe mirrors the `/implement` + `/code-review` + `/resolve` orchestration as of 2026-06-12. When those commands change, update it. No tooling detects drift (the LLM-vs-plumbing Iron Rule).

package/src/assets/commands/implement.mds

@@ -46,7 +46,7 @@ $ARGUMENTS
 
 ### Re-validation Continuation Path
 
-When the user explicitly asks to re-validate, re-check, or re-run quality gates after making their own changes, resolve `${CLAUDE_CONFIG_DIR:-$HOME/.claude}` in Bash, Read `<that directory>/skills/devflow:agent-references/references/commands/implement-revalidate.md` with the Read tool and follow it. Otherwise proceed with the full pipeline below.
+When the user explicitly asks to re-validate, re-check, or re-run quality gates after making their own changes, run `d="${CLAUDE_CONFIG_DIR:-}"; case "$d" in /*) ;; *) d="$HOME/.claude" ;; esac; printf '%s\n' "$d"` in Bash, Read `<that directory>/skills/devflow:agent-references/references/commands/implement-revalidate.md` with the Read tool and follow it. Otherwise proceed with the full pipeline below.
 
 ### Phase 1: Setup
 
@@ -56,7 +56,7 @@ When the user explicitly asks to re-validate, re-check, or re-run quality gates
 **Produces:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, PR_DESCRIPTION_GUIDANCE, ISSUE_NUMBER, ISSUE_PR_LINK, EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL, PR_EXCEPTIONS, TEST_PLAN, EVIDENCE_FILE, PR_TEST_PLAN_BLOCK, REVIEW_PUBLICATION
 <!-- learning:end -->
 
-Record the current branch name as `BASE_BRANCH` - this will be the PR target.
+Record the current branch name as `BASE_BRANCH`. Stop the run unless it matches `^[A-Za-z0-9._/+@,#-]{1,200}$`, telling the user it allows only ASCII letters, digits and `._/+@,#-`, at most 200.
 
 {{docs_root()}}
 
@@ -114,11 +114,6 @@ The two tests this command does make are its own under every provider:
   `setup-task` fetches whatever it is handed — so the command would derive a
   branch from a failed lookup and drop the request on the floor.
 
-The cost of the count gate is a one-word task description (`/implement refactor`)
-reaching `setup-task` as an issue reference, where it fails the lookup and is
-reported. That is the direction the failure has to fall: an unfetched issue is
-visible, a silently discarded request is not.
-
 **Capture from Git agent output** (used throughout flow):
 - `TASK_ID`: The branch name created by Git agent (use as TASK_ID for rest of flow)
 - `BASE_BRANCH`: Branch this feature was created from (for PR target)
@@ -127,7 +122,7 @@ visible, a silently discarded request is not.
 
 {{issue_capture_contract()}}
 
-**Ticket link, only when `ISSUE_REQUIRED` is `true`:** when the capture above holds no `ISSUE_PR_LINK` (absent, or `(none)`), resolve `${CLAUDE_CONFIG_DIR:-$HOME/.claude}` in Bash, Read `<that directory>/skills/devflow:agent-references/references/commands/implement-evidence-asks.md` with the Read tool (once per run), then run its ticket link ask and **Record the exception at once** as it directs, before any Code spawn. `PR_EXCEPTIONS` is `(none)` until an exception is recorded.
+**Ticket link, only when `ISSUE_REQUIRED` is `true`:** when the capture above holds no `ISSUE_PR_LINK` (absent, or `(none)`), run `d="${CLAUDE_CONFIG_DIR:-}"; case "$d" in /*) ;; *) d="$HOME/.claude" ;; esac; printf '%s\n' "$d"` in Bash, Read `<that directory>/skills/devflow:agent-references/references/commands/implement-evidence-asks.md` with the Read tool (once per run), then run its ticket link ask and **Record the exception at once** as it directs, before any Code spawn. `PR_EXCEPTIONS` is `(none)` until an exception is recorded.
 
 **Test plan.** Before any Code spawn, give the task a test plan in the evidence file `{worktree}/.devflow/docs/evidence-{branch_slug}.md` (`EVIDENCE_FILE`) — unlike the handoff file, it stays after the PR exists. It holds up to three sections, in this order and nothing else: `## Test Plan`; `## Evidence Exceptions`, a byte copy of `PR_EXCEPTIONS` present only while that is not `(none)`; and `## Claims`, always last, so every claim is appended at the end of the file. Create the file if absent; if it exists, replace its `## Test Plan` and `## Evidence Exceptions` sections and keep `## Claims` byte-identical.
 
@@ -181,14 +176,14 @@ Pass `DECISIONS_CONTEXT` to Code agent (Phase 2) and Harden agent (Phase 4).
 Based on Setup context (plan document, issue body, or conversation context), use the three-strategy framework:
 
 **Strategy Selection**:
-- If plan document provided: use `execution-strategy` from frontmatter (default: SINGLE_CODE_AGENT if absent)
-- Otherwise: default to SINGLE_CODE_AGENT unless task description signals high complexity
+- If plan document provided: use `execution-strategy` from frontmatter (if absent, use the table below)
+- Otherwise: SINGLE_CODE_AGENT, because there is no Subtask Breakdown to split
 
-| Strategy | When | Frequency |
-|----------|------|-----------|
-| **SINGLE_CODE_AGENT** | Default. Coherent A→Z implementation | ~80% |
-| **SEQUENTIAL_CODE_AGENTS** | Context overflow risk, layered dependencies | ~15% |
-| **PARALLEL_CODE_AGENTS** | True artifact independence (rare) | ~5% |
+| Strategy | When |
+|----------|------|
+| **SINGLE_CODE_AGENT** | Default. Coherent A→Z implementation |
+| **SEQUENTIAL_CODE_AGENTS** | The plan writes >= 10 files or has >= 7 steps |
+| **PARALLEL_CODE_AGENTS** | True artifact independence (rare) |
 
 ---
 
@@ -211,7 +206,7 @@ DECISIONS_CONTEXT: {decisions_context}
 
 ---
 
-**SEQUENTIAL_CODE_AGENTS** (for HIGH/CRITICAL context risk):
+**SEQUENTIAL_CODE_AGENTS** (>= 10 files or >= 7 steps):
 
 Spawn Code agents one at a time. Each appends its own phase section to the handoff file, and the next reads only the section before it:
 
@@ -298,15 +293,15 @@ DECISIONS_CONTEXT: {decisions_context}
 ### Phase 3: Polish
 
 **Produces:** POLISH_OUTPUT
-**Requires:** FILES_CHANGED
+**Requires:** BASE_BRANCH
 
-After the Code agent completes, spawn Polish agent to polish the code. The Phase 6 Validate covers its commits.
+After the Code agent completes, spawn Polish agent to polish the code. The Phase 6 Validate covers its commits. `{branch_diff}` is the output of `git diff --name-only --diff-filter=d {BASE_BRANCH}...HEAD`, run again at each spawn.
 
 ```
 Agent(subagent_type="Polish"):
 "Polish recently implemented code
 Task: {task description}
-FILES_CHANGED: {list of files from Code agent output}
+FILES_CHANGED: {branch_diff}
 Focus on code modified by Code agent, apply project standards, enhance clarity
 Commit any improvements with a conventional-commit message."
 ```
@@ -314,14 +309,14 @@ Commit any improvements with a conventional-commit message."
 ### Phase 4: Self-Review
 
 **Produces:** HARDEN_OUTPUT
-**Requires:** FILES_CHANGED
+**Requires:** BASE_BRANCH
 
 After Polish agent completes, spawn Harden agent as the quality gate:
 
 ```
 Agent(subagent_type="Harden"):
 "TASK_DESCRIPTION: {task description}
-FILES_CHANGED: {list of files from Code agent output}
+FILES_CHANGED: {branch_diff}
 <!-- learning:on -->
 DECISIONS_CONTEXT: {decisions_context}
 <!-- learning:end -->
@@ -334,7 +329,7 @@ Harden agent reports `### Status: PASS | FIXED | BLOCKED`. **If BLOCKED:** repor
 ### Phase 5: Alignment Check
 
 **Produces:** ALIGNMENT_RESULT
-**Requires:** FILES_CHANGED, EXECUTION_PLAN
+**Requires:** BASE_BRANCH, EXECUTION_PLAN
 
 After Harden agent passes, spawn Evaluate agent to validate alignment. Evaluate agent receives `FEATURE_KNOWLEDGE_RULES` as acceptance context only; pattern and anti-pattern judgments belong to Harden agent:
 
@@ -342,7 +337,7 @@ After Harden agent passes, spawn Evaluate agent to validate alignment. Evaluate
 Agent(subagent_type="Evaluate"):
 "ORIGINAL_REQUEST: {task description or issue content}
 EXECUTION_PLAN: {execution plan from Phase 1}
-FILES_CHANGED: {list of files from Code agent output}
+FILES_CHANGED: {branch_diff}
 ACCEPTANCE_CRITERIA: {extracted criteria if available}
 FEATURE_KNOWLEDGE: {feature_knowledge_rules}
 Validate alignment with request and plan. Report ALIGNED or MISALIGNED with details."
@@ -375,11 +370,11 @@ Validate alignment with request and plan. Report ALIGNED or MISALIGNED with deta
 **Produces:** VALIDATION_RESULT, VALIDATED_HEAD
 **Requires:** BASE_BRANCH
 
-Validate takes the one full-suite slot, after every commit it must cover: Code, Polish, Harden and the alignment fixes. After Evaluate agent passes, spawn Validate agent. `FILES_CHANGED` is the branch diff, because the Code agent's own list misses the Polish, Harden and fix commits (`{base}` is `BASE_BRANCH`):
+Validate takes the one full-suite slot, after every commit it must cover: Code, Polish, Harden and the alignment fixes. After Evaluate agent passes, spawn Validate agent. `FILES_CHANGED` is the branch diff:
 
 ```
 Agent(subagent_type="Validate"):
-"FILES_CHANGED: {output of `git diff --name-only {base}...HEAD`}
+"FILES_CHANGED: {branch_diff}
 VALIDATION_SCOPE: full
 Run build, typecheck, lint, test. Report pass/fail with failure details."
 ```
@@ -420,7 +415,7 @@ Run build, typecheck, lint, test. Report pass/fail with failure details."
 ### Phase 7: QA Testing
 
 **Produces:** QA_RESULT
-**Requires:** FILES_CHANGED, EXECUTION_PLAN, TEST_PLAN, VALIDATED_HEAD
+**Requires:** BASE_BRANCH, EXECUTION_PLAN, TEST_PLAN, VALIDATED_HEAD
 
 After Phase 6 passes, spawn Test agent for scenario-based acceptance testing:
 
@@ -428,7 +423,7 @@ After Phase 6 passes, spawn Test agent for scenario-based acceptance testing:
 Agent(subagent_type="Test"):
 "ORIGINAL_REQUEST: {task description or issue content}
 EXECUTION_PLAN: {execution plan from Phase 1}
-FILES_CHANGED: {list of files from Code agent output}
+FILES_CHANGED: {branch_diff}
 ACCEPTANCE_CRITERIA: {extracted criteria if available}
 TEST_PLAN: {the TP lines of the evidence file's ## Test Plan section, or (none)}
 Design and execute scenario-based acceptance tests. Report PASS or FAIL with evidence."
@@ -467,7 +462,7 @@ Run this phase only if a qa-fix committed (`git rev-parse HEAD` differs from `VA
 
 ```
 Agent(subagent_type="Validate"):
-"FILES_CHANGED: {output of `git diff --name-only VALIDATED_HEAD..HEAD`}
+"FILES_CHANGED: {output of `git diff --name-only --diff-filter=d VALIDATED_HEAD..HEAD`}
 VALIDATION_SCOPE: changed-only
 Verify the qa-fix commits did not break anything."
 ```
@@ -575,7 +570,7 @@ If Phase 1 recorded an evidence exception, show its `## Evidence Exceptions` lin
 /implement (orchestrator - spawns agents only)
 │
 ├─ Re-validation Path (when user says "re-validate"/"re-check"/"re-run gates")
-│  └─ Branch safety → skip Phase 2 → detect FILES_CHANGED → Phases 3-8 → Phase 9, 11, 12
+│  └─ Branch safety → skip Phase 2 → record BASE_BRANCH → Phases 3-8 → Phase 9, 11, 12
 │
 ├─ Phase 1: Setup
 ├─ Phase 2: Implement (3-strategy framework)