@xenonbyte/da-vinci-workflow 0.2.5 → 0.2.7

package/lib/task-execution.js

@@ -65,8 +65,37 @@ function normalizeTaskExecutionEnvelope(input = {}) {
   }
   const changedFiles = normalizeList(input.changedFiles);
   const testEvidence = normalizeList(input.testEvidence);
+  const pendingTestEvidence = normalizeList(input.pendingTestEvidence);
+  const confirmTestEvidenceExecuted = input.confirmTestEvidenceExecuted === true;
   const concerns = normalizeList(input.concerns);
   const blockers = normalizeList(input.blockers);
+  const outOfScopeWrites = normalizeList(input.outOfScopeWrites);
+  const partial = input.partial === true;
+
+  const overlap = testEvidence.filter((item) => pendingTestEvidence.includes(item));
+  if (overlap.length > 0) {
+    throw new Error(
+      `task-execution cannot mark the same command as both executed and pending: ${overlap.join(", ")}`
+    );
+  }
+
+  if (testEvidence.length > 0 && !confirmTestEvidenceExecuted) {
+    throw new Error(
+      "`task-execution` requires explicit executed-evidence confirmation when `--test-evidence` is provided. Pass `--confirm-test-evidence-executed`."
+    );
+  }
+
+  if (pendingTestEvidence.length > 0 && status === "DONE") {
+    throw new Error(
+      "`task-execution` cannot use status DONE when pending test evidence exists. Use DONE_WITH_CONCERNS, NEEDS_CONTEXT, or BLOCKED."
+    );
+  }
+
+  if (partial && status === "DONE") {
+    throw new Error(
+      "`task-execution` cannot use status DONE when --partial is set. Use DONE_WITH_CONCERNS, NEEDS_CONTEXT, or BLOCKED."
+    );
+  }
 
   return {
     taskGroupId,
@@ -74,8 +103,12 @@ function normalizeTaskExecutionEnvelope(input = {}) {
     summary,
     changedFiles,
     testEvidence,
+    pendingTestEvidence,
+    confirmTestEvidenceExecuted,
     concerns,
     blockers,
+    outOfScopeWrites,
+    partial,
     recordedAt: new Date().toISOString()
   };
 }
@@ -93,35 +126,65 @@ function writeTaskExecutionEnvelope(projectPathInput, options = {}) {
   }
 
   const envelope = normalizeTaskExecutionEnvelope(options);
+  const envelopeWithIdentity = {
+    ...envelope,
+    changeId: resolved.changeId
+  };
+  const signalStatus = mapImplementerStatusToSignal(envelopeWithIdentity.status);
+  const outOfScopeWriteWarnings = envelopeWithIdentity.outOfScopeWrites.map(
+    (item) => `out-of-scope write: ${item}`
+  );
+  const pendingTestWarnings = envelopeWithIdentity.pendingTestEvidence.map(
+    (item) => `test not executed: ${item}`
+  );
   const signalPath = writeExecutionSignal(projectRoot, {
     changeId: resolved.changeId,
-    surface: buildSurface(envelope.taskGroupId),
-    status: mapImplementerStatusToSignal(envelope.status),
+    surface: buildSurface(envelopeWithIdentity.taskGroupId),
+    status: signalStatus,
     advisory: false,
     strict: true,
-    failures: envelope.status === "BLOCKED" ? envelope.blockers : [],
+    failures: envelopeWithIdentity.status === "BLOCKED" ? envelopeWithIdentity.blockers : [],
     warnings:
-      envelope.status === "DONE_WITH_CONCERNS" || envelope.status === "NEEDS_CONTEXT"
-        ? envelope.concerns
-        : [],
-    notes: [envelope.summary, ...envelope.testEvidence.map((item) => `test: ${item}`)],
+      envelopeWithIdentity.status === "DONE_WITH_CONCERNS" || envelopeWithIdentity.status === "NEEDS_CONTEXT"
+        ? unique([...envelopeWithIdentity.concerns, ...outOfScopeWriteWarnings, ...pendingTestWarnings])
+        : unique([...outOfScopeWriteWarnings, ...pendingTestWarnings]),
+    notes: [
+      envelopeWithIdentity.summary,
+      ...envelopeWithIdentity.testEvidence.map((item) => `test: ${item}`)
+    ],
     details: {
       type: "task_execution",
-      envelope
+      envelope: {
+        taskGroupId: envelopeWithIdentity.taskGroupId,
+        changeId: envelopeWithIdentity.changeId,
+        status: envelopeWithIdentity.status,
+        summary: envelopeWithIdentity.summary,
+        changedFiles: envelopeWithIdentity.changedFiles,
+        testEvidence: envelopeWithIdentity.testEvidence,
+        pendingTestEvidence: envelopeWithIdentity.pendingTestEvidence,
+        concerns: envelopeWithIdentity.concerns,
+        blockers: envelopeWithIdentity.blockers,
+        recordedAt: envelopeWithIdentity.recordedAt
+      },
+      outOfScopeWrites: envelopeWithIdentity.outOfScopeWrites,
+      partial: envelopeWithIdentity.partial
     }
   });
 
   return {
-    status: mapImplementerStatusToSignal(envelope.status),
+    status: signalStatus,
     projectRoot,
     changeId: resolved.changeId,
-    taskGroupId: envelope.taskGroupId,
-    implementerStatus: envelope.status,
-    summary: envelope.summary,
-    changedFiles: envelope.changedFiles,
-    testEvidence: envelope.testEvidence,
-    concerns: envelope.concerns,
-    blockers: envelope.blockers,
+    taskGroupId: envelopeWithIdentity.taskGroupId,
+    implementerStatus: envelopeWithIdentity.status,
+    summary: envelopeWithIdentity.summary,
+    changedFiles: envelopeWithIdentity.changedFiles,
+    testEvidence: envelopeWithIdentity.testEvidence,
+    pendingTestEvidence: envelopeWithIdentity.pendingTestEvidence,
+    concerns: envelopeWithIdentity.concerns,
+    blockers: envelopeWithIdentity.blockers,
+    outOfScopeWrites: envelopeWithIdentity.outOfScopeWrites,
+    partial: envelopeWithIdentity.partial,
     signalPath
   };
 }
@@ -143,12 +206,21 @@ function formatTaskExecutionReport(result) {
   if (result.testEvidence.length > 0) {
     lines.push(`Test evidence: ${result.testEvidence.join(", ")}`);
   }
+  if (result.pendingTestEvidence.length > 0) {
+    lines.push(`Pending test evidence: ${result.pendingTestEvidence.join(", ")}`);
+  }
   if (result.concerns.length > 0) {
     lines.push(`Concerns: ${result.concerns.join(", ")}`);
   }
   if (result.blockers.length > 0) {
     lines.push(`Blockers: ${result.blockers.join(", ")}`);
   }
+  if (result.outOfScopeWrites.length > 0) {
+    lines.push(`Out-of-scope writes: ${result.outOfScopeWrites.join(", ")}`);
+  }
+  if (result.partial) {
+    lines.push("Partial: true");
+  }
   return lines.join("\n");
 }
 

package/lib/task-review.js

@@ -123,25 +123,31 @@ function writeTaskReviewEnvelope(projectPathInput, options = {}) {
 
   if (envelope.stage === "quality") {
     const specSignal = findLatestTaskReviewSignal(existingSignals, envelope.taskGroupId, "spec");
-    if (!specSignal || String(specSignal.status || "").toUpperCase() !== "PASS") {
+    const specStatus = specSignal ? String(specSignal.status || "").toUpperCase() : "";
+    if (!specSignal || specStatus !== "PASS") {
       throw new Error(
         `Quality review for task group ${envelope.taskGroupId} requires a prior spec review PASS.`
       );
     }
   }
 
+  const envelopeWithIdentity = {
+    ...envelope,
+    changeId: resolved.changeId
+  };
+
   const signalPath = writeExecutionSignal(projectRoot, {
     changeId: resolved.changeId,
-    surface: buildTaskReviewSurface(envelope.taskGroupId, envelope.stage),
-    status: mapReviewStatusToSignalStatus(envelope.status),
+    surface: buildTaskReviewSurface(envelopeWithIdentity.taskGroupId, envelopeWithIdentity.stage),
+    status: mapReviewStatusToSignalStatus(envelopeWithIdentity.status),
     advisory: false,
     strict: true,
-    failures: envelope.status === "BLOCK" ? envelope.issues : [],
-    warnings: envelope.status === "WARN" ? envelope.issues : [],
-    notes: [envelope.summary, `reviewer: ${envelope.reviewer}`],
+    failures: envelopeWithIdentity.status === "BLOCK" ? envelopeWithIdentity.issues : [],
+    warnings: envelopeWithIdentity.status === "WARN" ? envelopeWithIdentity.issues : [],
+    notes: [envelopeWithIdentity.summary, `reviewer: ${envelopeWithIdentity.reviewer}`],
     details: {
       type: "task_review",
-      envelope
+      envelope: envelopeWithIdentity
     }
   });
 
@@ -149,7 +155,7 @@ function writeTaskReviewEnvelope(projectPathInput, options = {}) {
   if (options.writeVerification === true) {
     verificationPath = path.join(resolved.changeDir, "verification.md");
     fs.mkdirSync(path.dirname(verificationPath), { recursive: true });
-    const nextVerification = appendTaskReviewEvidence(readTextIfExists(verificationPath), envelope);
+    const nextVerification = appendTaskReviewEvidence(readTextIfExists(verificationPath), envelopeWithIdentity);
     writeFileAtomic(verificationPath, nextVerification);
   }
 

package/lib/utils.js

@@ -49,6 +49,20 @@ function uniqueValues(values) {
   return Array.from(new Set((values || []).filter(Boolean)));
 }
 
+function dedupeMessages(items, options = {}) {
+  const normalize =
+    typeof options.normalize === "function"
+      ? options.normalize
+      : (value) => value;
+  return Array.from(
+    new Set(
+      (Array.isArray(items) ? items : [])
+        .map((item) => normalize(item))
+        .filter(Boolean)
+    )
+  );
+}
+
 function parseJsonText(raw, context = "JSON payload") {
   try {
     return JSON.parse(String(raw));
@@ -140,6 +154,7 @@ module.exports = {
   normalizeRelativePath,
   pathWithinRoot,
   uniqueValues,
+  dedupeMessages,
   parseJsonText,
   readJsonFile,
   sleepSync,

package/lib/workflow-persisted-state.js

@@ -1,8 +1,11 @@
 const fs = require("fs");
 const path = require("path");
+const crypto = require("crypto");
 const { writeFileAtomic, pathExists, readTextIfExists } = require("./utils");
 
-const WORKFLOW_STATE_VERSION = 2;
+// Route snapshot schema version; task-group metadata keeps its own version in workflow-state.js.
+const WORKFLOW_STATE_VERSION = 3;
+const SUPPORTED_WORKFLOW_STATE_VERSIONS = new Set([2, WORKFLOW_STATE_VERSION]);
 const DEFAULT_STALE_WINDOW_MS = 24 * 60 * 60 * 1000;
 const PERSISTED_NOTE_EXCLUDE_PATTERNS = [
   /^No persisted workflow state found for this change; deriving from artifacts\.$/i,
@@ -19,16 +22,29 @@ function resolveTaskGroupMetadataPath(projectRoot, changeId) {
   return path.join(projectRoot, ".da-vinci", "state", "task-groups", `${changeId}.json`);
 }
 
+function hashContent(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function digestForPath(targetPath) {
+  if (!pathExists(targetPath)) {
+    return null;
+  }
+  try {
+    return hashContent(fs.readFileSync(targetPath));
+  } catch (_error) {
+    return null;
+  }
+}
+
 function fingerprintForPath(targetPath) {
   if (!pathExists(targetPath)) {
     return null;
   }
   try {
-    const stat = fs.statSync(targetPath);
     return {
       path: targetPath,
-      mtimeMs: stat.mtimeMs,
-      size: stat.size
+      digest: digestForPath(targetPath)
     };
   } catch (_error) {
     return null;
@@ -46,8 +62,7 @@ function buildWorkflowFingerprint(projectRoot, changeId) {
     path.join(changeRoot, "pencil-design.md"),
     path.join(changeRoot, "pencil-bindings.md"),
     path.join(changeRoot, "tasks.md"),
-    path.join(changeRoot, "verification.md"),
-    path.join(changeRoot, "workflow.json")
+    path.join(changeRoot, "verification.md")
   ];
 
   const specRoot = path.join(changeRoot, "specs");
@@ -96,8 +111,7 @@ function stableFingerprintHash(fingerprint) {
   return JSON.stringify(
     (fingerprint || []).map((entry) => ({
       path: entry.path,
-      mtimeMs: entry.mtimeMs,
-      size: entry.size
+      digest: entry.digest
     }))
   );
 }
@@ -163,7 +177,7 @@ function selectPersistedStateForChange(projectRoot, changeId, options = {}) {
     };
   }
 
-  if (loaded.state.version !== WORKFLOW_STATE_VERSION) {
+  if (!SUPPORTED_WORKFLOW_STATE_VERSIONS.has(Number(loaded.state.version))) {
     return {
       usable: false,
       reason: "version-mismatch",
@@ -183,25 +197,6 @@ function selectPersistedStateForChange(projectRoot, changeId, options = {}) {
     };
   }
 
-  const persistedAt = Date.parse(String(changeRecord.persistedAt || ""));
-  if (!Number.isFinite(persistedAt)) {
-    return {
-      usable: false,
-      reason: "invalid-timestamp",
-      statePath: loaded.statePath,
-      persisted: loaded.state
-    };
-  }
-
-  if (Date.now() - persistedAt > staleWindowMs) {
-    return {
-      usable: false,
-      reason: "time-stale",
-      statePath: loaded.statePath,
-      persisted: loaded.state
-    };
-  }
-
   const currentFingerprint = buildWorkflowFingerprint(projectRoot, changeId);
   const currentHash = stableFingerprintHash(currentFingerprint);
   const persistedHash = String(changeRecord.fingerprintHash || "");
@@ -219,7 +214,20 @@ function selectPersistedStateForChange(projectRoot, changeId, options = {}) {
     reason: null,
     statePath: loaded.statePath,
     persisted: loaded.state,
-    changeRecord
+    changeRecord,
+    advisoryNotes:
+      (() => {
+        const persistedAt = Date.parse(String(changeRecord.persistedAt || ""));
+        if (!Number.isFinite(persistedAt)) {
+          return [];
+        }
+        if (Date.now() - persistedAt > staleWindowMs) {
+          return [
+            "Persisted workflow state is older than the historical stale-time threshold but remains usable because artifact content digests still match."
+          ];
+        }
+        return [];
+      })()
   };
 }
 
@@ -234,6 +242,14 @@ function persistDerivedWorkflowResult(projectRoot, changeId, workflowResult, opt
   }
 
   const fingerprint = buildWorkflowFingerprint(projectRoot, changeId);
+  const metadataRefsNormalized =
+    metadataRefs && typeof metadataRefs === "object"
+      ? {
+          ...metadataRefs,
+          taskGroupsPath: metadataRefs.taskGroupsPath || null,
+          taskGroupsDigest: metadataRefs.taskGroupsDigest || null
+        }
+      : {};
   changes[changeId] = {
     stage: workflowResult.stage,
     checkpointState: workflowResult.checkpointState,
@@ -243,8 +259,7 @@ function persistDerivedWorkflowResult(projectRoot, changeId, workflowResult, opt
     failures: workflowResult.failures,
     warnings: workflowResult.warnings,
     notes: sanitizePersistedNotes(workflowResult.notes),
-    taskGroups: workflowResult.taskGroups || null,
-    metadataRefs,
+    metadataRefs: metadataRefsNormalized,
     fingerprintHash: stableFingerprintHash(fingerprint),
     persistedAt: new Date().toISOString()
   };
@@ -264,7 +279,10 @@ function writeTaskGroupMetadata(projectRoot, changeId, metadataPayload) {
   const targetPath = resolveTaskGroupMetadataPath(projectRoot, changeId);
   fs.mkdirSync(path.dirname(targetPath), { recursive: true });
   writeFileAtomic(targetPath, `${JSON.stringify(metadataPayload, null, 2)}\n`);
-  return targetPath;
+  return {
+    path: targetPath,
+    digest: digestForPath(targetPath)
+  };
 }
 
 function readTaskGroupMetadata(projectRoot, changeId) {
@@ -284,11 +302,13 @@ function readTaskGroupMetadata(projectRoot, changeId) {
 
 module.exports = {
   WORKFLOW_STATE_VERSION,
+  SUPPORTED_WORKFLOW_STATE_VERSIONS,
   DEFAULT_STALE_WINDOW_MS,
   resolveWorkflowStatePath,
   resolveTaskGroupMetadataPath,
   buildWorkflowFingerprint,
   stableFingerprintHash,
+  digestForPath,
   sanitizePersistedNotes,
   readPersistedWorkflowState,
   writePersistedWorkflowState,