@xenonbyte/da-vinci-workflow 0.2.6 → 0.2.8

package/lib/workflow-state.js

@@ -25,6 +25,7 @@ const {
 const {
   selectPersistedStateForChange,
   persistDerivedWorkflowResult,
+  resolveWorkflowStatePath,
   resolveTaskGroupMetadataPath,
   writeTaskGroupMetadata,
   readTaskGroupMetadata,
@@ -40,10 +41,38 @@ const { evaluatePlanningSignalFreshness } = require("./planning-signal-freshness
 const { deriveExecutionProfile } = require("./execution-profile");
 const { collectVerificationFreshness } = require("./verify");
 const { runWorktreePreflight } = require("./worktree-preflight");
+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 TRACEABLE_TASK_GROUP_FOCUS_REASONS = new Set([
+  "implementer_block",
+  "implementer_warn",
+  "spec_review_missing",
+  "spec_review_block",
+  "spec_review_warn",
+  "quality_review_missing",
+  "quality_review_block",
+  "quality_review_warn"
+]);
+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"
+});
+const TASK_GROUP_SEED_TRACE_KEYS = Object.freeze({
+  missing: "seed_missing",
+  unreadable: "seed_unreadable",
+  "digest-mismatch": "seed_digest_mismatch",
+  legacy: "seed_legacy_embedded"
+});
 const BLOCKING_GATE_PRIORITY = Object.freeze([
   "clarify",
   "scenarioQuality",
@@ -61,6 +90,99 @@ const PLANNING_SIGNAL_PROMOTION_FALLBACKS = Object.freeze({
   "lint-tasks": "tasks"
 });
 
+function recordWorkflowDecision(records, record) {
+  if (!Array.isArray(records) || !record || typeof record !== "object") {
+    return;
+  }
+  records.push(record);
+}
+
+function buildTaskGroupFocusEvidenceRefs(taskGroupId, reason) {
+  if (reason === "implementer_block" || reason === "implementer_warn") {
+    return [`signal:task-execution.${taskGroupId}`];
+  }
+  if (
+    reason === "spec_review_block" ||
+    reason === "spec_review_warn"
+  ) {
+    return [`signal:task-review.${taskGroupId}.spec`];
+  }
+  if (
+    reason === "quality_review_block" ||
+    reason === "quality_review_warn"
+  ) {
+    return [`signal:task-review.${taskGroupId}.quality`];
+  }
+  return [];
+}
+
+function buildTaskGroupFocusReasonSummary(taskGroupId, reason) {
+  switch (reason) {
+    case "implementer_block":
+      return `Implementer BLOCK overrides planned checklist focus for task group ${taskGroupId}.`;
+    case "implementer_warn":
+      return `Implementer WARN overrides planned checklist focus for task group ${taskGroupId}.`;
+    case "spec_review_missing":
+      return `Missing spec review takes focus over planned checklist work for task group ${taskGroupId}.`;
+    case "spec_review_block":
+      return `Spec review BLOCK takes focus over planned checklist work for task group ${taskGroupId}.`;
+    case "spec_review_warn":
+      return `Spec review WARN follow-up takes focus over planned checklist work for task group ${taskGroupId}.`;
+    case "quality_review_missing":
+      return `Missing quality review takes focus over planned checklist work for task group ${taskGroupId}.`;
+    case "quality_review_block":
+      return `Quality review BLOCK takes focus over planned checklist work for task group ${taskGroupId}.`;
+    case "quality_review_warn":
+      return `Quality review WARN follow-up takes focus over planned checklist work for task group ${taskGroupId}.`;
+    default:
+      return "";
+  }
+}
+
+function collectVerificationFreshnessEvidenceRefs(verificationFreshness) {
+  const surfaces =
+    verificationFreshness && verificationFreshness.surfaces && typeof verificationFreshness.surfaces === "object"
+      ? verificationFreshness.surfaces
+      : {};
+  return Object.keys(surfaces)
+    .filter((surface) => surfaces[surface] && surfaces[surface].stale && surfaces[surface].present)
+    .sort()
+    .map((surface) => `signal:${surface}`);
+}
+
+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;
+}
+
 function summarizeAudit(result) {
   if (!result) {
     return null;
@@ -174,7 +296,7 @@ function collectPlanningSignalFreshnessState(projectRoot, changeId, signalSummar
   };
 }
 
-function applyPlanningSignalFreshnessFindings(stageId, findings, planningSignalFreshness) {
+function applyPlanningSignalFreshnessFindings(stageId, findings, planningSignalFreshness, decisionTraceRecords) {
   let nextStageId = stageId;
   const strictPromotion = isStrictPromotionEnabled();
   const stalePlanningSignals =
@@ -192,6 +314,20 @@ function applyPlanningSignalFreshnessFindings(stageId, findings, planningSignalF
       `Stale ${surface} planning signal requires rerun before routing can rely on it (${reasonText}).`
     );
     if (!strictPromotion) {
+      recordWorkflowDecision(decisionTraceRecords, {
+        decisionFamily: "planning_signal_freshness",
+        decisionKey: "stale_signal_rerun_required",
+        outcome: "rerun_required",
+        reasonSummary: `Stale ${surface} planning signal requires rerun before routing can rely on it.`,
+        context: {
+          planningSurface: surface,
+          strictPromotion: false,
+          signalStatus: freshness.signalStatus || null,
+          staleByMs: Number.isFinite(freshness.staleByMs) ? freshness.staleByMs : null,
+          reasons: Array.isArray(freshness.reasons) ? freshness.reasons : []
+        },
+        evidenceRefs: [`signal:${surface}`]
+      });
       continue;
     }
     findings.blockers.push(
@@ -204,10 +340,23 @@ function applyPlanningSignalFreshnessFindings(stageId, findings, planningSignalF
       null,
       `strict promotion requires rerun for stale ${surface} planning signal`
     );
-    nextStageId = fallbackStageIfBeyond(
-      nextStageId,
-      PLANNING_SIGNAL_PROMOTION_FALLBACKS[surface] || nextStageId
-    );
+    const fallbackStageId = PLANNING_SIGNAL_PROMOTION_FALLBACKS[surface] || nextStageId;
+    recordWorkflowDecision(decisionTraceRecords, {
+      decisionFamily: "planning_signal_freshness",
+      decisionKey: "stale_signal_strict_fallback",
+      outcome: "downgraded",
+      reasonSummary: `Strict promotion forces routing fallback because ${surface} planning signal is stale.`,
+      context: {
+        planningSurface: surface,
+        strictPromotion: true,
+        signalStatus: freshness.signalStatus || null,
+        fallbackStage: fallbackStageId,
+        staleByMs: Number.isFinite(freshness.staleByMs) ? freshness.staleByMs : null,
+        reasons: Array.isArray(freshness.reasons) ? freshness.reasons : []
+      },
+      evidenceRefs: [`signal:${surface}`]
+    });
+    nextStageId = fallbackStageIfBeyond(nextStageId, fallbackStageId);
   }
 
   return nextStageId;
@@ -436,6 +585,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\./, "") ||
@@ -445,6 +598,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}`);
     }
@@ -476,6 +634,12 @@ function applyTaskExecutionAndReviewFindings(findings, signals) {
       );
       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.`
@@ -1185,6 +1349,7 @@ function buildTaskGroupImplementerState(taskGroupId, signals, fallbackState) {
       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
     };
   }
@@ -1208,6 +1373,12 @@ function buildTaskGroupImplementerState(taskGroupId, signals, fallbackState) {
         : [],
     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
   };
 }
@@ -1262,6 +1433,21 @@ function buildEffectiveTaskGroupState(group, planned, implementer, review) {
     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",
@@ -1288,6 +1474,23 @@ function buildEffectiveTaskGroupState(group, planned, implementer, review) {
   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",
@@ -1418,7 +1621,7 @@ function buildEffectiveTaskGroupState(group, planned, implementer, review) {
   return effective;
 }
 
-function deriveTaskGroupRuntimeState(plannedTaskGroups, signals, seedTaskGroups) {
+function deriveTaskGroupRuntimeState(plannedTaskGroups, signals, seedTaskGroups, decisionTraceRecords) {
   const plannedGroups = Array.isArray(plannedTaskGroups) ? plannedTaskGroups : [];
   const seedMap = normalizeTaskGroupSeedMap(seedTaskGroups);
 
@@ -1436,6 +1639,22 @@ function deriveTaskGroupRuntimeState(plannedTaskGroups, signals, seedTaskGroups)
     const implementer = buildTaskGroupImplementerState(taskGroupId, signals, seed.implementer);
     const review = buildTaskGroupReviewState(plannedGroup, signals, seed.review);
     const effective = buildEffectiveTaskGroupState(plannedGroup, planned, implementer, review);
+    if (TRACEABLE_TASK_GROUP_FOCUS_REASONS.has(effective.reason)) {
+      recordWorkflowDecision(decisionTraceRecords, {
+        decisionFamily: "task_group_focus_resolution",
+        decisionKey: effective.reason,
+        outcome: "selected_focus",
+        reasonSummary: buildTaskGroupFocusReasonSummary(taskGroupId, effective.reason),
+        context: {
+          taskGroupId,
+          plannedStatus: planned.status || null,
+          effectiveStatus: effective.status || null,
+          liveFocus: effective.resumeCursor ? effective.resumeCursor.liveFocus || null : null,
+          nextAction: effective.nextAction || null
+        },
+        evidenceRefs: buildTaskGroupFocusEvidenceRefs(taskGroupId, effective.reason)
+      });
+    }
 
     return {
       taskGroupId,
@@ -1487,7 +1706,13 @@ function loadTaskGroupMetadataFromPath(targetPath) {
   }
 }
 
-function resolvePersistedTaskGroupSeed(projectRoot, changeId, persistedRecord, plannedTaskGroups) {
+function resolvePersistedTaskGroupSeed(
+  projectRoot,
+  changeId,
+  persistedRecord,
+  plannedTaskGroups,
+  decisionTraceRecords
+) {
   const metadataRefs =
     persistedRecord && persistedRecord.metadataRefs && typeof persistedRecord.metadataRefs === "object"
       ? persistedRecord.metadataRefs
@@ -1500,7 +1725,21 @@ function resolvePersistedTaskGroupSeed(projectRoot, changeId, persistedRecord, p
     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.");
+      const message =
+        "Canonical task-group runtime state digest mismatch; rebuilding task-group state from artifacts.";
+      notes.push(message);
+      recordWorkflowDecision(decisionTraceRecords, {
+        decisionFamily: "task_group_seed_fallback",
+        decisionKey: TASK_GROUP_SEED_TRACE_KEYS["digest-mismatch"],
+        outcome: "fallback",
+        reasonSummary: message,
+        context: {
+          metadataPath: formatPathRef(projectRoot, canonicalPath),
+          taskGroupCount: Array.isArray(plannedTaskGroups) ? plannedTaskGroups.length : 0,
+          expectedDigestPresent: true
+        },
+        evidenceRefs: [`state:${formatPathRef(projectRoot, canonicalPath)}`]
+      });
       return {
         taskGroups: plannedTaskGroups,
         notes
@@ -1516,7 +1755,22 @@ function resolvePersistedTaskGroupSeed(projectRoot, changeId, persistedRecord, p
         notes
       };
     }
-    notes.push("Canonical task-group runtime state is unreadable; rebuilding task-group state from artifacts.");
+    {
+      const message =
+        "Canonical task-group runtime state is unreadable; rebuilding task-group state from artifacts.";
+      notes.push(message);
+      recordWorkflowDecision(decisionTraceRecords, {
+        decisionFamily: "task_group_seed_fallback",
+        decisionKey: TASK_GROUP_SEED_TRACE_KEYS.unreadable,
+        outcome: "fallback",
+        reasonSummary: message,
+        context: {
+          metadataPath: formatPathRef(projectRoot, canonicalPath),
+          taskGroupCount: Array.isArray(plannedTaskGroups) ? plannedTaskGroups.length : 0
+        },
+        evidenceRefs: [`state:${formatPathRef(projectRoot, canonicalPath)}`]
+      });
+    }
     return {
       taskGroups: plannedTaskGroups,
       notes
@@ -1524,14 +1778,45 @@ function resolvePersistedTaskGroupSeed(projectRoot, changeId, persistedRecord, p
   }
 
   if (Array.isArray(persistedRecord && persistedRecord.taskGroups) && persistedRecord.taskGroups.length > 0) {
-    notes.push("Using legacy embedded task-group state as migration fallback.");
+    {
+      const message = "Using legacy embedded task-group state as migration fallback.";
+      notes.push(message);
+      recordWorkflowDecision(decisionTraceRecords, {
+        decisionFamily: "task_group_seed_fallback",
+        decisionKey: TASK_GROUP_SEED_TRACE_KEYS.legacy,
+        outcome: "fallback",
+        reasonSummary: message,
+        context: {
+          metadataPath: canonicalPath ? formatPathRef(projectRoot, canonicalPath) : null,
+          taskGroupCount: persistedRecord.taskGroups.length
+        },
+        evidenceRefs: [`state:${formatPathRef(projectRoot, resolveWorkflowStatePath(projectRoot))}`]
+      });
+    }
     return {
       taskGroups: persistedRecord.taskGroups,
       notes
     };
   }
 
-  notes.push("Canonical task-group runtime state is missing; rebuilding task-group state from artifacts.");
+  {
+    const message = "Canonical task-group runtime state is missing; rebuilding task-group state from artifacts.";
+    notes.push(message);
+    recordWorkflowDecision(decisionTraceRecords, {
+      decisionFamily: "task_group_seed_fallback",
+      decisionKey: TASK_GROUP_SEED_TRACE_KEYS.missing,
+      outcome: "fallback",
+      reasonSummary: message,
+      context: {
+        metadataPath: canonicalPath ? formatPathRef(projectRoot, canonicalPath) : null,
+        taskGroupCount: Array.isArray(plannedTaskGroups) ? plannedTaskGroups.length : 0
+      },
+      evidenceRefs:
+        canonicalPath && String(canonicalPath).trim()
+          ? [`state:${formatPathRef(projectRoot, canonicalPath)}`]
+          : []
+    });
+  }
   return {
     taskGroups: plannedTaskGroups,
     notes
@@ -1578,14 +1863,23 @@ function finalizeWorkflowView(options = {}) {
           stalePlanningSignals: {},
           needsRerunSurfaces: []
         };
+  const decisionTraceRecords = Array.isArray(options.decisionTraceRecords)
+    ? options.decisionTraceRecords
+    : null;
   const taskGroups = deriveTaskGroupRuntimeState(
     options.plannedTaskGroups,
     options.changeSignals,
-    options.taskGroupSeed
+    options.taskGroupSeed,
+    decisionTraceRecords
   );
 
   stageId = applyAuditFindings(stageId, findings, integrityAudit, completionAudit);
-  stageId = applyPlanningSignalFreshnessFindings(stageId, findings, planningSignalFreshness);
+  stageId = applyPlanningSignalFreshnessFindings(
+    stageId,
+    findings,
+    planningSignalFreshness,
+    decisionTraceRecords
+  );
   stageId = applyExecutionSignalFindings(stageId, findings, planningSignalFreshness.effectiveSignalSummary || {});
   applyTaskExecutionAndReviewFindings(findings, options.changeSignals || []);
 
@@ -1599,10 +1893,31 @@ function finalizeWorkflowView(options = {}) {
   }
 
   if (verificationFreshness && !verificationFreshness.fresh && (stageId === "verify" || stageId === "complete")) {
+    const stageBeforeFreshness = stageId;
     findings.blockers.push(
       "Completion-facing routing requires fresh verification evidence; stale evidence keeps the route in verify."
     );
     stageId = "verify";
+    if (stageBeforeFreshness === "complete") {
+      recordWorkflowDecision(decisionTraceRecords, {
+        decisionFamily: "verification_freshness_downgrade",
+        decisionKey: "verification_freshness_stale",
+        outcome: "downgraded",
+        reasonSummary: "Completion-facing routing stays in verify because verification evidence is stale.",
+        context: {
+          fromStage: "complete",
+          toStage: "verify",
+          baselineIso: verificationFreshness.baselineIso || null,
+          staleReasonCount: Array.isArray(verificationFreshness.staleReasons)
+            ? verificationFreshness.staleReasons.length
+            : 0,
+          requiredSurfaces: Array.isArray(verificationFreshness.requiredSurfaces)
+            ? verificationFreshness.requiredSurfaces
+            : []
+        },
+        evidenceRefs: collectVerificationFreshnessEvidenceRefs(verificationFreshness)
+      });
+    }
   }
 
   const gates = buildGatesWithLiveOverlays(
@@ -1633,6 +1948,26 @@ function finalizeWorkflowView(options = {}) {
       findings.warnings.push(
         "Bounded-parallel profile downgraded to serial until worktree isolation is ready or explicitly accepted."
       );
+      recordWorkflowDecision(decisionTraceRecords, {
+        decisionFamily: "worktree_isolation_downgrade",
+        decisionKey: "effective_serial_after_preflight",
+        outcome: "downgraded",
+        reasonSummary: "Worktree preflight downgraded advisory bounded parallel execution to effective serial mode.",
+        context: {
+          advisoryMode: executionProfile.mode,
+          effectiveMode: executionProfile.effectiveMode || "serial",
+          preflightStatus: worktreePreflight.status || null,
+          recommendedIsolation: Boolean(
+            worktreePreflight.summary && worktreePreflight.summary.recommendedIsolation
+          ),
+          dirtyEntries:
+            worktreePreflight.summary &&
+            Number.isFinite(Number(worktreePreflight.summary.dirtyEntries))
+              ? Number(worktreePreflight.summary.dirtyEntries)
+              : 0
+        },
+        evidenceRefs: ["surface:worktree-preflight"]
+      });
     }
   }
 
@@ -1713,23 +2048,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");
@@ -1766,6 +2108,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),
@@ -1831,6 +2180,26 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
       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 =
@@ -1841,40 +2210,49 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
         projectRoot,
         activeChangeId,
         persistedRecord,
-        plannedTaskGroups
-      );
-      return finalizeWorkflowView({
-        projectRoot,
-        changeId: activeChangeId,
-        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",
-        taskGroupSeed: persistedSeed.taskGroups,
         plannedTaskGroups,
-        changeSignals,
-        signalSummary,
-        planningSignalFreshness,
-        integrityAudit,
-        completionAudit,
-        disciplineState,
-        verificationFreshness,
-        hasTasksArtifact: artifactState.tasks
-      });
+        decisionTraceRecords
+      );
+      return finalizeResultWithWorkflowDecisionTracing(
+        finalizeWorkflowView({
+          projectRoot,
+          changeId: activeChangeId,
+          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",
+          taskGroupSeed: persistedSeed.taskGroups,
+          plannedTaskGroups,
+          changeSignals,
+          signalSummary,
+          planningSignalFreshness,
+          integrityAudit,
+          completionAudit,
+          disciplineState,
+          verificationFreshness,
+          hasTasksArtifact: artifactState.tasks,
+          decisionTraceRecords
+        }),
+        {
+          env: options.env,
+          surface: options.traceSurface,
+          records: decisionTraceRecords
+        }
+      );
     }
 
     if (!persistedSelection.usable && persistedSelection.reason) {
@@ -1888,6 +2266,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)}`]
+        });
       }
     }
   }
@@ -1945,7 +2339,8 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
     completionAudit,
     disciplineState,
     verificationFreshness,
-    hasTasksArtifact: artifactState.tasks
+    hasTasksArtifact: artifactState.tasks,
+    decisionTraceRecords
   });
 
   if (activeChangeId && !ambiguousChangeSelection) {
@@ -2015,7 +2410,11 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
     ]);
   }
 
-  return derivedResult;
+  return finalizeResultWithWorkflowDecisionTracing(derivedResult, {
+    env: options.env,
+    surface: options.traceSurface,
+    records: decisionTraceRecords
+  });
 }
 
 function buildWorkflowResult(params) {