@xenonbyte/da-vinci-workflow 0.2.5 → 0.2.6

package/lib/sidecars.js

@@ -17,6 +17,87 @@ const {
 
 const SCHEMA_VERSION = "1.0.0";
 
+function readJsonIfExists(targetPath) {
+  if (!targetPath || !pathExists(targetPath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(targetPath, "utf8"));
+  } catch (_error) {
+    return null;
+  }
+}
+
+function normalizeEvidenceText(value) {
+  return String(value || "")
+    .toLowerCase()
+    .replace(/[`*_~]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function resolveProjectRootFromChangeDir(changeDir) {
+  return path.resolve(changeDir || process.cwd(), "..", "..", "..");
+}
+
+function resolveSourceRefAbsolutePath(projectRoot, sourceRefPath) {
+  const sourcePath = String(sourceRefPath || "").trim();
+  if (!sourcePath) {
+    return null;
+  }
+  if (path.isAbsolute(sourcePath)) {
+    return sourcePath;
+  }
+  return path.join(projectRoot, sourcePath);
+}
+
+function evaluateSourceRefsFreshness(changeDir, payload) {
+  const sourceRefs = Array.isArray(payload && payload.sourceRefs) ? payload.sourceRefs : [];
+  if (sourceRefs.length === 0) {
+    return {
+      fresh: false,
+      checked: 0,
+      stale: ["missing_source_refs"]
+    };
+  }
+  const projectRoot = resolveProjectRootFromChangeDir(changeDir);
+  const stale = [];
+  for (const ref of sourceRefs) {
+    const absolutePath = resolveSourceRefAbsolutePath(projectRoot, ref && ref.path);
+    if (!absolutePath || !pathExists(absolutePath)) {
+      stale.push(`missing:${String((ref && ref.path) || "").trim() || "(unknown)"}`);
+      continue;
+    }
+    const expected = String((ref && ref.digest) || "").trim();
+    const actual = digestFile(absolutePath);
+    if (expected && actual && expected !== actual) {
+      stale.push(`digest_mismatch:${String(ref.path || absolutePath)}`);
+    }
+  }
+
+  return {
+    fresh: stale.length === 0,
+    checked: sourceRefs.length,
+    stale
+  };
+}
+
+function buildCollectionTextIdMap(items, idField = "id", textField = "text") {
+  const map = new Map();
+  for (const item of Array.isArray(items) ? items : []) {
+    const id = String(item && item[idField] ? item[idField] : "").trim();
+    const text = normalizeEvidenceText(item && item[textField]);
+    if (!id || !text) {
+      continue;
+    }
+    if (!map.has(text)) {
+      map.set(text, []);
+    }
+    map.get(text).push(id);
+  }
+  return map;
+}
+
 function buildEnvelope(projectRoot) {
   return {
     status: STATUS.PASS,
@@ -241,6 +322,316 @@ function writeSidecarFile(sidecarsDir, fileName, payload) {
   return absolutePath;
 }
 
+function loadPlanningAnchorIndex(changeDir) {
+  const sidecarsDir = path.join(changeDir, "sidecars");
+  const spec = readJsonIfExists(path.join(sidecarsDir, "spec.index.json"));
+  const bindings = readJsonIfExists(path.join(sidecarsDir, "bindings.index.json"));
+  const notes = [];
+  const warnings = [];
+
+  if (!pathExists(sidecarsDir)) {
+    notes.push("Planning sidecars are missing; anchor resolution will use artifact fallback.");
+    return {
+      sidecarsDir,
+      available: false,
+      index: {
+        behavior: new Set(),
+        acceptance: new Set(),
+        state: new Set(),
+        mapping: new Set()
+      },
+      notes,
+      warnings
+    };
+  }
+
+  if (!spec) {
+    warnings.push("Missing or unreadable `spec.index.json` in sidecars.");
+  }
+  if (!bindings) {
+    warnings.push("Missing or unreadable `bindings.index.json` in sidecars.");
+  }
+
+  const specFreshness = spec ? evaluateSourceRefsFreshness(changeDir, spec) : null;
+  const bindingsFreshness = bindings ? evaluateSourceRefsFreshness(changeDir, bindings) : null;
+  if (specFreshness && !specFreshness.fresh) {
+    warnings.push(
+      `spec.index.json appears stale (${specFreshness.stale.join(", ")}); anchor resolution will degrade.`
+    );
+  }
+  if (bindingsFreshness && !bindingsFreshness.fresh) {
+    warnings.push(
+      `bindings.index.json appears stale (${bindingsFreshness.stale.join(", ")}); anchor resolution will degrade.`
+    );
+  }
+
+  const behavior = new Set(
+    ((spec && spec.collections && spec.collections.behavior) || []).map((item) => item.id)
+  );
+  const acceptance = new Set(
+    ((spec && spec.collections && spec.collections.acceptance) || []).map((item) => item.id)
+  );
+  const state = new Set(
+    ((spec && spec.collections && spec.collections.states) || []).map((item) => item.id)
+  );
+  const mapping = new Set(((bindings && bindings.mappings) || []).map((item) => item.id));
+
+  const sourceFresh =
+    (!specFreshness || specFreshness.fresh) && (!bindingsFreshness || bindingsFreshness.fresh);
+  const available =
+    sourceFresh && (behavior.size > 0 || acceptance.size > 0 || state.size > 0 || mapping.size > 0);
+  if (!available) {
+    if (!sourceFresh) {
+      notes.push("Planning sidecars exist but are stale; anchor resolution falls back to artifact evidence.");
+    } else {
+      notes.push("Planning sidecars are present but empty for anchor id resolution.");
+    }
+  }
+
+  return {
+    sidecarsDir,
+    available,
+    fresh: sourceFresh,
+    freshness: {
+      spec: specFreshness,
+      bindings: bindingsFreshness
+    },
+    index: {
+      behavior,
+      acceptance,
+      state,
+      mapping
+    },
+    raw: {
+      spec,
+      bindings
+    },
+    notes,
+    warnings
+  };
+}
+
+function resolvePlanningAnchorRefs(anchorRefs, options = {}) {
+  const refs = Array.isArray(anchorRefs) ? anchorRefs : [];
+  const sidecarIndex = options.sidecarIndex || {
+    available: false,
+    index: {
+      behavior: new Set(),
+      acceptance: new Set(),
+      state: new Set(),
+      mapping: new Set()
+    }
+  };
+  const artifactResolver = typeof options.resolveArtifactRef === "function" ? options.resolveArtifactRef : null;
+  const anchorIdResolver = typeof options.resolveAnchorIdRef === "function" ? options.resolveAnchorIdRef : null;
+
+  const resolved = [];
+  const unresolved = [];
+  const notes = [];
+
+  for (const ref of refs) {
+    const normalized = String(ref || "").trim();
+    if (!normalized) {
+      continue;
+    }
+
+    const familyMatch = normalized.match(/^(behavior|acceptance|state|mapping)-/i);
+    if (familyMatch) {
+      const family = String(familyMatch[1] || "").toLowerCase();
+      if (sidecarIndex.available && sidecarIndex.index[family] && sidecarIndex.index[family].has(normalized)) {
+        resolved.push({
+          ref: normalized,
+          source: "sidecar",
+          family
+        });
+      } else {
+        let fallback = null;
+        if (anchorIdResolver) {
+          fallback = anchorIdResolver({
+            ref: normalized,
+            family,
+            sidecarAvailable: sidecarIndex.available,
+            sidecarFresh: sidecarIndex.fresh !== false
+          });
+          if (fallback && fallback.ok) {
+            resolved.push({
+              ref: normalized,
+              source: fallback.source || "artifact-parse",
+              family
+            });
+            if (fallback.note) {
+              notes.push(String(fallback.note));
+            }
+            continue;
+          }
+        }
+        const fallbackReason =
+          fallback && fallback.reason ? String(fallback.reason).trim() : "";
+        const fallbackClassification =
+          fallback && fallback.classification ? String(fallback.classification).trim() : "";
+        unresolved.push({
+          ref: normalized,
+          reason:
+            fallbackReason ||
+            (sidecarIndex.available ? "unknown_sidecar_id" : "sidecar_unavailable"),
+          family,
+          classification: fallbackClassification ||
+            (sidecarIndex.available || sidecarIndex.fresh === false || fallbackReason
+              ? "invalid_or_stale_sidecar_anchor"
+              : "sidecar_not_available")
+        });
+      }
+      continue;
+    }
+
+    const artifactMatch = normalized.match(/^artifact:([^#\s]+)(?:#(.+))?$/i);
+    if (artifactMatch && artifactResolver) {
+      const artifactPath = String(artifactMatch[1] || "").trim();
+      const artifactToken = String(artifactMatch[2] || "").trim();
+      const artifactResult = artifactResolver({
+        artifactPath,
+        artifactToken
+      });
+      if (artifactResult && artifactResult.ok) {
+        resolved.push({
+          ref: normalized,
+          source: "artifact",
+          artifactPath,
+          artifactToken
+        });
+      } else {
+        unresolved.push({
+          ref: normalized,
+          reason:
+            artifactResult && artifactResult.reason ? artifactResult.reason : "artifact_ref_unresolved"
+        });
+      }
+      continue;
+    }
+
+    unresolved.push({
+      ref: normalized,
+      reason: "unsupported_anchor_format",
+      classification: "malformed_anchor"
+    });
+  }
+
+  if (!sidecarIndex.available) {
+    notes.push("Anchor id resolution degraded: sidecars unavailable; artifact refs are preferred.");
+  }
+
+  return {
+    resolved,
+    unresolved,
+    notes
+  };
+}
+
+function loadAnalyzeEvidenceIndex(changeDir) {
+  const sidecarIndex = loadPlanningAnchorIndex(changeDir);
+  const sidecarsDir = sidecarIndex.sidecarsDir;
+  const spec = sidecarIndex.raw && sidecarIndex.raw.spec ? sidecarIndex.raw.spec : null;
+  const bindings = sidecarIndex.raw && sidecarIndex.raw.bindings ? sidecarIndex.raw.bindings : null;
+
+  const behaviorMap = buildCollectionTextIdMap(spec && spec.collections && spec.collections.behavior);
+  const acceptanceMap = buildCollectionTextIdMap(spec && spec.collections && spec.collections.acceptance);
+  const stateMap = buildCollectionTextIdMap(spec && spec.collections && spec.collections.states);
+  const mappingByImplementation = new Map();
+  for (const mapping of (bindings && bindings.mappings) || []) {
+    const implementation = String(mapping && mapping.implementation ? mapping.implementation : "").trim();
+    if (!implementation) {
+      continue;
+    }
+    const normalized = implementation.replace(/\\/g, "/");
+    if (!mappingByImplementation.has(normalized)) {
+      mappingByImplementation.set(normalized, []);
+    }
+    mappingByImplementation.get(normalized).push(String(mapping.id || "").trim());
+  }
+
+  return {
+    sidecarsDir,
+    available: sidecarIndex.available,
+    fresh: sidecarIndex.fresh === true,
+    notes: sidecarIndex.notes.slice(),
+    warnings: sidecarIndex.warnings.slice(),
+    maps: {
+      behavior: behaviorMap,
+      acceptance: acceptanceMap,
+      state: stateMap,
+      mappingByImplementation
+    }
+  };
+}
+
+function resolveAnalyzeEvidenceRefs(evidenceItems, options = {}) {
+  const items = Array.isArray(evidenceItems) ? evidenceItems : [];
+  const index = options.index || {
+    available: false,
+    maps: {
+      behavior: new Map(),
+      acceptance: new Map(),
+      state: new Map(),
+      mappingByImplementation: new Map()
+    }
+  };
+  const refs = [];
+  const notes = [];
+
+  for (const item of items) {
+    const artifactPath = String(item && item.artifactPath ? item.artifactPath : "").trim();
+    const itemText = String(item && item.itemText ? item.itemText : "").trim();
+    const kind = String(item && item.kind ? item.kind : "").trim().toLowerCase();
+    const implementationPath = String(item && item.implementationPath ? item.implementationPath : "").trim();
+    const normalizedText = normalizeEvidenceText(itemText);
+
+    if (index.available && normalizedText) {
+      const candidateIds = [];
+      if (kind === "behavior" && index.maps.behavior.has(normalizedText)) {
+        candidateIds.push(...index.maps.behavior.get(normalizedText));
+      }
+      if (kind === "acceptance" && index.maps.acceptance.has(normalizedText)) {
+        candidateIds.push(...index.maps.acceptance.get(normalizedText));
+      }
+      if (kind === "state" && index.maps.state.has(normalizedText)) {
+        candidateIds.push(...index.maps.state.get(normalizedText));
+      }
+      for (const id of candidateIds) {
+        refs.push(`sidecar:${id}`);
+      }
+    }
+
+    if (index.available && implementationPath) {
+      const normalizedImplementation = implementationPath.replace(/\\/g, "/");
+      const mappingIds = index.maps.mappingByImplementation.get(normalizedImplementation) || [];
+      for (const id of mappingIds) {
+        refs.push(`sidecar:${id}`);
+      }
+    }
+
+    if (artifactPath) {
+      const fallbackToken = itemText
+        ? itemText
+            .split(/\s+/)
+            .slice(0, 8)
+            .join(" ")
+        : "";
+      refs.push(
+        fallbackToken ? `artifact:${artifactPath}#${fallbackToken}` : `artifact:${artifactPath}`
+      );
+    }
+  }
+
+  if (!index.available) {
+    notes.push("Analyze evidence mapping degraded to artifact refs because sidecars are unavailable or stale.");
+  }
+
+  return {
+    refs: unique(refs),
+    notes
+  };
+}
+
 function generatePlanningSidecars(projectPathInput, options = {}) {
   const projectRoot = path.resolve(projectPathInput || process.cwd());
   const write = options.write !== false;
@@ -365,5 +756,9 @@ function formatGenerateSidecarsReport(result) {
 module.exports = {
   SCHEMA_VERSION,
   generatePlanningSidecars,
-  formatGenerateSidecarsReport
+  formatGenerateSidecarsReport,
+  loadPlanningAnchorIndex,
+  resolvePlanningAnchorRefs,
+  loadAnalyzeEvidenceIndex,
+  resolveAnalyzeEvidenceRefs
 };

package/lib/task-review.js

@@ -123,7 +123,8 @@ 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.`
       );

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,