@xenonbyte/da-vinci-workflow 0.1.26 → 0.2.2

package/lib/workflow-state.js

@@ -0,0 +1,785 @@
+const path = require("path");
+const { auditProject } = require("./audit");
+const { parseCheckpointStatusMap, normalizeCheckpointLabel } = require("./audit-parsers");
+const { pathExists, readTextIfExists } = require("./utils");
+const {
+  parseTasksArtifact,
+  listImmediateDirs,
+  hasAnyFile,
+  pickLatestChange,
+  detectSpecFiles
+} = require("./planning-parsers");
+const {
+  STATUS,
+  CHECKPOINT_LABELS,
+  HANDOFF_GATES,
+  getStageById
+} = require("./workflow-contract");
+const {
+  selectPersistedStateForChange,
+  persistDerivedWorkflowResult,
+  writeTaskGroupMetadata,
+  readTaskGroupMetadata,
+  sanitizePersistedNotes
+} = require("./workflow-persisted-state");
+const { readExecutionSignals, summarizeSignalsBySurface } = require("./execution-signals");
+
+const MAX_REPORTED_MESSAGES = 3;
+
+function summarizeAudit(result) {
+  if (!result) {
+    return null;
+  }
+
+  return {
+    status: result.status,
+    failures: Array.isArray(result.failures) ? result.failures.slice(0, MAX_REPORTED_MESSAGES) : [],
+    warnings: Array.isArray(result.warnings) ? result.warnings.slice(0, MAX_REPORTED_MESSAGES) : [],
+    notes: Array.isArray(result.notes) ? result.notes.slice(0, MAX_REPORTED_MESSAGES) : []
+  };
+}
+
+function dedupeMessages(items) {
+  return Array.from(new Set((items || []).filter(Boolean)));
+}
+
+function dedupeFindings(findings) {
+  findings.blockers = dedupeMessages(findings.blockers);
+  findings.warnings = dedupeMessages(findings.warnings);
+  findings.notes = dedupeMessages(findings.notes);
+}
+
+function collectIntegrityAudit(projectRoot, workflowRoot, signalSummary) {
+  if (!pathExists(workflowRoot)) {
+    return null;
+  }
+  return summarizeAudit(
+    auditProject(projectRoot, {
+      mode: "integrity",
+      preloadedSignalSummary: signalSummary
+    })
+  );
+}
+
+function collectCompletionAudit(projectRoot, workflowRoot, changeId, signalSummary) {
+  if (!changeId || !pathExists(workflowRoot)) {
+    return null;
+  }
+  return summarizeAudit(
+    auditProject(projectRoot, {
+      mode: "completion",
+      changeId,
+      preloadedSignalSummary: signalSummary
+    })
+  );
+}
+
+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 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 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 buildRouteRecommendation(stageId, context = {}) {
+  const projectRoot = context.projectRoot || process.cwd();
+  const changeId = context.changeId || "change-001";
+
+  if (context.ambiguousChangeSelection) {
+    return {
+      route: "select-change",
+      command: `da-vinci workflow-status --project ${projectRoot} --change <change-id>`,
+      reason: "Multiple change directories were found. Choose one change id first."
+    };
+  }
+
+  switch (stageId) {
+    case "bootstrap":
+      return {
+        route: "bootstrap-project",
+        command: `da-vinci bootstrap-project --project ${projectRoot} --change ${changeId}`,
+        reason: "Workflow base artifacts are missing."
+      };
+    case "breakdown":
+      return {
+        route: "/dv:breakdown",
+        command: "/dv:breakdown",
+        reason: "Proposal or spec artifacts are incomplete."
+      };
+    case "design":
+      return {
+        route: "/dv:design",
+        command: "/dv:design",
+        reason: "Design artifacts or design checkpoints are not ready."
+      };
+    case "tasks":
+      return {
+        route: "/dv:tasks",
+        command: "/dv:tasks",
+        reason: "Task planning artifacts are missing or blocked."
+      };
+    case "build":
+      return {
+        route: "/dv:build",
+        command: "/dv:build",
+        reason: "Implementation should proceed before verification."
+      };
+    case "verify":
+      return {
+        route: "/dv:verify",
+        command: "/dv:verify",
+        reason: "Verification and completion readiness are not satisfied yet."
+      };
+    default:
+      return {
+        route: null,
+        command: null,
+        reason: "No next route. Workflow appears complete."
+      };
+  }
+}
+
+function readCheckpointStatuses(changeDir) {
+  const collected = {};
+  const files = [
+    path.join(changeDir, "design.md"),
+    path.join(changeDir, "pencil-design.md"),
+    path.join(changeDir, "tasks.md"),
+    path.join(changeDir, "verification.md")
+  ];
+
+  for (const artifactPath of files) {
+    const text = readTextIfExists(artifactPath);
+    if (!text) {
+      continue;
+    }
+    const statuses = parseCheckpointStatusMap(text);
+    for (const [label, value] of Object.entries(statuses)) {
+      const normalized = normalizeCheckpointLabel(label);
+      if (!normalized) {
+        continue;
+      }
+      collected[normalized] = String(value || "").toUpperCase();
+    }
+  }
+
+  return collected;
+}
+
+function deriveStageFromArtifacts(artifactState, checkpointStatuses, findings) {
+  if (!artifactState.workflowRootReady) {
+    findings.blockers.push("Missing `.da-vinci/` directory.");
+    return "bootstrap";
+  }
+
+  if (!artifactState.changeSelected) {
+    findings.blockers.push("No active change selected under `.da-vinci/changes/`.");
+    return "breakdown";
+  }
+
+  if (!artifactState.proposal || artifactState.specFiles.length === 0) {
+    if (!artifactState.proposal) {
+      findings.blockers.push("Missing `proposal.md` for the active change.");
+    }
+    if (artifactState.specFiles.length === 0) {
+      findings.blockers.push("Missing `specs/*/spec.md` for the active change.");
+    }
+    return "breakdown";
+  }
+
+  if (
+    !artifactState.design ||
+    !artifactState.pencilDesign ||
+    !artifactState.pencilBindings
+  ) {
+    if (!artifactState.design) {
+      findings.blockers.push("Missing `design.md` for the active change.");
+    }
+    if (!artifactState.pencilDesign) {
+      findings.blockers.push("Missing `pencil-design.md` for the active change.");
+    }
+    if (!artifactState.pencilBindings) {
+      findings.blockers.push("Missing `pencil-bindings.md` for the active change.");
+    }
+    return "design";
+  }
+
+  const designCheckpoint = checkpointStatuses[CHECKPOINT_LABELS.DESIGN];
+  if (designCheckpoint === STATUS.BLOCK) {
+    findings.blockers.push("`design checkpoint` is BLOCK.");
+    return "design";
+  }
+  if (designCheckpoint === STATUS.WARN) {
+    findings.warnings.push("`design checkpoint` is WARN.");
+  }
+
+  const mappingCheckpoint = checkpointStatuses[CHECKPOINT_LABELS.MAPPING];
+  if (mappingCheckpoint === STATUS.BLOCK) {
+    findings.blockers.push("`mapping checkpoint` is BLOCK.");
+    return "design";
+  }
+  if (mappingCheckpoint === STATUS.WARN) {
+    findings.warnings.push("`mapping checkpoint` is WARN.");
+  }
+
+  if (!artifactState.tasks) {
+    findings.blockers.push("Missing `tasks.md` for the active change.");
+    return "tasks";
+  }
+
+  const taskCheckpoint = checkpointStatuses[CHECKPOINT_LABELS.TASK];
+  if (taskCheckpoint === STATUS.BLOCK) {
+    findings.blockers.push("`task checkpoint` is BLOCK.");
+    return "tasks";
+  }
+  if (taskCheckpoint === STATUS.WARN) {
+    findings.warnings.push("`task checkpoint` is WARN.");
+  }
+
+  if (!artifactState.verification) {
+    findings.blockers.push("Missing `verification.md` for the active change.");
+    return "build";
+  }
+
+  return "verify";
+}
+
+function deriveTaskGroupMetadata(tasksMarkdownText, checkpointStatuses) {
+  if (!tasksMarkdownText) {
+    return [];
+  }
+
+  const taskArtifact = parseTasksArtifact(tasksMarkdownText);
+  const lines = String(tasksMarkdownText || "").replace(/\r\n?/g, "\n").split("\n");
+  const sections = [];
+  let current = null;
+  for (const line of lines) {
+    const headingMatch = line.match(/^\s{0,3}##\s+(\d+(?:\.\d+)*)\.\s+(.+)$/);
+    if (headingMatch) {
+      if (current) {
+        sections.push(current);
+      }
+      current = {
+        id: headingMatch[1],
+        title: String(headingMatch[2] || "").trim(),
+        checklistItems: []
+      };
+      continue;
+    }
+    if (!current) {
+      continue;
+    }
+    const checklistMatch = line.match(/^\s*-\s*\[([ xX])\]\s+(.+)$/);
+    if (checklistMatch) {
+      current.checklistItems.push({
+        checked: String(checklistMatch[1] || "").toLowerCase() === "x",
+        text: String(checklistMatch[2] || "").trim()
+      });
+    }
+  }
+  if (current) {
+    sections.push(current);
+  }
+
+  const normalizedTaskCheckpoint = checkpointStatuses[CHECKPOINT_LABELS.TASK] || STATUS.WARN;
+  const metadata = sections.map((section, index) => {
+    const total = section.checklistItems.length;
+    const done = section.checklistItems.filter((item) => item.checked).length;
+    const completion = total > 0 ? Math.round((done / total) * 100) : 0;
+    const sectionStatus =
+      total === 0 ? "pending" : done === 0 ? "pending" : done < total ? "in_progress" : "completed";
+    const nextAction =
+      sectionStatus === "completed"
+        ? "advance to next task group"
+        : section.checklistItems.find((item) => !item.checked)?.text || "continue group work";
+
+    return {
+      taskGroupId: section.id,
+      title: section.title,
+      status: sectionStatus,
+      completion,
+      checkpointOutcome: normalizedTaskCheckpoint,
+      evidence: section.checklistItems.filter((item) => item.checked).map((item) => item.text),
+      nextAction,
+      resumeCursor: {
+        groupIndex: index,
+        nextUncheckedItem:
+          section.checklistItems.find((item) => !item.checked)?.text ||
+          section.checklistItems[section.checklistItems.length - 1]?.text ||
+          null
+      }
+    };
+  });
+
+  if (metadata.length === 0 && taskArtifact.taskGroups.length > 0) {
+    return taskArtifact.taskGroups.map((group, index) => ({
+      taskGroupId: group.id,
+      title: group.title,
+      status: "pending",
+      completion: 0,
+      checkpointOutcome: normalizedTaskCheckpoint,
+      evidence: [],
+      nextAction: "start task group",
+      resumeCursor: {
+        groupIndex: index,
+        nextUncheckedItem: null
+      }
+    }));
+  }
+
+  return metadata;
+}
+
+function statusFromFindings(findings) {
+  if (findings.blockers.length > 0) {
+    return STATUS.BLOCK;
+  }
+  if (findings.warnings.length > 0) {
+    return STATUS.WARN;
+  }
+  return STATUS.PASS;
+}
+
+function deriveWorkflowStatus(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
+  const findings = {
+    blockers: [],
+    warnings: [],
+    notes: []
+  };
+
+  if (!pathExists(projectRoot)) {
+    findings.blockers.push(`Project path does not exist: ${projectRoot}`);
+    const stageId = "bootstrap";
+    return buildWorkflowResult({
+      projectRoot,
+      changeId: null,
+      stageId,
+      findings,
+      checkpoints: {},
+      gates: {},
+      audits: {
+        integrity: null,
+        completion: null
+      },
+      routeContext: {
+        projectRoot,
+        changeId: requestedChangeId || "change-001",
+        ambiguousChangeSelection: false
+      }
+    });
+  }
+
+  const workflowRoot = path.join(projectRoot, ".da-vinci");
+  const changesRoot = path.join(workflowRoot, "changes");
+  const changeDirs = listImmediateDirs(changesRoot).filter((changeDir) => hasAnyFile(changeDir));
+  const changeIds = changeDirs.map((changeDir) => path.basename(changeDir)).sort();
+
+  let activeChangeDir = null;
+  let ambiguousChangeSelection = false;
+  if (!pathExists(workflowRoot)) {
+    findings.blockers.push("Missing `.da-vinci/` directory.");
+  } else if (requestedChangeId) {
+    activeChangeDir = path.join(changesRoot, requestedChangeId);
+    if (!pathExists(activeChangeDir) || !hasAnyFile(activeChangeDir)) {
+      findings.blockers.push(
+        `Requested change was not found or is empty: .da-vinci/changes/${requestedChangeId}`
+      );
+      activeChangeDir = null;
+    }
+  } else if (changeDirs.length === 1) {
+    activeChangeDir = changeDirs[0];
+  } else if (changeDirs.length > 1) {
+    ambiguousChangeSelection = true;
+    findings.blockers.push(
+      "Multiple non-empty change directories found. Re-run with `--change <change-id>`."
+    );
+    findings.notes.push(`Available change ids: ${changeIds.join(", ")}`);
+    activeChangeDir = pickLatestChange(changeDirs);
+    if (activeChangeDir) {
+      findings.notes.push(
+        `Latest inferred change for context only: ${path.basename(activeChangeDir)}`
+      );
+    }
+  } else {
+    findings.blockers.push("No non-empty change directory found under `.da-vinci/changes/`.");
+  }
+
+  const activeChangeId = activeChangeDir ? path.basename(activeChangeDir) : null;
+  const artifactState = {
+    workflowRootReady: pathExists(workflowRoot),
+    changeSelected: Boolean(activeChangeDir),
+    proposal: activeChangeDir ? pathExists(path.join(activeChangeDir, "proposal.md")) : false,
+    specFiles: activeChangeDir ? detectSpecFiles(path.join(activeChangeDir, "specs")) : [],
+    design: activeChangeDir ? pathExists(path.join(activeChangeDir, "design.md")) : false,
+    pencilDesign: activeChangeDir ? pathExists(path.join(activeChangeDir, "pencil-design.md")) : false,
+    pencilBindings: activeChangeDir ? pathExists(path.join(activeChangeDir, "pencil-bindings.md")) : false,
+    tasks: activeChangeDir ? pathExists(path.join(activeChangeDir, "tasks.md")) : false,
+    verification: activeChangeDir ? pathExists(path.join(activeChangeDir, "verification.md")) : false
+  };
+
+  const tasksArtifactText = activeChangeDir ? readTextIfExists(path.join(activeChangeDir, "tasks.md")) : "";
+  const checkpointStatuses = activeChangeDir ? readCheckpointStatuses(activeChangeDir) : {};
+  const signalSummary = activeChangeId
+    ? summarizeSignalsBySurface(
+        readExecutionSignals(projectRoot, {
+          changeId: activeChangeId
+        })
+      )
+    : {};
+  const integrityAudit = collectIntegrityAudit(projectRoot, workflowRoot, signalSummary);
+
+  if (activeChangeId) {
+    const persistedSelection = selectPersistedStateForChange(projectRoot, activeChangeId, {
+      staleWindowMs: options.staleWindowMs
+    });
+    if (persistedSelection.usable && persistedSelection.changeRecord) {
+      const persistedRecord = persistedSelection.changeRecord;
+      const stageRecord = getStageById(persistedRecord.stage) || getStageById("bootstrap");
+      const persistedTaskMetadata = readTaskGroupMetadata(projectRoot, activeChangeId);
+      const persistedFindings = {
+        blockers: Array.isArray(persistedRecord.failures) ? persistedRecord.failures.slice() : [],
+        warnings: Array.isArray(persistedRecord.warnings) ? persistedRecord.warnings.slice() : [],
+        notes: sanitizePersistedNotes(persistedRecord.notes)
+      };
+      let persistedStageId = stageRecord.id;
+      const persistedNeedsCompletionAudit =
+        persistedStageId === "verify" || persistedStageId === "complete";
+      const completionAudit = persistedNeedsCompletionAudit
+        ? collectCompletionAudit(projectRoot, workflowRoot, activeChangeId, signalSummary)
+        : null;
+      persistedStageId = applyAuditFindings(
+        persistedStageId,
+        persistedFindings,
+        integrityAudit,
+        completionAudit
+      );
+      persistedStageId = applyExecutionSignalFindings(
+        persistedStageId,
+        persistedFindings,
+        signalSummary
+      );
+      persistedFindings.notes.push("workflow-status is using trusted persisted workflow state.");
+      dedupeFindings(persistedFindings);
+
+      const persistedGates =
+        persistedRecord && persistedRecord.gates && typeof persistedRecord.gates === "object"
+          ? { ...persistedRecord.gates }
+          : {};
+      if (completionAudit) {
+        persistedGates[HANDOFF_GATES.VERIFY_TO_COMPLETE] =
+          completionAudit.status === "PASS" ? STATUS.PASS : STATUS.WARN;
+      }
+
+      return buildWorkflowResult({
+        projectRoot,
+        changeId: activeChangeId,
+        stageId: persistedStageId,
+        findings: persistedFindings,
+        checkpoints: checkpointStatuses,
+        gates: persistedGates,
+        audits: {
+          integrity: integrityAudit,
+          completion: completionAudit
+        },
+        routeContext: {
+          projectRoot,
+          changeId: activeChangeId,
+          ambiguousChangeSelection
+        },
+        source: "persisted",
+        taskGroups:
+          persistedTaskMetadata && Array.isArray(persistedTaskMetadata.taskGroups)
+            ? persistedTaskMetadata.taskGroups
+            : Array.isArray(persistedRecord.taskGroups)
+            ? persistedRecord.taskGroups
+            : []
+      });
+    }
+
+    if (!persistedSelection.usable && persistedSelection.reason) {
+      const reasonMessage = {
+        missing: "No persisted workflow state found for this change; deriving from artifacts.",
+        "parse-error": "Persisted workflow state is unreadable; deriving from artifacts.",
+        "version-mismatch": "Persisted workflow state version mismatch; deriving from artifacts.",
+        "change-missing": "Persisted workflow state has no entry for this change; deriving from artifacts.",
+        "invalid-timestamp": "Persisted workflow state timestamp invalid; deriving from artifacts.",
+        "time-stale": "Persisted workflow state is stale by time; deriving from artifacts.",
+        "fingerprint-mismatch": "Persisted workflow state conflicts with artifact truth; deriving from artifacts."
+      };
+      const message = reasonMessage[persistedSelection.reason];
+      if (message) {
+        findings.notes.push(message);
+      }
+    }
+  }
+
+  let stageId = deriveStageFromArtifacts(artifactState, checkpointStatuses, findings);
+  const needsCompletionAudit = stageId === "verify" || stageId === "complete";
+  const completionAudit = needsCompletionAudit
+    ? collectCompletionAudit(projectRoot, workflowRoot, activeChangeId, signalSummary)
+    : null;
+  stageId = applyAuditFindings(stageId, findings, integrityAudit, completionAudit);
+  stageId = applyExecutionSignalFindings(stageId, findings, signalSummary);
+
+  const gates = {
+    [HANDOFF_GATES.BREAKDOWN_TO_DESIGN]:
+      artifactState.proposal && artifactState.specFiles.length > 0 ? STATUS.PASS : STATUS.BLOCK,
+    [HANDOFF_GATES.DESIGN_TO_TASKS]:
+      artifactState.design && artifactState.pencilDesign && artifactState.pencilBindings
+        ? STATUS.PASS
+        : STATUS.BLOCK,
+    [HANDOFF_GATES.TASKS_TO_BUILD]: artifactState.tasks ? STATUS.PASS : STATUS.BLOCK,
+    [HANDOFF_GATES.BUILD_TO_VERIFY]: artifactState.verification ? STATUS.PASS : STATUS.BLOCK,
+    [HANDOFF_GATES.VERIFY_TO_COMPLETE]:
+      completionAudit && completionAudit.status === "PASS" ? STATUS.PASS : STATUS.WARN
+  };
+
+  const derivedTaskGroups = deriveTaskGroupMetadata(tasksArtifactText, checkpointStatuses);
+  if (activeChangeId && !ambiguousChangeSelection && derivedTaskGroups.length > 0) {
+    const metadataPayload = {
+      version: 1,
+      changeId: activeChangeId,
+      checkpointOutcome: checkpointStatuses[CHECKPOINT_LABELS.TASK] || STATUS.WARN,
+      taskGroups: derivedTaskGroups,
+      updatedAt: new Date().toISOString()
+    };
+    const metadataPath = writeTaskGroupMetadata(projectRoot, activeChangeId, metadataPayload);
+    if (metadataPath) {
+      findings.notes.push(`Task-group metadata refreshed: ${metadataPath}`);
+    }
+  } else if (activeChangeId && ambiguousChangeSelection && derivedTaskGroups.length > 0) {
+    findings.notes.push(
+      "Skipped task-group metadata persistence because change selection is ambiguous."
+    );
+  }
+  dedupeFindings(findings);
+
+  const derivedResult = buildWorkflowResult({
+    projectRoot,
+    changeId: activeChangeId,
+    stageId,
+    findings,
+    checkpoints: checkpointStatuses,
+    gates,
+    audits: {
+      integrity: integrityAudit,
+      completion: completionAudit
+    },
+    routeContext: {
+      projectRoot,
+      changeId: activeChangeId || requestedChangeId || "change-001",
+      ambiguousChangeSelection
+    },
+    taskGroups: derivedTaskGroups
+  });
+
+  if (activeChangeId && !ambiguousChangeSelection) {
+    try {
+      persistDerivedWorkflowResult(projectRoot, activeChangeId, derivedResult, {
+        metadataRefs: {
+          taskGroupsPath: activeChangeId
+            ? path.join(projectRoot, ".da-vinci", "state", "task-groups", `${activeChangeId}.json`)
+            : null
+        }
+      });
+      derivedResult.notes.push("workflow-status persisted a fresh derived workflow snapshot.");
+    } catch (error) {
+      const message =
+        error && error.message
+          ? error.message
+          : "unknown write error";
+      derivedResult.warnings = dedupeMessages([
+        ...derivedResult.warnings,
+        `Failed to persist workflow snapshot: ${message}`
+      ]);
+      if (derivedResult.checkpointState === STATUS.PASS) {
+        derivedResult.checkpointState = STATUS.WARN;
+      }
+      if (derivedResult.status === STATUS.PASS) {
+        derivedResult.status = STATUS.WARN;
+      }
+    }
+  } else if (activeChangeId && ambiguousChangeSelection) {
+    derivedResult.notes = dedupeMessages([
+      ...derivedResult.notes,
+      "Skipped workflow snapshot persistence because change selection is ambiguous."
+    ]);
+  }
+
+  return derivedResult;
+}
+
+function buildWorkflowResult(params) {
+  const stage = getStageById(params.stageId) || getStageById("bootstrap");
+  const nextStep = buildRouteRecommendation(params.stageId, params.routeContext);
+  const checkpointState = statusFromFindings(params.findings);
+
+  return {
+    status: checkpointState,
+    failures: params.findings.blockers,
+    warnings: params.findings.warnings,
+    notes: params.findings.notes,
+    projectRoot: params.projectRoot,
+    changeId: params.changeId || null,
+    stage: stage.id,
+    stageLabel: stage.label,
+    stageOrder: stage.order,
+    checkpointState,
+    checkpoints: params.checkpoints,
+    gates: params.gates,
+    audits: params.audits,
+    nextStep,
+    source: params.source || "derived",
+    taskGroups: Array.isArray(params.taskGroups) ? params.taskGroups : []
+  };
+}
+
+function formatWorkflowStatusReport(result) {
+  const lines = [
+    "Da Vinci workflow-status",
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId || "(not selected)"}`,
+    `Stage: ${result.stageLabel} (${result.stage})`,
+    `Checkpoint state: ${result.checkpointState}`
+  ];
+
+  if (result.nextStep && result.nextStep.command) {
+    lines.push(`Next route: ${result.nextStep.command}`);
+    if (result.nextStep.reason) {
+      lines.push(`Route reason: ${result.nextStep.reason}`);
+    }
+  } else {
+    lines.push("Next route: none");
+  }
+
+  if (result.failures.length > 0) {
+    lines.push("Blockers:");
+    for (const message of result.failures) {
+      lines.push(`- ${message}`);
+    }
+  }
+
+  if (result.warnings.length > 0) {
+    lines.push("Warnings:");
+    for (const message of result.warnings) {
+      lines.push(`- ${message}`);
+    }
+  }
+
+  if (result.notes.length > 0) {
+    lines.push("Notes:");
+    for (const message of result.notes) {
+      lines.push(`- ${message}`);
+    }
+  }
+
+  if (result.audits.integrity) {
+    lines.push(`Integrity audit: ${result.audits.integrity.status}`);
+  }
+  if (result.audits.completion) {
+    lines.push(`Completion audit: ${result.audits.completion.status}`);
+  }
+  if (result.source) {
+    lines.push(`State source: ${result.source}`);
+  }
+  if (Array.isArray(result.taskGroups) && result.taskGroups.length > 0) {
+    lines.push("Task-group metadata:");
+    for (const group of result.taskGroups) {
+      lines.push(
+        `- ${group.taskGroupId || group.id || "group"}: ${group.status || "unknown"} (${group.completion || 0}%)`
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function formatNextStepReport(result) {
+  const lines = [
+    "Da Vinci next-step",
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId || "(not selected)"}`,
+    `Stage: ${result.stageLabel} (${result.stage})`,
+    `Checkpoint state: ${result.checkpointState}`
+  ];
+
+  if (!result.nextStep || !result.nextStep.command) {
+    lines.push("Next action: no further route is required.");
+    return lines.join("\n");
+  }
+
+  lines.push(`Next action: ${result.nextStep.command}`);
+  if (result.nextStep.reason) {
+    lines.push(`Reason: ${result.nextStep.reason}`);
+  }
+  if (Array.isArray(result.taskGroups) && result.taskGroups.length > 0) {
+    const active =
+      result.taskGroups.find((group) => group.status === "in_progress") ||
+      result.taskGroups.find((group) => group.status === "pending");
+    if (active) {
+      lines.push(`Task-group focus: ${active.taskGroupId || active.id} -> ${active.nextAction || "continue"}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  deriveWorkflowStatus,
+  formatWorkflowStatusReport,
+  formatNextStepReport
+};