@xenonbyte/da-vinci-workflow 0.2.7 → 0.2.9

package/lib/workflow-overlay.js

@@ -0,0 +1,1033 @@
+const fs = require("fs");
+const path = require("path");
+const {
+  parseDisciplineMarkers,
+  DISCIPLINE_MARKER_NAMES
+} = require("./audit-parsers");
+const { readTextIfExists, dedupeMessages } = require("./utils");
+const { listSignalsBySurfacePrefix } = require("./execution-signals");
+const { evaluatePlanningSignalFreshness } = require("./planning-signal-freshness");
+const { deriveExecutionProfile } = require("./execution-profile");
+const { runWorktreePreflight } = require("./worktree-preflight");
+const { STATUS, HANDOFF_GATES, getStageById } = require("./workflow-contract");
+
+const MAX_REPORTED_MESSAGES = 3;
+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"
+});
+
+/**
+ * @typedef {Object} WorkflowFindings
+ * @property {string[]} blockers
+ * @property {string[]} warnings
+ * @property {string[]} notes
+ * @property {Array<{ id: string, surface: string, reason: string, evidence: string[] }>} [blockingGates]
+ */
+
+/**
+ * @typedef {Object} PlanningSignalFreshnessState
+ * @property {Object.<string, object>} effectiveSignalSummary
+ * @property {Object.<string, object>} stalePlanningSignals
+ * @property {string[]} needsRerunSurfaces
+ */
+
+/**
+ * @typedef {Object} WorkflowDisciplineState
+ * @property {boolean} strictMode
+ * @property {boolean} hasAnyMarker
+ * @property {{ state: string, stale: boolean, marker: object | null }} designApproval
+ * @property {{ marker: object | null }} planSelfReview
+ * @property {{ marker: object | null }} operatorReviewAck
+ * @property {Array<object>} malformed
+ * @property {string[]} blockers
+ * @property {string[]} warnings
+ * @property {string[]} notes
+ */
+
+/**
+ * @typedef {Object} WorkflowOverlayResult
+ * @property {string} stageId
+ * @property {WorkflowFindings} findings
+ * @property {Object.<string, string>} gates
+ * @property {Array<object>} taskGroups
+ * @property {object} executionProfile
+ * @property {object | null} worktreePreflight
+ * @property {object | null} blockingGate
+ * @property {string[]} needsRerunSurfaces
+ * @property {Object.<string, object>} stalePlanningSignals
+ */
+
+function recordDecision(callback, records, record) {
+  if (typeof callback === "function") {
+    callback(records, record);
+  }
+}
+
+function dedupeFindings(findings) {
+  findings.blockers = dedupeMessages(findings.blockers);
+  findings.warnings = dedupeMessages(findings.warnings);
+  findings.notes = dedupeMessages(findings.notes);
+}
+
+function resolveDisciplineGateMode() {
+  const strictEnv = String(process.env.DA_VINCI_DISCIPLINE_REQUIRE_APPROVAL || "").trim();
+  const strict = strictEnv === "1" || /^true$/i.test(strictEnv);
+  return {
+    strict
+  };
+}
+
+function isStrictPromotionEnabled() {
+  const raw = String(process.env.DA_VINCI_DISCIPLINE_STRICT_PROMOTION || "").trim();
+  return raw === "1" || /^true$/i.test(raw);
+}
+
+function fallbackStageIfBeyond(currentStageId, targetStageId) {
+  const current = getStageById(currentStageId);
+  const target = getStageById(targetStageId);
+  if (!current || !target) {
+    return currentStageId;
+  }
+  if (current.order > target.order) {
+    return target.id;
+  }
+  return current.id;
+}
+
+function ensureGateTracking(findings) {
+  if (!Array.isArray(findings.blockingGates)) {
+    findings.blockingGates = [];
+  }
+}
+
+function collectGateEvidenceRefs(gate) {
+  return Array.isArray(gate && gate.evidence) ? gate.evidence.slice(0, MAX_REPORTED_MESSAGES) : [];
+}
+
+function addBlockingGateRecord(findings, gateId, surface, gate, reason) {
+  ensureGateTracking(findings);
+  findings.blockingGates.push({
+    id: gateId,
+    surface,
+    reason: String(reason || "").trim(),
+    evidence: collectGateEvidenceRefs(gate)
+  });
+}
+
+function 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 getSignalGate(signal, gateKey) {
+  if (!signal || !signal.details || !signal.details.gates) {
+    return null;
+  }
+  const gates = signal.details.gates;
+  if (!gates || typeof gates !== "object" || !gateKey) {
+    return null;
+  }
+  return gates[gateKey] && typeof gates[gateKey] === "object" ? gates[gateKey] : null;
+}
+
+function resolveEffectiveGateStatus(gate, signal) {
+  const gateStatus = normalizeSignalStatus(gate && gate.status);
+  if (gateStatus) {
+    return gateStatus;
+  }
+  const signalStatus = normalizeSignalStatus(signal && signal.status);
+  return signalStatus || STATUS.PASS;
+}
+
+function statusTokenMatches(status, acceptedTokens) {
+  const normalized = String(status || "").trim().toUpperCase();
+  return acceptedTokens.includes(normalized);
+}
+
+function 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}`);
+}
+
+/**
+ * Inspect planning-signal freshness and remove stale planning signals from the effective routing summary.
+ *
+ * @param {string} projectRoot
+ * @param {string | null} changeId
+ * @param {Object.<string, object>} signalSummary
+ * @returns {PlanningSignalFreshnessState}
+ */
+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,
+  decisionTraceRecords,
+  recordWorkflowDecision
+) {
+  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) {
+      recordDecision(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(
+      `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`
+    );
+    const fallbackStageId = PLANNING_SIGNAL_PROMOTION_FALLBACKS[surface] || nextStageId;
+    recordDecision(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;
+}
+
+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];
+}
+
+/**
+ * Inspect discipline markers and staleness on design/tasks artifacts.
+ *
+ * @param {string} changeDir
+ * @returns {WorkflowDisciplineState}
+ */
+function inspectDisciplineState(changeDir) {
+  const designPath = path.join(changeDir, "design.md");
+  const pencilDesignPath = path.join(changeDir, "pencil-design.md");
+  const pencilBindingsPath = path.join(changeDir, "pencil-bindings.md");
+  const tasksPath = path.join(changeDir, "tasks.md");
+  const designText = readTextIfExists(designPath);
+  const tasksText = readTextIfExists(tasksPath);
+  const designMarkers = parseDisciplineMarkers(designText);
+  const taskMarkers = parseDisciplineMarkers(tasksText);
+  const gateMode = resolveDisciplineGateMode();
+  const hasAnyMarker =
+    designMarkers.ordered.length > 0 ||
+    taskMarkers.ordered.length > 0 ||
+    designMarkers.malformed.length > 0 ||
+    taskMarkers.malformed.length > 0;
+
+  const designApproval =
+    designMarkers.markers[DISCIPLINE_MARKER_NAMES.designApproval] ||
+    taskMarkers.markers[DISCIPLINE_MARKER_NAMES.designApproval] ||
+    null;
+  const planSelfReview = taskMarkers.markers[DISCIPLINE_MARKER_NAMES.planSelfReview] || null;
+  const operatorReviewAck = taskMarkers.markers[DISCIPLINE_MARKER_NAMES.operatorReviewAck] || null;
+
+  const blockers = [];
+  const warnings = [];
+  const notes = [];
+  const designApprovalArtifacts = [
+    { label: "design.md", path: designPath },
+    { label: "pencil-design.md", path: pencilDesignPath },
+    { label: "pencil-bindings.md", path: pencilBindingsPath }
+  ];
+
+  for (const malformed of [...designMarkers.malformed, ...taskMarkers.malformed]) {
+    warnings.push(`Malformed discipline marker at line ${malformed.line}: ${malformed.reason}`);
+  }
+
+  let designApprovalState = "missing";
+  let designApprovalStale = false;
+  if (designApproval) {
+    if (!statusTokenMatches(designApproval.status, ["APPROVED", "PASS", "ACCEPTED"])) {
+      designApprovalState = "rejected";
+      blockers.push(
+        `Design approval marker is not approved (${designApproval.status}); keep workflow in tasks/design.`
+      );
+    } else {
+      designApprovalState = "approved";
+      if (designApproval.time) {
+        const approvalMs = Date.parse(designApproval.time);
+        const staleArtifacts = [];
+        if (Number.isFinite(approvalMs)) {
+          for (const artifact of designApprovalArtifacts) {
+            let artifactMtimeMs = 0;
+            try {
+              artifactMtimeMs = fs.statSync(artifact.path).mtimeMs;
+            } catch (_error) {
+              continue;
+            }
+            if (artifactMtimeMs > approvalMs) {
+              staleArtifacts.push(artifact.label);
+            }
+          }
+        }
+        if (staleArtifacts.length > 0) {
+          designApprovalState = "stale";
+          designApprovalStale = true;
+          blockers.push(
+            `Design approval marker is stale because design artifacts changed after approval timestamp: ${staleArtifacts.join(", ")}.`
+          );
+        }
+      } else {
+        warnings.push("Design approval marker is missing timestamp; staleness checks are limited.");
+      }
+    }
+  } else if (hasAnyMarker || gateMode.strict) {
+    blockers.push(
+      "Missing required design approval marker (`- design approval: APPROVED @ <ISO8601>`) for disciplined handoff."
+    );
+  } else {
+    warnings.push(
+      "Design approval marker is missing; legacy compatibility mode keeps this advisory. Set DA_VINCI_DISCIPLINE_REQUIRE_APPROVAL=1 to enforce."
+    );
+    notes.push("Legacy compatibility mode: missing discipline markers are advisory.");
+  }
+
+  if (!planSelfReview) {
+    warnings.push("Missing plan self-review marker in tasks.md (`- plan self review: PASS @ <ISO8601>`).");
+  } else if (!statusTokenMatches(planSelfReview.status, ["PASS", "APPROVED", "DONE"])) {
+    warnings.push(`Plan self-review marker is not PASS (${planSelfReview.status}).`);
+  }
+
+  if (!operatorReviewAck) {
+    warnings.push("Missing operator review acknowledgment marker in tasks.md (`- operator review ack: ACKNOWLEDGED @ <ISO8601>`).");
+  } else if (!statusTokenMatches(operatorReviewAck.status, ["ACKNOWLEDGED", "ACK", "CONFIRMED", "APPROVED"])) {
+    warnings.push(`Operator review acknowledgment marker is not acknowledged (${operatorReviewAck.status}).`);
+  }
+
+  return {
+    strictMode: gateMode.strict,
+    hasAnyMarker,
+    designApproval: {
+      state: designApprovalState,
+      stale: designApprovalStale,
+      marker: designApproval
+    },
+    planSelfReview: {
+      marker: planSelfReview
+    },
+    operatorReviewAck: {
+      marker: operatorReviewAck
+    },
+    malformed: [...designMarkers.malformed, ...taskMarkers.malformed],
+    blockers,
+    warnings,
+    notes
+  };
+}
+
+function mergeSignalBySurface(signals) {
+  const summary = {};
+  for (const signal of signals || []) {
+    const key = String(signal.surface || "").trim();
+    if (!key || summary[key]) {
+      continue;
+    }
+    summary[key] = signal;
+  }
+  return summary;
+}
+
+function applyTaskExecutionAndReviewFindings(findings, signals) {
+  const taskExecutionSignals = listSignalsBySurfacePrefix(signals, "task-execution.");
+  const taskReviewSignals = listSignalsBySurfacePrefix(signals, "task-review.");
+  const latestTaskExecution = mergeSignalBySurface(taskExecutionSignals);
+  const latestTaskReview = mergeSignalBySurface(taskReviewSignals);
+
+  for (const signal of Object.values(latestTaskExecution)) {
+    const envelope = signal.details && signal.details.envelope ? signal.details.envelope : null;
+    const outOfScopeWrites =
+      signal.details && Array.isArray(signal.details.outOfScopeWrites)
+        ? dedupeMessages(signal.details.outOfScopeWrites.map((item) => String(item || "").trim()).filter(Boolean))
+        : [];
+    const taskGroupId =
+      (envelope && envelope.taskGroupId) ||
+      String(signal.surface || "").replace(/^task-execution\./, "") ||
+      "unknown";
+    if (signal.status === STATUS.BLOCK) {
+      findings.blockers.push(`Task group ${taskGroupId} is BLOCKED in implementer status envelope.`);
+    } else if (signal.status === STATUS.WARN) {
+      findings.warnings.push(`Task group ${taskGroupId} has unresolved implementer concerns/context needs.`);
+    }
+    if (outOfScopeWrites.length > 0) {
+      findings.blockers.push(
+        `Task group ${taskGroupId} reported out-of-scope writes: ${outOfScopeWrites.join(", ")}.`
+      );
+    }
+    if (envelope && envelope.summary) {
+      findings.notes.push(`Implementer summary ${taskGroupId}: ${envelope.summary}`);
+    }
+  }
+
+  const reviewStateByGroup = {};
+  for (const signal of Object.values(latestTaskReview)) {
+    const envelope = signal.details && signal.details.envelope ? signal.details.envelope : null;
+    const taskGroupId =
+      (envelope && envelope.taskGroupId) ||
+      String(signal.surface || "").replace(/^task-review\./, "").split(".")[0] ||
+      "unknown";
+    const stage = envelope && envelope.stage ? envelope.stage : String(signal.surface || "").split(".").pop();
+    if (!reviewStateByGroup[taskGroupId]) {
+      reviewStateByGroup[taskGroupId] = {};
+    }
+    reviewStateByGroup[taskGroupId][stage] = signal.status;
+    if (signal.status === STATUS.BLOCK) {
+      findings.blockers.push(`Task review ${taskGroupId}/${stage} is BLOCK.`);
+    } else if (signal.status === STATUS.WARN) {
+      findings.warnings.push(`Task review ${taskGroupId}/${stage} is WARN and requires follow-up.`);
+    }
+  }
+
+  for (const [taskGroupId, state] of Object.entries(reviewStateByGroup)) {
+    if (state.quality && !state.spec) {
+      findings.blockers.push(
+        `Task review ordering violation for ${taskGroupId}: quality review exists without a prior spec review result.`
+      );
+      continue;
+    }
+    if (state.quality && state.spec === STATUS.WARN) {
+      findings.blockers.push(
+        `Task review ordering violation for ${taskGroupId}: quality review was recorded before spec review reached PASS.`
+      );
+      continue;
+    }
+    if (state.quality && state.spec === STATUS.BLOCK) {
+      findings.blockers.push(
+        `Task review ordering violation for ${taskGroupId}: quality review was recorded while spec review is BLOCK.`
+      );
+    }
+  }
+}
+
+function applyAuditFindings(stageId, findings, integrityAudit, completionAudit) {
+  let nextStageId = stageId;
+
+  if (integrityAudit && integrityAudit.status === "FAIL") {
+    findings.warnings.push("Integrity audit currently reports FAIL.");
+  } else if (integrityAudit && integrityAudit.status === "WARN") {
+    findings.warnings.push("Integrity audit currently reports WARN.");
+  }
+
+  if ((nextStageId === "verify" || nextStageId === "complete") && completionAudit) {
+    if (completionAudit.status === "PASS") {
+      if (nextStageId === "verify") {
+        nextStageId = "complete";
+      }
+      findings.notes.push("Completion audit reports PASS for the active change.");
+    } else if (completionAudit.status === "WARN") {
+      findings.warnings.push("Completion audit currently reports WARN.");
+      if (nextStageId === "complete") {
+        nextStageId = "verify";
+      }
+    } else if (completionAudit.status === "FAIL") {
+      findings.blockers.push("Completion audit currently reports FAIL.");
+      if (nextStageId === "complete") {
+        nextStageId = "verify";
+      }
+    }
+  }
+
+  return nextStageId;
+}
+
+function applyExecutionSignalFindings(stageId, findings, signalSummary) {
+  let nextStageId = stageId;
+  const strictPromotion = isStrictPromotionEnabled();
+  const signalParseIssue = signalSummary["signal-file-parse"];
+  if (signalParseIssue) {
+    const warningText =
+      Array.isArray(signalParseIssue.warnings) && signalParseIssue.warnings[0]
+        ? String(signalParseIssue.warnings[0])
+        : "Malformed execution signal files were detected.";
+    findings.warnings.push(warningText);
+  }
+
+  const diffSignal = signalSummary["diff-spec"];
+  if (diffSignal && diffSignal.status && diffSignal.status !== STATUS.PASS) {
+    findings.warnings.push(`Planning diff signal diff-spec reports ${diffSignal.status}.`);
+  }
+
+  const lintSpecSignal = signalSummary["lint-spec"];
+  const lintSpecGateConfigs = [
+    { id: "principleInheritance", label: "principleInheritance", fallbackStage: "breakdown" },
+    { id: "clarify", label: "clarify", fallbackStage: "breakdown" },
+    { id: "scenarioQuality", label: "scenarioQuality", fallbackStage: "breakdown" }
+  ];
+  let lintSpecGateObserved = false;
+  let strongestLintSpecGateStatus = "";
+  for (const config of lintSpecGateConfigs) {
+    const gate = getSignalGate(lintSpecSignal, config.id);
+    if (!gate) {
+      continue;
+    }
+    lintSpecGateObserved = true;
+    const gateStatus = resolveEffectiveGateStatus(gate, lintSpecSignal);
+    if (statusSeverity(gateStatus) > statusSeverity(strongestLintSpecGateStatus)) {
+      strongestLintSpecGateStatus = gateStatus;
+    }
+    const evidenceRefs = collectGateEvidenceRefs(gate);
+    const evidenceSuffix =
+      evidenceRefs.length > 0 ? ` Evidence: ${evidenceRefs.join(", ")}` : "";
+    if (gateStatus === STATUS.BLOCK) {
+      findings.blockers.push(
+        `lint-spec gate ${config.label} is BLOCK and prevents planning promotion.${evidenceSuffix}`
+      );
+      addBlockingGateRecord(
+        findings,
+        config.id,
+        "lint-spec",
+        gate,
+        `lint-spec gate ${config.label} is BLOCK`
+      );
+      nextStageId = fallbackStageIfBeyond(nextStageId, config.fallbackStage);
+    } else if (gateStatus === STATUS.WARN) {
+      findings.warnings.push(`lint-spec gate ${config.label} is WARN.${evidenceSuffix}`);
+      if (strictPromotion) {
+        findings.blockers.push(
+          `DA_VINCI_DISCIPLINE_STRICT_PROMOTION is enabled; lint-spec gate ${config.label} WARN blocks promotion.`
+        );
+        addBlockingGateRecord(
+          findings,
+          config.id,
+          "lint-spec",
+          gate,
+          `strict promotion escalated lint-spec gate ${config.label} WARN`
+        );
+        nextStageId = fallbackStageIfBeyond(nextStageId, config.fallbackStage);
+      }
+    }
+    for (const message of Array.isArray(gate.compatibility) ? gate.compatibility : []) {
+      findings.notes.push(`lint-spec gate ${config.label} compatibility: ${message}`);
+    }
+    if (config.id === "clarify") {
+      for (const bounded of Array.isArray(gate.bounded) ? gate.bounded : []) {
+        findings.notes.push(`lint-spec gate clarify bounded ambiguity: ${bounded}`);
+      }
+    }
+  }
+  const lintSpecSignalStatus = normalizeSignalStatus(lintSpecSignal && lintSpecSignal.status);
+  if (
+    lintSpecSignal &&
+    (!lintSpecGateObserved || statusSeverity(lintSpecSignalStatus) > statusSeverity(strongestLintSpecGateStatus))
+  ) {
+    if (lintSpecSignalStatus === STATUS.BLOCK) {
+      findings.blockers.push("lint-spec signal is BLOCK.");
+      addBlockingGateRecord(
+        findings,
+        "lint-spec",
+        "lint-spec",
+        lintSpecSignal.details && lintSpecSignal.details.gates ? lintSpecSignal.details.gates : null,
+        "lint-spec signal is BLOCK"
+      );
+      nextStageId = fallbackStageIfBeyond(nextStageId, "breakdown");
+    } else if (lintSpecSignalStatus === STATUS.WARN) {
+      findings.warnings.push("lint-spec signal is WARN.");
+      if (strictPromotion) {
+        findings.blockers.push(
+          "DA_VINCI_DISCIPLINE_STRICT_PROMOTION is enabled; lint-spec WARN blocks promotion."
+        );
+        addBlockingGateRecord(
+          findings,
+          "lint-spec",
+          "lint-spec",
+          lintSpecSignal.details && lintSpecSignal.details.gates ? lintSpecSignal.details.gates : null,
+          "strict promotion escalated lint-spec WARN"
+        );
+        nextStageId = fallbackStageIfBeyond(nextStageId, "breakdown");
+      }
+    }
+  }
+
+  const analyzeSignal = signalSummary["scope-check"];
+  const analyzeGate = getSignalGate(analyzeSignal, "analyze");
+  let analyzeGateStatus = "";
+  if (analyzeGate) {
+    const evidenceRefs = collectGateEvidenceRefs(analyzeGate);
+    const evidenceSuffix =
+      evidenceRefs.length > 0 ? ` Evidence: ${evidenceRefs.join(", ")}` : "";
+    analyzeGateStatus = resolveEffectiveGateStatus(analyzeGate, analyzeSignal);
+    if (analyzeGateStatus === STATUS.BLOCK) {
+      findings.blockers.push(`scope-check gate analyze is BLOCK.${evidenceSuffix}`);
+      addBlockingGateRecord(
+        findings,
+        "analyze",
+        "scope-check",
+        analyzeGate,
+        "scope-check gate analyze is BLOCK"
+      );
+      nextStageId = fallbackStageIfBeyond(nextStageId, "tasks");
+    } else if (analyzeGateStatus === STATUS.WARN) {
+      findings.warnings.push(`scope-check gate analyze is WARN.${evidenceSuffix}`);
+      if (strictPromotion) {
+        findings.blockers.push(
+          "DA_VINCI_DISCIPLINE_STRICT_PROMOTION is enabled; scope-check gate analyze WARN blocks promotion."
+        );
+        addBlockingGateRecord(
+          findings,
+          "analyze",
+          "scope-check",
+          analyzeGate,
+          "strict promotion escalated scope-check gate analyze WARN"
+        );
+        nextStageId = fallbackStageIfBeyond(nextStageId, "tasks");
+      }
+    }
+    for (const message of Array.isArray(analyzeGate.compatibility) ? analyzeGate.compatibility : []) {
+      findings.notes.push(`scope-check gate analyze compatibility: ${message}`);
+    }
+  }
+  const analyzeSignalStatus = normalizeSignalStatus(analyzeSignal && analyzeSignal.status);
+  if (
+    analyzeSignal &&
+    (!analyzeGate || statusSeverity(analyzeSignalStatus) > statusSeverity(analyzeGateStatus))
+  ) {
+    if (analyzeSignalStatus === STATUS.BLOCK) {
+      findings.blockers.push("scope-check signal is BLOCK.");
+      addBlockingGateRecord(
+        findings,
+        "scope-check",
+        "scope-check",
+        analyzeSignal.details && analyzeSignal.details.gates ? analyzeSignal.details.gates : null,
+        "scope-check signal is BLOCK"
+      );
+      nextStageId = fallbackStageIfBeyond(nextStageId, "tasks");
+    } else if (analyzeSignalStatus === STATUS.WARN) {
+      findings.warnings.push("scope-check signal is WARN.");
+      if (strictPromotion) {
+        findings.blockers.push(
+          "DA_VINCI_DISCIPLINE_STRICT_PROMOTION is enabled; scope-check WARN blocks promotion."
+        );
+        addBlockingGateRecord(
+          findings,
+          "scope-check",
+          "scope-check",
+          analyzeSignal.details && analyzeSignal.details.gates ? analyzeSignal.details.gates : null,
+          "strict promotion escalated scope-check WARN"
+        );
+        nextStageId = fallbackStageIfBeyond(nextStageId, "tasks");
+      }
+    }
+  }
+
+  const lintTasksSignal = signalSummary["lint-tasks"];
+  const taskCheckpointGate = getSignalGate(lintTasksSignal, "taskCheckpoint");
+  const taskCheckpointGateStatus = taskCheckpointGate
+    ? resolveEffectiveGateStatus(taskCheckpointGate, lintTasksSignal)
+    : "";
+  const lintTasksSignalStatus = normalizeSignalStatus(lintTasksSignal && lintTasksSignal.status);
+  if (taskCheckpointGate && taskCheckpointGateStatus === STATUS.BLOCK) {
+    const evidenceRefs = collectGateEvidenceRefs(taskCheckpointGate);
+    const evidenceSuffix =
+      evidenceRefs.length > 0 ? ` Evidence: ${evidenceRefs.join(", ")}` : "";
+    findings.blockers.push(`lint-tasks task-checkpoint is BLOCK and prevents promotion into build.${evidenceSuffix}`);
+    addBlockingGateRecord(
+      findings,
+      "taskCheckpoint",
+      "lint-tasks",
+      taskCheckpointGate,
+      "lint-tasks task-checkpoint is BLOCK"
+    );
+    nextStageId = fallbackStageIfBeyond(nextStageId, "tasks");
+  } else if (taskCheckpointGate && taskCheckpointGateStatus === STATUS.WARN) {
+    const evidenceRefs = collectGateEvidenceRefs(taskCheckpointGate);
+    const evidenceSuffix =
+      evidenceRefs.length > 0 ? ` Evidence: ${evidenceRefs.join(", ")}` : "";
+    findings.warnings.push(`lint-tasks task-checkpoint is WARN.${evidenceSuffix}`);
+    if (strictPromotion) {
+      findings.blockers.push(
+        "DA_VINCI_DISCIPLINE_STRICT_PROMOTION is enabled; lint-tasks WARN blocks promotion into build."
+      );
+      addBlockingGateRecord(
+        findings,
+        "taskCheckpoint",
+        "lint-tasks",
+        taskCheckpointGate,
+        "strict promotion escalated lint-tasks task-checkpoint WARN"
+      );
+      nextStageId = fallbackStageIfBeyond(nextStageId, "tasks");
+    }
+  }
+  if (
+    lintTasksSignal &&
+    (!taskCheckpointGate || statusSeverity(lintTasksSignalStatus) > statusSeverity(taskCheckpointGateStatus))
+  ) {
+    if (lintTasksSignalStatus === STATUS.BLOCK) {
+      findings.blockers.push("lint-tasks signal is BLOCK.");
+      addBlockingGateRecord(
+        findings,
+        "lint-tasks",
+        "lint-tasks",
+        lintTasksSignal.details && lintTasksSignal.details.gates ? lintTasksSignal.details.gates : null,
+        "lint-tasks signal is BLOCK"
+      );
+      nextStageId = fallbackStageIfBeyond(nextStageId, "tasks");
+    } else if (lintTasksSignalStatus === STATUS.WARN) {
+      findings.warnings.push("lint-tasks signal is WARN.");
+      if (strictPromotion) {
+        findings.blockers.push(
+          "DA_VINCI_DISCIPLINE_STRICT_PROMOTION is enabled; lint-tasks WARN blocks promotion into build."
+        );
+        addBlockingGateRecord(
+          findings,
+          "lint-tasks",
+          "lint-tasks",
+          lintTasksSignal.details && lintTasksSignal.details.gates ? lintTasksSignal.details.gates : null,
+          "strict promotion escalated lint-tasks WARN"
+        );
+        nextStageId = fallbackStageIfBeyond(nextStageId, "tasks");
+      }
+    }
+  }
+  if (taskCheckpointGate) {
+    for (const message of Array.isArray(taskCheckpointGate.compatibility)
+      ? taskCheckpointGate.compatibility
+      : []) {
+      findings.notes.push(`lint-tasks gate taskCheckpoint compatibility: ${message}`);
+    }
+  }
+
+  const verificationSignal = signalSummary["verify-coverage"];
+  if (verificationSignal && verificationSignal.status === STATUS.BLOCK) {
+    findings.blockers.push("verify-coverage signal is BLOCK.");
+    if (nextStageId === "complete") {
+      nextStageId = "verify";
+    }
+  } else if (verificationSignal && verificationSignal.status === STATUS.WARN) {
+    findings.warnings.push("verify-coverage signal is WARN.");
+  }
+
+  return nextStageId;
+}
+
+function buildGatesWithLiveOverlays(baseGates, completionAudit, disciplineState, verificationFreshness) {
+  const gates = baseGates && typeof baseGates === "object" ? { ...baseGates } : {};
+  if (completionAudit) {
+    gates[HANDOFF_GATES.VERIFY_TO_COMPLETE] =
+      completionAudit.status === 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;
+}
+
+/**
+ * Apply runtime/live overlays on top of a base workflow view.
+ *
+ * @param {{
+ *   projectRoot: string,
+ *   changeId?: string | null,
+ *   stageId: string,
+ *   findings: WorkflowFindings,
+ *   baseGates: Object.<string, string>,
+ *   taskGroups?: Array<object>,
+ *   changeSignals?: Array<object>,
+ *   signalSummary?: Object.<string, object>,
+ *   planningSignalFreshness?: PlanningSignalFreshnessState,
+ *   integrityAudit?: object | null,
+ *   completionAudit?: object | null,
+ *   disciplineState?: object | null,
+ *   verificationFreshness?: object | null,
+ *   hasTasksArtifact?: boolean,
+ *   decisionTraceRecords?: Array<object> | null,
+ *   recordWorkflowDecision?: Function
+ * }} [options]
+ * @returns {WorkflowOverlayResult}
+ */
+function applyWorkflowOverlays(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 = Array.isArray(options.taskGroups) ? options.taskGroups : [];
+  const decisionTraceRecords = Array.isArray(options.decisionTraceRecords)
+    ? options.decisionTraceRecords
+    : null;
+  const recordWorkflowDecision = options.recordWorkflowDecision;
+
+  stageId = applyAuditFindings(stageId, findings, integrityAudit, completionAudit);
+  stageId = applyPlanningSignalFreshnessFindings(
+    stageId,
+    findings,
+    planningSignalFreshness,
+    decisionTraceRecords,
+    recordWorkflowDecision
+  );
+  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")) {
+    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") {
+      recordDecision(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(
+    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."
+      );
+      recordDecision(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"]
+      });
+    }
+  }
+
+  dedupeFindings(findings);
+
+  return {
+    stageId,
+    findings,
+    gates,
+    taskGroups,
+    executionProfile,
+    worktreePreflight,
+    blockingGate: selectBlockingGateIdentity(findings),
+    needsRerunSurfaces: planningSignalFreshness.needsRerunSurfaces,
+    stalePlanningSignals: planningSignalFreshness.stalePlanningSignals
+  };
+}
+
+module.exports = {
+  collectPlanningSignalFreshnessState,
+  inspectDisciplineState,
+  applyWorkflowOverlays
+};