@xenonbyte/da-vinci-workflow 0.2.5 → 0.2.7

package/lib/workflow-state.js

@@ -7,7 +7,7 @@ const {
   parseDisciplineMarkers,
   DISCIPLINE_MARKER_NAMES
 } = require("./audit-parsers");
-const { pathExists, readTextIfExists } = require("./utils");
+const { pathExists, readTextIfExists, dedupeMessages } = require("./utils");
 const {
   parseTasksArtifact,
   listImmediateDirs,
@@ -25,8 +25,10 @@ const {
 const {
   selectPersistedStateForChange,
   persistDerivedWorkflowResult,
+  resolveTaskGroupMetadataPath,
   writeTaskGroupMetadata,
   readTaskGroupMetadata,
+  digestForPath,
   sanitizePersistedNotes
 } = require("./workflow-persisted-state");
 const {
@@ -34,11 +36,30 @@ const {
   summarizeSignalsBySurface,
   listSignalsBySurfacePrefix
 } = require("./execution-signals");
+const { evaluatePlanningSignalFreshness } = require("./planning-signal-freshness");
 const { deriveExecutionProfile } = require("./execution-profile");
 const { collectVerificationFreshness } = require("./verify");
 const { runWorktreePreflight } = require("./worktree-preflight");
 
 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"
+});
 
 function summarizeAudit(result) {
   if (!result) {
@@ -53,10 +74,6 @@ function summarizeAudit(result) {
   };
 }
 
-function dedupeMessages(items) {
-  return Array.from(new Set((items || []).filter(Boolean)));
-}
-
 function dedupeFindings(findings) {
   findings.blockers = dedupeMessages(findings.blockers);
   findings.warnings = dedupeMessages(findings.warnings);
@@ -71,6 +88,212 @@ function resolveDisciplineGateMode() {
   };
 }
 
+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);
@@ -213,6 +436,10 @@ function applyTaskExecutionAndReviewFindings(findings, signals) {
 
   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\./, "") ||
@@ -222,6 +449,11 @@ function applyTaskExecutionAndReviewFindings(findings, signals) {
     } 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}`);
     }
@@ -247,9 +479,21 @@ function applyTaskExecutionAndReviewFindings(findings, signals) {
   }
 
   for (const [taskGroupId, state] of Object.entries(reviewStateByGroup)) {
-    if (state.quality && state.quality === STATUS.PASS && state.spec !== STATUS.PASS) {
+    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 passed before spec review PASS.`
+        `Task review ordering violation for ${taskGroupId}: quality review was recorded while spec review is BLOCK.`
       );
     }
   }
@@ -321,6 +565,7 @@ function applyAuditFindings(stageId, findings, integrityAudit, completionAudit)
 
 function applyExecutionSignalFindings(stageId, findings, signalSummary) {
   let nextStageId = stageId;
+  const strictPromotion = isStrictPromotionEnabled();
   const signalParseIssue = signalSummary["signal-file-parse"];
   if (signalParseIssue) {
     const warningText =
@@ -335,22 +580,242 @@ function applyExecutionSignalFindings(stageId, findings, signalSummary) {
     findings.warnings.push(`Planning diff signal diff-spec reports ${diffSignal.status}.`);
   }
 
-  const lintTasksSignal = signalSummary["lint-tasks"];
-  const strictPromotion =
-    String(process.env.DA_VINCI_DISCIPLINE_STRICT_PROMOTION || "").trim() === "1" ||
-    /^true$/i.test(String(process.env.DA_VINCI_DISCIPLINE_STRICT_PROMOTION || "").trim());
-  if (lintTasksSignal && lintTasksSignal.status === STATUS.BLOCK) {
-    findings.blockers.push("lint-tasks signal is BLOCK and prevents promotion into build.");
-    if (nextStageId === "build" || nextStageId === "verify" || nextStageId === "complete") {
-      nextStageId = "tasks";
+  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}`);
     }
-  } else if (lintTasksSignal && lintTasksSignal.status === STATUS.WARN) {
-    findings.warnings.push("lint-tasks signal is WARN.");
-    if (strictPromotion && (nextStageId === "build" || nextStageId === "verify" || nextStageId === "complete")) {
+  }
+  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."
       );
-      nextStageId = "tasks";
+      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}`);
     }
   }
 
@@ -669,6 +1134,618 @@ function deriveTaskGroupMetadata(tasksMarkdownText, checkpointStatuses) {
   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"
+        };
+      }
+    }
+  }
+
+  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"
+    };
+  }
+
+  return effective;
+}
+
+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
+    };
+  });
+}
+
+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: []
+        };
+  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
+  );
+  const executionProfile = deriveExecutionProfile({
+    stage: stageId,
+    taskGroups
+  });
+  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({
+    projectRoot: options.projectRoot,
+    changeId: options.changeId,
+    stageId,
+    findings,
+    checkpoints: options.checkpoints || {},
+    gates,
+    audits: {
+      integrity: integrityAudit,
+      completion: completionAudit
+    },
+    routeContext: options.routeContext,
+    source: options.source || "derived",
+    taskGroups,
+    discipline: disciplineState,
+    executionProfile,
+    worktreePreflight,
+    verificationFreshness,
+    blockingGate,
+    needsRerunSurfaces: planningSignalFreshness.needsRerunSurfaces,
+    stalePlanningSignals: planningSignalFreshness.stalePlanningSignals
+  });
+}
+
+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;
@@ -690,11 +1767,10 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
 
   if (!pathExists(projectRoot)) {
     findings.blockers.push(`Project path does not exist: ${projectRoot}`);
-    const stageId = "bootstrap";
     return buildWorkflowResult({
       projectRoot,
       changeId: null,
-      stageId,
+      stageId: "bootstrap",
       findings,
       checkpoints: {},
       gates: {},
@@ -737,9 +1813,7 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
     findings.notes.push(`Available change ids: ${changeIds.join(", ")}`);
     activeChangeDir = pickLatestChange(changeDirs);
     if (activeChangeDir) {
-      findings.notes.push(
-        `Latest inferred change for context only: ${path.basename(activeChangeDir)}`
-      );
+      findings.notes.push(`Latest inferred change for context only: ${path.basename(activeChangeDir)}`);
     }
   } else {
     findings.blockers.push("No non-empty change directory found under `.da-vinci/changes/`.");
@@ -760,12 +1834,19 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
 
   const tasksArtifactText = activeChangeDir ? readTextIfExists(path.join(activeChangeDir, "tasks.md")) : "";
   const checkpointStatuses = activeChangeDir ? readCheckpointStatuses(activeChangeDir) : {};
+  const plannedTaskGroups = deriveTaskGroupMetadata(tasksArtifactText, checkpointStatuses);
   const changeSignals = activeChangeId
     ? readExecutionSignals(projectRoot, {
         changeId: activeChangeId
       })
     : [];
   const signalSummary = summarizeSignalsBySurface(changeSignals);
+  const planningSignalFreshness = collectPlanningSignalFreshnessState(
+    projectRoot,
+    activeChangeId,
+    signalSummary
+  );
+  const routingSignalSummary = planningSignalFreshness.effectiveSignalSummary;
   const disciplineState = activeChangeDir ? inspectDisciplineState(activeChangeDir) : null;
   const freshnessArtifactPaths = activeChangeDir
     ? {
@@ -776,7 +1857,7 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
         verificationPath: path.join(activeChangeDir, "verification.md")
       }
     : null;
-  const integrityAudit = collectIntegrityAudit(projectRoot, workflowRoot, signalSummary);
+  const integrityAudit = collectIntegrityAudit(projectRoot, workflowRoot, routingSignalSummary);
   const designCheckpointStatus = normalizeCheckpointStatus(checkpointStatuses[CHECKPOINT_LABELS.DESIGN]);
   const designSourceCheckpointStatus = normalizeCheckpointStatus(
     checkpointStatuses[CHECKPOINT_LABELS.DESIGN_SOURCE]
@@ -786,6 +1867,18 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
   );
   const mappingCheckpointStatus = normalizeCheckpointStatus(checkpointStatuses[CHECKPOINT_LABELS.MAPPING]);
   const taskCheckpointStatus = normalizeCheckpointStatus(checkpointStatuses[CHECKPOINT_LABELS.TASK]);
+  const verificationFreshness = activeChangeId
+    ? collectVerificationFreshness(projectRoot, {
+        changeId: activeChangeId,
+        resolved: { changeDir: activeChangeDir },
+        artifactPaths: freshnessArtifactPaths
+      })
+    : null;
+  const routeContext = {
+    projectRoot,
+    changeId: activeChangeId || requestedChangeId || "change-001",
+    ambiguousChangeSelection
+  };
 
   if (activeChangeId) {
     const persistedSelection = selectPersistedStateForChange(projectRoot, activeChangeId, {
@@ -794,123 +1887,47 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
     if (persistedSelection.usable && persistedSelection.changeRecord) {
       const persistedRecord = persistedSelection.changeRecord;
       const stageRecord = getStageById(persistedRecord.stage) || getStageById("bootstrap");
-      const persistedTaskMetadata = readTaskGroupMetadata(projectRoot, activeChangeId);
-      const persistedFindings = {
-        blockers: Array.isArray(persistedRecord.failures) ? persistedRecord.failures.slice() : [],
-        warnings: Array.isArray(persistedRecord.warnings) ? persistedRecord.warnings.slice() : [],
-        notes: sanitizePersistedNotes(persistedRecord.notes)
-      };
-      let persistedStageId = stageRecord.id;
-      const persistedNeedsCompletionAudit =
-        persistedStageId === "verify" || persistedStageId === "complete";
-      const completionAudit = persistedNeedsCompletionAudit
-        ? collectCompletionAudit(projectRoot, workflowRoot, activeChangeId, signalSummary)
-        : null;
-      persistedStageId = applyAuditFindings(
-        persistedStageId,
-        persistedFindings,
-        integrityAudit,
-        completionAudit
-      );
-      persistedStageId = applyExecutionSignalFindings(
-        persistedStageId,
-        persistedFindings,
-        signalSummary
+      const completionAudit =
+        stageRecord.id === "verify" || stageRecord.id === "complete"
+          ? collectCompletionAudit(projectRoot, workflowRoot, activeChangeId, routingSignalSummary)
+          : null;
+      const persistedSeed = resolvePersistedTaskGroupSeed(
+        projectRoot,
+        activeChangeId,
+        persistedRecord,
+        plannedTaskGroups
       );
-      applyTaskExecutionAndReviewFindings(persistedFindings, changeSignals);
-      if (disciplineState) {
-        persistedFindings.blockers.push(...disciplineState.blockers);
-        persistedFindings.warnings.push(...disciplineState.warnings);
-        persistedFindings.notes.push(...disciplineState.notes);
-        if (disciplineState.blockers.length > 0 && ["build", "verify", "complete"].includes(persistedStageId)) {
-          persistedStageId = artifactState.tasks ? "tasks" : "design";
-        }
-      }
-
-      const verificationFreshness = activeChangeId
-        ? collectVerificationFreshness(projectRoot, {
-            changeId: activeChangeId,
-            resolved: { changeDir: activeChangeDir },
-            artifactPaths: freshnessArtifactPaths
-          })
-        : null;
-      if (
-        verificationFreshness &&
-        !verificationFreshness.fresh &&
-        (persistedStageId === "verify" || persistedStageId === "complete")
-      ) {
-        persistedFindings.blockers.push(
-          "Completion-facing routing requires fresh verification evidence; stale evidence keeps the route in verify."
-        );
-        persistedStageId = "verify";
-      }
-      persistedFindings.notes.push("workflow-status is using trusted persisted workflow state.");
-      dedupeFindings(persistedFindings);
-
-      const persistedGates =
-        persistedRecord && persistedRecord.gates && typeof persistedRecord.gates === "object"
-          ? { ...persistedRecord.gates }
-          : {};
-      if (completionAudit) {
-        persistedGates[HANDOFF_GATES.VERIFY_TO_COMPLETE] =
-          completionAudit.status === "PASS" ? STATUS.PASS : STATUS.WARN;
-      }
-      if (disciplineState && disciplineState.blockers.length > 0) {
-        persistedGates[HANDOFF_GATES.TASKS_TO_BUILD] = STATUS.BLOCK;
-      }
-      if (verificationFreshness && !verificationFreshness.fresh) {
-        persistedGates[HANDOFF_GATES.VERIFY_TO_COMPLETE] = STATUS.BLOCK;
-      }
-      const persistedTaskGroups =
-        persistedTaskMetadata && Array.isArray(persistedTaskMetadata.taskGroups)
-          ? persistedTaskMetadata.taskGroups
-          : Array.isArray(persistedRecord.taskGroups)
-          ? persistedRecord.taskGroups
-          : [];
-      const executionProfile = deriveExecutionProfile({
-        stage: persistedStageId,
-        taskGroups: persistedTaskGroups
-      });
-      let worktreePreflight = null;
-      if (activeChangeId && (persistedStageId === "build" || persistedStageId === "verify")) {
-        worktreePreflight = runWorktreePreflight(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"
-          ]);
-        }
-      }
-
-      return buildWorkflowResult({
+      return finalizeWorkflowView({
         projectRoot,
         changeId: activeChangeId,
-        stageId: persistedStageId,
-        findings: persistedFindings,
-        checkpoints: checkpointStatuses,
-        gates: persistedGates,
-        audits: {
-          integrity: integrityAudit,
-          completion: completionAudit
-        },
-        routeContext: {
-          projectRoot,
-          changeId: activeChangeId,
-          ambiguousChangeSelection
+        stageId: stageRecord.id,
+        findings: {
+          blockers: Array.isArray(persistedRecord.failures) ? persistedRecord.failures.slice() : [],
+          warnings: Array.isArray(persistedRecord.warnings) ? persistedRecord.warnings.slice() : [],
+          notes: [
+            ...sanitizePersistedNotes(persistedRecord.notes),
+            ...(Array.isArray(persistedSelection.advisoryNotes) ? persistedSelection.advisoryNotes : []),
+            ...persistedSeed.notes,
+            "workflow-status is using trusted persisted workflow state."
+          ]
         },
+        baseGates:
+          persistedRecord && persistedRecord.gates && typeof persistedRecord.gates === "object"
+            ? { ...persistedRecord.gates }
+            : {},
+        checkpoints: checkpointStatuses,
+        routeContext,
         source: "persisted",
-        taskGroups: persistedTaskGroups,
-        discipline: disciplineState,
-        executionProfile,
-        worktreePreflight,
-        verificationFreshness
+        taskGroupSeed: persistedSeed.taskGroups,
+        plannedTaskGroups,
+        changeSignals,
+        signalSummary,
+        planningSignalFreshness,
+        integrityAudit,
+        completionAudit,
+        disciplineState,
+        verificationFreshness,
+        hasTasksArtifact: artifactState.tasks
       });
     }
 
@@ -920,8 +1937,6 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
         "parse-error": "Persisted workflow state is unreadable; deriving from artifacts.",
         "version-mismatch": "Persisted workflow state version mismatch; deriving from artifacts.",
         "change-missing": "Persisted workflow state has no entry for this change; deriving from artifacts.",
-        "invalid-timestamp": "Persisted workflow state timestamp invalid; deriving from artifacts.",
-        "time-stale": "Persisted workflow state is stale by time; deriving from artifacts.",
         "fingerprint-mismatch": "Persisted workflow state conflicts with artifact truth; deriving from artifacts."
       };
       const message = reasonMessage[persistedSelection.reason];
@@ -931,38 +1946,17 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
     }
   }
 
-  let stageId = deriveStageFromArtifacts(artifactState, checkpointStatuses, findings);
-  const needsCompletionAudit = stageId === "verify" || stageId === "complete";
-  const completionAudit = needsCompletionAudit
-    ? collectCompletionAudit(projectRoot, workflowRoot, activeChangeId, signalSummary)
-    : null;
-  stageId = applyAuditFindings(stageId, findings, integrityAudit, completionAudit);
-  stageId = applyExecutionSignalFindings(stageId, findings, signalSummary);
-  applyTaskExecutionAndReviewFindings(findings, 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 = artifactState.tasks ? "tasks" : "design";
-    }
-  }
-
-  const verificationFreshness = activeChangeId
-    ? collectVerificationFreshness(projectRoot, {
-        changeId: activeChangeId,
-        resolved: { changeDir: activeChangeDir },
-        artifactPaths: freshnessArtifactPaths
-      })
-    : null;
-  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 = {
+  const baseFindings = {
+    blockers: findings.blockers.slice(),
+    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([
@@ -986,90 +1980,72 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
     [HANDOFF_GATES.VERIFY_TO_COMPLETE]:
       completionAudit && 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;
-  }
-
-  const derivedTaskGroups = deriveTaskGroupMetadata(tasksArtifactText, checkpointStatuses);
-  const executionProfile = deriveExecutionProfile({
-    stage: stageId,
-    taskGroups: derivedTaskGroups
-  });
-  let worktreePreflight = null;
-  if (activeChangeId && (stageId === "build" || stageId === "verify")) {
-    worktreePreflight = runWorktreePreflight(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."
-      );
-    }
-  }
-  if (activeChangeId && !ambiguousChangeSelection && derivedTaskGroups.length > 0) {
-    const metadataPayload = {
-      version: 1,
-      changeId: activeChangeId,
-      checkpointOutcome: checkpointStatuses[CHECKPOINT_LABELS.TASK] || STATUS.WARN,
-      taskGroups: derivedTaskGroups,
-      updatedAt: new Date().toISOString()
-    };
-    const metadataPath = writeTaskGroupMetadata(projectRoot, activeChangeId, metadataPayload);
-    if (metadataPath) {
-      findings.notes.push(`Task-group metadata refreshed: ${metadataPath}`);
-    }
-  } else if (activeChangeId && ambiguousChangeSelection && derivedTaskGroups.length > 0) {
-    findings.notes.push(
-      "Skipped task-group metadata persistence because change selection is ambiguous."
-    );
-  }
-  dedupeFindings(findings);
 
-  const derivedResult = buildWorkflowResult({
+  const derivedResult = finalizeWorkflowView({
     projectRoot,
     changeId: activeChangeId,
     stageId,
-    findings,
+    findings: baseFindings,
+    baseGates,
     checkpoints: checkpointStatuses,
-    gates,
-    audits: {
-      integrity: integrityAudit,
-      completion: completionAudit
-    },
-    routeContext: {
-      projectRoot,
-      changeId: activeChangeId || requestedChangeId || "change-001",
-      ambiguousChangeSelection
-    },
-    taskGroups: derivedTaskGroups,
-    discipline: disciplineState,
-    executionProfile,
-    worktreePreflight,
-    verificationFreshness
+    routeContext,
+    source: "derived",
+    taskGroupSeed: plannedTaskGroups,
+    plannedTaskGroups,
+    changeSignals,
+    signalSummary,
+    planningSignalFreshness,
+    integrityAudit,
+    completionAudit,
+    disciplineState,
+    verificationFreshness,
+    hasTasksArtifact: artifactState.tasks
   });
 
   if (activeChangeId && !ambiguousChangeSelection) {
+    let metadataRef = {
+      taskGroupsPath: null,
+      taskGroupsDigest: null
+    };
+    try {
+      const metadataRecord = writeTaskGroupMetadata(
+        projectRoot,
+        activeChangeId,
+        buildTaskGroupMetadataPayload(activeChangeId, checkpointStatuses, derivedResult.taskGroups)
+      );
+      if (metadataRecord && metadataRecord.path) {
+        metadataRef = {
+          taskGroupsPath: metadataRecord.path,
+          taskGroupsDigest: metadataRecord.digest || null
+        };
+        derivedResult.notes = dedupeMessages([
+          ...derivedResult.notes,
+          `Task-group metadata refreshed: ${metadataRecord.path}`
+        ]);
+      }
+    } catch (error) {
+      derivedResult.warnings = dedupeMessages([
+        ...derivedResult.warnings,
+        `Failed to persist canonical task-group metadata: ${
+          error && error.message ? error.message : "unknown write error"
+        }`
+      ]);
+      if (derivedResult.checkpointState === STATUS.PASS) {
+        derivedResult.checkpointState = STATUS.WARN;
+      }
+      if (derivedResult.status === STATUS.PASS) {
+        derivedResult.status = STATUS.WARN;
+      }
+    }
+
     try {
       persistDerivedWorkflowResult(projectRoot, activeChangeId, derivedResult, {
-        metadataRefs: {
-          taskGroupsPath: activeChangeId
-            ? path.join(projectRoot, ".da-vinci", "state", "task-groups", `${activeChangeId}.json`)
-            : null
-        }
+        metadataRefs: metadataRef
       });
-      derivedResult.notes.push("workflow-status persisted a fresh derived workflow snapshot.");
+      derivedResult.notes = dedupeMessages([
+        ...derivedResult.notes,
+        "workflow-status persisted a fresh derived workflow snapshot."
+      ]);
     } catch (error) {
       const message =
         error && error.message
@@ -1121,7 +2097,13 @@ function buildWorkflowResult(params) {
     discipline: params.discipline || null,
     executionProfile: params.executionProfile || null,
     worktreePreflight: params.worktreePreflight || null,
-    verificationFreshness: params.verificationFreshness || null
+    verificationFreshness: params.verificationFreshness || null,
+    blockingGate: params.blockingGate || null,
+    needsRerunSurfaces: Array.isArray(params.needsRerunSurfaces) ? params.needsRerunSurfaces : [],
+    stalePlanningSignals:
+      params.stalePlanningSignals && typeof params.stalePlanningSignals === "object"
+        ? params.stalePlanningSignals
+        : {}
   };
 }
 
@@ -1142,6 +2124,12 @@ function formatWorkflowStatusReport(result) {
   } else {
     lines.push("Next route: none");
   }
+  if (result.blockingGate && result.blockingGate.id) {
+    lines.push(`Blocking gate: ${result.blockingGate.id} (${result.blockingGate.surface || "unknown"})`);
+  }
+  if (Array.isArray(result.needsRerunSurfaces) && result.needsRerunSurfaces.length > 0) {
+    lines.push(`Needs rerun surfaces: ${result.needsRerunSurfaces.join(", ")}`);
+  }
 
   if (result.discipline && result.discipline.designApproval) {
     lines.push(`Discipline design approval: ${result.discipline.designApproval.state}`);
@@ -1196,7 +2184,7 @@ function formatWorkflowStatusReport(result) {
     lines.push("Task-group metadata:");
     for (const group of result.taskGroups) {
       lines.push(
-        `- ${group.taskGroupId || group.id || "group"}: ${group.status || "unknown"} (${group.completion || 0}%)`
+        `- ${group.taskGroupId || group.id || "group"}: ${group.status || "unknown"} (${group.completion || 0}%) -> ${group.nextAction || "continue"}`
       );
     }
   }
@@ -1222,6 +2210,12 @@ function formatNextStepReport(result) {
   if (result.nextStep.reason) {
     lines.push(`Reason: ${result.nextStep.reason}`);
   }
+  if (result.blockingGate && result.blockingGate.id) {
+    lines.push(`Blocking gate: ${result.blockingGate.id} (${result.blockingGate.surface || "unknown"})`);
+  }
+  if (Array.isArray(result.needsRerunSurfaces) && result.needsRerunSurfaces.length > 0) {
+    lines.push(`Needs rerun surfaces: ${result.needsRerunSurfaces.join(", ")}`);
+  }
   if (result.executionProfile) {
     lines.push(
       `Execution profile: ${result.executionProfile.mode}${
@@ -1238,9 +2232,7 @@ function formatNextStepReport(result) {
     lines.push("Completion evidence is stale; stay in verify until fresh evidence is recorded.");
   }
   if (Array.isArray(result.taskGroups) && result.taskGroups.length > 0) {
-    const active =
-      result.taskGroups.find((group) => group.status === "in_progress") ||
-      result.taskGroups.find((group) => group.status === "pending");
+    const active = selectFocusedTaskGroup(result.taskGroups);
     if (active) {
       lines.push(`Task-group focus: ${active.taskGroupId || active.id} -> ${active.nextAction || "continue"}`);
     }