@xenonbyte/da-vinci-workflow 0.2.7 → 0.2.9

package/lib/workflow-persisted-state.js

@@ -2,6 +2,7 @@ const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
 const { writeFileAtomic, pathExists, readTextIfExists } = require("./utils");
+const { listExecutionSignalPathsForChange } = require("./execution-signals");
 
 // Route snapshot schema version; task-group metadata keeps its own version in workflow-state.js.
 const WORKFLOW_STATE_VERSION = 3;
@@ -64,6 +65,9 @@ function buildWorkflowFingerprint(projectRoot, changeId) {
     path.join(changeRoot, "tasks.md"),
     path.join(changeRoot, "verification.md")
   ];
+  if (changeId) {
+    candidates.push(...listExecutionSignalPathsForChange(projectRoot, { changeId }));
+  }
 
   const specRoot = path.join(changeRoot, "specs");
   if (pathExists(specRoot)) {

package/lib/workflow-stage.js

@@ -0,0 +1,244 @@
+const path = require("path");
+const {
+  parseCheckpointStatusMap,
+  normalizeCheckpointLabel
+} = require("./audit-parsers");
+const { readTextIfExists } = require("./utils");
+const {
+  STATUS,
+  CHECKPOINT_LABELS,
+  HANDOFF_GATES,
+  mergeStatuses
+} = require("./workflow-contract");
+
+/**
+ * @typedef {Object} WorkflowArtifactState
+ * @property {boolean} workflowRootReady
+ * @property {boolean} changeSelected
+ * @property {boolean} proposal
+ * @property {string[]} specFiles
+ * @property {boolean} design
+ * @property {boolean} pencilDesign
+ * @property {boolean} pencilBindings
+ * @property {boolean} tasks
+ * @property {boolean} verification
+ */
+
+/**
+ * @typedef {Object.<string, string>} WorkflowCheckpointStatusMap
+ */
+
+/**
+ * @typedef {"bootstrap"|"breakdown"|"design"|"tasks"|"build"|"verify"|"complete"} WorkflowStageId
+ */
+
+/**
+ * @typedef {Object} WorkflowFindings
+ * @property {string[]} blockers
+ * @property {string[]} warnings
+ * @property {string[]} notes
+ */
+
+/**
+ * @typedef {Object.<string, string>} WorkflowBaseGateMap
+ */
+
+/**
+ * Read normalized checkpoint statuses from change-local workflow artifacts.
+ *
+ * @param {string} changeDir
+ * @returns {WorkflowCheckpointStatusMap}
+ */
+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;
+}
+
+/**
+ * Normalize a checkpoint status token into PASS/WARN/BLOCK, defaulting to PASS.
+ *
+ * @param {string} status
+ * @returns {string}
+ */
+function normalizeCheckpointStatus(status) {
+  const normalized = String(status || "").toUpperCase();
+  if (normalized === STATUS.PASS || normalized === STATUS.WARN || normalized === STATUS.BLOCK) {
+    return normalized;
+  }
+  return STATUS.PASS;
+}
+
+/**
+ * Derive the artifact-backed workflow stage before any runtime overlays apply.
+ *
+ * @param {WorkflowArtifactState} artifactState
+ * @param {WorkflowCheckpointStatusMap} checkpointStatuses
+ * @param {WorkflowFindings} findings
+ * @returns {WorkflowStageId}
+ */
+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 designSourceCheckpoint = checkpointStatuses[CHECKPOINT_LABELS.DESIGN_SOURCE];
+  if (designSourceCheckpoint === STATUS.BLOCK) {
+    findings.blockers.push("`design source checkpoint` is BLOCK.");
+    return "design";
+  }
+  if (designSourceCheckpoint === STATUS.WARN) {
+    findings.warnings.push("`design source checkpoint` is WARN.");
+  }
+
+  const runtimeGateCheckpoint = checkpointStatuses[CHECKPOINT_LABELS.RUNTIME_GATE];
+  if (runtimeGateCheckpoint === STATUS.BLOCK) {
+    findings.blockers.push("`mcp runtime gate` is BLOCK.");
+    return "design";
+  }
+  if (runtimeGateCheckpoint === STATUS.WARN) {
+    findings.warnings.push("`mcp runtime gate` 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";
+}
+
+/**
+ * Build the handoff-gate baseline that corresponds to artifact/checkpoint truth.
+ *
+ * @param {WorkflowArtifactState} artifactState
+ * @param {WorkflowCheckpointStatusMap} checkpointStatuses
+ * @param {{ completionAudit?: { status?: string } | null }} [options]
+ * @returns {WorkflowBaseGateMap}
+ */
+function buildBaseHandoffGates(artifactState, checkpointStatuses, options = {}) {
+  const designCheckpointStatus = normalizeCheckpointStatus(checkpointStatuses[CHECKPOINT_LABELS.DESIGN]);
+  const designSourceCheckpointStatus = normalizeCheckpointStatus(
+    checkpointStatuses[CHECKPOINT_LABELS.DESIGN_SOURCE]
+  );
+  const runtimeGateCheckpointStatus = normalizeCheckpointStatus(
+    checkpointStatuses[CHECKPOINT_LABELS.RUNTIME_GATE]
+  );
+  const mappingCheckpointStatus = normalizeCheckpointStatus(checkpointStatuses[CHECKPOINT_LABELS.MAPPING]);
+  const taskCheckpointStatus = normalizeCheckpointStatus(checkpointStatuses[CHECKPOINT_LABELS.TASK]);
+  const completionAudit = options.completionAudit || null;
+
+  return {
+    [HANDOFF_GATES.BREAKDOWN_TO_DESIGN]:
+      artifactState.proposal && artifactState.specFiles.length > 0 ? STATUS.PASS : STATUS.BLOCK,
+    [HANDOFF_GATES.DESIGN_TO_TASKS]: mergeStatuses([
+      artifactState.design && artifactState.pencilDesign && artifactState.pencilBindings
+        ? STATUS.PASS
+        : STATUS.BLOCK,
+      designCheckpointStatus,
+      designSourceCheckpointStatus,
+      runtimeGateCheckpointStatus,
+      mappingCheckpointStatus
+    ]),
+    [HANDOFF_GATES.TASKS_TO_BUILD]: mergeStatuses([
+      artifactState.tasks ? STATUS.PASS : STATUS.BLOCK,
+      designCheckpointStatus,
+      designSourceCheckpointStatus,
+      runtimeGateCheckpointStatus,
+      mappingCheckpointStatus,
+      taskCheckpointStatus
+    ]),
+    [HANDOFF_GATES.BUILD_TO_VERIFY]: artifactState.verification ? STATUS.PASS : STATUS.BLOCK,
+    [HANDOFF_GATES.VERIFY_TO_COMPLETE]:
+      completionAudit && completionAudit.status === STATUS.PASS ? STATUS.PASS : STATUS.WARN
+  };
+}
+
+module.exports = {
+  readCheckpointStatuses,
+  normalizeCheckpointStatus,
+  deriveStageFromArtifacts,
+  buildBaseHandoffGates
+};