@xenonbyte/da-vinci-workflow 0.2.7 → 0.2.9

package/lib/execution-signals.js

@@ -118,6 +118,38 @@ function readExecutionSignals(projectRoot, options = {}) {
   );
 }
 
+function listExecutionSignalPathsForChange(projectRoot, options = {}) {
+  const changeId = options.changeId ? String(options.changeId).trim() : "";
+  const signalsDir = resolveSignalsDir(projectRoot);
+  if (!changeId || !pathExists(signalsDir)) {
+    return [];
+  }
+
+  const entries = fs
+    .readdirSync(signalsDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"));
+  const paths = [];
+
+  for (const entry of entries) {
+    const absolutePath = path.join(signalsDir, entry.name);
+    const parsedName = parseSignalFileName(entry.name);
+    let include = false;
+
+    try {
+      const payload = JSON.parse(fs.readFileSync(absolutePath, "utf8"));
+      include = String(payload.changeId || "") === changeId;
+    } catch (_error) {
+      include = String(parsedName.changeId || "").trim() === changeId;
+    }
+
+    if (include) {
+      paths.push(absolutePath);
+    }
+  }
+
+  return paths.sort((left, right) => left.localeCompare(right));
+}
+
 function summarizeSignalsBySurface(signals) {
   const summary = {};
   for (const signal of signals || []) {
@@ -148,6 +180,7 @@ function getLatestSignalBySurfacePrefix(signals, prefix) {
 module.exports = {
   writeExecutionSignal,
   readExecutionSignals,
+  listExecutionSignalPathsForChange,
   summarizeSignalsBySurface,
   listSignalsBySurfacePrefix,
   getLatestSignalBySurfacePrefix

package/lib/fs-safety.js

@@ -1,6 +1,7 @@
 const fs = require("fs");
 const path = require("path");
 const { pathExists } = require("./utils");
+const { isPathInside } = require("./path-inside");
 
 const DEFAULT_MAX_DEPTH = 32;
 const DEFAULT_MAX_ENTRIES = 20000;
@@ -19,18 +20,6 @@ function toPositiveInteger(value, fallback) {
   return normalized;
 }
 
-function isPathInside(basePath, targetPath) {
-  const resolvedBase = path.resolve(basePath);
-  const resolvedTarget = path.resolve(targetPath);
-
-  if (resolvedBase === resolvedTarget) {
-    return true;
-  }
-
-  const relative = path.relative(resolvedBase, resolvedTarget);
-  return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
-}
-
 function listFilesRecursiveSafe(rootDir, options = {}) {
   const maxDepth = toPositiveInteger(options.maxDepth, DEFAULT_MAX_DEPTH);
   const maxEntries = toPositiveInteger(options.maxEntries, DEFAULT_MAX_ENTRIES);

package/lib/path-inside.js

@@ -0,0 +1,17 @@
+const path = require("path");
+
+function isPathInside(basePath, targetPath) {
+  const resolvedBase = path.resolve(basePath);
+  const resolvedTarget = path.resolve(targetPath);
+
+  if (resolvedBase === resolvedTarget) {
+    return true;
+  }
+
+  const relative = path.relative(resolvedBase, resolvedTarget);
+  return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+module.exports = {
+  isPathInside
+};

package/lib/utils.js

@@ -1,5 +1,6 @@
 const fs = require("fs");
 const path = require("path");
+const { isPathInside } = require("./path-inside");
 
 const HAS_SYNC_WAIT =
   typeof SharedArrayBuffer === "function" &&
@@ -36,13 +37,7 @@ function normalizeRelativePath(relativePath) {
 }
 
 function pathWithinRoot(projectRoot, candidatePath) {
-  const root = path.resolve(projectRoot);
-  const candidate = path.resolve(candidatePath);
-  if (candidate === root) {
-    return true;
-  }
-  const prefix = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
-  return candidate.startsWith(prefix);
+  return isPathInside(projectRoot, candidatePath);
 }
 
 function uniqueValues(values) {

package/lib/workflow-base-view.js

@@ -0,0 +1,134 @@
+const { getStageById } = require("./workflow-contract");
+const {
+  deriveStageFromArtifacts,
+  buildBaseHandoffGates
+} = require("./workflow-stage");
+
+/**
+ * @typedef {Object} WorkflowFindings
+ * @property {string[]} blockers
+ * @property {string[]} warnings
+ * @property {string[]} notes
+ */
+
+/**
+ * @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 {Object} WorkflowCompletionAudit
+ * @property {string} [status]
+ * @property {string[]} [failures]
+ * @property {string[]} [warnings]
+ * @property {string[]} [notes]
+ */
+
+/**
+ * @typedef {Object} PersistedWorkflowRecord
+ * @property {string} [stage]
+ * @property {Object.<string, string>} [gates]
+ */
+
+/**
+ * @typedef {Object} WorkflowBaseView
+ * @property {"persisted"|"derived"} source
+ * @property {string} stageId
+ * @property {WorkflowFindings} findings
+ * @property {Object.<string, string>} baseGates
+ * @property {WorkflowCompletionAudit | null} completionAudit
+ * @property {Array<object>} taskGroupSeed
+ */
+
+function cloneFindings(findings) {
+  return {
+    blockers: Array.isArray(findings && findings.blockers) ? findings.blockers.slice() : [],
+    warnings: Array.isArray(findings && findings.warnings) ? findings.warnings.slice() : [],
+    notes: Array.isArray(findings && findings.notes) ? findings.notes.slice() : []
+  };
+}
+
+function resolveCompletionAudit(stageId, resolver) {
+  if (typeof resolver !== "function") {
+    return null;
+  }
+  return resolver(stageId);
+}
+
+/**
+ * Normalize a trusted persisted workflow snapshot into the shared base-view shape.
+ *
+ * @param {{
+ *   persistedRecord?: PersistedWorkflowRecord,
+ *   findings?: WorkflowFindings,
+ *   taskGroupSeed?: Array<object>,
+ *   resolveCompletionAudit?: (stageId: string) => (WorkflowCompletionAudit | null)
+ * }} [options]
+ * @returns {WorkflowBaseView}
+ */
+function buildPersistedWorkflowBaseView(options = {}) {
+  const persistedRecord = options.persistedRecord || {};
+  const stage = getStageById(persistedRecord.stage) || getStageById("bootstrap");
+
+  return {
+    source: "persisted",
+    stageId: stage.id,
+    findings: cloneFindings(options.findings),
+    baseGates:
+      persistedRecord && persistedRecord.gates && typeof persistedRecord.gates === "object"
+        ? { ...persistedRecord.gates }
+        : {},
+    completionAudit: resolveCompletionAudit(stage.id, options.resolveCompletionAudit),
+    taskGroupSeed: Array.isArray(options.taskGroupSeed) ? options.taskGroupSeed : []
+  };
+}
+
+/**
+ * Build the artifact/checkpoint-backed base view before runtime overlays apply.
+ *
+ * @param {{
+ *   artifactState?: WorkflowArtifactState,
+ *   checkpointStatuses?: WorkflowCheckpointStatusMap,
+ *   findings?: WorkflowFindings,
+ *   taskGroupSeed?: Array<object>,
+ *   resolveCompletionAudit?: (stageId: string) => (WorkflowCompletionAudit | null)
+ * }} [options]
+ * @returns {WorkflowBaseView}
+ */
+function buildDerivedWorkflowBaseView(options = {}) {
+  const findings = cloneFindings(options.findings);
+  const stageId = deriveStageFromArtifacts(
+    options.artifactState || {},
+    options.checkpointStatuses || {},
+    findings
+  );
+  const completionAudit = resolveCompletionAudit(stageId, options.resolveCompletionAudit);
+
+  return {
+    source: "derived",
+    stageId,
+    findings,
+    baseGates: buildBaseHandoffGates(options.artifactState || {}, options.checkpointStatuses || {}, {
+      completionAudit
+    }),
+    completionAudit,
+    taskGroupSeed: Array.isArray(options.taskGroupSeed) ? options.taskGroupSeed : []
+  };
+}
+
+module.exports = {
+  buildPersistedWorkflowBaseView,
+  buildDerivedWorkflowBaseView
+};

package/lib/workflow-decision-trace.js

@@ -0,0 +1,335 @@
+const fs = require("fs");
+const path = require("path");
+const { normalizeRelativePath } = require("./utils");
+
+const TRACE_ENABLE_ENV = "DA_VINCI_TRACE_WORKFLOW_DECISIONS";
+const ELIGIBLE_SURFACES = new Set(["workflow-status", "next-step"]);
+const DECISION_FAMILIES = new Set([
+  "persisted_state_trust",
+  "task_group_seed_fallback",
+  "task_group_focus_resolution",
+  "planning_signal_freshness",
+  "verification_freshness_downgrade",
+  "worktree_isolation_downgrade"
+]);
+const OUTCOMES = new Set([
+  "accepted",
+  "fallback",
+  "selected_focus",
+  "rerun_required",
+  "downgraded",
+  "suppressed"
+]);
+const DECISION_KEYS_BY_FAMILY = Object.freeze({
+  persisted_state_trust: new Set([
+    "accepted_digest_match",
+    "accepted_age_advisory",
+    "fallback_missing",
+    "fallback_parse_error",
+    "fallback_version_mismatch",
+    "fallback_change_missing",
+    "fallback_fingerprint_mismatch"
+  ]),
+  task_group_seed_fallback: new Set([
+    "seed_missing",
+    "seed_unreadable",
+    "seed_digest_mismatch",
+    "seed_legacy_embedded"
+  ]),
+  task_group_focus_resolution: new Set([
+    "implementer_block",
+    "implementer_warn",
+    "spec_review_missing",
+    "spec_review_block",
+    "spec_review_warn",
+    "quality_review_missing",
+    "quality_review_block",
+    "quality_review_warn"
+  ]),
+  planning_signal_freshness: new Set([
+    "stale_signal_rerun_required",
+    "stale_signal_strict_fallback"
+  ]),
+  verification_freshness_downgrade: new Set(["verification_freshness_stale"]),
+  worktree_isolation_downgrade: new Set(["effective_serial_after_preflight"])
+});
+
+const MAX_CONTEXT_ARRAY_LENGTH = 8;
+const MAX_EVIDENCE_REFS = 8;
+const MAX_TEXT_LENGTH = 240;
+
+function truncateText(value, maxLength = MAX_TEXT_LENGTH) {
+  const text = String(value || "").trim();
+  if (!text) {
+    return "";
+  }
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return `${text.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+
+function formatDateToken(date = new Date()) {
+  const year = date.getFullYear();
+  const month = `${date.getMonth() + 1}`.padStart(2, "0");
+  const day = `${date.getDate()}`.padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+function isWorkflowDecisionTracingEnabled(env = process.env) {
+  return String(env && env[TRACE_ENABLE_ENV] ? env[TRACE_ENABLE_ENV] : "").trim() === "1";
+}
+
+function isEligibleWorkflowTraceSurface(surface) {
+  return ELIGIBLE_SURFACES.has(String(surface || "").trim());
+}
+
+function shouldTraceWorkflowDecisions(options = {}) {
+  return (
+    isWorkflowDecisionTracingEnabled(options.env) &&
+    isEligibleWorkflowTraceSurface(options.surface)
+  );
+}
+
+function resolveWorkflowDecisionTracePath(projectRoot, date = new Date()) {
+  return path.join(
+    path.resolve(projectRoot || process.cwd()),
+    ".da-vinci",
+    "logs",
+    "workflow-decisions",
+    `${formatDateToken(date)}.ndjson`
+  );
+}
+
+function formatPathRef(projectRoot, candidatePath) {
+  const resolved = path.resolve(String(candidatePath || ""));
+  const root = path.resolve(projectRoot || process.cwd());
+  const relative = path.relative(root, resolved);
+  if (!relative || (!relative.startsWith("..") && !path.isAbsolute(relative))) {
+    return normalizeRelativePath(relative || ".");
+  }
+  return resolved.split(path.sep).join("/");
+}
+
+function normalizeContextValue(value) {
+  if (value === null) {
+    return null;
+  }
+  if (typeof value === "string") {
+    const text = truncateText(value);
+    return text || undefined;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : undefined;
+  }
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    const items = value
+      .map((item) => truncateText(item))
+      .filter(Boolean)
+      .slice(0, MAX_CONTEXT_ARRAY_LENGTH);
+    return items.length > 0 ? items : undefined;
+  }
+  return undefined;
+}
+
+function normalizeContext(context) {
+  const normalized = {};
+  if (!context || typeof context !== "object" || Array.isArray(context)) {
+    return normalized;
+  }
+
+  for (const [key, value] of Object.entries(context)) {
+    const normalizedValue = normalizeContextValue(value);
+    if (normalizedValue !== undefined) {
+      normalized[key] = normalizedValue;
+    }
+  }
+
+  return normalized;
+}
+
+function normalizeEvidenceRefs(evidenceRefs) {
+  return Array.from(
+    new Set(
+      (Array.isArray(evidenceRefs) ? evidenceRefs : [])
+        .map((item) => truncateText(item))
+        .filter(Boolean)
+    )
+  ).slice(0, MAX_EVIDENCE_REFS);
+}
+
+function inspectWorkflowDecisionRecord(record) {
+  if (!record || typeof record !== "object") {
+    return {
+      normalized: null,
+      rejection: "record must be an object"
+    };
+  }
+
+  const decisionFamily = String(record.decisionFamily || "").trim();
+  const decisionKey = String(record.decisionKey || "").trim();
+  const outcome = String(record.outcome || "").trim();
+  const reasonSummary = truncateText(record.reasonSummary);
+
+  if (!DECISION_FAMILIES.has(decisionFamily)) {
+    return {
+      normalized: null,
+      rejection: `unsupported decisionFamily: ${decisionFamily || "(empty)"}`
+    };
+  }
+  if (!OUTCOMES.has(outcome)) {
+    return {
+      normalized: null,
+      rejection: `unsupported outcome for ${decisionFamily}: ${outcome || "(empty)"}`
+    };
+  }
+  const allowedKeys = DECISION_KEYS_BY_FAMILY[decisionFamily];
+  if (!allowedKeys || !allowedKeys.has(decisionKey)) {
+    return {
+      normalized: null,
+      rejection: `unsupported decisionKey for ${decisionFamily}: ${decisionKey || "(empty)"}`
+    };
+  }
+  if (!reasonSummary) {
+    return {
+      normalized: null,
+      rejection: `reasonSummary is required for ${decisionFamily}/${decisionKey}`
+    };
+  }
+
+  return {
+    normalized: {
+      decisionFamily,
+      decisionKey,
+      outcome,
+      reasonSummary,
+      context: normalizeContext(record.context),
+      evidenceRefs: normalizeEvidenceRefs(record.evidenceRefs)
+    },
+    rejection: null
+  };
+}
+
+function emitWorkflowDecisionTraces(options = {}) {
+  if (!shouldTraceWorkflowDecisions(options)) {
+    return {
+      enabled: false,
+      written: 0,
+      tracePath: null,
+      error: null,
+      rejectedCount: 0,
+      rejections: []
+    };
+  }
+
+  const changeId = String(options.changeId || "").trim();
+  const stage = String(options.stage || "").trim();
+  if (!changeId || !stage) {
+    return {
+      enabled: true,
+      written: 0,
+      tracePath: null,
+      error: null,
+      rejectedCount: 0,
+      rejections: []
+    };
+  }
+
+  const rejections = [];
+  const normalizedRecords = [];
+  for (const record of Array.isArray(options.records) ? options.records : []) {
+    const inspected = inspectWorkflowDecisionRecord(record);
+    if (inspected.normalized) {
+      normalizedRecords.push(inspected.normalized);
+      continue;
+    }
+    if (inspected.rejection) {
+      rejections.push(inspected.rejection);
+    }
+  }
+  if (normalizedRecords.length === 0) {
+    return {
+      enabled: true,
+      written: 0,
+      tracePath: null,
+      error: null,
+      rejectedCount: rejections.length,
+      rejections: rejections.slice(0, 3)
+    };
+  }
+
+  const now = options.now instanceof Date ? options.now : new Date();
+  const timestamp = now.toISOString();
+  const surface = String(options.surface || "").trim();
+  const tracePath = resolveWorkflowDecisionTracePath(options.projectRoot, now);
+  const lines = [];
+  const seen = new Set();
+
+  for (const record of normalizedRecords) {
+    const payload = {
+      timestamp,
+      surface,
+      changeId,
+      stage,
+      decisionFamily: record.decisionFamily,
+      decisionKey: record.decisionKey,
+      outcome: record.outcome,
+      reasonSummary: record.reasonSummary,
+      context: record.context,
+      evidenceRefs: record.evidenceRefs
+    };
+    const serialized = JSON.stringify(payload);
+    if (seen.has(serialized)) {
+      continue;
+    }
+    seen.add(serialized);
+    lines.push(serialized);
+  }
+
+  if (lines.length === 0) {
+    return {
+      enabled: true,
+      written: 0,
+      tracePath: null,
+      error: null
+    };
+  }
+
+  try {
+    fs.mkdirSync(path.dirname(tracePath), { recursive: true });
+    fs.appendFileSync(tracePath, `${lines.join("\n")}\n`, "utf8");
+    return {
+      enabled: true,
+      written: lines.length,
+      tracePath,
+      error: null,
+      rejectedCount: rejections.length,
+      rejections: rejections.slice(0, 3)
+    };
+  } catch (error) {
+    return {
+      enabled: true,
+      written: 0,
+      tracePath,
+      error,
+      rejectedCount: rejections.length,
+      rejections: rejections.slice(0, 3)
+    };
+  }
+}
+
+module.exports = {
+  TRACE_ENABLE_ENV,
+  DECISION_FAMILIES,
+  DECISION_KEYS_BY_FAMILY,
+  OUTCOMES,
+  formatPathRef,
+  isWorkflowDecisionTracingEnabled,
+  isEligibleWorkflowTraceSurface,
+  shouldTraceWorkflowDecisions,
+  resolveWorkflowDecisionTracePath,
+  emitWorkflowDecisionTraces
+};