devflow-kit 3.2.0 → 3.4.0

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

@@ -3,7 +3,7 @@ description: Dependency-aware build engine — implement, review, and verify a s
 argument-hint: "[ticket | issue-url | plan-doc]"
 output-dir: dist/commands
 ---
-@import { authoring_preamble } from "./_partials/_preamble.mds"
+@import { authoring_preamble, authoring_decisions } from "./_partials/_preamble.mds"
 @import { evidence_policy } from "./_partials/_evidence_policy.mds"
 @import { docs_root } from "./_partials/_docs_root.mds"
 @import { agent_roster, agent_caveats } from "./_partials/_roster.mds"
@@ -13,8 +13,14 @@ output-dir: dist/commands
 @import { issue_ref_grammar, issue_capture_contract } from "./_partials/_tracker.mds"
 @import "./_partials/_publication.mds" as pub
 @import "./_partials/_compliance.mds" as compliance
+@import "./_partials/_settings.mds" as settings
 {{authoring_preamble()}}
 
+### Settings line
+
+{{settings.settings_resolve()}}
+
+{{authoring_decisions()}}
 ---
 
 ## dynamic-build — author and run a build workflow
@@ -69,10 +75,12 @@ Pass it as `complianceFrameworks` when invoking the workflow; the engine hands i
 
 `{integration worktree root}` is the toplevel of the checkout the integration branch is checked out in: `{worktree}` unless the wave runs in a linked worktree.
 
+<!-- learning:on -->
 **1. Apply decisions context**
 
-Apply the `devflow:apply-decisions` algorithm to the DECISIONS_CONTEXT loaded per the preamble above: scan the index, Read relevant entries, note the verbatim ADR/PF IDs you will inject into Code agent and Evaluate agent prompts.
+Apply the `devflow:apply-decisions` algorithm to the DECISIONS_CONTEXT loaded by the decisions step above: scan the index, Read relevant entries, note the verbatim ADR/PF IDs you will inject into Code agent prompts.
 
+<!-- learning:end -->
 **2. Read budget**
 
 Note the `budget` value from the Workflow tool context (or default to "medium" if not provided). This governs Review agent roster size and verification vote count.
@@ -150,7 +158,9 @@ const TICKET = args.ticket || args[0] || "see task description";
 const PLAN = args.plan || null;
 const CRITERIA = args.criteria || null;
 const TEST_PLAN = args.testPlan || null;  // the plan's checked TP lines, one string (Pre-authoring step 4)
+<!-- learning:on -->
 const DECISIONS_CONTEXT = args.decisionsContext || "";  // injected before authoring
+<!-- learning:end -->
 const ISSUE_INPUT = args.issueInput || args.issueNumber || "(none)";  // this ticket's OWN raw reference (Pre-authoring step 5; a wave passes issueInput) — setup-task's input, never a Code agent's
 const ISSUE_REQUIRED = String(args.issueRequired) === "false" ? "false" : "true";  // Pre-authoring step 0; only an explicit false turns it off — absent or unrecognised fails closed, like the resolver
 const APPLY_CONVENTIONS = String(args.applyConventions) === "false" ? "false" : "true";
@@ -187,15 +197,18 @@ 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}
 
 ${PLAN ? `Implementation plan:\n${PLAN}` : "No plan provided — use best judgment."}
 
+<!-- learning:on -->
 Relevant architectural decisions (apply devflow:apply-decisions algorithm):
 ${DECISIONS_CONTEXT}
 
+<!-- learning:end -->
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
 COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
@@ -208,39 +221,54 @@ 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}.
 Follow your Running commands block for every build and test command.
-Report: PASS or FAIL with details.`, { agentType: "Validate" });
+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}
+<!-- learning:on -->
+DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
 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) {
@@ -249,21 +277,22 @@ 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"}
+<!-- learning:on -->
+DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
 COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
@@ -282,8 +311,12 @@ Cover: functionality, API contracts, performance, and cover every TEST_PLAN scen
     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}
+<!-- learning:on -->
+DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
 COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
@@ -309,7 +342,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 = [];
@@ -326,7 +359,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}`);
@@ -391,13 +424,21 @@ ${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
+<!-- learning:on -->
+DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
 COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
@@ -436,38 +477,43 @@ 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).
 Follow your Running commands block for every build and test command.
-Report: PASS or FAIL with details.`, { agentType: "Validate" });
+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}
+<!-- learning:on -->
+DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
 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} (follow your Running commands block). 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; follow your Running commands block). Report: PASS or FAIL.`, { agentType: "Validate" });
-  }
-
   return { verdict: "PASS" };
 });
 
@@ -496,7 +542,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,
@@ -540,7 +586,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):
 
@@ -551,11 +597,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.
@@ -584,14 +631,44 @@ Return: {"ready": [...ticket-ids], "blocked": [{"ticket": "id", "namedBlocker":
     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)
+<!-- 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.
       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" });
@@ -602,11 +679,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 };
 ```
 
 ---
@@ -630,6 +708,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

@@ -3,13 +3,21 @@ description: Parallel wave planning — plan-challenge every ticket, produce acc
 argument-hint: "[tickets-dir | issue-list]"
 output-dir: dist/commands
 ---
-@import { authoring_preamble } from "./_partials/_preamble.mds"
+@import { authoring_preamble, authoring_decisions } from "./_partials/_preamble.mds"
 @import { docs_root } from "./_partials/_docs_root.mds"
 @import { agent_roster, agent_caveats } from "./_partials/_roster.mds"
 @import { acceptance_criteria_contract } from "./_partials/_plan_contract.mds"
 @import { issue_ref_grammar, issue_capture_contract } from "./_partials/_tracker.mds"
+@import "./_partials/_settings.mds" as settings
 {{authoring_preamble()}}
 
+<!-- learning:on -->
+### Settings line
+
+{{settings.settings_resolve()}}
+
+<!-- learning:end -->
+{{authoring_decisions()}}
 ---
 
 ## dynamic-plan — author and run a parallel planning + plan-challenge workflow
@@ -44,10 +52,12 @@ Before authoring, verify:
 
 Pass `{worktree}` to the workflow as its `root` argument.
 
+<!-- learning:on -->
 **1. Apply decisions context**
 
-Apply the `devflow:apply-decisions` algorithm to the DECISIONS_CONTEXT loaded per the preamble above: scan the index, Read relevant entries, note verbatim ADR/PF IDs to inject into Design agent and Evaluate agent prompts.
+Apply the `devflow:apply-decisions` algorithm to the DECISIONS_CONTEXT loaded by the decisions step above: scan the index, Read relevant entries, note verbatim ADR/PF IDs to inject into Design agent prompts.
 
+<!-- learning:end -->
 **2. Read the preference profile**
 
 Check whether `~/.devflow/preference-profile.md` exists:
@@ -112,7 +122,9 @@ export const meta = {
 // AskUserQuestion happens at the command boundary after this workflow returns — NOT here.
 
 const ticketSource = args.ticketSource || args[0] || "see task description";
+<!-- learning:on -->
 const DECISIONS_CONTEXT = args.decisionsContext || "";   // injected before authoring
+<!-- learning:end -->
 const PREFERENCE_PROFILE = args.preferenceProfile || "";  // injected before authoring
 const TP_CONTRACT = args.tpContract || "";  // the "Test-plan line (TP)" contract below — its paragraph and four bullets — passed verbatim as tpContract when invoking the workflow, never pasted into this script (it holds backticks)
 const slug = args.slug || "wave";
@@ -133,7 +145,9 @@ const plans = await phase("plan-parallel", () =>
   parallel((tickets || []).map(ticket => () =>
     agent(`Write an implementation plan for this ticket.
 Ticket: ${JSON.stringify(ticket)}
+<!-- learning:on -->
 Decisions context (apply devflow:apply-decisions; a plan file can be posted to the tracker, so state each decision in words, never by ID): ${DECISIONS_CONTEXT}
+<!-- learning:end -->
 The plan must cover: approach overview, affected files and modules, key design decisions, implementation sequence (what to build first), risks and mitigations, and any open questions you cannot resolve from the ticket alone.
 Write a thorough but tight plan — every section must earn its place for a Code agent who has no other context.
 Return: { ticketTitle, planMarkdown, openDecisions (array of genuine unknowns requiring user input) }.`, { agentType: "Design" })
@@ -149,7 +163,6 @@ const challenged = await phase("plan-challenge", () =>
 
 Plan under review: ${JSON.stringify(plan)}
 Ticket: ${JSON.stringify((tickets || [])[i])}
-Decisions context: ${DECISIONS_CONTEXT}
 
 Produce:
 1. List of improvements / gaps / edge cases / side-effects identified.
@@ -160,7 +173,7 @@ Produce:
    - its verification method is its method: a test committed to the suite is ci; a command run and read (a load test, a script) is local; a step performed and observed is manual;
    - the paths it exercises, from the plan's affected files, are its files: globs.
    Setup and expected outcome never go in a line: give them per TP in testScenarios.
-4. A list of genuine design decisions that require user input (not settled by the plan, the preference profile, or existing ADRs).
+4. A list of genuine design decisions that require user input (not settled by the plan or the preference profile).
 
 Test-plan line contract:
 ${TP_CONTRACT}
@@ -178,7 +191,9 @@ Return: { ticketTitle, improvements (array), acceptanceCriteria (array of number
 const crossCritic = await phase("cross-plan-critic", () =>
   agent(`Cross-plan conflict audit.
 All ticket plans + challenged criteria: ${JSON.stringify(challenged)}
+<!-- learning:on -->
 Decisions context: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
 
 Audit:
 1. API conflicts: two tickets defining the same API differently (different signatures, return types, error codes).
@@ -186,7 +201,11 @@ Audit:
 3. Undeclared dependencies: ticket A's plan implicitly requires something ticket B provides, but no dependency is declared.
 4. Scope overlap: two tickets both claim ownership of the same module or behavior.
 
+<!-- learning:on -->
 For each conflict found: state which two tickets are involved, describe the conflict precisely, and propose a resolution aligned with the decisions ledger.
+<!-- learning:off -->
+For each conflict found: state which two tickets are involved, describe the conflict precisely, and propose a resolution.
+<!-- learning:end -->
 
 Return: { conflicts (array of {tickets, conflictDescription, proposedResolution}), planAmendments (array of {ticketTitle, amendment}) }.`, { agentType: "Design" })
 );
@@ -199,10 +218,9 @@ const resolved = await phase("preference-resolve", () =>
 Preference profile: ${PREFERENCE_PROFILE || "(none — no profile found)"}
 Open decisions from plan-challenge: ${JSON.stringify((challenged || []).flatMap(c => c.openDecisions || []))}
 Cross-plan conflicts needing resolution: ${JSON.stringify((crossCritic && crossCritic.conflicts) || [])}
-Decisions context (ADRs/PFs already settled): ${DECISIONS_CONTEXT}
 
 For each open decision:
-- If the preference profile or an existing ADR/PF settles it clearly: auto-resolve and note the rationale.
+- If the preference profile settles it clearly: auto-resolve and note the rationale.
 - If not settled: add to the DECISIONS-NEEDED list for the user.
 
 Return: { autoResolved (array of {decision, resolution, source}), decisionsNeeded (array of {decision, context, options}) }.`, { agentType: "Synthesize" })
@@ -224,14 +242,26 @@ For each ticket, write ${OUTDIR}/{ticket-slug}-plan.md containing:
 - ## Acceptance Criteria (numbered, positive + negative)
 - ## Test Plan — the challenger's testPlan lines, verbatim, one per line, and nothing else: no prose, no blank line between them, no setup or outcome
 - ## Test Scenarios — one line per TP, in TP order: TP-n: its setup, then its expected outcome, from testScenarios
+<!-- learning:on -->
 - ## Auto-Resolved Decisions (if any — list each as: decision → resolution → source, naming a recorded decision in words, never by ID)
+<!-- learning:off -->
+- ## Auto-Resolved Decisions (if any — list each as: decision → resolution → source)
+<!-- learning:end -->
 
 Then write ${OUTDIR}/DECISIONS-NEEDED.md:
+<!-- learning:on -->
 - ## Auto-Resolved Decisions — list each silently-resolved decision as: decision → resolution → source (preference profile / ADR-NNN), so auto-resolution is auditable and reversible. If none, write "None."
+<!-- learning:off -->
+- ## Auto-Resolved Decisions — list each silently-resolved decision as: decision → resolution → source (preference profile), so auto-resolution is auditable and reversible. If none, write "None."
+<!-- learning:end -->
 - ## Decisions Needed
 - One section per open decision: what the decision is, why it matters, what options exist.
 - Include cross-plan conflicts that were not auto-resolved.
+<!-- learning:on -->
 - If no decisions needed, write: "No open decisions — all settled by preference profile or existing ADRs."
+<!-- learning:off -->
+- If no decisions needed, write: "No open decisions — all settled by the preference profile."
+<!-- learning:end -->
 
 Return: { planPaths (array), decisionsNeededPath (string), decisionsNeededCount (number) }.`, { agentType: "Synthesize" })
 );

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

@@ -3,9 +3,17 @@ description: Decision-preference profile distiller — mine past session transcr
 argument-hint: "[--dry-run]"
 output-dir: dist/commands
 ---
-@import { authoring_preamble } from "./_partials/_preamble.mds"
+@import { authoring_preamble, authoring_decisions } from "./_partials/_preamble.mds"
+@import "./_partials/_settings.mds" as settings
 {{authoring_preamble()}}
 
+<!-- learning:on -->
+### Settings line
+
+{{settings.settings_resolve()}}
+
+<!-- learning:end -->
+{{authoring_decisions()}}
 ---
 
 ## dynamic-profile — distill a decision-preference profile from past sessions

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

@@ -3,14 +3,22 @@ description: Generalized ticket-factory — turn an initiative or spec into a re
 argument-hint: "[initiative | spec-doc]"
 output-dir: dist/commands
 ---
-@import { authoring_preamble } from "./_partials/_preamble.mds"
+@import { authoring_preamble, authoring_decisions } from "./_partials/_preamble.mds"
 @import { agent_roster, agent_caveats } from "./_partials/_roster.mds"
 @import { ticket_body_template } from "./_partials/_ticket_template.mds"
 @import { factory_shape } from "./_partials/_factory.mds"
 @import { evidence_policy } from "./_partials/_evidence_policy.mds"
 @import { docs_root } from "./_partials/_docs_root.mds"
+@import "./_partials/_settings.mds" as settings
 {{authoring_preamble()}}
 
+<!-- learning:on -->
+### Settings line
+
+{{settings.settings_resolve()}}
+
+<!-- learning:end -->
+{{authoring_decisions()}}
 ---
 
 ## dynamic-tickets — author and run a ticket-factory workflow
@@ -53,10 +61,12 @@ Before you write the workflow script:
 
 Pass `{worktree}` to the workflow as its `root` argument.
 
+<!-- learning:on -->
 **1. Apply decisions context**
 
-Apply the `devflow:apply-decisions` algorithm to the DECISIONS_CONTEXT loaded per the preamble above: scan the index, Read relevant entries, note the verbatim ADR/PF IDs you will inject into Design agent and Review agent prompts.
+Apply the `devflow:apply-decisions` algorithm to the DECISIONS_CONTEXT loaded by the decisions step above: scan the index, Read relevant entries, note the verbatim ADR/PF IDs you will inject into Design agent prompts.
 
+<!-- learning:end -->
 **2. Read and distill the initiative**
 
 Read or note the user's input:
@@ -93,7 +103,9 @@ export const meta = {
 const candidates = args.candidates || [];   // [{title, summary, wave, dependsOn}]
 const initiative = args.initiative || args[0] || "see task description";
 const constraints = args.constraints || "";
+<!-- learning:on -->
 const DECISIONS_CONTEXT = args.decisionsContext || "";   // injected before authoring
+<!-- learning:end -->
 const slug = args.slug || initiative.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 40);
 const ts = new Date().toISOString().slice(0,16).replace(/[-:T]/g, (c) => c === 'T' ? '_' : c === ':' ? '' : c);
 const ROOT = args.root;  // {worktree} from Pre-authoring setup: the checkout's toplevel, never cwd
@@ -105,7 +117,9 @@ const drafts = await phase("draft", () =>
     agent(`Draft ticket for initiative: "${initiative}"
 Ticket: ${JSON.stringify(c)}
 Constraints: ${constraints}
+<!-- learning:on -->
 Decisions context (apply devflow:apply-decisions; the ticket is filed to the tracker, so state each decision in words, never by ID): ${DECISIONS_CONTEXT}
+<!-- learning:end -->
 Write the ticket body following the ticket_body_template structure (Wave/Depends-on header, Summary, Scope with In/Out + anti-features, Invariants, numbered Acceptance Criteria with at least one negative criterion, Open Questions).
 Return a JSON object with: title (string), summary (string), wave (number), dependsOn (array), bodyMarkdown (string), openQuestions (array).`, { agentType: "Design" })
   ))