@xenonbyte/da-vinci-workflow 0.2.6 → 0.2.8

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

@@ -131,18 +131,23 @@ function writeTaskReviewEnvelope(projectPathInput, options = {}) {
     }
   }
 
+  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
     }
   });
 
@@ -150,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/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
+};