@xenonbyte/da-vinci-workflow 0.2.7 → 0.2.9

package/lib/workflow-state.js

@@ -1,66 +1,116 @@
-const fs = require("fs");
 const path = require("path");
 const { auditProject } = require("./audit");
-const {
-  parseCheckpointStatusMap,
-  normalizeCheckpointLabel,
-  parseDisciplineMarkers,
-  DISCIPLINE_MARKER_NAMES
-} = require("./audit-parsers");
 const { pathExists, readTextIfExists, dedupeMessages } = require("./utils");
 const {
-  parseTasksArtifact,
   listImmediateDirs,
   hasAnyFile,
   pickLatestChange,
   detectSpecFiles
 } = require("./planning-parsers");
+const { STATUS, getStageById } = require("./workflow-contract");
+const { readCheckpointStatuses } = require("./workflow-stage");
+const {
+  buildPersistedWorkflowBaseView,
+  buildDerivedWorkflowBaseView
+} = require("./workflow-base-view");
 const {
-  STATUS,
-  CHECKPOINT_LABELS,
-  HANDOFF_GATES,
-  getStageById,
-  mergeStatuses
-} = require("./workflow-contract");
+  deriveTaskGroupMetadata,
+  deriveTaskGroupRuntimeState,
+  buildTaskGroupMetadataPayload,
+  resolvePersistedTaskGroupSeed,
+  selectFocusedTaskGroup
+} = require("./workflow-task-groups");
 const {
   selectPersistedStateForChange,
   persistDerivedWorkflowResult,
-  resolveTaskGroupMetadataPath,
   writeTaskGroupMetadata,
-  readTaskGroupMetadata,
-  digestForPath,
   sanitizePersistedNotes
 } = require("./workflow-persisted-state");
 const {
   readExecutionSignals,
-  summarizeSignalsBySurface,
-  listSignalsBySurfacePrefix
+  summarizeSignalsBySurface
 } = require("./execution-signals");
-const { evaluatePlanningSignalFreshness } = require("./planning-signal-freshness");
-const { deriveExecutionProfile } = require("./execution-profile");
 const { collectVerificationFreshness } = require("./verify");
-const { runWorktreePreflight } = require("./worktree-preflight");
+const {
+  collectPlanningSignalFreshnessState,
+  inspectDisciplineState,
+  applyWorkflowOverlays
+} = require("./workflow-overlay");
+const {
+  formatPathRef,
+  emitWorkflowDecisionTraces,
+  shouldTraceWorkflowDecisions
+} = require("./workflow-decision-trace");
 
 const MAX_REPORTED_MESSAGES = 3;
-// Task-group metadata is versioned independently from workflow route snapshots.
-const TASK_GROUP_METADATA_VERSION = 2;
-const BLOCKING_GATE_PRIORITY = Object.freeze([
-  "clarify",
-  "scenarioQuality",
-  "analyze",
-  "taskCheckpoint",
-  "stalePlanningSignal",
-  "principleInheritance",
-  "lint-tasks",
-  "lint-spec",
-  "scope-check"
-]);
-const PLANNING_SIGNAL_PROMOTION_FALLBACKS = Object.freeze({
-  "lint-spec": "breakdown",
-  "scope-check": "tasks",
-  "lint-tasks": "tasks"
+const PERSISTED_STATE_TRACE_KEYS = Object.freeze({
+  missing: "fallback_missing",
+  "parse-error": "fallback_parse_error",
+  "version-mismatch": "fallback_version_mismatch",
+  "change-missing": "fallback_change_missing",
+  "fingerprint-mismatch": "fallback_fingerprint_mismatch"
 });
 
+/**
+ * Append a workflow decision-trace record when tracing is enabled for the current run.
+ *
+ * @param {Array<object> | null} records
+ * @param {object} record
+ * @returns {void}
+ */
+function recordWorkflowDecision(records, record) {
+  if (!Array.isArray(records) || !record || typeof record !== "object") {
+    return;
+  }
+  records.push(record);
+}
+
+/**
+ * Flush decision-trace records and attach non-fatal trace diagnostics to the workflow result.
+ *
+ * @param {object} result
+ * @param {{ env?: object, surface?: string, projectRoot?: string, records?: Array<object> | null }} [options]
+ * @returns {object}
+ */
+function finalizeResultWithWorkflowDecisionTracing(result, options = {}) {
+  const traceResult = emitWorkflowDecisionTraces({
+    env: options.env,
+    surface: options.surface,
+    projectRoot: result && result.projectRoot ? result.projectRoot : options.projectRoot,
+    changeId: result ? result.changeId : null,
+    stage: result ? result.stage : "",
+    records: options.records
+  });
+  if (
+    result &&
+    typeof result === "object" &&
+    traceResult &&
+    traceResult.enabled &&
+    (traceResult.rejectedCount > 0 || traceResult.error)
+  ) {
+    result.traceDiagnostics = {
+      enabled: true,
+      written: traceResult.written,
+      rejectedCount: traceResult.rejectedCount,
+      rejections: Array.isArray(traceResult.rejections) ? traceResult.rejections : [],
+      tracePath: traceResult.tracePath,
+      error:
+        traceResult.error && traceResult.error.message
+          ? traceResult.error.message
+          : traceResult.error
+          ? String(traceResult.error)
+          : null
+    };
+  }
+  return result;
+}
+
+/**
+ * Reduce full audit payloads to the capped summary stored on workflow results.
+ *
+ * @param {object | null} result
+ * @returns {{ status: string, failures: string[], warnings: string[], notes: string[] } | null}
+ */
 function summarizeAudit(result) {
   if (!result) {
     return null;
@@ -74,439 +124,14 @@ function summarizeAudit(result) {
   };
 }
 
-function dedupeFindings(findings) {
-  findings.blockers = dedupeMessages(findings.blockers);
-  findings.warnings = dedupeMessages(findings.warnings);
-  findings.notes = dedupeMessages(findings.notes);
-}
-
-function resolveDisciplineGateMode() {
-  const strictEnv = String(process.env.DA_VINCI_DISCIPLINE_REQUIRE_APPROVAL || "").trim();
-  const strict = strictEnv === "1" || /^true$/i.test(strictEnv);
-  return {
-    strict
-  };
-}
-
-function isStrictPromotionEnabled() {
-  const raw = String(process.env.DA_VINCI_DISCIPLINE_STRICT_PROMOTION || "").trim();
-  return raw === "1" || /^true$/i.test(raw);
-}
-
-function fallbackStageIfBeyond(currentStageId, targetStageId) {
-  const current = getStageById(currentStageId);
-  const target = getStageById(targetStageId);
-  if (!current || !target) {
-    return currentStageId;
-  }
-  if (current.order > target.order) {
-    return target.id;
-  }
-  return current.id;
-}
-
-function ensureGateTracking(findings) {
-  if (!Array.isArray(findings.blockingGates)) {
-    findings.blockingGates = [];
-  }
-}
-
-function collectGateEvidenceRefs(gate) {
-  return Array.isArray(gate && gate.evidence) ? gate.evidence.slice(0, MAX_REPORTED_MESSAGES) : [];
-}
-
-function addBlockingGateRecord(findings, gateId, surface, gate, reason) {
-  ensureGateTracking(findings);
-  findings.blockingGates.push({
-    id: gateId,
-    surface,
-    reason: String(reason || "").trim(),
-    evidence: collectGateEvidenceRefs(gate)
-  });
-}
-
-function collectPlanningSignalFreshnessState(projectRoot, changeId, signalSummary) {
-  const effectiveSignalSummary =
-    signalSummary && typeof signalSummary === "object"
-      ? { ...signalSummary }
-      : {};
-  const stalePlanningSignals = {};
-
-  if (!changeId) {
-    return {
-      effectiveSignalSummary,
-      stalePlanningSignals,
-      needsRerunSurfaces: []
-    };
-  }
-
-  for (const surface of Object.keys(PLANNING_SIGNAL_PROMOTION_FALLBACKS)) {
-    const signal = effectiveSignalSummary[surface];
-    if (!signal) {
-      continue;
-    }
-    const freshness = evaluatePlanningSignalFreshness(projectRoot, {
-      changeId,
-      surface,
-      signal
-    });
-    if (!freshness.applicable || freshness.fresh) {
-      continue;
-    }
-    stalePlanningSignals[surface] = {
-      surface,
-      reasons: Array.isArray(freshness.reasons) ? freshness.reasons.slice() : [],
-      signalStatus: normalizeSignalStatus(signal.status),
-      signalTimestamp: signal && signal.timestamp ? String(signal.timestamp) : null,
-      signalTimestampMs: freshness.signalTimestampMs,
-      latestArtifactMtimeMs: freshness.latestArtifactMtimeMs,
-      latestArtifactTimestamp:
-        freshness.latestArtifactMtimeMs > 0 ? new Date(freshness.latestArtifactMtimeMs).toISOString() : null,
-      staleByMs: freshness.staleByMs
-    };
-    delete effectiveSignalSummary[surface];
-  }
-
-  return {
-    effectiveSignalSummary,
-    stalePlanningSignals,
-    needsRerunSurfaces: Object.keys(stalePlanningSignals).sort()
-  };
-}
-
-function applyPlanningSignalFreshnessFindings(stageId, findings, planningSignalFreshness) {
-  let nextStageId = stageId;
-  const strictPromotion = isStrictPromotionEnabled();
-  const stalePlanningSignals =
-    planningSignalFreshness && planningSignalFreshness.stalePlanningSignals
-      ? planningSignalFreshness.stalePlanningSignals
-      : {};
-
-  for (const surface of Object.keys(stalePlanningSignals).sort()) {
-    const freshness = stalePlanningSignals[surface];
-    const reasonText =
-      Array.isArray(freshness.reasons) && freshness.reasons.length > 0
-        ? freshness.reasons.join(", ")
-        : "unknown_staleness_reason";
-    findings.warnings.push(
-      `Stale ${surface} planning signal requires rerun before routing can rely on it (${reasonText}).`
-    );
-    if (!strictPromotion) {
-      continue;
-    }
-    findings.blockers.push(
-      `DA_VINCI_DISCIPLINE_STRICT_PROMOTION is enabled; stale ${surface} planning signal blocks promotion until ${surface} is rerun.`
-    );
-    addBlockingGateRecord(
-      findings,
-      "stalePlanningSignal",
-      surface,
-      null,
-      `strict promotion requires rerun for stale ${surface} planning signal`
-    );
-    nextStageId = fallbackStageIfBeyond(
-      nextStageId,
-      PLANNING_SIGNAL_PROMOTION_FALLBACKS[surface] || nextStageId
-    );
-  }
-
-  return nextStageId;
-}
-
-function selectBlockingGateIdentity(findings) {
-  const candidates = Array.isArray(findings && findings.blockingGates) ? findings.blockingGates : [];
-  if (candidates.length === 0) {
-    return null;
-  }
-  const sorted = candidates
-    .slice()
-    .sort((left, right) => {
-      const leftPriority = BLOCKING_GATE_PRIORITY.indexOf(left.id);
-      const rightPriority = BLOCKING_GATE_PRIORITY.indexOf(right.id);
-      const normalizedLeft = leftPriority === -1 ? Number.MAX_SAFE_INTEGER : leftPriority;
-      const normalizedRight = rightPriority === -1 ? Number.MAX_SAFE_INTEGER : rightPriority;
-      if (normalizedLeft !== normalizedRight) {
-        return normalizedLeft - normalizedRight;
-      }
-      return String(left.surface || "").localeCompare(String(right.surface || ""));
-    });
-  return sorted[0];
-}
-
-function getSignalGate(signal, gateKey) {
-  if (!signal || !signal.details || !signal.details.gates) {
-    return null;
-  }
-  const gates = signal.details.gates;
-  if (!gates || typeof gates !== "object") {
-    return null;
-  }
-  if (!gateKey) {
-    return null;
-  }
-  return gates[gateKey] && typeof gates[gateKey] === "object" ? gates[gateKey] : null;
-}
-
-function normalizeSignalStatus(status) {
-  const normalized = String(status || "").trim().toUpperCase();
-  if (normalized === STATUS.BLOCK || normalized === STATUS.WARN || normalized === STATUS.PASS) {
-    return normalized;
-  }
-  return "";
-}
-
-function statusSeverity(status) {
-  if (status === STATUS.BLOCK) {
-    return 2;
-  }
-  if (status === STATUS.WARN) {
-    return 1;
-  }
-  if (status === STATUS.PASS) {
-    return 0;
-  }
-  return -1;
-}
-
-function clampGateStatusBySignal(gateStatus, signalStatus) {
-  const normalizedGate = normalizeSignalStatus(gateStatus);
-  const normalizedSignal = normalizeSignalStatus(signalStatus);
-  if (!normalizedGate && normalizedSignal) {
-    return normalizedSignal;
-  }
-  if (normalizedGate && !normalizedSignal) {
-    return normalizedGate;
-  }
-  if (!normalizedGate && !normalizedSignal) {
-    return STATUS.PASS;
-  }
-  return statusSeverity(normalizedGate) >= statusSeverity(normalizedSignal)
-    ? normalizedGate
-    : normalizedSignal;
-}
-
-function resolveEffectiveGateStatus(gate, signal) {
-  const gateStatus = normalizeSignalStatus(gate && gate.status);
-  if (gateStatus) {
-    return gateStatus;
-  }
-  const signalStatus = normalizeSignalStatus(signal && signal.status);
-  return signalStatus || STATUS.PASS;
-}
-
-function statusTokenMatches(status, acceptedTokens) {
-  const normalized = String(status || "").trim().toUpperCase();
-  return acceptedTokens.includes(normalized);
-}
-
-function inspectDisciplineState(changeDir) {
-  const designPath = path.join(changeDir, "design.md");
-  const pencilDesignPath = path.join(changeDir, "pencil-design.md");
-  const pencilBindingsPath = path.join(changeDir, "pencil-bindings.md");
-  const tasksPath = path.join(changeDir, "tasks.md");
-  const designText = readTextIfExists(designPath);
-  const tasksText = readTextIfExists(tasksPath);
-  const designMarkers = parseDisciplineMarkers(designText);
-  const taskMarkers = parseDisciplineMarkers(tasksText);
-  const gateMode = resolveDisciplineGateMode();
-  const hasAnyMarker =
-    designMarkers.ordered.length > 0 ||
-    taskMarkers.ordered.length > 0 ||
-    designMarkers.malformed.length > 0 ||
-    taskMarkers.malformed.length > 0;
-
-  const designApproval =
-    designMarkers.markers[DISCIPLINE_MARKER_NAMES.designApproval] ||
-    taskMarkers.markers[DISCIPLINE_MARKER_NAMES.designApproval] ||
-    null;
-  const planSelfReview = taskMarkers.markers[DISCIPLINE_MARKER_NAMES.planSelfReview] || null;
-  const operatorReviewAck = taskMarkers.markers[DISCIPLINE_MARKER_NAMES.operatorReviewAck] || null;
-
-  const blockers = [];
-  const warnings = [];
-  const notes = [];
-  const designApprovalArtifacts = [
-    { label: "design.md", path: designPath },
-    { label: "pencil-design.md", path: pencilDesignPath },
-    { label: "pencil-bindings.md", path: pencilBindingsPath }
-  ];
-
-  for (const malformed of [...designMarkers.malformed, ...taskMarkers.malformed]) {
-    warnings.push(`Malformed discipline marker at line ${malformed.line}: ${malformed.reason}`);
-  }
-
-  let designApprovalState = "missing";
-  let designApprovalStale = false;
-  if (designApproval) {
-    if (!statusTokenMatches(designApproval.status, ["APPROVED", "PASS", "ACCEPTED"])) {
-      designApprovalState = "rejected";
-      blockers.push(
-        `Design approval marker is not approved (${designApproval.status}); keep workflow in tasks/design.`
-      );
-    } else {
-      designApprovalState = "approved";
-      if (designApproval.time) {
-        const approvalMs = Date.parse(designApproval.time);
-        const staleArtifacts = [];
-        if (Number.isFinite(approvalMs)) {
-          for (const artifact of designApprovalArtifacts) {
-            let artifactMtimeMs = 0;
-            try {
-              artifactMtimeMs = fs.statSync(artifact.path).mtimeMs;
-            } catch (_error) {
-              continue;
-            }
-            if (artifactMtimeMs > approvalMs) {
-              staleArtifacts.push(artifact.label);
-            }
-          }
-        }
-        if (staleArtifacts.length > 0) {
-          designApprovalState = "stale";
-          designApprovalStale = true;
-          blockers.push(
-            `Design approval marker is stale because design artifacts changed after approval timestamp: ${staleArtifacts.join(", ")}.`
-          );
-        }
-      } else {
-        warnings.push("Design approval marker is missing timestamp; staleness checks are limited.");
-      }
-    }
-  } else if (hasAnyMarker || gateMode.strict) {
-    blockers.push(
-      "Missing required design approval marker (`- design approval: APPROVED @ <ISO8601>`) for disciplined handoff."
-    );
-  } else {
-    warnings.push(
-      "Design approval marker is missing; legacy compatibility mode keeps this advisory. Set DA_VINCI_DISCIPLINE_REQUIRE_APPROVAL=1 to enforce."
-    );
-    notes.push("Legacy compatibility mode: missing discipline markers are advisory.");
-  }
-
-  if (!planSelfReview) {
-    warnings.push("Missing plan self-review marker in tasks.md (`- plan self review: PASS @ <ISO8601>`).");
-  } else if (!statusTokenMatches(planSelfReview.status, ["PASS", "APPROVED", "DONE"])) {
-    warnings.push(`Plan self-review marker is not PASS (${planSelfReview.status}).`);
-  }
-
-  if (!operatorReviewAck) {
-    warnings.push("Missing operator review acknowledgment marker in tasks.md (`- operator review ack: ACKNOWLEDGED @ <ISO8601>`).");
-  } else if (!statusTokenMatches(operatorReviewAck.status, ["ACKNOWLEDGED", "ACK", "CONFIRMED", "APPROVED"])) {
-    warnings.push(`Operator review acknowledgment marker is not acknowledged (${operatorReviewAck.status}).`);
-  }
-
-  return {
-    strictMode: gateMode.strict,
-    hasAnyMarker,
-    designApproval: {
-      state: designApprovalState,
-      stale: designApprovalStale,
-      marker: designApproval
-    },
-    planSelfReview: {
-      marker: planSelfReview
-    },
-    operatorReviewAck: {
-      marker: operatorReviewAck
-    },
-    malformed: [...designMarkers.malformed, ...taskMarkers.malformed],
-    blockers,
-    warnings,
-    notes
-  };
-}
-
-function mergeSignalBySurface(signals) {
-  const summary = {};
-  for (const signal of signals || []) {
-    const key = String(signal.surface || "").trim();
-    if (!key || summary[key]) {
-      continue;
-    }
-    summary[key] = signal;
-  }
-  return summary;
-}
-
-function applyTaskExecutionAndReviewFindings(findings, signals) {
-  const taskExecutionSignals = listSignalsBySurfacePrefix(signals, "task-execution.");
-  const taskReviewSignals = listSignalsBySurfacePrefix(signals, "task-review.");
-  const latestTaskExecution = mergeSignalBySurface(taskExecutionSignals);
-  const latestTaskReview = mergeSignalBySurface(taskReviewSignals);
-
-  for (const signal of Object.values(latestTaskExecution)) {
-    const envelope = signal.details && signal.details.envelope ? signal.details.envelope : null;
-    const outOfScopeWrites =
-      signal.details && Array.isArray(signal.details.outOfScopeWrites)
-        ? dedupeMessages(signal.details.outOfScopeWrites.map((item) => String(item || "").trim()).filter(Boolean))
-        : [];
-    const taskGroupId =
-      (envelope && envelope.taskGroupId) ||
-      String(signal.surface || "").replace(/^task-execution\./, "") ||
-      "unknown";
-    if (signal.status === STATUS.BLOCK) {
-      findings.blockers.push(`Task group ${taskGroupId} is BLOCKED in implementer status envelope.`);
-    } else if (signal.status === STATUS.WARN) {
-      findings.warnings.push(`Task group ${taskGroupId} has unresolved implementer concerns/context needs.`);
-    }
-    if (outOfScopeWrites.length > 0) {
-      findings.blockers.push(
-        `Task group ${taskGroupId} reported out-of-scope writes: ${outOfScopeWrites.join(", ")}.`
-      );
-    }
-    if (envelope && envelope.summary) {
-      findings.notes.push(`Implementer summary ${taskGroupId}: ${envelope.summary}`);
-    }
-  }
-
-  const reviewStateByGroup = {};
-  for (const signal of Object.values(latestTaskReview)) {
-    const envelope = signal.details && signal.details.envelope ? signal.details.envelope : null;
-    const taskGroupId =
-      (envelope && envelope.taskGroupId) ||
-      String(signal.surface || "").replace(/^task-review\./, "").split(".")[0] ||
-      "unknown";
-    const stage = envelope && envelope.stage ? envelope.stage : String(signal.surface || "").split(".").pop();
-    if (!reviewStateByGroup[taskGroupId]) {
-      reviewStateByGroup[taskGroupId] = {};
-    }
-    reviewStateByGroup[taskGroupId][stage] = signal.status;
-    if (signal.status === STATUS.BLOCK) {
-      findings.blockers.push(`Task review ${taskGroupId}/${stage} is BLOCK.`);
-    } else if (signal.status === STATUS.WARN) {
-      findings.warnings.push(`Task review ${taskGroupId}/${stage} is WARN and requires follow-up.`);
-    }
-  }
-
-  for (const [taskGroupId, state] of Object.entries(reviewStateByGroup)) {
-    if (state.quality && !state.spec) {
-      findings.blockers.push(
-        `Task review ordering violation for ${taskGroupId}: quality review exists without a prior spec review result.`
-      );
-      continue;
-    }
-    if (state.quality && state.spec === STATUS.WARN) {
-      findings.blockers.push(
-        `Task review ordering violation for ${taskGroupId}: quality review was recorded before spec review reached PASS.`
-      );
-      continue;
-    }
-    if (state.quality && state.spec === STATUS.BLOCK) {
-      findings.blockers.push(
-        `Task review ordering violation for ${taskGroupId}: quality review was recorded while spec review is BLOCK.`
-      );
-    }
-  }
-}
-
-function normalizeCheckpointStatus(status) {
-  const normalized = String(status || "").toUpperCase();
-  if (normalized === STATUS.PASS || normalized === STATUS.WARN || normalized === STATUS.BLOCK) {
-    return normalized;
-  }
-  return STATUS.PASS;
-}
-
+/**
+ * Collect the integrity audit with the already-computed routing signal summary preloaded.
+ *
+ * @param {string} projectRoot
+ * @param {string} workflowRoot
+ * @param {Object.<string, object>} signalSummary
+ * @returns {object | null}
+ */
 function collectIntegrityAudit(projectRoot, workflowRoot, signalSummary) {
   if (!pathExists(workflowRoot)) {
     return null;
@@ -519,6 +144,15 @@ function collectIntegrityAudit(projectRoot, workflowRoot, signalSummary) {
   );
 }
 
+/**
+ * Collect the completion audit for an active change with the already-computed routing signal summary.
+ *
+ * @param {string} projectRoot
+ * @param {string} workflowRoot
+ * @param {string | null} changeId
+ * @param {Object.<string, object>} signalSummary
+ * @returns {object | null}
+ */
 function collectCompletionAudit(projectRoot, workflowRoot, changeId, signalSummary) {
   if (!changeId || !pathExists(workflowRoot)) {
     return null;
@@ -532,306 +166,13 @@ function collectCompletionAudit(projectRoot, workflowRoot, changeId, signalSumma
   );
 }
 
-function applyAuditFindings(stageId, findings, integrityAudit, completionAudit) {
-  let nextStageId = stageId;
-
-  if (integrityAudit && integrityAudit.status === "FAIL") {
-    findings.warnings.push("Integrity audit currently reports FAIL.");
-  } else if (integrityAudit && integrityAudit.status === "WARN") {
-    findings.warnings.push("Integrity audit currently reports WARN.");
-  }
-
-  if ((nextStageId === "verify" || nextStageId === "complete") && completionAudit) {
-    if (completionAudit.status === "PASS") {
-      if (nextStageId === "verify") {
-        nextStageId = "complete";
-      }
-      findings.notes.push("Completion audit reports PASS for the active change.");
-    } else if (completionAudit.status === "WARN") {
-      findings.warnings.push("Completion audit currently reports WARN.");
-      if (nextStageId === "complete") {
-        nextStageId = "verify";
-      }
-    } else if (completionAudit.status === "FAIL") {
-      findings.blockers.push("Completion audit currently reports FAIL.");
-      if (nextStageId === "complete") {
-        nextStageId = "verify";
-      }
-    }
-  }
-
-  return nextStageId;
-}
-
-function applyExecutionSignalFindings(stageId, findings, signalSummary) {
-  let nextStageId = stageId;
-  const strictPromotion = isStrictPromotionEnabled();
-  const signalParseIssue = signalSummary["signal-file-parse"];
-  if (signalParseIssue) {
-    const warningText =
-      Array.isArray(signalParseIssue.warnings) && signalParseIssue.warnings[0]
-        ? String(signalParseIssue.warnings[0])
-        : "Malformed execution signal files were detected.";
-    findings.warnings.push(warningText);
-  }
-
-  const diffSignal = signalSummary["diff-spec"];
-  if (diffSignal && diffSignal.status && diffSignal.status !== STATUS.PASS) {
-    findings.warnings.push(`Planning diff signal diff-spec reports ${diffSignal.status}.`);
-  }
-
-  const lintSpecSignal = signalSummary["lint-spec"];
-  const lintSpecGateConfigs = [
-    { id: "principleInheritance", label: "principleInheritance", fallbackStage: "breakdown" },
-    { id: "clarify", label: "clarify", fallbackStage: "breakdown" },
-    { id: "scenarioQuality", label: "scenarioQuality", fallbackStage: "breakdown" }
-  ];
-  let lintSpecGateObserved = false;
-  let strongestLintSpecGateStatus = "";
-  for (const config of lintSpecGateConfigs) {
-    const gate = getSignalGate(lintSpecSignal, config.id);
-    if (!gate) {
-      continue;
-    }
-    lintSpecGateObserved = true;
-    const gateStatus = resolveEffectiveGateStatus(gate, lintSpecSignal);
-    if (statusSeverity(gateStatus) > statusSeverity(strongestLintSpecGateStatus)) {
-      strongestLintSpecGateStatus = gateStatus;
-    }
-    const evidenceRefs = collectGateEvidenceRefs(gate);
-    const evidenceSuffix =
-      evidenceRefs.length > 0 ? ` Evidence: ${evidenceRefs.join(", ")}` : "";
-    if (gateStatus === STATUS.BLOCK) {
-      findings.blockers.push(
-        `lint-spec gate ${config.label} is BLOCK and prevents planning promotion.${evidenceSuffix}`
-      );
-      addBlockingGateRecord(
-        findings,
-        config.id,
-        "lint-spec",
-        gate,
-        `lint-spec gate ${config.label} is BLOCK`
-      );
-      nextStageId = fallbackStageIfBeyond(nextStageId, config.fallbackStage);
-    } else if (gateStatus === STATUS.WARN) {
-      findings.warnings.push(`lint-spec gate ${config.label} is WARN.${evidenceSuffix}`);
-      if (strictPromotion) {
-        findings.blockers.push(
-          `DA_VINCI_DISCIPLINE_STRICT_PROMOTION is enabled; lint-spec gate ${config.label} WARN blocks promotion.`
-        );
-        addBlockingGateRecord(
-          findings,
-          config.id,
-          "lint-spec",
-          gate,
-          `strict promotion escalated lint-spec gate ${config.label} WARN`
-        );
-        nextStageId = fallbackStageIfBeyond(nextStageId, config.fallbackStage);
-      }
-    }
-    for (const message of Array.isArray(gate.compatibility) ? gate.compatibility : []) {
-      findings.notes.push(`lint-spec gate ${config.label} compatibility: ${message}`);
-    }
-    if (config.id === "clarify") {
-      for (const bounded of Array.isArray(gate.bounded) ? gate.bounded : []) {
-        findings.notes.push(`lint-spec gate clarify bounded ambiguity: ${bounded}`);
-      }
-    }
-  }
-  const lintSpecSignalStatus = normalizeSignalStatus(lintSpecSignal && lintSpecSignal.status);
-  if (
-    lintSpecSignal &&
-    (!lintSpecGateObserved || statusSeverity(lintSpecSignalStatus) > statusSeverity(strongestLintSpecGateStatus))
-  ) {
-    if (lintSpecSignalStatus === STATUS.BLOCK) {
-      findings.blockers.push("lint-spec signal is BLOCK.");
-      addBlockingGateRecord(
-        findings,
-        "lint-spec",
-        "lint-spec",
-        lintSpecSignal.details && lintSpecSignal.details.gates ? lintSpecSignal.details.gates : null,
-        "lint-spec signal is BLOCK"
-      );
-      nextStageId = fallbackStageIfBeyond(nextStageId, "breakdown");
-    } else if (lintSpecSignalStatus === STATUS.WARN) {
-      findings.warnings.push("lint-spec signal is WARN.");
-      if (strictPromotion) {
-        findings.blockers.push(
-          "DA_VINCI_DISCIPLINE_STRICT_PROMOTION is enabled; lint-spec WARN blocks promotion."
-        );
-        addBlockingGateRecord(
-          findings,
-          "lint-spec",
-          "lint-spec",
-          lintSpecSignal.details && lintSpecSignal.details.gates ? lintSpecSignal.details.gates : null,
-          "strict promotion escalated lint-spec WARN"
-        );
-        nextStageId = fallbackStageIfBeyond(nextStageId, "breakdown");
-      }
-    }
-  }
-
-  const analyzeSignal = signalSummary["scope-check"];
-  const analyzeGate = getSignalGate(analyzeSignal, "analyze");
-  let analyzeGateStatus = "";
-  if (analyzeGate) {
-    const evidenceRefs = collectGateEvidenceRefs(analyzeGate);
-    const evidenceSuffix =
-      evidenceRefs.length > 0 ? ` Evidence: ${evidenceRefs.join(", ")}` : "";
-    analyzeGateStatus = resolveEffectiveGateStatus(analyzeGate, analyzeSignal);
-    if (analyzeGateStatus === STATUS.BLOCK) {
-      findings.blockers.push(`scope-check gate analyze is BLOCK.${evidenceSuffix}`);
-      addBlockingGateRecord(
-        findings,
-        "analyze",
-        "scope-check",
-        analyzeGate,
-        "scope-check gate analyze is BLOCK"
-      );
-      nextStageId = fallbackStageIfBeyond(nextStageId, "tasks");
-    } else if (analyzeGateStatus === STATUS.WARN) {
-      findings.warnings.push(`scope-check gate analyze is WARN.${evidenceSuffix}`);
-      if (strictPromotion) {
-        findings.blockers.push(
-          "DA_VINCI_DISCIPLINE_STRICT_PROMOTION is enabled; scope-check gate analyze WARN blocks promotion."
-        );
-        addBlockingGateRecord(
-          findings,
-          "analyze",
-          "scope-check",
-          analyzeGate,
-          "strict promotion escalated scope-check gate analyze WARN"
-        );
-        nextStageId = fallbackStageIfBeyond(nextStageId, "tasks");
-      }
-    }
-    for (const message of Array.isArray(analyzeGate.compatibility) ? analyzeGate.compatibility : []) {
-      findings.notes.push(`scope-check gate analyze compatibility: ${message}`);
-    }
-  }
-  const analyzeSignalStatus = normalizeSignalStatus(analyzeSignal && analyzeSignal.status);
-  if (
-    analyzeSignal &&
-    (!analyzeGate || statusSeverity(analyzeSignalStatus) > statusSeverity(analyzeGateStatus))
-  ) {
-    if (analyzeSignalStatus === STATUS.BLOCK) {
-      findings.blockers.push("scope-check signal is BLOCK.");
-      addBlockingGateRecord(
-        findings,
-        "scope-check",
-        "scope-check",
-        analyzeSignal.details && analyzeSignal.details.gates ? analyzeSignal.details.gates : null,
-        "scope-check signal is BLOCK"
-      );
-      nextStageId = fallbackStageIfBeyond(nextStageId, "tasks");
-    } else if (analyzeSignalStatus === STATUS.WARN) {
-      findings.warnings.push("scope-check signal is WARN.");
-      if (strictPromotion) {
-        findings.blockers.push(
-          "DA_VINCI_DISCIPLINE_STRICT_PROMOTION is enabled; scope-check WARN blocks promotion."
-        );
-        addBlockingGateRecord(
-          findings,
-          "scope-check",
-          "scope-check",
-          analyzeSignal.details && analyzeSignal.details.gates ? analyzeSignal.details.gates : null,
-          "strict promotion escalated scope-check WARN"
-        );
-        nextStageId = fallbackStageIfBeyond(nextStageId, "tasks");
-      }
-    }
-  }
-
-  const lintTasksSignal = signalSummary["lint-tasks"];
-  const taskCheckpointGate = getSignalGate(lintTasksSignal, "taskCheckpoint");
-  const taskCheckpointGateStatus = taskCheckpointGate
-    ? resolveEffectiveGateStatus(taskCheckpointGate, lintTasksSignal)
-    : "";
-  const lintTasksSignalStatus = normalizeSignalStatus(lintTasksSignal && lintTasksSignal.status);
-  if (taskCheckpointGate && taskCheckpointGateStatus === STATUS.BLOCK) {
-    const evidenceRefs = collectGateEvidenceRefs(taskCheckpointGate);
-    const evidenceSuffix =
-      evidenceRefs.length > 0 ? ` Evidence: ${evidenceRefs.join(", ")}` : "";
-    findings.blockers.push(`lint-tasks task-checkpoint is BLOCK and prevents promotion into build.${evidenceSuffix}`);
-    addBlockingGateRecord(
-      findings,
-      "taskCheckpoint",
-      "lint-tasks",
-      taskCheckpointGate,
-      "lint-tasks task-checkpoint is BLOCK"
-    );
-    nextStageId = fallbackStageIfBeyond(nextStageId, "tasks");
-  } else if (taskCheckpointGate && taskCheckpointGateStatus === STATUS.WARN) {
-    const evidenceRefs = collectGateEvidenceRefs(taskCheckpointGate);
-    const evidenceSuffix =
-      evidenceRefs.length > 0 ? ` Evidence: ${evidenceRefs.join(", ")}` : "";
-    findings.warnings.push(`lint-tasks task-checkpoint is WARN.${evidenceSuffix}`);
-    if (strictPromotion) {
-      findings.blockers.push(
-        "DA_VINCI_DISCIPLINE_STRICT_PROMOTION is enabled; lint-tasks WARN blocks promotion into build."
-      );
-      addBlockingGateRecord(
-        findings,
-        "taskCheckpoint",
-        "lint-tasks",
-        taskCheckpointGate,
-        "strict promotion escalated lint-tasks task-checkpoint WARN"
-      );
-      nextStageId = fallbackStageIfBeyond(nextStageId, "tasks");
-    }
-  }
-  if (
-    lintTasksSignal &&
-    (!taskCheckpointGate || statusSeverity(lintTasksSignalStatus) > statusSeverity(taskCheckpointGateStatus))
-  ) {
-    if (lintTasksSignalStatus === STATUS.BLOCK) {
-      findings.blockers.push("lint-tasks signal is BLOCK.");
-      addBlockingGateRecord(
-        findings,
-        "lint-tasks",
-        "lint-tasks",
-        lintTasksSignal.details && lintTasksSignal.details.gates ? lintTasksSignal.details.gates : null,
-        "lint-tasks signal is BLOCK"
-      );
-      nextStageId = fallbackStageIfBeyond(nextStageId, "tasks");
-    } else if (lintTasksSignalStatus === STATUS.WARN) {
-      findings.warnings.push("lint-tasks signal is WARN.");
-      if (strictPromotion) {
-        findings.blockers.push(
-          "DA_VINCI_DISCIPLINE_STRICT_PROMOTION is enabled; lint-tasks WARN blocks promotion into build."
-        );
-        addBlockingGateRecord(
-          findings,
-          "lint-tasks",
-          "lint-tasks",
-          lintTasksSignal.details && lintTasksSignal.details.gates ? lintTasksSignal.details.gates : null,
-          "strict promotion escalated lint-tasks WARN"
-        );
-        nextStageId = fallbackStageIfBeyond(nextStageId, "tasks");
-      }
-    }
-  }
-  if (taskCheckpointGate) {
-    for (const message of Array.isArray(taskCheckpointGate.compatibility)
-      ? taskCheckpointGate.compatibility
-      : []) {
-      findings.notes.push(`lint-tasks gate taskCheckpoint compatibility: ${message}`);
-    }
-  }
-
-  const verificationSignal = signalSummary["verify-coverage"];
-  if (verificationSignal && verificationSignal.status === STATUS.BLOCK) {
-    findings.blockers.push("verify-coverage signal is BLOCK.");
-    if (nextStageId === "complete") {
-      nextStageId = "verify";
-    }
-  } else if (verificationSignal && verificationSignal.status === STATUS.WARN) {
-    findings.warnings.push("verify-coverage signal is WARN.");
-  }
-
-  return nextStageId;
-}
-
+/**
+ * Map the effective workflow stage to the next operator-facing route suggestion.
+ *
+ * @param {string} stageId
+ * @param {{ projectRoot?: string, changeId?: string, ambiguousChangeSelection?: boolean }} [context]
+ * @returns {{ route: string | null, command: string | null, reason: string }}
+ */
 function buildRouteRecommendation(stageId, context = {}) {
   const projectRoot = context.projectRoot || process.cwd();
   const changeId = context.changeId || "change-001";
@@ -890,872 +231,166 @@ function buildRouteRecommendation(stageId, context = {}) {
   }
 }
 
-function readCheckpointStatuses(changeDir) {
-  const collected = {};
-  const files = [
-    path.join(changeDir, "design.md"),
-    path.join(changeDir, "pencil-design.md"),
-    path.join(changeDir, "tasks.md"),
-    path.join(changeDir, "verification.md")
-  ];
-
-  for (const artifactPath of files) {
-    const text = readTextIfExists(artifactPath);
-    if (!text) {
-      continue;
-    }
-    const statuses = parseCheckpointStatusMap(text);
-    for (const [label, value] of Object.entries(statuses)) {
-      const normalized = normalizeCheckpointLabel(label);
-      if (!normalized) {
-        continue;
-      }
-      collected[normalized] = String(value || "").toUpperCase();
-    }
-  }
-
-  return collected;
-}
-
-function deriveStageFromArtifacts(artifactState, checkpointStatuses, findings) {
-  if (!artifactState.workflowRootReady) {
-    findings.blockers.push("Missing `.da-vinci/` directory.");
-    return "bootstrap";
-  }
-
-  if (!artifactState.changeSelected) {
-    findings.blockers.push("No active change selected under `.da-vinci/changes/`.");
-    return "breakdown";
-  }
-
-  if (!artifactState.proposal || artifactState.specFiles.length === 0) {
-    if (!artifactState.proposal) {
-      findings.blockers.push("Missing `proposal.md` for the active change.");
-    }
-    if (artifactState.specFiles.length === 0) {
-      findings.blockers.push("Missing `specs/*/spec.md` for the active change.");
-    }
-    return "breakdown";
-  }
-
-  if (
-    !artifactState.design ||
-    !artifactState.pencilDesign ||
-    !artifactState.pencilBindings
-  ) {
-    if (!artifactState.design) {
-      findings.blockers.push("Missing `design.md` for the active change.");
-    }
-    if (!artifactState.pencilDesign) {
-      findings.blockers.push("Missing `pencil-design.md` for the active change.");
-    }
-    if (!artifactState.pencilBindings) {
-      findings.blockers.push("Missing `pencil-bindings.md` for the active change.");
-    }
-    return "design";
-  }
-
-  const designCheckpoint = checkpointStatuses[CHECKPOINT_LABELS.DESIGN];
-  if (designCheckpoint === STATUS.BLOCK) {
-    findings.blockers.push("`design checkpoint` is BLOCK.");
-    return "design";
-  }
-  if (designCheckpoint === STATUS.WARN) {
-    findings.warnings.push("`design checkpoint` is WARN.");
-  }
-
-  const designSourceCheckpoint = checkpointStatuses[CHECKPOINT_LABELS.DESIGN_SOURCE];
-  if (designSourceCheckpoint === STATUS.BLOCK) {
-    findings.blockers.push("`design source checkpoint` is BLOCK.");
-    return "design";
-  }
-  if (designSourceCheckpoint === STATUS.WARN) {
-    findings.warnings.push("`design source checkpoint` is WARN.");
-  }
-
-  const runtimeGateCheckpoint = checkpointStatuses[CHECKPOINT_LABELS.RUNTIME_GATE];
-  if (runtimeGateCheckpoint === STATUS.BLOCK) {
-    findings.blockers.push("`mcp runtime gate` is BLOCK.");
-    return "design";
-  }
-  if (runtimeGateCheckpoint === STATUS.WARN) {
-    findings.warnings.push("`mcp runtime gate` is WARN.");
-  }
-
-  const mappingCheckpoint = checkpointStatuses[CHECKPOINT_LABELS.MAPPING];
-  if (mappingCheckpoint === STATUS.BLOCK) {
-    findings.blockers.push("`mapping checkpoint` is BLOCK.");
-    return "design";
-  }
-  if (mappingCheckpoint === STATUS.WARN) {
-    findings.warnings.push("`mapping checkpoint` is WARN.");
-  }
-
-  if (!artifactState.tasks) {
-    findings.blockers.push("Missing `tasks.md` for the active change.");
-    return "tasks";
-  }
-
-  const taskCheckpoint = checkpointStatuses[CHECKPOINT_LABELS.TASK];
-  if (taskCheckpoint === STATUS.BLOCK) {
-    findings.blockers.push("`task checkpoint` is BLOCK.");
-    return "tasks";
-  }
-  if (taskCheckpoint === STATUS.WARN) {
-    findings.warnings.push("`task checkpoint` is WARN.");
-  }
-
-  if (!artifactState.verification) {
-    findings.blockers.push("Missing `verification.md` for the active change.");
-    return "build";
-  }
-
-  return "verify";
-}
-
-function deriveTaskGroupMetadata(tasksMarkdownText, checkpointStatuses) {
-  if (!tasksMarkdownText) {
-    return [];
-  }
-
-  const taskArtifact = parseTasksArtifact(tasksMarkdownText);
-  const lines = String(tasksMarkdownText || "").replace(/\r\n?/g, "\n").split("\n");
-  const sections = [];
-  let current = null;
-  for (const line of lines) {
-    const headingMatch = line.match(/^\s{0,3}##\s+(\d+(?:\.\d+)*)\.\s+(.+)$/);
-    if (headingMatch) {
-      if (current) {
-        sections.push(current);
-      }
-      current = {
-        id: headingMatch[1],
-        title: String(headingMatch[2] || "").trim(),
-        checklistItems: []
-      };
-      continue;
-    }
-    if (!current) {
-      continue;
-    }
-    const checklistMatch = line.match(/^\s*-\s*\[([ xX])\]\s+(.+)$/);
-    if (checklistMatch) {
-      current.checklistItems.push({
-        checked: String(checklistMatch[1] || "").toLowerCase() === "x",
-        text: String(checklistMatch[2] || "").trim()
-      });
-    }
-  }
-  if (current) {
-    sections.push(current);
-  }
-
-  const normalizedTaskCheckpoint = checkpointStatuses[CHECKPOINT_LABELS.TASK] || STATUS.WARN;
-  const groupMetadataById = new Map(
-    (taskArtifact.taskGroups || []).map((group) => [
-      group.id,
-      {
-        targetFiles: Array.isArray(group.targetFiles) ? group.targetFiles : [],
-        fileReferences: Array.isArray(group.fileReferences) ? group.fileReferences : [],
-        verificationActions: Array.isArray(group.verificationActions) ? group.verificationActions : [],
-        verificationCommands: Array.isArray(group.verificationCommands) ? group.verificationCommands : [],
-        executionIntent: Array.isArray(group.executionIntent) ? group.executionIntent : [],
-        reviewIntent: group.reviewIntent === true,
-        testingIntent: group.testingIntent === true,
-        codeChangeLikely: group.codeChangeLikely === true
-      }
-    ])
-  );
-  const metadata = sections.map((section, index) => {
-    const total = section.checklistItems.length;
-    const done = section.checklistItems.filter((item) => item.checked).length;
-    const completion = total > 0 ? Math.round((done / total) * 100) : 0;
-    const sectionStatus =
-      total === 0 ? "pending" : done === 0 ? "pending" : done < total ? "in_progress" : "completed";
-    const nextAction =
-      sectionStatus === "completed"
-        ? "advance to next task group"
-        : section.checklistItems.find((item) => !item.checked)?.text || "continue group work";
-    const groupMetadata = groupMetadataById.get(section.id) || {};
-
-    return {
-      taskGroupId: section.id,
-      title: section.title,
-      status: sectionStatus,
-      completion,
-      checkpointOutcome: normalizedTaskCheckpoint,
-      evidence: section.checklistItems.filter((item) => item.checked).map((item) => item.text),
-      nextAction,
-      targetFiles: groupMetadata.targetFiles || [],
-      fileReferences: groupMetadata.fileReferences || [],
-      verificationActions: groupMetadata.verificationActions || [],
-      verificationCommands: groupMetadata.verificationCommands || [],
-      executionIntent: groupMetadata.executionIntent || [],
-      reviewIntent: groupMetadata.reviewIntent === true,
-      testingIntent: groupMetadata.testingIntent === true,
-      codeChangeLikely: groupMetadata.codeChangeLikely === true,
-      resumeCursor: {
-        groupIndex: index,
-        nextUncheckedItem:
-          section.checklistItems.find((item) => !item.checked)?.text ||
-          section.checklistItems[section.checklistItems.length - 1]?.text ||
-          null
-      }
-    };
-  });
-
-  if (metadata.length === 0 && taskArtifact.taskGroups.length > 0) {
-    return taskArtifact.taskGroups.map((group, index) => {
-      const groupMetadata = groupMetadataById.get(group.id) || {};
-      return {
-        taskGroupId: group.id,
-        title: group.title,
-        status: "pending",
-        completion: 0,
-        checkpointOutcome: normalizedTaskCheckpoint,
-        evidence: [],
-        nextAction: "start task group",
-        targetFiles: groupMetadata.targetFiles || [],
-        fileReferences: groupMetadata.fileReferences || [],
-        verificationActions: groupMetadata.verificationActions || [],
-        verificationCommands: groupMetadata.verificationCommands || [],
-        executionIntent: groupMetadata.executionIntent || [],
-        reviewIntent: groupMetadata.reviewIntent === true,
-        testingIntent: groupMetadata.testingIntent === true,
-        codeChangeLikely: groupMetadata.codeChangeLikely === true,
-        resumeCursor: {
-          groupIndex: index,
-          nextUncheckedItem: null
-        }
-      };
-    });
-  }
-
-  return metadata;
-}
-
-function normalizeTaskGroupId(value) {
-  return String(value || "").trim();
-}
-
-function normalizeResumeCursor(cursor, fallbackGroupIndex = null) {
-  const groupIndex =
-    cursor && Number.isInteger(cursor.groupIndex)
-      ? cursor.groupIndex
-      : Number.isInteger(fallbackGroupIndex)
-      ? fallbackGroupIndex
-      : null;
-  return {
-    groupIndex,
-    nextUncheckedItem:
-      cursor && Object.prototype.hasOwnProperty.call(cursor, "nextUncheckedItem")
-        ? cursor.nextUncheckedItem
-        : null
-  };
-}
-
-function normalizeTaskGroupSeedMap(taskGroups) {
-  const byId = new Map();
-  for (const group of Array.isArray(taskGroups) ? taskGroups : []) {
-    const taskGroupId = normalizeTaskGroupId(group && (group.taskGroupId || group.id));
-    if (!taskGroupId || byId.has(taskGroupId)) {
-      continue;
-    }
-    byId.set(taskGroupId, group);
-  }
-  return byId;
-}
-
-function findLatestSignalBySurface(signals, surface) {
-  const normalizedSurface = String(surface || "").trim();
-  if (!normalizedSurface) {
-    return null;
-  }
-  return (signals || []).find((signal) => String(signal.surface || "").trim() === normalizedSurface) || null;
-}
-
-function summarizeSignalIssues(signal, envelopeItems) {
-  if (!signal) {
-    return [];
-  }
-  const fromEnvelope = Array.isArray(envelopeItems) ? envelopeItems : [];
-  const fromSignal = [
-    ...(Array.isArray(signal.failures) ? signal.failures : []),
-    ...(Array.isArray(signal.warnings) ? signal.warnings : [])
-  ];
-  return dedupeMessages([...fromEnvelope, ...fromSignal].map((item) => String(item || "").trim()).filter(Boolean));
-}
-
-function buildTaskGroupImplementerState(taskGroupId, signals, fallbackState) {
-  const fallback = fallbackState && typeof fallbackState === "object" ? fallbackState : {};
-  const signal = findLatestSignalBySurface(signals, `task-execution.${taskGroupId}`);
-  const envelope = signal && signal.details && signal.details.envelope ? signal.details.envelope : null;
-  if (!signal) {
-    return {
-      present: false,
-      signalStatus: null,
-      implementerStatus: fallback.implementerStatus || null,
-      summary: fallback.summary || null,
-      changedFiles: Array.isArray(fallback.changedFiles) ? fallback.changedFiles : [],
-      testEvidence: Array.isArray(fallback.testEvidence) ? fallback.testEvidence : [],
-      concerns: Array.isArray(fallback.concerns) ? fallback.concerns : [],
-      blockers: Array.isArray(fallback.blockers) ? fallback.blockers : [],
-      outOfScopeWrites: Array.isArray(fallback.outOfScopeWrites) ? fallback.outOfScopeWrites : [],
-      recordedAt: fallback.recordedAt || null
-    };
-  }
-
-  return {
-    present: true,
-    signalStatus: signal.status || null,
-    implementerStatus: envelope && envelope.status ? envelope.status : fallback.implementerStatus || null,
-    summary: envelope && envelope.summary ? envelope.summary : fallback.summary || null,
-    changedFiles:
-      envelope && Array.isArray(envelope.changedFiles)
-        ? envelope.changedFiles
-        : Array.isArray(fallback.changedFiles)
-        ? fallback.changedFiles
-        : [],
-    testEvidence:
-      envelope && Array.isArray(envelope.testEvidence)
-        ? envelope.testEvidence
-        : Array.isArray(fallback.testEvidence)
-        ? fallback.testEvidence
-        : [],
-    concerns: summarizeSignalIssues(signal, envelope && envelope.concerns),
-    blockers: summarizeSignalIssues(signal, envelope && envelope.blockers),
-    outOfScopeWrites:
-      signal.details && Array.isArray(signal.details.outOfScopeWrites)
-        ? dedupeMessages(signal.details.outOfScopeWrites.map((item) => String(item || "").trim()).filter(Boolean))
-        : Array.isArray(fallback.outOfScopeWrites)
-        ? fallback.outOfScopeWrites
-        : [],
-    recordedAt: (envelope && envelope.recordedAt) || signal.timestamp || fallback.recordedAt || null
-  };
-}
-
-function buildTaskGroupReviewStageState(taskGroupId, stage, signals, fallbackState) {
-  const fallback = fallbackState && typeof fallbackState === "object" ? fallbackState : {};
-  const signal = findLatestSignalBySurface(signals, `task-review.${taskGroupId}.${stage}`);
-  const envelope = signal && signal.details && signal.details.envelope ? signal.details.envelope : null;
-  if (!signal) {
-    return {
-      present: false,
-      status: fallback.status || "missing",
-      summary: fallback.summary || null,
-      reviewer: fallback.reviewer || null,
-      issues: Array.isArray(fallback.issues) ? fallback.issues : [],
-      recordedAt: fallback.recordedAt || null
-    };
-  }
-
-  return {
-    present: true,
-    status: signal.status || "missing",
-    summary: envelope && envelope.summary ? envelope.summary : fallback.summary || null,
-    reviewer: envelope && envelope.reviewer ? envelope.reviewer : fallback.reviewer || null,
-    issues: summarizeSignalIssues(signal, envelope && envelope.issues),
-    recordedAt: (envelope && envelope.recordedAt) || signal.timestamp || fallback.recordedAt || null
-  };
-}
-
-function buildTaskGroupReviewState(taskGroup, signals, fallbackState) {
-  const fallback = fallbackState && typeof fallbackState === "object" ? fallbackState : {};
-  const taskGroupId = normalizeTaskGroupId(taskGroup.taskGroupId || taskGroup.id);
-  const required = taskGroup.reviewIntent === true;
-  const spec = buildTaskGroupReviewStageState(taskGroupId, "spec", signals, fallback.spec);
-  const quality = buildTaskGroupReviewStageState(taskGroupId, "quality", signals, fallback.quality);
-
-  return {
-    required,
-    ordering: required ? "spec_then_quality" : "none",
-    spec,
-    quality
-  };
-}
-
-function buildEffectiveTaskGroupState(group, planned, implementer, review) {
-  const fallbackCursor = normalizeResumeCursor(planned.resumeCursor, null);
-  const effective = {
-    status: planned.status,
-    nextAction: planned.nextAction,
-    resumeCursor: fallbackCursor,
-    source: "planned",
-    reason: "planned_checklist"
-  };
-
-  if (implementer.present && implementer.outOfScopeWrites.length > 0) {
-    return {
-      status: "blocked",
-      nextAction:
-        `resolve out-of-scope writes for task group ${group.taskGroupId}: ${implementer.outOfScopeWrites.join(", ")}`,
-      resumeCursor: {
-        groupIndex: fallbackCursor.groupIndex,
-        nextUncheckedItem: null,
-        liveFocus: "out_of_scope_write"
-      },
-      source: "implementer",
-      reason: "out_of_scope_write"
-    };
-  }
-
-  if (implementer.present && implementer.signalStatus === STATUS.BLOCK) {
-    return {
-      status: "blocked",
-      nextAction:
-        implementer.blockers[0] ||
-        implementer.summary ||
-        `resolve implementer blocker for task group ${group.taskGroupId}`,
-      resumeCursor: {
-        groupIndex: fallbackCursor.groupIndex,
-        nextUncheckedItem: null,
-        liveFocus: "implementer_block"
-      },
-      source: "implementer",
-      reason: "implementer_block"
-    };
-  }
-
-  const reviewSignalsPresent = review.spec.present || review.quality.present;
-  const plannedCompletion = Number.isFinite(Number(planned.completion))
-    ? Number(planned.completion)
-    : 0;
-  const reviewNearComplete = planned.status !== "completed" && plannedCompletion >= 75;
-  const reviewHardDue = planned.status === "completed" || reviewNearComplete;
-  const reviewContextReady = review.required && (reviewSignalsPresent || reviewHardDue || implementer.present);
-
-  if (reviewContextReady) {
-    if (
-      review.quality.present &&
-      (!review.spec.present || review.spec.status === "missing" || review.spec.status === STATUS.WARN)
-    ) {
-      return {
-        status: "blocked",
-        nextAction:
-          `remove or rerun out-of-order quality review for task group ${group.taskGroupId} after spec review PASS`,
-        resumeCursor: {
-          groupIndex: fallbackCursor.groupIndex,
-          nextUncheckedItem: null,
-          liveFocus: "review_ordering_violation"
-        },
-        source: "review",
-        reason: "review_ordering_violation"
-      };
-    }
-    if (review.spec.status === STATUS.BLOCK) {
-      return {
-        status: "blocked",
-        nextAction:
-          review.spec.issues[0] || review.spec.summary || `resolve spec review BLOCK for task group ${group.taskGroupId}`,
-        resumeCursor: {
-          groupIndex: fallbackCursor.groupIndex,
-          nextUncheckedItem: null,
-          liveFocus: "spec_review_block"
-        },
-        source: "review",
-        reason: "spec_review_block"
-      };
-    }
-    if (!review.spec.present || review.spec.status === "missing") {
-      if (reviewHardDue || reviewSignalsPresent) {
-        return {
-          status: "review_pending",
-          nextAction: `record spec review PASS or WARN for task group ${group.taskGroupId} before quality review`,
-          resumeCursor: {
-            groupIndex: fallbackCursor.groupIndex,
-            nextUncheckedItem: null,
-            liveFocus: "spec_review_missing"
-          },
-          source: "review",
-          reason: "spec_review_missing"
-        };
-      }
-    } else {
-      const specWarn = review.spec.status === STATUS.WARN;
-      if (review.quality.status === STATUS.BLOCK) {
-        return {
-          status: "blocked",
-          nextAction:
-            review.quality.issues[0] ||
-            review.quality.summary ||
-            `resolve quality review BLOCK for task group ${group.taskGroupId}`,
-          resumeCursor: {
-            groupIndex: fallbackCursor.groupIndex,
-            nextUncheckedItem: null,
-            liveFocus: "quality_review_block"
-          },
-          source: "review",
-          reason: "quality_review_block"
-        };
-      }
-      if (!review.quality.present || review.quality.status === "missing") {
-        if (reviewHardDue) {
-          return {
-            status: "review_pending",
-            nextAction: `record quality review PASS or WARN for task group ${group.taskGroupId}`,
-            resumeCursor: {
-              groupIndex: fallbackCursor.groupIndex,
-              nextUncheckedItem: null,
-              liveFocus: "quality_review_missing"
-            },
-            source: "review",
-            reason: "quality_review_missing"
-          };
-        }
-        if (specWarn) {
-          return {
-            status: "in_progress",
-            nextAction:
-              review.spec.issues[0] ||
-              review.spec.summary ||
-              `resolve spec review follow-up for task group ${group.taskGroupId}`,
-            resumeCursor: {
-              groupIndex: fallbackCursor.groupIndex,
-              nextUncheckedItem: null,
-              liveFocus: "spec_review_warn"
-            },
-            source: "review",
-            reason: "spec_review_warn"
-          };
-        }
-      } else if (review.quality.status === STATUS.WARN) {
-        return {
-          status: "in_progress",
-          nextAction:
-            review.quality.issues[0] ||
-            review.quality.summary ||
-            `resolve quality review follow-up for task group ${group.taskGroupId}`,
-          resumeCursor: {
-            groupIndex: fallbackCursor.groupIndex,
-            nextUncheckedItem: null,
-            liveFocus: "quality_review_warn"
-          },
-          source: "review",
-          reason: "quality_review_warn"
-        };
-      } else if (specWarn) {
-        return {
-          status: "in_progress",
-          nextAction:
-            review.spec.issues[0] ||
-            review.spec.summary ||
-            `resolve spec review follow-up for task group ${group.taskGroupId}`,
-          resumeCursor: {
-            groupIndex: fallbackCursor.groupIndex,
-            nextUncheckedItem: null,
-            liveFocus: "spec_review_warn"
-          },
-          source: "review",
-          reason: "spec_review_warn"
-        };
-      }
-    }
+/**
+ * Collapse findings into the top-level workflow status token.
+ *
+ * @param {{ blockers: string[], warnings: string[] }} findings
+ * @returns {string}
+ */
+function statusFromFindings(findings) {
+  if (findings.blockers.length > 0) {
+    return STATUS.BLOCK;
   }
-
-  if (implementer.present && implementer.signalStatus === STATUS.WARN) {
-    return {
-      status: "in_progress",
-      nextAction:
-        implementer.concerns[0] ||
-        implementer.summary ||
-        `resolve implementer concerns for task group ${group.taskGroupId}`,
-      resumeCursor: {
-        groupIndex: fallbackCursor.groupIndex,
-        nextUncheckedItem: null,
-        liveFocus: "implementer_warn"
-      },
-      source: "implementer",
-      reason: "implementer_warn"
-    };
+  if (findings.warnings.length > 0) {
+    return STATUS.WARN;
   }
-
-  return effective;
+  return STATUS.PASS;
 }
 
-function deriveTaskGroupRuntimeState(plannedTaskGroups, signals, seedTaskGroups) {
-  const plannedGroups = Array.isArray(plannedTaskGroups) ? plannedTaskGroups : [];
-  const seedMap = normalizeTaskGroupSeedMap(seedTaskGroups);
-
-  return plannedGroups.map((plannedGroup, index) => {
-    const taskGroupId = normalizeTaskGroupId(plannedGroup.taskGroupId || plannedGroup.id);
-    const seed = seedMap.get(taskGroupId) || {};
-    const planned = {
-      status: plannedGroup.status,
-      completion: plannedGroup.completion,
-      checkpointOutcome: plannedGroup.checkpointOutcome,
-      evidence: Array.isArray(plannedGroup.evidence) ? plannedGroup.evidence : [],
-      nextAction: plannedGroup.nextAction,
-      resumeCursor: normalizeResumeCursor(plannedGroup.resumeCursor, index)
-    };
-    const implementer = buildTaskGroupImplementerState(taskGroupId, signals, seed.implementer);
-    const review = buildTaskGroupReviewState(plannedGroup, signals, seed.review);
-    const effective = buildEffectiveTaskGroupState(plannedGroup, planned, implementer, review);
-
-    return {
-      taskGroupId,
-      title: plannedGroup.title,
-      status: effective.status,
-      completion: planned.completion,
-      checkpointOutcome: planned.checkpointOutcome,
-      evidence: planned.evidence,
-      nextAction: effective.nextAction,
-      targetFiles: Array.isArray(plannedGroup.targetFiles) ? plannedGroup.targetFiles : [],
-      fileReferences: Array.isArray(plannedGroup.fileReferences) ? plannedGroup.fileReferences : [],
-      verificationActions: Array.isArray(plannedGroup.verificationActions)
-        ? plannedGroup.verificationActions
-        : [],
-      verificationCommands: Array.isArray(plannedGroup.verificationCommands)
-        ? plannedGroup.verificationCommands
-        : [],
-      executionIntent: Array.isArray(plannedGroup.executionIntent) ? plannedGroup.executionIntent : [],
-      reviewIntent: plannedGroup.reviewIntent === true,
-      testingIntent: plannedGroup.testingIntent === true,
-      codeChangeLikely: plannedGroup.codeChangeLikely === true,
-      resumeCursor: effective.resumeCursor,
-      planned,
-      implementer,
-      review,
-      effective
-    };
+/**
+ * Convert an overlay result into the stable workflow-status result schema.
+ *
+ * @param {{
+ *   projectRoot: string,
+ *   changeId: string | null,
+ *   overlay: {
+ *     stageId: string,
+ *     findings: { blockers: string[], warnings: string[], notes: string[] },
+ *     gates: Object.<string, string>,
+ *     taskGroups: Array<object>,
+ *     executionProfile?: object,
+ *     worktreePreflight?: object | null,
+ *     blockingGate?: object | null,
+ *     needsRerunSurfaces?: string[],
+ *     stalePlanningSignals?: Object.<string, object>
+ *   },
+ *   checkpoints?: Object.<string, string>,
+ *   audits?: { integrity: object | null, completion: object | null },
+ *   routeContext?: object,
+ *   source?: string,
+ *   discipline?: object | null,
+ *   verificationFreshness?: object | null
+ * }} params
+ * @returns {object}
+ */
+function buildWorkflowResultFromOverlay(params) {
+  return buildWorkflowResult({
+    projectRoot: params.projectRoot,
+    changeId: params.changeId,
+    stageId: params.overlay.stageId,
+    findings: params.overlay.findings,
+    checkpoints: params.checkpoints || {},
+    gates: params.overlay.gates,
+    audits: params.audits || {
+      integrity: null,
+      completion: null
+    },
+    routeContext: params.routeContext,
+    source: params.source || "derived",
+    taskGroups: params.overlay.taskGroups,
+    discipline: params.discipline || null,
+    executionProfile: params.overlay.executionProfile || null,
+    worktreePreflight: params.overlay.worktreePreflight || null,
+    verificationFreshness: params.verificationFreshness || null,
+    blockingGate: params.overlay.blockingGate || null,
+    needsRerunSurfaces: params.overlay.needsRerunSurfaces,
+    stalePlanningSignals: params.overlay.stalePlanningSignals
   });
 }
 
-function buildTaskGroupMetadataPayload(changeId, checkpointStatuses, taskGroups) {
-  return {
-    version: TASK_GROUP_METADATA_VERSION,
-    changeId,
-    checkpointOutcome: checkpointStatuses[CHECKPOINT_LABELS.TASK] || STATUS.WARN,
-    taskGroups: Array.isArray(taskGroups) ? taskGroups : [],
-    updatedAt: new Date().toISOString()
-  };
-}
-
-function loadTaskGroupMetadataFromPath(targetPath) {
-  if (!targetPath || !pathExists(targetPath)) {
-    return null;
-  }
-  try {
-    return JSON.parse(readTextIfExists(targetPath));
-  } catch (_error) {
-    return null;
-  }
-}
-
-function resolvePersistedTaskGroupSeed(projectRoot, changeId, persistedRecord, plannedTaskGroups) {
-  const metadataRefs =
-    persistedRecord && persistedRecord.metadataRefs && typeof persistedRecord.metadataRefs === "object"
-      ? persistedRecord.metadataRefs
-      : {};
-  const canonicalPath =
-    metadataRefs.taskGroupsPath || resolveTaskGroupMetadataPath(projectRoot, changeId);
-  const notes = [];
-
-  if (canonicalPath && pathExists(canonicalPath)) {
-    const actualDigest = digestForPath(canonicalPath);
-    const expectedDigest = metadataRefs.taskGroupsDigest || null;
-    if (expectedDigest && actualDigest && expectedDigest !== actualDigest) {
-      notes.push("Canonical task-group runtime state digest mismatch; rebuilding task-group state from artifacts.");
-      return {
-        taskGroups: plannedTaskGroups,
-        notes
-      };
-    }
-
-    const loaded = canonicalPath === resolveTaskGroupMetadataPath(projectRoot, changeId)
-      ? readTaskGroupMetadata(projectRoot, changeId)
-      : loadTaskGroupMetadataFromPath(canonicalPath);
-    if (loaded && Array.isArray(loaded.taskGroups)) {
-      return {
-        taskGroups: loaded.taskGroups,
-        notes
-      };
-    }
-    notes.push("Canonical task-group runtime state is unreadable; rebuilding task-group state from artifacts.");
-    return {
-      taskGroups: plannedTaskGroups,
-      notes
-    };
-  }
-
-  if (Array.isArray(persistedRecord && persistedRecord.taskGroups) && persistedRecord.taskGroups.length > 0) {
-    notes.push("Using legacy embedded task-group state as migration fallback.");
-    return {
-      taskGroups: persistedRecord.taskGroups,
-      notes
-    };
-  }
-
-  notes.push("Canonical task-group runtime state is missing; rebuilding task-group state from artifacts.");
-  return {
-    taskGroups: plannedTaskGroups,
-    notes
-  };
-}
-
-function buildGatesWithLiveOverlays(baseGates, completionAudit, disciplineState, verificationFreshness) {
-  const gates = baseGates && typeof baseGates === "object" ? { ...baseGates } : {};
-  if (completionAudit) {
-    gates[HANDOFF_GATES.VERIFY_TO_COMPLETE] =
-      completionAudit.status === "PASS" ? STATUS.PASS : STATUS.WARN;
-  }
-  if (disciplineState && disciplineState.blockers.length > 0) {
-    gates[HANDOFF_GATES.TASKS_TO_BUILD] = STATUS.BLOCK;
-  }
-  if (verificationFreshness && !verificationFreshness.fresh) {
-    gates[HANDOFF_GATES.VERIFY_TO_COMPLETE] = STATUS.BLOCK;
-  }
-  return gates;
-}
-
-function finalizeWorkflowView(options = {}) {
-  const findings = {
-    blockers: Array.isArray(options.findings && options.findings.blockers)
-      ? options.findings.blockers.slice()
-      : [],
-    warnings: Array.isArray(options.findings && options.findings.warnings)
-      ? options.findings.warnings.slice()
-      : [],
-    notes: Array.isArray(options.findings && options.findings.notes)
-      ? options.findings.notes.slice()
-      : []
-  };
-  let stageId = options.stageId;
-  const integrityAudit = options.integrityAudit || null;
-  const completionAudit = options.completionAudit || null;
-  const disciplineState = options.disciplineState || null;
-  const verificationFreshness = options.verificationFreshness || null;
-  const planningSignalFreshness =
-    options.planningSignalFreshness && typeof options.planningSignalFreshness === "object"
-      ? options.planningSignalFreshness
-      : {
-          effectiveSignalSummary: options.signalSummary || {},
-          stalePlanningSignals: {},
-          needsRerunSurfaces: []
-        };
+/**
+ * Shared base-view pipeline:
+ * 1. derive task-group runtime state from the chosen base seed,
+ * 2. apply workflow overlays,
+ * 3. normalize the final workflow result shape.
+ *
+ * @param {{
+ *   projectRoot: string,
+ *   changeId: string | null,
+ *   baseView: {
+ *     source: string,
+ *     stageId: string,
+ *     findings: { blockers: string[], warnings: string[], notes: string[] },
+ *     baseGates: Object.<string, string>,
+ *     completionAudit: object | null,
+ *     taskGroupSeed: Array<object>
+ *   },
+ *   plannedTaskGroups: Array<object>,
+ *   changeSignals: Array<object>,
+ *   signalSummary: Object.<string, object>,
+ *   planningSignalFreshness: object,
+ *   integrityAudit: object | null,
+ *   disciplineState: object | null,
+ *   verificationFreshness: object | null,
+ *   hasTasksArtifact: boolean,
+ *   decisionTraceRecords: Array<object> | null,
+ *   checkpoints: Object.<string, string>,
+ *   routeContext: object
+ * }} [options]
+ * @returns {object}
+ */
+function buildWorkflowResultForBaseView(options = {}) {
   const taskGroups = deriveTaskGroupRuntimeState(
     options.plannedTaskGroups,
     options.changeSignals,
-    options.taskGroupSeed
-  );
-
-  stageId = applyAuditFindings(stageId, findings, integrityAudit, completionAudit);
-  stageId = applyPlanningSignalFreshnessFindings(stageId, findings, planningSignalFreshness);
-  stageId = applyExecutionSignalFindings(stageId, findings, planningSignalFreshness.effectiveSignalSummary || {});
-  applyTaskExecutionAndReviewFindings(findings, options.changeSignals || []);
-
-  if (disciplineState) {
-    findings.blockers.push(...disciplineState.blockers);
-    findings.warnings.push(...disciplineState.warnings);
-    findings.notes.push(...disciplineState.notes);
-    if (disciplineState.blockers.length > 0 && ["build", "verify", "complete"].includes(stageId)) {
-      stageId = options.hasTasksArtifact ? "tasks" : "design";
-    }
-  }
-
-  if (verificationFreshness && !verificationFreshness.fresh && (stageId === "verify" || stageId === "complete")) {
-    findings.blockers.push(
-      "Completion-facing routing requires fresh verification evidence; stale evidence keeps the route in verify."
-    );
-    stageId = "verify";
-  }
-
-  const gates = buildGatesWithLiveOverlays(
-    options.baseGates,
-    completionAudit,
-    disciplineState,
-    verificationFreshness
+    options.baseView.taskGroupSeed,
+    options.decisionTraceRecords,
+    recordWorkflowDecision
   );
-  const executionProfile = deriveExecutionProfile({
-    stage: stageId,
-    taskGroups
+  const overlay = applyWorkflowOverlays({
+    projectRoot: options.projectRoot,
+    changeId: options.changeId,
+    stageId: options.baseView.stageId,
+    findings: options.baseView.findings,
+    baseGates: options.baseView.baseGates,
+    taskGroups,
+    changeSignals: options.changeSignals,
+    signalSummary: options.signalSummary,
+    planningSignalFreshness: options.planningSignalFreshness,
+    integrityAudit: options.integrityAudit,
+    completionAudit: options.baseView.completionAudit,
+    disciplineState: options.disciplineState,
+    verificationFreshness: options.verificationFreshness,
+    hasTasksArtifact: options.hasTasksArtifact,
+    decisionTraceRecords: options.decisionTraceRecords,
+    recordWorkflowDecision
   });
-  let worktreePreflight = null;
-  if (options.changeId && (stageId === "build" || stageId === "verify")) {
-    worktreePreflight = runWorktreePreflight(options.projectRoot, {
-      parallelPreferred: executionProfile.mode === "bounded_parallel"
-    });
-    if (
-      executionProfile.mode === "bounded_parallel" &&
-      worktreePreflight.summary &&
-      worktreePreflight.summary.recommendedIsolation
-    ) {
-      executionProfile.effectiveMode = "serial";
-      executionProfile.rationale = dedupeMessages([
-        ...(executionProfile.rationale || []),
-        "worktree preflight recommends isolation; effective mode downgraded to serial"
-      ]);
-      findings.warnings.push(
-        "Bounded-parallel profile downgraded to serial until worktree isolation is ready or explicitly accepted."
-      );
-    }
-  }
-
-  dedupeFindings(findings);
-  const blockingGate = selectBlockingGateIdentity(findings);
 
-  return buildWorkflowResult({
+  return buildWorkflowResultFromOverlay({
     projectRoot: options.projectRoot,
     changeId: options.changeId,
-    stageId,
-    findings,
-    checkpoints: options.checkpoints || {},
-    gates,
+    checkpoints: options.checkpoints,
+    routeContext: options.routeContext,
+    source: options.baseView.source,
+    overlay,
     audits: {
-      integrity: integrityAudit,
-      completion: completionAudit
+      integrity: options.integrityAudit,
+      completion: options.baseView.completionAudit
     },
-    routeContext: options.routeContext,
-    source: options.source || "derived",
-    taskGroups,
-    discipline: disciplineState,
-    executionProfile,
-    worktreePreflight,
-    verificationFreshness,
-    blockingGate,
-    needsRerunSurfaces: planningSignalFreshness.needsRerunSurfaces,
-    stalePlanningSignals: planningSignalFreshness.stalePlanningSignals
+    discipline: options.disciplineState,
+    verificationFreshness: options.verificationFreshness
   });
 }
 
-function selectFocusedTaskGroup(taskGroups) {
-  const priority = {
-    blocked: 0,
-    review_pending: 1,
-    in_progress: 2,
-    pending: 3,
-    completed: 4
-  };
-  const groups = Array.isArray(taskGroups) ? taskGroups : [];
-  return groups
-    .slice()
-    .sort((left, right) => {
-      const leftRank = Object.prototype.hasOwnProperty.call(priority, left.status) ? priority[left.status] : 5;
-      const rightRank = Object.prototype.hasOwnProperty.call(priority, right.status) ? priority[right.status] : 5;
-      if (leftRank !== rightRank) {
-        return leftRank - rightRank;
-      }
-      const leftIndex =
-        left && left.resumeCursor && Number.isInteger(left.resumeCursor.groupIndex)
-          ? left.resumeCursor.groupIndex
-          : Number.MAX_SAFE_INTEGER;
-      const rightIndex =
-        right && right.resumeCursor && Number.isInteger(right.resumeCursor.groupIndex)
-          ? right.resumeCursor.groupIndex
-          : Number.MAX_SAFE_INTEGER;
-      return leftIndex - rightIndex;
-    })[0] || null;
-}
-
-function statusFromFindings(findings) {
-  if (findings.blockers.length > 0) {
-    return STATUS.BLOCK;
-  }
-  if (findings.warnings.length > 0) {
-    return STATUS.WARN;
-  }
-  return STATUS.PASS;
-}
-
+/**
+ * Main workflow-status orchestrator.
+ *
+ * Responsibilities:
+ * 1. resolve the active project/change context,
+ * 2. gather artifact, signal, audit, and freshness inputs,
+ * 3. choose a trusted persisted or artifact-derived base view,
+ * 4. apply runtime overlays,
+ * 5. persist refreshed derived snapshots when appropriate.
+ *
+ * @param {string} projectPathInput
+ * @param {{
+ *   changeId?: string,
+ *   staleWindowMs?: number,
+ *   env?: object,
+ *   traceSurface?: string
+ * }} [options]
+ * @returns {object}
+ */
 function deriveWorkflowStatus(projectPathInput, options = {}) {
   const projectRoot = path.resolve(projectPathInput || process.cwd());
   const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
@@ -1767,23 +402,30 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
 
   if (!pathExists(projectRoot)) {
     findings.blockers.push(`Project path does not exist: ${projectRoot}`);
-    return buildWorkflowResult({
-      projectRoot,
-      changeId: null,
-      stageId: "bootstrap",
-      findings,
-      checkpoints: {},
-      gates: {},
-      audits: {
-        integrity: null,
-        completion: null
-      },
-      routeContext: {
+    return finalizeResultWithWorkflowDecisionTracing(
+      buildWorkflowResult({
         projectRoot,
-        changeId: requestedChangeId || "change-001",
-        ambiguousChangeSelection: false
+        changeId: null,
+        stageId: "bootstrap",
+        findings,
+        checkpoints: {},
+        gates: {},
+        audits: {
+          integrity: null,
+          completion: null
+        },
+        routeContext: {
+          projectRoot,
+          changeId: requestedChangeId || "change-001",
+          ambiguousChangeSelection: false
+        }
+      }),
+      {
+        env: options.env,
+        surface: options.traceSurface,
+        records: null
       }
-    });
+    );
   }
 
   const workflowRoot = path.join(projectRoot, ".da-vinci");
@@ -1820,6 +462,13 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
   }
 
   const activeChangeId = activeChangeDir ? path.basename(activeChangeDir) : null;
+  const decisionTraceRecords =
+    shouldTraceWorkflowDecisions({
+      env: options.env,
+      surface: options.traceSurface
+    }) && !ambiguousChangeSelection
+      ? []
+      : null;
   const artifactState = {
     workflowRootReady: pathExists(workflowRoot),
     changeSelected: Boolean(activeChangeDir),
@@ -1858,15 +507,6 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
       }
     : null;
   const integrityAudit = collectIntegrityAudit(projectRoot, workflowRoot, routingSignalSummary);
-  const designCheckpointStatus = normalizeCheckpointStatus(checkpointStatuses[CHECKPOINT_LABELS.DESIGN]);
-  const designSourceCheckpointStatus = normalizeCheckpointStatus(
-    checkpointStatuses[CHECKPOINT_LABELS.DESIGN_SOURCE]
-  );
-  const runtimeGateCheckpointStatus = normalizeCheckpointStatus(
-    checkpointStatuses[CHECKPOINT_LABELS.RUNTIME_GATE]
-  );
-  const mappingCheckpointStatus = normalizeCheckpointStatus(checkpointStatuses[CHECKPOINT_LABELS.MAPPING]);
-  const taskCheckpointStatus = normalizeCheckpointStatus(checkpointStatuses[CHECKPOINT_LABELS.TASK]);
   const verificationFreshness = activeChangeId
     ? collectVerificationFreshness(projectRoot, {
         changeId: activeChangeId,
@@ -1880,27 +520,44 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
     ambiguousChangeSelection
   };
 
+  // Persisted snapshots can be reused only when the fingerprint still matches
+  // current artifact/signal truth; otherwise we fall back to the derived path.
   if (activeChangeId) {
     const persistedSelection = selectPersistedStateForChange(projectRoot, activeChangeId, {
       staleWindowMs: options.staleWindowMs
     });
     if (persistedSelection.usable && persistedSelection.changeRecord) {
+      const advisoryAgeAccepted =
+        Array.isArray(persistedSelection.advisoryNotes) && persistedSelection.advisoryNotes.length > 0;
+      recordWorkflowDecision(decisionTraceRecords, {
+        decisionFamily: "persisted_state_trust",
+        decisionKey: advisoryAgeAccepted ? "accepted_age_advisory" : "accepted_digest_match",
+        outcome: "accepted",
+        reasonSummary: advisoryAgeAccepted
+          ? "Persisted workflow snapshot remains trusted because artifact content digests still match despite advisory age."
+          : "Persisted workflow snapshot is trusted because artifact content digests still match.",
+        context: {
+          statePath: formatPathRef(projectRoot, persistedSelection.statePath),
+          persistedVersion:
+            persistedSelection.persisted && Number.isFinite(Number(persistedSelection.persisted.version))
+              ? Number(persistedSelection.persisted.version)
+              : null,
+          advisoryAge: advisoryAgeAccepted,
+          fingerprintMatched: true
+        },
+        evidenceRefs: [`state:${formatPathRef(projectRoot, persistedSelection.statePath)}`]
+      });
       const persistedRecord = persistedSelection.changeRecord;
-      const stageRecord = getStageById(persistedRecord.stage) || getStageById("bootstrap");
-      const completionAudit =
-        stageRecord.id === "verify" || stageRecord.id === "complete"
-          ? collectCompletionAudit(projectRoot, workflowRoot, activeChangeId, routingSignalSummary)
-          : null;
       const persistedSeed = resolvePersistedTaskGroupSeed(
         projectRoot,
         activeChangeId,
         persistedRecord,
-        plannedTaskGroups
+        plannedTaskGroups,
+        decisionTraceRecords,
+        recordWorkflowDecision
       );
-      return finalizeWorkflowView({
-        projectRoot,
-        changeId: activeChangeId,
-        stageId: stageRecord.id,
+      const persistedBaseView = buildPersistedWorkflowBaseView({
+        persistedRecord,
         findings: {
           blockers: Array.isArray(persistedRecord.failures) ? persistedRecord.failures.slice() : [],
           warnings: Array.isArray(persistedRecord.warnings) ? persistedRecord.warnings.slice() : [],
@@ -1911,24 +568,36 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
             "workflow-status is using trusted persisted workflow state."
           ]
         },
-        baseGates:
-          persistedRecord && persistedRecord.gates && typeof persistedRecord.gates === "object"
-            ? { ...persistedRecord.gates }
-            : {},
-        checkpoints: checkpointStatuses,
-        routeContext,
-        source: "persisted",
         taskGroupSeed: persistedSeed.taskGroups,
-        plannedTaskGroups,
-        changeSignals,
-        signalSummary,
-        planningSignalFreshness,
-        integrityAudit,
-        completionAudit,
-        disciplineState,
-        verificationFreshness,
-        hasTasksArtifact: artifactState.tasks
+        resolveCompletionAudit(stageId) {
+          return stageId === "verify" || stageId === "complete"
+            ? collectCompletionAudit(projectRoot, workflowRoot, activeChangeId, routingSignalSummary)
+            : null;
+        }
       });
+      return finalizeResultWithWorkflowDecisionTracing(
+        buildWorkflowResultForBaseView({
+          projectRoot,
+          changeId: activeChangeId,
+          baseView: persistedBaseView,
+          plannedTaskGroups,
+          changeSignals,
+          signalSummary,
+          planningSignalFreshness,
+          integrityAudit,
+          disciplineState,
+          verificationFreshness,
+          hasTasksArtifact: artifactState.tasks,
+          decisionTraceRecords,
+          checkpoints: checkpointStatuses,
+          routeContext
+        }),
+        {
+          env: options.env,
+          surface: options.traceSurface,
+          records: decisionTraceRecords
+        }
+      );
     }
 
     if (!persistedSelection.usable && persistedSelection.reason) {
@@ -1942,6 +611,22 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
       const message = reasonMessage[persistedSelection.reason];
       if (message) {
         findings.notes.push(message);
+        recordWorkflowDecision(decisionTraceRecords, {
+          decisionFamily: "persisted_state_trust",
+          decisionKey: PERSISTED_STATE_TRACE_KEYS[persistedSelection.reason],
+          outcome: "fallback",
+          reasonSummary: message,
+          context: {
+            statePath: formatPathRef(projectRoot, persistedSelection.statePath),
+            persistedVersion:
+              persistedSelection.persisted && Number.isFinite(Number(persistedSelection.persisted.version))
+                ? Number(persistedSelection.persisted.version)
+                : null,
+            fingerprintMatched:
+              persistedSelection.reason === "fingerprint-mismatch" ? false : null
+          },
+          evidenceRefs: [`state:${formatPathRef(projectRoot, persistedSelection.statePath)}`]
+        });
       }
     }
   }
@@ -1951,55 +636,36 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
     warnings: findings.warnings.slice(),
     notes: findings.notes.slice()
   };
-  const stageId = deriveStageFromArtifacts(artifactState, checkpointStatuses, baseFindings);
-  const completionAudit =
-    stageId === "verify" || stageId === "complete"
-      ? collectCompletionAudit(projectRoot, workflowRoot, activeChangeId, routingSignalSummary)
-      : null;
-  const baseGates = {
-    [HANDOFF_GATES.BREAKDOWN_TO_DESIGN]:
-      artifactState.proposal && artifactState.specFiles.length > 0 ? STATUS.PASS : STATUS.BLOCK,
-    [HANDOFF_GATES.DESIGN_TO_TASKS]: mergeStatuses([
-      artifactState.design && artifactState.pencilDesign && artifactState.pencilBindings
-        ? STATUS.PASS
-        : STATUS.BLOCK,
-      designCheckpointStatus,
-      designSourceCheckpointStatus,
-      runtimeGateCheckpointStatus,
-      mappingCheckpointStatus
-    ]),
-    [HANDOFF_GATES.TASKS_TO_BUILD]: mergeStatuses([
-      artifactState.tasks ? STATUS.PASS : STATUS.BLOCK,
-      designCheckpointStatus,
-      designSourceCheckpointStatus,
-      runtimeGateCheckpointStatus,
-      mappingCheckpointStatus,
-      taskCheckpointStatus
-    ]),
-    [HANDOFF_GATES.BUILD_TO_VERIFY]: artifactState.verification ? STATUS.PASS : STATUS.BLOCK,
-    [HANDOFF_GATES.VERIFY_TO_COMPLETE]:
-      completionAudit && completionAudit.status === "PASS" ? STATUS.PASS : STATUS.WARN
-  };
 
-  const derivedResult = finalizeWorkflowView({
-    projectRoot,
-    changeId: activeChangeId,
-    stageId,
+  // The derived path rebuilds base routing from artifacts, then re-applies
+  // live overlays before refreshing canonical task-group metadata and the
+  // persisted workflow snapshot.
+  const derivedBaseView = buildDerivedWorkflowBaseView({
+    artifactState,
+    checkpointStatuses,
     findings: baseFindings,
-    baseGates,
-    checkpoints: checkpointStatuses,
-    routeContext,
-    source: "derived",
     taskGroupSeed: plannedTaskGroups,
+    resolveCompletionAudit(stageId) {
+      return stageId === "verify" || stageId === "complete"
+        ? collectCompletionAudit(projectRoot, workflowRoot, activeChangeId, routingSignalSummary)
+        : null;
+    }
+  });
+  const derivedResult = buildWorkflowResultForBaseView({
+    projectRoot,
+    changeId: activeChangeId,
+    baseView: derivedBaseView,
     plannedTaskGroups,
     changeSignals,
     signalSummary,
     planningSignalFreshness,
     integrityAudit,
-    completionAudit,
     disciplineState,
     verificationFreshness,
-    hasTasksArtifact: artifactState.tasks
+    hasTasksArtifact: artifactState.tasks,
+    decisionTraceRecords,
+    checkpoints: checkpointStatuses,
+    routeContext
   });
 
   if (activeChangeId && !ambiguousChangeSelection) {
@@ -2069,9 +735,37 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
     ]);
   }
 
-  return derivedResult;
+  return finalizeResultWithWorkflowDecisionTracing(derivedResult, {
+    env: options.env,
+    surface: options.traceSurface,
+    records: decisionTraceRecords
+  });
 }
 
+/**
+ * Build the public workflow-status payload.
+ *
+ * @param {{
+ *   projectRoot: string,
+ *   changeId: string | null,
+ *   stageId: string,
+ *   findings: { blockers: string[], warnings: string[], notes: string[] },
+ *   checkpoints: Object.<string, string>,
+ *   gates: Object.<string, string>,
+ *   audits: { integrity: object | null, completion: object | null },
+ *   routeContext: object,
+ *   source?: string,
+ *   taskGroups?: Array<object>,
+ *   discipline?: object | null,
+ *   executionProfile?: object | null,
+ *   worktreePreflight?: object | null,
+ *   verificationFreshness?: object | null,
+ *   blockingGate?: object | null,
+ *   needsRerunSurfaces?: string[],
+ *   stalePlanningSignals?: Object.<string, object>
+ * }} params
+ * @returns {object}
+ */
 function buildWorkflowResult(params) {
   const stage = getStageById(params.stageId) || getStageById("bootstrap");
   const nextStep = buildRouteRecommendation(params.stageId, params.routeContext);
@@ -2107,6 +801,12 @@ function buildWorkflowResult(params) {
   };
 }
 
+/**
+ * Render the human-readable `workflow-status` report.
+ *
+ * @param {object} result
+ * @returns {string}
+ */
 function formatWorkflowStatusReport(result) {
   const lines = [
     "Da Vinci workflow-status",
@@ -2192,6 +892,12 @@ function formatWorkflowStatusReport(result) {
   return lines.join("\n");
 }
 
+/**
+ * Render the human-readable `next-step` report.
+ *
+ * @param {object} result
+ * @returns {string}
+ */
 function formatNextStepReport(result) {
   const lines = [
     "Da Vinci next-step",