devflow-kit 3.1.0 → 3.3.0

package/src/assets/commands/debug.mds

@@ -19,7 +19,13 @@ Investigate bugs by spawning parallel agents, each pursuing a different hypothes
 
 ## Input
 
-`$ARGUMENTS` contains whatever follows `/debug`:
+What follows `/debug` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+`COMMAND_INPUT` is one of:
 - Bug description: "login fails after session timeout"
 - Issue reference: "#42"
 - Empty: use conversation context
@@ -30,8 +36,6 @@ Investigate bugs by spawning parallel agents, each pursuing a different hypothes
 
 **Produces:** DECISIONS_CONTEXT
 
-**Load Companion Skills** — Load via Skill tool: `devflow:test-driven-development`, `devflow:software-design`, `devflow:testing`. If a skill fails to load, continue without it.
-
 {{decisions_load()}}
 
 The orchestrator uses `DECISIONS_CONTEXT` locally when generating hypotheses (Phase 2) — prior pitfalls and decisions can suggest specific root causes to investigate. Follow `devflow:apply-decisions` to Read full entry bodies on demand. **Do NOT pass `DECISIONS_CONTEXT` to Explore investigators** — decisions context stays in the orchestrator; investigators examine code directly.
@@ -43,7 +47,7 @@ The orchestrator uses `DECISIONS_CONTEXT` locally when generating hypotheses (Ph
 **Produces:** HYPOTHESES, BUG_CONTEXT
 **Requires:** DECISIONS_CONTEXT
 
-If `$ARGUMENTS` opens with a candidate issue reference, fetch the issue:
+If `COMMAND_INPUT` opens with a candidate issue reference, fetch the issue:
 
 {{issue_ref_grammar()}}
 
@@ -88,7 +92,8 @@ Return a structured report:
 - Status: CONFIRMED / DISPROVED / PARTIAL
 - Evidence FOR: [list with file:line refs]
 - Evidence AGAINST: [list with file:line refs]
-- Key finding: {one-sentence summary}"
+- Key finding: {one-sentence summary}
+Keep the whole report to at most about 1,500 tokens."
 
 Agent(subagent_type="Explore"):
 "Investigate this bug: {bug_description}
@@ -96,7 +101,7 @@ Agent(subagent_type="Explore"):
 Hypothesis: {hypothesis B description}
 Focus area: {specific code area, mechanism, or condition}
 
-[same steps and return format]"
+[same steps and return format; the whole report at most about 1,500 tokens]"
 
 Agent(subagent_type="Explore"):
 "Investigate this bug: {bug_description}
@@ -104,7 +109,7 @@ Agent(subagent_type="Explore"):
 Hypothesis: {hypothesis C description}
 Focus area: {specific code area, mechanism, or condition}
 
-[same steps and return format]"
+[same steps and return format; the whole report at most about 1,500 tokens]"
 
 (Add more investigators if bug complexity warrants 4-5 hypotheses)
 ```
@@ -116,7 +121,7 @@ Focus area: {specific code area, mechanism, or condition}
 
 Evaluate investigation verdicts before synthesis:
 
-- **One CONFIRMED**: Spawn 1-2 additional `Agent(subagent_type="Explore")` agents to validate from different angles (prevent confirmation bias)
+- **One CONFIRMED**: Spawn 1-2 additional `Agent(subagent_type="Explore")` agents to validate from different angles (prevent confirmation bias), each reporting at most about 1,500 tokens
 - **Multiple PARTIAL**: Look for a unifying root cause that explains all partial evidence
 - **All DISPROVED**: Report honestly — "No root cause identified from initial hypotheses." Generate 2-3 second-round hypotheses if conversation context suggests avenues not yet explored. Loop back to Phase 3.
 

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

@@ -79,7 +79,13 @@ Note the `budget` value from the Workflow tool context (or default to "medium" i
 
 **3. Detect mode: SINGLE or WAVE**
 
-- **SINGLE mode:** input is one ticket, one issue, one task description, or one plan document
+What follows the command is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+- **SINGLE mode:** `COMMAND_INPUT` is one ticket, one issue, one task description, or one plan document
 - **WAVE mode:** input is a set of tracker issues (wave labels, milestone, issue list), or the user says "wave" / "all tickets in wave N"
 - **A `/devflow:dynamic-tickets` ticket directory** (`{worktree}/.devflow/docs/tickets/{slug}/{ts}/`) is WAVE input: in each ticket file (every `.md` there but `tracking-issue.md`), the `**Issue:**` line directly after `**Depends on:**` is one raw `ISSUE_REFS` token, forwarded to the wave's pre-fetch verbatim — never rendered, normalised or re-derived. A ticket file with no `**Issue:**` line, or more than one, contributes no token; name it in the run summary as `not filed`.
 
@@ -113,7 +119,7 @@ If none found: build proceeds Gate-1-only (Gate 2 skipped with a note). Never re
 **5. Resolve tracking-issue number (optional)**
 
 Check, in priority order:
-- An explicit candidate issue reference or issue URL in the user's input (e.g. `#42`, `42`, or `https://github.com/…/issues/42`)
+- An explicit candidate issue reference or issue URL in `COMMAND_INPUT` (e.g. `#42`, `42`, or `https://github.com/…/issues/42`)
 - The `**Issue:**` line directly after the H1 of the ticket set's `tracking-issue.md` (written by `/devflow:dynamic-tickets`' filing step; the file is at `{worktree}/.devflow/docs/tickets/{slug}/{ts}/tracking-issue.md`), as a raw token — only when the file holds exactly one `**Issue:**` line
 - Otherwise: none
 
@@ -181,7 +187,8 @@ if (BRANCH === "(none)") {
 
 // Phase 2: Implement
 await phase("implement", () =>
-  agent(`Implement the following ticket on branch ${BRANCH}:
+  agent(`OPERATION: implement
+Implement the following ticket on branch ${BRANCH}:
 
 ${TICKET}
 
@@ -194,7 +201,7 @@ ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
 COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
 
-When you build or run tests to verify your work, use your "Long-running commands" discipline (background-Bash + Monitor poll) for anything that may run silent >120s, and prefer package-scoped commands.
+When you build or run tests to verify your work, follow your Running commands block.
 
 After implementing, commit your changes with a conventional-commit message and report:
 - Files changed
@@ -202,39 +209,51 @@ After implementing, commit your changes with a conventional-commit message and r
 - Any open questions or blockers`, { agentType: "Code" })
 );
 
-// Phase 3: Gate 1 — post-code pipeline
+// Phase 3: Gate 1 #1 — post-code pipeline: Simplify agent → Scrutinize agent → Validate agent.
+// Validate runs last and unconditionally, so its one full run covers every commit the pass made (see gate1_postcode()).
 const gate1 = await phase("gate1", async () => {
-  // Gate 1 #1 — runs once, immediately after the initial implementation.
+  await agent(`Simplify and reduce complexity of recent changes on branch ${BRANCH}. Commit any improvements.`, { agentType: "Simplify" });
+
+  const scrutiny = await agent(`9-pillar self-review of recent changes on branch ${BRANCH}. Fix P0/P1 issues and commit the fixes.
+Return: {"status": "PASS" | "FIXED" | "BLOCKED"}`, { agentType: "Scrutinize" });
+  // Anything but an explicit PASS or FIXED is a stop: a Scrutinize that returned no status, or one this skeleton does not know, has not accepted the code.
+  if (!["PASS", "FIXED"].includes(scrutiny?.status)) {
+    return { verdict: "ESCALATED", type: "scrutiny-blocked", reason: scrutiny?.status === "BLOCKED" ? "Scrutinize agent returned BLOCKED: a P0 issue cannot be fixed in scope" : "Scrutinize agent returned no recognised status: counted as BLOCKED" };
+  }
+
   const validation = await agent(`Run build, typecheck, lint, and tests on branch ${BRANCH}.
-For any build/test that may run silent >120s, use the background-Bash + Monitor poll procedure (your "Long-running commands" discipline) so you never trip the 180s watchdog; prefer package-scoped commands.
-Report: PASS or FAIL with details.`, { agentType: "Validate" });
+Follow your Running commands block for every build and test command.
+Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate" });
 
-  if (validation.verdict === "FAIL") {
-    // Up to 2 fix attempts
+  // Anything but an explicit PASS is a failure: a Validate that returned no verdict has not validated the branch.
+  if (validation?.verdict !== "PASS") {
+    let failureDetails = validation?.details || "Validate agent returned no PASS verdict";
+    // Up to 2 fix attempts, each followed by a Validate re-run
     for (let attempt = 1; attempt <= 2; attempt++) {
-      await agent(`Fix the validation failures on branch ${BRANCH}:
-${validation.details}
+      await agent(`OPERATION: validation-fix
+Fix the validation failures on branch ${BRANCH}:
+${failureDetails}
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
 COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
 Commit fixes with conventional-commit message.`, { agentType: "Code" });
-      const recheck = await agent(`Re-run build, typecheck, lint, tests on branch ${BRANCH}. Report: PASS or FAIL.`, { agentType: "Validate" });
-      if (recheck.verdict === "PASS") break;
-      if (attempt === 2) return { verdict: "ESCALATED", reason: "Validation exhausted after 2 Code agent fix attempts" };
+      const recheck = await agent(`Re-run build, typecheck, lint, tests on branch ${BRANCH} after fix attempt ${attempt} (follow your Running commands block).
+Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate" });
+      if (recheck?.verdict === "PASS") break;
+      failureDetails = recheck?.details || failureDetails;
+      if (attempt === 2) return { verdict: "ESCALATED", type: "validation-exhausted", reason: "Validation exhausted after 2 Code agent fix attempts" };
     }
   }
 
-  await agent(`Simplify and reduce complexity of recent changes on branch ${BRANCH}. Commit any improvements.`, { agentType: "Simplify" });
-
-  const scrutiny = await agent(`9-pillar self-review of recent changes on branch ${BRANCH}. Report any code you changed and your findings.`, { agentType: "Scrutinize" });
-
-  if (scrutiny.codeChanged) {
-    await agent(`Re-run build, typecheck, lint, tests on branch ${BRANCH} (Scrutinize agent made changes). Report: PASS or FAIL.`, { agentType: "Validate" });
-  }
-
   return { verdict: "PASS" };
 });
 
+// Gate 1 #1 stop, before Gate 2: an exhausted Validate or a BLOCKED Scrutinize leaves a broken or unfinished build,
+// so Gate 2 and the review pass never run on it — a correctness stop, like the ticket-link and branch stops.
+if (gate1.verdict === "ESCALATED") {
+  return { ticket: TICKET, branch: BRANCH, verdict: "ESCALATED", issueId: ISSUE_NUMBER, issuePrLink: ISSUE_PR_LINK, escalations: [{ type: gate1.type, description: gate1.reason }] };
+}
+
 // Phase 4: Gate 2 — acceptance gate (once, before review pass)
 const gate2 = await phase("gate2", async () => {
   if (!PLAN && !CRITERIA && !TEST_PLAN) {
@@ -243,25 +262,23 @@ const gate2 = await phase("gate2", async () => {
 
   let evalVerdict = "SKIPPED";
   if (PLAN) {
-    const panel = await parallel([
-      () => agent(`Acceptance-criteria evaluator: does the implementation on branch ${BRANCH} satisfy each numbered criterion, INCLUDING negative criteria?
+    const evaluation = await agent(`Acceptance and scope check on branch ${BRANCH}. Answer both questions:
+1. Does the implementation satisfy each numbered criterion, INCLUDING negative criteria (what it must NOT do)?
+2. Did the Code agent introduce any unplanned changes, smuggled anti-features, or drift from the plan's intent?
 Plan: ${PLAN}
 Criteria: ${CRITERIA || "see plan"}
-Report: PASS or FAIL per criterion with rationale.`, { agentType: "Evaluate" }),
-      () => agent(`Scope/intent-drift evaluator: did the Code agent on branch ${BRANCH} introduce any unplanned changes, smuggled anti-features, or drift from the plan's intent?
-Plan: ${PLAN}
-Report: PASS or FAIL with rationale.`, { agentType: "Evaluate" }),
-    ]);
-    evalVerdict = panel.every(p => p.verdict === "PASS") ? "PASS" : "FAIL";
+Return: {"verdict": "PASS" | "FAIL", "rationale": "..."} — FAIL if either answer is no, naming the failing criterion or the drift.`, { agentType: "Evaluate" });
+    evalVerdict = evaluation?.verdict === "PASS" ? "PASS" : "FAIL";
     if (evalVerdict === "FAIL") {
       // fix-and-continue — no re-evaluate, no inline Gate 1. The final Gate 1 (#2)
       // after the review pass is the build gate before the branch is handed back.
-      await agent(`Fix the alignment issues identified by the Evaluate agent panel on branch ${BRANCH}:
-${panel.filter(p => p.verdict === "FAIL").map(p => p.rationale).join("\n")}
+      await agent(`OPERATION: alignment-fix
+Fix the alignment issues identified by the Evaluate agent on branch ${BRANCH}:
+${evaluation?.rationale || "see the Evaluate agent's report"}
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
 COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
-Self-verify your fix compiles (background-Bash + Monitor for any build >120s — see your "Long-running commands" discipline). Commit fixes.`, { agentType: "Code" });
+Self-verify your fix compiles, following your Running commands block. Commit fixes.`, { agentType: "Code" });
       evalVerdict = "FAIL-FIXED";  // issues found, fixes applied, not re-evaluated by design
     }
   }
@@ -271,17 +288,18 @@ Self-verify your fix compiles (background-Bash + Monitor for any build >120s —
     const testResult = await agent(`Run scenario-based acceptance tests on branch ${BRANCH} against these criteria:
 ${CRITERIA || "(none)"}
 TEST_PLAN: ${TEST_PLAN || "(none)"}
-For any test/build command that may run silent >120s, use the background-Bash + Monitor poll procedure (your "Long-running commands" discipline) so you never trip the 180s watchdog.
+Follow your Running commands block for every scenario command.
 Cover: functionality, API contracts, performance, and cover every TEST_PLAN scenario. Report: PASS or FAIL per scenario.`, { agentType: "Test" });
     testVerdict = testResult.verdict;
     if (testVerdict === "FAIL") {
       // fix-and-continue — no re-test, no inline Gate 1.
-      await agent(`Fix the failing acceptance test scenarios on branch ${BRANCH}:
+      await agent(`OPERATION: qa-fix
+Fix the failing acceptance test scenarios on branch ${BRANCH}:
 ${testResult.failures}
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
 COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
-Self-verify your fix compiles and the scenarios pass (background-Bash + Monitor for any build/test >120s). Commit fixes.`, { agentType: "Code" });
+Self-verify your fix compiles and the scenarios pass, following your Running commands block. Commit fixes.`, { agentType: "Code" });
       testVerdict = "FAIL-FIXED";  // issues found, fixes applied, not re-evaluated by design
     }
   }
@@ -303,7 +321,7 @@ const reviewResult = await phase("review", async () => {
   const chunkSize = 5;
   const reviewThunks = reviewFocuses.map(focus =>
     () => agent(`${focus.charAt(0).toUpperCase() + focus.slice(1)} review. ${reviewScope}
-Focus discipline: ${focus}. Return: {"focus": "${focus}", "reviewed": true, "filesExamined": ["<path>"], "findings": [{"file": "<path-or-null>", "description": "<one-sentence issue>", "severity": "critical|high|medium|low"}]}`, { agentType: "Review" })
+Focus discipline: ${focus}. Return: {"focus": "${focus}", "reviewed": true, "filesExamined": ["<path>"], "findings": [{"file": "<path-or-null>", "line": <number-or-null>, "description": "<one-sentence issue>", "severity": "critical|high|medium|low"}]}`, { agentType: "Review" })
   );
 
   let rawReviews = [];
@@ -320,7 +338,7 @@ Focus discipline: ${focus}. Return: {"focus": "${focus}", "reviewed": true, "fil
     const focus = reviewFocuses[i];
     if (!r || r.reviewed !== true) {
       // Dead Review agent: retry once sequentially
-      const retry = await agent(`Retry ${focus} review. ${reviewScope} Focus: ${focus} discipline. Return: {"focus": "${focus}", "reviewed": true, "filesExamined": ["<path>"], "findings": [{"file": "<path-or-null>", "description": "<one-sentence issue>", "severity": "critical|high|medium|low"}]}`, { agentType: "Review" });
+      const retry = await agent(`Retry ${focus} review. ${reviewScope} Focus: ${focus} discipline. Return: {"focus": "${focus}", "reviewed": true, "filesExamined": ["<path>"], "findings": [{"file": "<path-or-null>", "line": <number-or-null>, "description": "<one-sentence issue>", "severity": "critical|high|medium|low"}]}`, { agentType: "Review" });
       if (!retry || retry.reviewed !== true) {
         coverageGaps.push(focus);
         log(`review coverage incomplete: ${focus}`);
@@ -385,17 +403,22 @@ ${JSON.stringify(allFindings.map((f, i) => ({ index: i, description: f.descripti
   // Distinct-file groups are paced in chunks of FIX_CHUNK — same pacing bar as the Review spawn
   // path — to avoid launching all Code agents at once on a large branch (reliability: explicit bound).
   const FIX_CHUNK = 5;
-  const fixThunks = Object.entries(fileGroups).map(([fileKey, findings]) => async () => {
+  // issue-fix SCOPE per finding: CRITICAL or HIGH takes the Careful protocol (failing regression test first); anything else is Standard.
+  const CAREFUL_SEVERITIES = new Set(["critical", "high"]);
+  const fixThunks = Object.values(fileGroups).map(findings => async () => {
     const chunkResults = [];
     for (let i = 0; i < findings.length; i += MAX_BATCH) {
       const chunk = findings.slice(i, i + MAX_BATCH);
-      const r = await agent(`Fix the following confirmed review findings on branch ${BRANCH}${fileKey.startsWith("__nofile") ? "" : ` in ${fileKey}`}:
-${chunk.map(f => `- ${f.description} (${f.severity})`).join("\n")}
-
+      const r = await agent(`OPERATION: issue-fix
+Fix the following confirmed review findings on branch ${BRANCH}:
+ISSUES:
+${chunk.map((f, n) => `${n + 1}. ${f.file ? `${f.file}${f.line ? `:${f.line}` : ""} — ` : ""}${f.description} (${f.severity})`).join("\n")}
+SCOPE: ${chunk.map((f, n) => `${n + 1}=${CAREFUL_SEVERITIES.has(String(f.severity).toLowerCase()) ? "Careful" : "Standard"}`).join(", ")}
+PUSH: false
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
 COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
-Fix all findings in this batch. Self-verify your fix compiles (background-Bash + Monitor for any build >120s — see your "Long-running commands" discipline). Commit with conventional-commit message.
+Fix all findings in this batch. Self-verify your fix compiles, following your Running commands block. Commit with conventional-commit message.
 Return: {"status": "fixed"|"blocked", "commitShas": ["<sha>"], "unresolved": ["<description of any finding that could not be fixed>"]}`, { agentType: "Code" });
       chunkResults.push({ chunk, result: r });
     }
@@ -430,38 +453,40 @@ Return: {"status": "fixed"|"blocked", "commitShas": ["<sha>"], "unresolved": ["<
   return { survivingFindings: notAddressed, fixedFindings, coverageGaps };
 });
 
-// Phase 5.5: Gate 1 #2 — FINAL post-fix gate (full Validate agent → Simplify agent → Scrutinize agent).
+// Phase 5.5: Gate 1 #2 — FINAL post-fix gate (Simplify agent → Scrutinize agent → full Validate agent, Validate last and unconditional).
 // Runs ONCE, after the review pass. Inside the pass the Code agent self-verified its own fixes;
 // this is the build gate before the branch is handed back. See gate1_postcode() cadence.
 const gate1Final = await phase("gate1-final", async () => {
+  await agent(`Simplify and reduce complexity of recent changes on branch ${BRANCH}. Commit any improvements.`, { agentType: "Simplify" });
+
+  const scrutiny = await agent(`9-pillar self-review of recent changes on branch ${BRANCH}. Fix P0/P1 issues and commit the fixes.
+Return: {"status": "PASS" | "FIXED" | "BLOCKED"}`, { agentType: "Scrutinize" });
+  if (!["PASS", "FIXED"].includes(scrutiny?.status)) {
+    return { verdict: "ESCALATED", type: "scrutiny-blocked", reason: scrutiny?.status === "BLOCKED" ? "Final Gate 1 Scrutinize agent returned BLOCKED: a P0 issue cannot be fixed in scope" : "Final Gate 1 Scrutinize agent returned no recognised status: counted as BLOCKED" };
+  }
+
   const validation = await agent(`Run build, typecheck, lint, and tests on branch ${BRANCH} (final gate after all fixing).
-For any build/test that may run silent >120s, use the background-Bash + Monitor poll procedure (your "Long-running commands" discipline) so you never trip the 180s watchdog; prefer package-scoped commands.
-Report: PASS or FAIL with details.`, { agentType: "Validate" });
+Follow your Running commands block for every build and test command.
+Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate" });
 
-  if (validation.verdict === "FAIL") {
-    let failureDetails = validation.details;
+  if (validation?.verdict !== "PASS") {
+    let failureDetails = validation?.details || "Validate agent returned no PASS verdict";
     for (let attempt = 1; attempt <= 2; attempt++) {
-      await agent(`Fix the final validation failures on branch ${BRANCH}:
+      await agent(`OPERATION: validation-fix
+Fix the final validation failures on branch ${BRANCH}:
 ${failureDetails}
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
 COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
 Self-verify your fix compiles. Commit fixes with conventional-commit message.`, { agentType: "Code" });
-      const recheck = await agent(`Re-run build, typecheck, lint, tests on branch ${BRANCH} (background+Monitor for long commands). Report: PASS or FAIL.`, { agentType: "Validate" });
-      if (recheck.verdict === "PASS") break;
-      failureDetails = recheck.details || failureDetails;
-      if (attempt === 2) return { verdict: "ESCALATED", reason: "Final Gate 1 validation exhausted after 2 Code agent fix attempts" };
+      const recheck = await agent(`Re-run build, typecheck, lint, tests on branch ${BRANCH} (final gate, after fix attempt ${attempt}; follow your Running commands block).
+Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate" });
+      if (recheck?.verdict === "PASS") break;
+      failureDetails = recheck?.details || failureDetails;
+      if (attempt === 2) return { verdict: "ESCALATED", type: "validation-exhausted", reason: "Final Gate 1 validation exhausted after 2 Code agent fix attempts" };
     }
   }
 
-  await agent(`Simplify and reduce complexity of recent changes on branch ${BRANCH}. Commit any improvements.`, { agentType: "Simplify" });
-
-  const scrutiny = await agent(`9-pillar self-review of recent changes on branch ${BRANCH}. Report any code you changed and your findings.`, { agentType: "Scrutinize" });
-
-  if (scrutiny.codeChanged) {
-    await agent(`Re-run build, typecheck, lint, tests on branch ${BRANCH} (Scrutinize agent made changes; background+Monitor for long commands). Report: PASS or FAIL.`, { agentType: "Validate" });
-  }
-
   return { verdict: "PASS" };
 });
 
@@ -490,7 +515,7 @@ Write a concise report. Present only surviving findings as outstanding — never
     survivingFindings: reviewResult.survivingFindings || [], fixedFindings: reviewResult.fixedFindings || [],
     reviewCoverage: { failedFocuses: coverageGaps, complete: coverageGaps.length === 0 },
     escalations: [
-      ...(gate1Final.verdict === "ESCALATED" ? [{ type: "validation-exhausted", description: gate1Final.reason || "final Gate 1 escalated" }] : []),
+      ...(gate1Final.verdict === "ESCALATED" ? [{ type: gate1Final.type || "validation-exhausted", description: gate1Final.reason || "final Gate 1 escalated" }] : []),
       ...coverageGaps.map(focus => ({ type: "review-coverage-incomplete", description: `review coverage incomplete: ${focus}` })),
     ],
     gate2, report,
@@ -534,7 +559,7 @@ 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: Validate agent (build + test). 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). 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.
 
 Wave skeleton — compact reference (see `wave_loop()` doctrine for full semantics):
 
@@ -545,11 +570,12 @@ Wave skeleton — compact reference (see `wave_loop()` doctrine for full semanti
 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
 // A row from an engine result: the fields step 3 after the workflow renders
-const rowOf = (ticketId, r, merged) => ({ ticket: ticketId, ran: true, verdict: r?.verdict || r?.overallVerdict || null, merged, issuePrLink: r?.issuePrLink || "(none)", evaluateVerdict: r?.gate2?.evaluateVerdict, testVerdict: r?.gate2?.testVerdict, surviving: r?.survivingFindings?.length, coverageComplete: r?.reviewCoverage?.complete });
+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 waveState = { quarantined: [], round: 0 };
+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 waveState = { quarantined: [], round: 0, halted: null };
 let reAskedThisDeadlock = false;  // re-ask guard: re-ask once on empty ready-set, then escalate
-while (remainingTickets.length > 0 && waveState.round < MAX_ROUNDS) {
+while (remainingTickets.length > 0 && waveState.round < MAX_ROUNDS && waveState.halted === null) {
   waveState.round++;
 
   // Design agent reader (opus) applies vacuous-truth rule: a ticket with no unmet dependencies is ALWAYS ready.
@@ -582,10 +608,36 @@ Return: {"ready": [...ticket-ids], "blocked": [{"ticket": "id", "namedBlocker":
       // 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.
       if (["PASS", "UNVERIFIED"].includes(engineResult.verdict || engineResult.overallVerdict)) {
-        const merge = await agent(`Merge ${engineResult.branch} to ${INTEGRATION_BRANCH}. Include ticket ID ${ticketId} in the merge commit message. Run Validate agent (build + test) after merge.
-Return: {"merged": true} — or {"merged": false, "reason": "<why>"} when the merge or the post-merge build failed and the merge was not kept.`, { agentType: "Git" });
-        results[ticketId] = rowOf(ticketId, engineResult, merge?.merged === true);
-        if (merge?.merged !== true) waveState.quarantined.push({ ticket: ticketId, reason: merge?.reason || "merge or post-merge build failed" });
+        // 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);
+        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" });
@@ -596,11 +648,12 @@ Return: {"merged": true} — or {"merged": false, "reason": "<why>"} when the me
       waveState.quarantined.push({ ticket: ticketId, reason: `engine crash: ${String(err)}` });
     }
     remainingTickets = remainingTickets.filter(t => t !== ticketId);
+    if (waveState.halted !== null) break;  // a red integration HEAD takes no further merge in this round
   }
 }
 
 // After the wave report is written: one row per wave ticket, in input order. No entry ⇒ never ran (cascade, deadlock, MAX_ROUNDS).
-return { tickets: WAVE_TICKETS.map(t => results[t] || { ticket: t, ran: false, verdict: null, merged: false, issuePrLink: "(none)" }), quarantined: waveState.quarantined };
+return { tickets: WAVE_TICKETS.map(t => results[t] || { ticket: t, ran: false, verdict: null, merged: false, treeEqual: null, issuePrLink: "(none)" }), quarantined: waveState.quarantined, halted: waveState.halted };
 ```
 
 ---
@@ -624,6 +677,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.
    - **Nothing merged** (no entry has `merged: true`): record `Wave PR: skipped (nothing merged)` and go to step 4.
    - Otherwise compose (a) and then (b).
 

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

@@ -59,7 +59,13 @@ If present, note its contents as `PREFERENCE_PROFILE`. This will be used to auto
 
 **3. Resolve ticket input**
 
-Determine the ticket source (in priority order):
+What follows the command is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+Determine the ticket source from `COMMAND_INPUT` (in priority order):
 - A directory of ticket `.md` files (from `/devflow:dynamic-tickets` output)
 - A list of candidate issue references or issue URLs
 - Inline ticket descriptions passed as args

package/src/assets/commands/explore.mds

@@ -18,7 +18,13 @@ Explore a codebase area by spawning parallel agents for flow tracing, dependency
 
 ## Input
 
-`$ARGUMENTS` contains whatever follows `/explore`:
+What follows `/explore` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+`COMMAND_INPUT` is one of:
 - Area description: "how does the auth system work"
 - Flow question: "trace the request lifecycle"
 - Empty: use conversation context
@@ -58,6 +64,8 @@ Based on Skim agent findings, spawn 2-3 `Agent(subagent_type="Explore")` agents
 
 Adjust explorer focus based on the specific exploration question.
 
+Ask each explorer for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
+
 ### Phase 4: Synthesize
 
 **Produces:** MERGED_FINDINGS