devflow-kit 3.6.0 → 3.8.0

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

@@ -75,12 +75,12 @@ Pass it as `complianceFrameworks` when invoking the workflow; the engine builds
 
 `{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 -->
+<!-- curation:on -->
 **1. Apply decisions context**
 
 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 -->
+<!-- curation: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.
@@ -158,9 +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 -->
+<!-- curation:on -->
 const DECISIONS_CONTEXT = args.decisionsContext || "";  // injected before authoring
-<!-- learning:end -->
+<!-- curation: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";
@@ -175,7 +175,7 @@ TASK_DESCRIPTION: ${TICKET}
 ISSUE_REQUIRED: ${ISSUE_REQUIRED}
 APPLY_CONVENTIONS: ${APPLY_CONVENTIONS}
 ${ISSUE_INPUT !== "(none)" ? "ISSUE_INPUT: " + ISSUE_INPUT : ""}
-Return: {"branch": "<the - **Branch name**: value under your ### Branch, or (none)>", "issueId": "<the - **Issue ID**: value under your ### Handoff Values, or (none)>", "prLinkLine": "<the - **PR link line**: value, or (none)>"}`, { agentType: "Git" })
+Return: {"branch": "<the - **Branch name**: value under your ### Branch, or (none)>", "issueId": "<the - **Issue ID**: value under your ### Handoff Values, or (none)>", "prLinkLine": "<the - **PR link line**: value, or (none)>", "baseSha": "<the 40 or 64 hex git rev-parse HEAD prints before step 4>"}`, { agentType: "Git" })
 );
 
 // The ticket's own Handoff Values, read from setup-task's Output — never derived from ISSUE_INPUT.
@@ -185,6 +185,7 @@ const ISSUE_NUMBER = ISSUE_ID_SHAPE.test(String(setup?.issueId ?? "")) ? setup.i
 const ISSUE_PR_LINK = setup?.prLinkLine || "(none)";  // "(none)" ⇒ the wave PR carries no closing reference for this ticket
 // The branch setup-task created, as it reported it: every later phase and the merge use it. The engine never names one.
 const BRANCH = typeof setup?.branch === "string" && setup.branch.trim() !== "" && setup.branch.trim() !== "(none)" ? setup.branch : "(none)";
+const BASE_SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(String(setup?.baseSha ?? "")) ? setup.baseSha : "(none)";  // the commit the ticket branch was forked from
 
 // Ticket-link stop, before implement. The workflow cannot ask, so it never records an exception: it stops.
 if (ISSUE_REQUIRED === "true" && ISSUE_NUMBER === "(none)") {
@@ -196,6 +197,11 @@ if (BRANCH === "(none)") {
   return { ticket: TICKET, branch: BRANCH, verdict: "ESCALATED", issueId: ISSUE_NUMBER, issuePrLink: ISSUE_PR_LINK, escalations: [{ type: "branch-missing", description: "setup-task reported no branch name — check its Output, then re-run" }] };
 }
 
+// Base stop: every review range starts at the commit the ticket branch was forked from.
+if (BASE_SHA === "(none)") {
+  return { ticket: TICKET, branch: BRANCH, verdict: "ESCALATED", issueId: ISSUE_NUMBER, issuePrLink: ISSUE_PR_LINK, escalations: [{ type: "base-missing", description: "setup-task reported no base commit — check its Output, then re-run" }] };
+}
+
 // Phase 2: Implement
 await phase("implement", () =>
   agent(`OPERATION: implement
@@ -205,11 +211,11 @@ ${TICKET}
 
 ${PLAN ? `Implementation plan:\n${PLAN}` : "No plan provided — use best judgment."}
 
-<!-- learning:on -->
+<!-- curation:on -->
 Relevant architectural decisions (apply devflow:apply-decisions algorithm):
 ${DECISIONS_CONTEXT}
 
-<!-- learning:end -->
+<!-- curation:end -->
 ${COMPLIANCE_DIRECTIVE}
 
 When you build or run tests to verify your work, follow your Running commands block.
@@ -244,9 +250,9 @@ Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate"
       await agent(`OPERATION: validation-fix
 Fix the validation failures on branch ${BRANCH}:
 ${failureDetails}
-<!-- learning:on -->
+<!-- curation:on -->
 DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
-<!-- learning:end -->
+<!-- curation:end -->
 ${COMPLIANCE_DIRECTIVE}
 Commit fixes with conventional-commit message.`, { agentType: "Fix" });
       const recheck = await agent(`Re-run build, typecheck, lint, tests on branch ${BRANCH} after fix attempt ${attempt} (follow your Running commands block).
@@ -287,9 +293,9 @@ Return: {"verdict": "PASS" | "FAIL", "rationale": "..."} — FAIL if either answ
       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 -->
+<!-- curation:on -->
 DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
-<!-- learning:end -->
+<!-- curation:end -->
 ${COMPLIANCE_DIRECTIVE}
 Self-verify your fix compiles, following your Running commands block. Commit fixes.`, { agentType: "Fix" });
       evalVerdict = "FAIL-FIXED";  // issues found, fixes applied, not re-evaluated by design
@@ -309,9 +315,9 @@ Cover: functionality, API contracts, performance, and cover every TEST_PLAN scen
       await agent(`OPERATION: qa-fix
 Fix the failing acceptance test scenarios on branch ${BRANCH}:
 ${testResult.failures}
-<!-- learning:on -->
+<!-- curation:on -->
 DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
-<!-- learning:end -->
+<!-- curation:end -->
 ${COMPLIANCE_DIRECTIVE}
 Self-verify your fix compiles and the scenarios pass, following your Running commands block. Commit fixes.`, { agentType: "Fix" });
       testVerdict = "FAIL-FIXED";  // issues found, fixes applied, not re-evaluated by design
@@ -323,10 +329,9 @@ Self-verify your fix compiles and the scenarios pass, following your Running com
 
 // Phase 5: Review → verify → fix (single pass)
 const reviewResult = await phase("review", async () => {
-  // Review scope: the entire branch diff from the base branch to HEAD. No base SHA is tracked —
-  // Review agents diff the branch against its merge-base with the default branch.
+  // Review scope: the entire branch diff, from the commit the ticket branch was forked from to HEAD.
   // The pass runs exactly ONCE.
-  const reviewScope = `Review the full branch diff on branch ${BRANCH}. Diff the branch against its merge-base with the default branch (do not guess a base SHA — compute the merge-base from git).`;
+  const reviewScope = `Review the full branch diff on branch ${BRANCH}.\nDIFF_RANGE: ${BASE_SHA}...HEAD\n`;
 
   // Review agent focus list (order = index mapping for dead-reviewer detection)
   const reviewFocuses = ["security", "architecture", "performance", "complexity", "consistency", "regression", "testing", "reliability"];
@@ -370,13 +375,12 @@ Focus discipline: ${focus}. Return: {"focus": "${focus}", "reviewed": true, "fil
     return { survivingFindings: [], fixedFindings: [], coverageGaps };
   }
 
-  // Adversarial verification — bounded 2-3 agent panel, majority-survives
-  // Panel asks perspective-diverse questions over the WHOLE finding set (not one agent per finding).
-  // A finding survives if >50% of panel agents CONFIRM it.
+  // Adversarial panel over the WHOLE finding set (not one agent per finding): >50% CONFIRMED survives
   const VERIFY_PANEL = 3;
   const panels = await parallel(
     Array.from({ length: VERIFY_PANEL }, (_, lens) => () =>
       agent(`Adversarially verify all ${allFindings.length} findings on branch ${BRANCH}.
+DIFF_RANGE: ${BASE_SHA}...HEAD
 Lens ${lens + 1} of ${VERIFY_PANEL}:
 ${["Does each finding actually reproduce in the current code? Hunt for findings that describe patterns not present in the diff.",
    "Is each finding a real issue or a false positive in context? Consider intent, surrounding code, and project conventions.",
@@ -394,16 +398,13 @@ ${JSON.stringify(allFindings.map((f, i) => ({ index: i, description: f.descripti
     panels.filter(p => (p.verdicts || []).find(v => v.index === i)?.verdict === "CONFIRMED").length > VERIFY_PANEL / 2
   );
 
-  // No confirmed findings — coverageGaps carry forward and block PASS downstream; also eliminates the empty-batch parallel() path
+  // No confirmed findings: coverageGaps carry forward and block PASS downstream
   if (confirmedFindings.length === 0) {
     return { survivingFindings: [], fixedFindings: [], coverageGaps };
   }
 
-  // Batched fix Code agents — one file per set of sub-batches; max 5 findings per sub-batch.
-  // Sub-batches for the SAME file run sequentially (never two Code agents editing the same file concurrently —
-  // concurrent same-file edits cause index contention and lost fixes).
-  // Sub-batches for DISTINCT files run in parallel (different code areas — safe per concurrency doctrine).
-  // A finding with no file field gets its own singleton group (unknown scope — never mix with known files).
+  // Sub-batches (max 5 findings): same file in sequence, distinct files in parallel.
+  // A finding with no file is a singleton group.
   const MAX_BATCH = 5;  // max 5 findings per sub-batch
   const fileGroups = {};
   for (let fi = 0; fi < confirmedFindings.length; fi++) {
@@ -413,9 +414,7 @@ ${JSON.stringify(allFindings.map((f, i) => ({ index: i, description: f.descripti
     fileGroups[key].push(f);
   }
 
-  // One entry per distinct file; each entry runs its sub-batches sequentially.
-  // 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).
+  // One entry per file; FIX_CHUNK chunks bound concurrent Code agents
   const FIX_CHUNK = 5;
   // 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"]);
@@ -429,9 +428,9 @@ 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 -->
+<!-- curation:on -->
 DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
-<!-- learning:end -->
+<!-- curation:end -->
 ${COMPLIANCE_DIRECTIVE}
 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" });
@@ -490,9 +489,9 @@ Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate"
       await agent(`OPERATION: validation-fix
 Fix the final validation failures on branch ${BRANCH}:
 ${failureDetails}
-<!-- learning:on -->
+<!-- curation:on -->
 DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
-<!-- learning:end -->
+<!-- curation:end -->
 ${COMPLIANCE_DIRECTIVE}
 Self-verify your fix compiles. Commit fixes with conventional-commit message.`, { agentType: "Fix" });
       const recheck = await agent(`Re-run build, typecheck, lint, tests on branch ${BRANCH} (final gate, after fix attempt ${attempt}; follow your Running commands block).
@@ -575,22 +574,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}$/;  // STRICT_NAME_RE's deliberate variant, less its origin/ refusal; 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 +640,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)
-<!-- learning:on -->
+      // 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)
+<!-- curation: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 -->
+<!-- curation: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.
+<!-- curation:end -->
+      // 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 +695,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).
 
@@ -762,12 +760,14 @@ Do NOT ask questions mid-workflow — that is impossible (F4). The workflow only
 
 7. **Wave PR evidence** — only when step 6 reported the wave PR, after it; it never blocks, and every outcome below goes into the run summary. Take `{n}` from step 6's `- **PR**: #{n}` line when `{n}` matches `^[1-9][0-9]{0,9}$` as a whole; no such line ⇒ record `TRACEABILITY: DEGRADED (wave PR number not captured)` and skip this step. `PR_TEST_PLAN_BLOCK` `(none)` ⇒ record `Wave evidence: skipped (no wave test plan)` and skip it.
 
+   **Changed files.** Take `{base_ref}` from step 6's `- **Base ref**:` line; only when it is 40 or 64 lowercase hex, run `git -C "{integration worktree root}" diff --name-only --diff-filter=d {base_ref}...HEAD; echo "exit=$?"`. Unless it ran and printed `exit=0`, record `TRACEABILITY: DEGRADED (wave base unusable)` and skip this step.
+
    **(a) Test the wave.** Spawn one Test agent on the integration worktree with the wave test plan — the TP lines of the `## Test Plan` section step 3(b) wrote to `{integration worktree root}/.devflow/docs/evidence-wave-{slug}.md`:
 
 ```
 Agent(subagent_type="Test"):
 "ORIGINAL_REQUEST: the merged tickets of wave/{slug}, as the wave test plan names them
-FILES_CHANGED: {the files wave/{slug} changes against the - **Base**: branch step 6 reported}
+FILES_CHANGED: {the file list that diff printed}
 TEST_PLAN: {the TP lines of the wave evidence file's ## Test Plan section}
 WORKTREE_PATH: {integration worktree root}
 Cover every TEST_PLAN line on the integration branch as it stands. Report PASS or FAIL with evidence."
@@ -807,4 +807,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/dynamic-plan.mds

@@ -11,12 +11,12 @@ output-dir: dist/commands
 @import "./_partials/_settings.mds" as settings
 {{authoring_preamble()}}
 
-<!-- learning:on -->
+<!-- curation:on -->
 ### Settings line
 
 {{settings.settings_resolve()}}
 
-<!-- learning:end -->
+<!-- curation:end -->
 {{authoring_decisions()}}
 ---
 
@@ -52,12 +52,12 @@ Before authoring, verify:
 
 Pass `{worktree}` to the workflow as its `root` argument, and its `slug` argument: the `{slug}` of the ticket directory (`tickets/{slug}/{ts}/`) when that is the ticket source, otherwise `wave`.
 
-<!-- learning:on -->
+<!-- curation:on -->
 **1. Apply decisions context**
 
 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 -->
+<!-- curation:end -->
 **2. Read the preference profile**
 
 Check whether `~/.devflow/preference-profile.md` exists:
@@ -122,9 +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 -->
+<!-- curation:on -->
 const DECISIONS_CONTEXT = args.decisionsContext || "";   // injected before authoring
-<!-- learning:end -->
+<!-- curation: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";
@@ -146,9 +146,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 -->
+<!-- curation: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 -->
+<!-- curation: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" })
@@ -192,9 +192,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 -->
+<!-- curation:on -->
 Decisions context: ${DECISIONS_CONTEXT}
-<!-- learning:end -->
+<!-- curation:end -->
 
 Audit:
 1. API conflicts: two tickets defining the same API differently (different signatures, return types, error codes).
@@ -202,11 +202,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 -->
+<!-- curation: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 -->
+<!-- curation:off -->
 For each conflict found: state which two tickets are involved, describe the conflict precisely, and propose a resolution.
-<!-- learning:end -->
+<!-- curation:end -->
 
 Return: { conflicts (array of {tickets, conflictDescription, proposedResolution}), planAmendments (array of {ticketTitle, amendment}) }.`, { agentType: "Design" })
 );
@@ -243,26 +243,26 @@ For each ticket, write ${OUTDIR}/{ticket-slug}-plan.md, {ticket-slug} being the
 - ## 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 -->
+<!-- curation:on -->
 - ## Auto-Resolved Decisions (if any — list each as: decision → resolution → source, naming a recorded decision in words, never by ID)
-<!-- learning:off -->
+<!-- curation:off -->
 - ## Auto-Resolved Decisions (if any — list each as: decision → resolution → source)
-<!-- learning:end -->
+<!-- curation:end -->
 
 Then write ${OUTDIR}/DECISIONS-NEEDED.md:
-<!-- learning:on -->
+<!-- curation: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 -->
+<!-- curation: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 -->
+<!-- curation: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 -->
+<!-- curation:on -->
 - If no decisions needed, write: "No open decisions — all settled by preference profile or existing ADRs."
-<!-- learning:off -->
+<!-- curation:off -->
 - If no decisions needed, write: "No open decisions — all settled by the preference profile."
-<!-- learning:end -->
+<!-- curation:end -->
 
 Return: { planPaths (array), decisionsNeededPath (string), decisionsNeededCount (number) }.`, { agentType: "Synthesize" })
 );

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

@@ -7,12 +7,12 @@ output-dir: dist/commands
 @import "./_partials/_settings.mds" as settings
 {{authoring_preamble()}}
 
-<!-- learning:on -->
+<!-- curation:on -->
 ### Settings line
 
 {{settings.settings_resolve()}}
 
-<!-- learning:end -->
+<!-- curation:end -->
 {{authoring_decisions()}}
 ---
 

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

@@ -12,12 +12,12 @@ output-dir: dist/commands
 @import "./_partials/_settings.mds" as settings
 {{authoring_preamble()}}
 
-<!-- learning:on -->
+<!-- curation:on -->
 ### Settings line
 
 {{settings.settings_resolve()}}
 
-<!-- learning:end -->
+<!-- curation:end -->
 {{authoring_decisions()}}
 ---
 
@@ -61,12 +61,12 @@ Before you write the workflow script:
 
 Pass `{worktree}` to the workflow as its `root` argument.
 
-<!-- learning:on -->
+<!-- curation:on -->
 **1. Apply decisions context**
 
 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 -->
+<!-- curation:end -->
 **2. Read and distill the initiative**
 
 Read or note the user's input:
@@ -103,9 +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 -->
+<!-- curation:on -->
 const DECISIONS_CONTEXT = args.decisionsContext || "";   // injected before authoring
-<!-- learning:end -->
+<!-- curation:end -->
 const slug = args.slug || initiative.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+/, '').slice(0, 50).replace(/-+$/, '') || 'untitled';
 const now = new Date(), two = (n) => String(n).padStart(2, '0');
 const ts = `${now.getFullYear()}-${two(now.getMonth() + 1)}-${two(now.getDate())}_${two(now.getHours())}${two(now.getMinutes())}`;
@@ -118,9 +118,9 @@ const drafts = await phase("draft", () =>
     agent(`Draft ticket for initiative: "${initiative}"
 Ticket: ${JSON.stringify(c)}
 Constraints: ${constraints}
-<!-- learning:on -->
+<!-- curation: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 -->
+<!-- curation: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" })
   ))

package/src/assets/commands/explore.mds

@@ -32,34 +32,34 @@ $ARGUMENTS
 
 ## Phases
 
-<!-- learning:on -->
+<!-- curation:on -->
 ### Phase 1: Load Decisions (Orchestrator-Local)
-<!-- learning:off -->
+<!-- curation:off -->
 ### Phase 1: Resolve Settings
-<!-- learning:end -->
+<!-- curation:end -->
 
-<!-- learning:on -->
+<!-- curation:on -->
 **Produces:** DECISIONS_CONTEXT
 
-<!-- learning:end -->
+<!-- curation:end -->
 {{settings.settings_resolve()}}
 
 {{decisions_load()}}
-<!-- learning:on -->
+<!-- curation:on -->
 The orchestrator uses `DECISIONS_CONTEXT` locally when framing exploration — prior decisions and pitfalls suggest specific areas to investigate. Follow `devflow:apply-decisions` to Read full entry bodies on demand. **Do NOT pass `DECISIONS_CONTEXT` to Explore sub-agents** — decisions context stays in the orchestrator, not in the investigation workers.
 
-<!-- learning:end -->
+<!-- curation:end -->
 **No up-front feature knowledge load** — explore investigation workers read code directly to avoid confirmation bias. Feature knowledge is only created as a write-back at the end, after exploration is complete.
 
 ### Phase 2: Orient
 
 **Produces:** ORIENT_OUTPUT
 
-<!-- learning:on -->
-Spawn `Agent(subagent_type="Skim")` with `LEARNING` from the settings line, to get codebase overview relevant to the exploration question:
-<!-- learning:off -->
+<!-- curation:on -->
+Spawn `Agent(subagent_type="Skim")` with `CURATION` from the settings line, to get codebase overview relevant to the exploration question:
+<!-- curation:off -->
 Spawn `Agent(subagent_type="Skim")` to get codebase overview relevant to the exploration question:
-<!-- learning:end -->
+<!-- curation:end -->
 
 - File structure and module boundaries in the target area
 - Entry points and key abstractions
@@ -105,11 +105,11 @@ Present findings to user. Use AskUserQuestion to offer focused follow-up explora
 
 ### Phase 6: Suggest Feature Knowledge Creation (Conditional)
 
-<!-- learning:on -->
+<!-- curation:on -->
 **Requires:** MERGED_FINDINGS, DECISIONS_CONTEXT
-<!-- learning:off -->
+<!-- curation:off -->
 **Requires:** MERGED_FINDINGS
-<!-- learning:end -->
+<!-- curation:end -->
 **Produces:** FEATURE_KNOWLEDGE_STATUS (created | skipped)
 
 1. Check if matching feature knowledge already exists by reading `{worktree}/.devflow/features/index.md` (or globbing frontmatter if absent). If covered → skip
@@ -143,11 +143,11 @@ Structured exploration findings with concrete code references:
 ```
 /explore (orchestrator)
 │
-<!-- learning:on -->
+<!-- curation:on -->
 ├─ Phase 1: Load Decisions (Orchestrator-Local)
-<!-- learning:off -->
+<!-- curation:off -->
 ├─ Phase 1: Resolve Settings
-<!-- learning:end -->
+<!-- curation:end -->
 │
 ├─ Phase 2: Orient
 │  └─ Skim agent (codebase overview)
@@ -168,11 +168,11 @@ Structured exploration findings with concrete code references:
 
 1. **Structure over browsing** - Every claim must cite file:line references
 2. **Parallel execution** - All explorers run simultaneously for speed
-<!-- learning:on -->
+<!-- curation:on -->
 3. **Knowledge-informed** - Prior decisions guide where to look; NO pre-loaded feature knowledge in sub-agents (avoids confirmation bias)
-<!-- learning:off -->
+<!-- curation:off -->
 3. **Knowledge-informed** - NO pre-loaded feature knowledge in sub-agents (avoids confirmation bias)
-<!-- learning:end -->
+<!-- curation:end -->
 4. **User-driven depth** - Present findings, then offer drill-down into specific areas
 
 ## Error Handling