@xenonbyte/da-vinci-workflow 0.2.7 → 0.2.8

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## v0.2.8 - 2026-04-05
+
+### Added
+- optional workflow decision tracing via `.da-vinci/logs/workflow-decisions/YYYY-MM-DD.ndjson`, gated by `DA_VINCI_TRACE_WORKFLOW_DECISIONS=1`
+- compact trace coverage for persisted-state trust, canonical task-group seed fallback, task-group focus override, stale planning-signal fallback, verification freshness downgrade, and worktree-isolation downgrade
+- targeted regression coverage in `scripts/test-workflow-decision-tracing.js` for eligible surfaces, silence rules, sink-write failures, and trace-schema validation behavior
+
+### Changed
+- `workflow-status` and `next-step` now emit bounded decision traces only on the explicitly allowed surfaces, while keeping route/state truth unchanged
+- workflow trace records now reject invalid family/key/outcome combinations with visible diagnostic feedback instead of silently disappearing
+- current release notes in `README.md` and `README.zh-CN.md` now point to the `0.2.8` workflow decision tracing release
+
+### Fixed
+- missing review or verification evidence no longer produces fake `evidenceRefs` in workflow decision traces
+- persisted-state fallback traces no longer imply a fingerprint comparison happened for non-fingerprint fallback paths
+- workflow tracing diagnostics remain non-blocking even when trace persistence fails or candidate trace records are invalid
+
 ## v0.2.7 - 2026-04-05
 
 ### Added

package/README.md

@@ -34,15 +34,15 @@ Use `da-vinci maintainer-readiness` as the canonical maintainer diagnosis surfac
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.2.7`
+- `@xenonbyte/da-vinci-workflow@0.2.8`
 
-Release highlights for `0.2.7`:
+Release highlights for `0.2.8`:
 
-- bounded worker isolation is now formalized as a contract-only OpenSpec change, with explicit task-group ownership, isolated workspace, handoff, sequencing, writeback, and downgrade rules
-- `task-execution`, `task-review`, and `workflow-state` now align with that contract by blocking out-of-scope writes, preserving review ordering, and rejecting `partial=true` + `DONE`
-- the reviewer bridge now runs `codex exec` with closed stdin plus explicit prompt separation, and preserves raw diagnostics when structured reviewer output is missing
-- contract CI now exercises bounded-worker-isolation phase 1-4 tests directly instead of relying only on docs/asset consistency checks
-- supervisor-review smoke fixtures now use valid exported screenshots, and the real reviewer bridge integration passes end to end
+- optional workflow decision tracing is now available for `workflow-status` and `next-step` through `DA_VINCI_TRACE_WORKFLOW_DECISIONS=1`, with records written to `.da-vinci/logs/workflow-decisions/YYYY-MM-DD.ndjson`
+- the initial trace-family allowlist now covers persisted-state trust, task-group seed fallback, task-group focus override, stale planning-signal fallback, verification freshness downgrade, and worktree-isolation downgrade
+- workflow decision traces remain bounded and diagnostic-only: they do not change routing truth, do not run on non-eligible commands, and do not block normal command execution when trace persistence fails
+- trace records now reject invalid schema combinations with visible diagnostics instead of silently disappearing
+- trace payloads no longer claim missing evidence exists, and persisted fallback traces no longer imply a fingerprint comparison happened when it did not
 
 ## Discipline And Orchestration Upgrade
 

package/README.zh-CN.md

@@ -37,15 +37,15 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.2.7`
+- `@xenonbyte/da-vinci-workflow@0.2.8`
 
-`0.2.7` 版本重点：
+`0.2.8` 版本重点：
 
-- `bounded-worker-isolation-contract` 现已作为 contract-only OpenSpec 变更落地，明确 task-group ownership、isolated workspace、handoff、sequencing、writeback 与 downgrade 规则
-- `task-execution`、`task-review`、`workflow-state` 现已与该 contract 对齐：会阻断 out-of-scope writes，保持 review 顺序，并拒绝 `partial=true` 与 `DONE` 组合
-- reviewer bridge 现在会以显式 prompt 分隔并关闭 stdin 的方式运行 `codex exec`，同时在 reviewer 缺失结构化输出时保留原始诊断
-- contract CI 现在会直接跑 bounded-worker-isolation phase 1-4 回归，不再只依赖文档/命令资产一致性检查
-- supervisor-review smoke fixture 现在使用有效截图，真实 reviewer bridge integration 已能端到端通过
+- 现在可以通过 `DA_VINCI_TRACE_WORKFLOW_DECISIONS=1` 为 `workflow-status` 与 `next-step` 开启可选的 workflow decision tracing，记录会写入 `.da-vinci/logs/workflow-decisions/YYYY-MM-DD.ndjson`
+- 首批 trace-family allowlist 已覆盖 persisted-state trust、task-group seed fallback、task-group focus override、stale planning-signal fallback、verification freshness downgrade 与 worktree-isolation downgrade
+- workflow decision trace 仍然是 bounded 且 diagnostic-only：不会改变 routing truth，不会在非 eligible command 上发射，也不会因为 trace 持久化失败而阻断正常命令
+- trace record 现在会对非法 schema 组合给出可见诊断，不再静默丢失
+- trace payload 不再为缺失证据伪造 `evidenceRefs`，persisted fallback trace 也不再错误暗示某些未发生的 fingerprint comparison
 
 ## Discipline And Orchestration 升级
 

package/lib/cli.js

@@ -1097,7 +1097,11 @@ async function runCli(argv) {
   if (command === "workflow-status") {
     const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
     const changeId = getOption(argv, "--change");
-    const result = deriveWorkflowStatus(projectPath, { changeId });
+    const result = deriveWorkflowStatus(projectPath, {
+      changeId,
+      traceSurface: "workflow-status",
+      env: process.env
+    });
 
     if (argv.includes("--json")) {
       console.log(JSON.stringify(result, null, 2));
@@ -1111,7 +1115,11 @@ async function runCli(argv) {
   if (command === "next-step") {
     const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
     const changeId = getOption(argv, "--change");
-    const result = deriveWorkflowStatus(projectPath, { changeId });
+    const result = deriveWorkflowStatus(projectPath, {
+      changeId,
+      traceSurface: "next-step",
+      env: process.env
+    });
 
     if (argv.includes("--json")) {
       console.log(
@@ -1124,7 +1132,8 @@ async function runCli(argv) {
             discipline: result.discipline || null,
             executionProfile: result.executionProfile || null,
             worktreePreflight: result.worktreePreflight || null,
-            verificationFreshness: result.verificationFreshness || null
+            verificationFreshness: result.verificationFreshness || null,
+            traceDiagnostics: result.traceDiagnostics || null
           },
           null,
           2

package/lib/workflow-decision-trace.js

@@ -0,0 +1,335 @@
+const fs = require("fs");
+const path = require("path");
+const { normalizeRelativePath } = require("./utils");
+
+const TRACE_ENABLE_ENV = "DA_VINCI_TRACE_WORKFLOW_DECISIONS";
+const ELIGIBLE_SURFACES = new Set(["workflow-status", "next-step"]);
+const DECISION_FAMILIES = new Set([
+  "persisted_state_trust",
+  "task_group_seed_fallback",
+  "task_group_focus_resolution",
+  "planning_signal_freshness",
+  "verification_freshness_downgrade",
+  "worktree_isolation_downgrade"
+]);
+const OUTCOMES = new Set([
+  "accepted",
+  "fallback",
+  "selected_focus",
+  "rerun_required",
+  "downgraded",
+  "suppressed"
+]);
+const DECISION_KEYS_BY_FAMILY = Object.freeze({
+  persisted_state_trust: new Set([
+    "accepted_digest_match",
+    "accepted_age_advisory",
+    "fallback_missing",
+    "fallback_parse_error",
+    "fallback_version_mismatch",
+    "fallback_change_missing",
+    "fallback_fingerprint_mismatch"
+  ]),
+  task_group_seed_fallback: new Set([
+    "seed_missing",
+    "seed_unreadable",
+    "seed_digest_mismatch",
+    "seed_legacy_embedded"
+  ]),
+  task_group_focus_resolution: new Set([
+    "implementer_block",
+    "implementer_warn",
+    "spec_review_missing",
+    "spec_review_block",
+    "spec_review_warn",
+    "quality_review_missing",
+    "quality_review_block",
+    "quality_review_warn"
+  ]),
+  planning_signal_freshness: new Set([
+    "stale_signal_rerun_required",
+    "stale_signal_strict_fallback"
+  ]),
+  verification_freshness_downgrade: new Set(["verification_freshness_stale"]),
+  worktree_isolation_downgrade: new Set(["effective_serial_after_preflight"])
+});
+
+const MAX_CONTEXT_ARRAY_LENGTH = 8;
+const MAX_EVIDENCE_REFS = 8;
+const MAX_TEXT_LENGTH = 240;
+
+function truncateText(value, maxLength = MAX_TEXT_LENGTH) {
+  const text = String(value || "").trim();
+  if (!text) {
+    return "";
+  }
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return `${text.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+
+function formatDateToken(date = new Date()) {
+  const year = date.getFullYear();
+  const month = `${date.getMonth() + 1}`.padStart(2, "0");
+  const day = `${date.getDate()}`.padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+function isWorkflowDecisionTracingEnabled(env = process.env) {
+  return String(env && env[TRACE_ENABLE_ENV] ? env[TRACE_ENABLE_ENV] : "").trim() === "1";
+}
+
+function isEligibleWorkflowTraceSurface(surface) {
+  return ELIGIBLE_SURFACES.has(String(surface || "").trim());
+}
+
+function shouldTraceWorkflowDecisions(options = {}) {
+  return (
+    isWorkflowDecisionTracingEnabled(options.env) &&
+    isEligibleWorkflowTraceSurface(options.surface)
+  );
+}
+
+function resolveWorkflowDecisionTracePath(projectRoot, date = new Date()) {
+  return path.join(
+    path.resolve(projectRoot || process.cwd()),
+    ".da-vinci",
+    "logs",
+    "workflow-decisions",
+    `${formatDateToken(date)}.ndjson`
+  );
+}
+
+function formatPathRef(projectRoot, candidatePath) {
+  const resolved = path.resolve(String(candidatePath || ""));
+  const root = path.resolve(projectRoot || process.cwd());
+  const relative = path.relative(root, resolved);
+  if (!relative || (!relative.startsWith("..") && !path.isAbsolute(relative))) {
+    return normalizeRelativePath(relative || ".");
+  }
+  return resolved.split(path.sep).join("/");
+}
+
+function normalizeContextValue(value) {
+  if (value === null) {
+    return null;
+  }
+  if (typeof value === "string") {
+    const text = truncateText(value);
+    return text || undefined;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : undefined;
+  }
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    const items = value
+      .map((item) => truncateText(item))
+      .filter(Boolean)
+      .slice(0, MAX_CONTEXT_ARRAY_LENGTH);
+    return items.length > 0 ? items : undefined;
+  }
+  return undefined;
+}
+
+function normalizeContext(context) {
+  const normalized = {};
+  if (!context || typeof context !== "object" || Array.isArray(context)) {
+    return normalized;
+  }
+
+  for (const [key, value] of Object.entries(context)) {
+    const normalizedValue = normalizeContextValue(value);
+    if (normalizedValue !== undefined) {
+      normalized[key] = normalizedValue;
+    }
+  }
+
+  return normalized;
+}
+
+function normalizeEvidenceRefs(evidenceRefs) {
+  return Array.from(
+    new Set(
+      (Array.isArray(evidenceRefs) ? evidenceRefs : [])
+        .map((item) => truncateText(item))
+        .filter(Boolean)
+    )
+  ).slice(0, MAX_EVIDENCE_REFS);
+}
+
+function inspectWorkflowDecisionRecord(record) {
+  if (!record || typeof record !== "object") {
+    return {
+      normalized: null,
+      rejection: "record must be an object"
+    };
+  }
+
+  const decisionFamily = String(record.decisionFamily || "").trim();
+  const decisionKey = String(record.decisionKey || "").trim();
+  const outcome = String(record.outcome || "").trim();
+  const reasonSummary = truncateText(record.reasonSummary);
+
+  if (!DECISION_FAMILIES.has(decisionFamily)) {
+    return {
+      normalized: null,
+      rejection: `unsupported decisionFamily: ${decisionFamily || "(empty)"}`
+    };
+  }
+  if (!OUTCOMES.has(outcome)) {
+    return {
+      normalized: null,
+      rejection: `unsupported outcome for ${decisionFamily}: ${outcome || "(empty)"}`
+    };
+  }
+  const allowedKeys = DECISION_KEYS_BY_FAMILY[decisionFamily];
+  if (!allowedKeys || !allowedKeys.has(decisionKey)) {
+    return {
+      normalized: null,
+      rejection: `unsupported decisionKey for ${decisionFamily}: ${decisionKey || "(empty)"}`
+    };
+  }
+  if (!reasonSummary) {
+    return {
+      normalized: null,
+      rejection: `reasonSummary is required for ${decisionFamily}/${decisionKey}`
+    };
+  }
+
+  return {
+    normalized: {
+      decisionFamily,
+      decisionKey,
+      outcome,
+      reasonSummary,
+      context: normalizeContext(record.context),
+      evidenceRefs: normalizeEvidenceRefs(record.evidenceRefs)
+    },
+    rejection: null
+  };
+}
+
+function emitWorkflowDecisionTraces(options = {}) {
+  if (!shouldTraceWorkflowDecisions(options)) {
+    return {
+      enabled: false,
+      written: 0,
+      tracePath: null,
+      error: null,
+      rejectedCount: 0,
+      rejections: []
+    };
+  }
+
+  const changeId = String(options.changeId || "").trim();
+  const stage = String(options.stage || "").trim();
+  if (!changeId || !stage) {
+    return {
+      enabled: true,
+      written: 0,
+      tracePath: null,
+      error: null,
+      rejectedCount: 0,
+      rejections: []
+    };
+  }
+
+  const rejections = [];
+  const normalizedRecords = [];
+  for (const record of Array.isArray(options.records) ? options.records : []) {
+    const inspected = inspectWorkflowDecisionRecord(record);
+    if (inspected.normalized) {
+      normalizedRecords.push(inspected.normalized);
+      continue;
+    }
+    if (inspected.rejection) {
+      rejections.push(inspected.rejection);
+    }
+  }
+  if (normalizedRecords.length === 0) {
+    return {
+      enabled: true,
+      written: 0,
+      tracePath: null,
+      error: null,
+      rejectedCount: rejections.length,
+      rejections: rejections.slice(0, 3)
+    };
+  }
+
+  const now = options.now instanceof Date ? options.now : new Date();
+  const timestamp = now.toISOString();
+  const surface = String(options.surface || "").trim();
+  const tracePath = resolveWorkflowDecisionTracePath(options.projectRoot, now);
+  const lines = [];
+  const seen = new Set();
+
+  for (const record of normalizedRecords) {
+    const payload = {
+      timestamp,
+      surface,
+      changeId,
+      stage,
+      decisionFamily: record.decisionFamily,
+      decisionKey: record.decisionKey,
+      outcome: record.outcome,
+      reasonSummary: record.reasonSummary,
+      context: record.context,
+      evidenceRefs: record.evidenceRefs
+    };
+    const serialized = JSON.stringify(payload);
+    if (seen.has(serialized)) {
+      continue;
+    }
+    seen.add(serialized);
+    lines.push(serialized);
+  }
+
+  if (lines.length === 0) {
+    return {
+      enabled: true,
+      written: 0,
+      tracePath: null,
+      error: null
+    };
+  }
+
+  try {
+    fs.mkdirSync(path.dirname(tracePath), { recursive: true });
+    fs.appendFileSync(tracePath, `${lines.join("\n")}\n`, "utf8");
+    return {
+      enabled: true,
+      written: lines.length,
+      tracePath,
+      error: null,
+      rejectedCount: rejections.length,
+      rejections: rejections.slice(0, 3)
+    };
+  } catch (error) {
+    return {
+      enabled: true,
+      written: 0,
+      tracePath,
+      error,
+      rejectedCount: rejections.length,
+      rejections: rejections.slice(0, 3)
+    };
+  }
+}
+
+module.exports = {
+  TRACE_ENABLE_ENV,
+  DECISION_FAMILIES,
+  DECISION_KEYS_BY_FAMILY,
+  OUTCOMES,
+  formatPathRef,
+  isWorkflowDecisionTracingEnabled,
+  isEligibleWorkflowTraceSurface,
+  shouldTraceWorkflowDecisions,
+  resolveWorkflowDecisionTracePath,
+  emitWorkflowDecisionTraces
+};

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;
@@ -1472,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);
 
@@ -1490,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,
@@ -1541,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
@@ -1554,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
@@ -1570,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
@@ -1578,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
@@ -1632,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 || []);
 
@@ -1653,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(
@@ -1687,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"]
+      });
     }
   }
 
@@ -1767,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");
@@ -1820,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),
@@ -1885,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 =
@@ -1895,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) {
@@ -1942,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)}`]
+        });
       }
     }
   }
@@ -1999,7 +2339,8 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
     completionAudit,
     disciplineState,
     verificationFreshness,
-    hasTasksArtifact: artifactState.tasks
+    hasTasksArtifact: artifactState.tasks,
+    decisionTraceRecords
   });
 
   if (activeChangeId && !ambiguousChangeSelection) {
@@ -2069,7 +2410,11 @@ function deriveWorkflowStatus(projectPathInput, options = {}) {
     ]);
   }
 
-  return derivedResult;
+  return finalizeResultWithWorkflowDecisionTracing(derivedResult, {
+    env: options.env,
+    surface: options.traceSurface,
+    records: decisionTraceRecords
+  });
 }
 
 function buildWorkflowResult(params) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/da-vinci-workflow",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Requirement-to-design-to-code workflow skill for Codex, Claude, and Gemini",
   "bin": {
     "da-vinci": "bin/da-vinci.js",