@xenonbyte/da-vinci-workflow 0.2.2 → 0.2.4

package/lib/supervisor-review.js

@@ -67,7 +67,8 @@ function resolveCodexBinaryPath(explicitPath) {
 }
 
 function normalizePositiveInt(value, fallback, minimum = 1, maximum = Number.POSITIVE_INFINITY) {
-  const parsed = Number.parseInt(String(value || ""), 10);
+  const raw = value === undefined || value === null ? "" : String(value).trim();
+  const parsed = Number.parseInt(raw, 10);
   if (!Number.isFinite(parsed)) {
     return fallback;
   }
@@ -416,7 +417,7 @@ function extractMcpRuntimeGateStatus(markdownText) {
   }
 
   const statusMatch = String(section).match(
-    /(?:^|\n)\s*-\s*(?:Status|状态)\s*:\s*`?(PASS|WARN|BLOCK)`?\b/i
+    /(?:^|\n)\s*-\s*(?:Final runtime gate status|Status|状态)\s*:\s*`?(PASS|WARN|BLOCK)`?\b/i
   );
   return statusMatch ? String(statusMatch[1]).toUpperCase() : "";
 }

package/lib/task-execution.js

@@ -0,0 +1,160 @@
+const path = require("path");
+const { resolveChangeDir, unique } = require("./planning-parsers");
+const { writeExecutionSignal } = require("./execution-signals");
+
+const VALID_IMPLEMENTER_STATUSES = new Set([
+  "DONE",
+  "DONE_WITH_CONCERNS",
+  "NEEDS_CONTEXT",
+  "BLOCKED"
+]);
+
+function normalizeStatus(value) {
+  const normalized = String(value || "").trim().toUpperCase();
+  if (!VALID_IMPLEMENTER_STATUSES.has(normalized)) {
+    throw new Error(
+      "`task-execution --status` must be one of DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED."
+    );
+  }
+  return normalized;
+}
+
+function normalizeList(value) {
+  if (Array.isArray(value)) {
+    return unique(value.map((item) => String(item || "").trim()).filter(Boolean));
+  }
+  return unique(
+    String(value || "")
+      .split(/[,\n;]/)
+      .map((item) => item.trim())
+      .filter(Boolean)
+  );
+}
+
+function normalizeTaskGroupId(value) {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    throw new Error("`task-execution` requires `--task-group <id>`.");
+  }
+  return normalized;
+}
+
+function mapImplementerStatusToSignal(status) {
+  if (status === "DONE") {
+    return "PASS";
+  }
+  if (status === "DONE_WITH_CONCERNS" || status === "NEEDS_CONTEXT") {
+    return "WARN";
+  }
+  return "BLOCK";
+}
+
+function buildSurface(taskGroupId) {
+  const safeId = String(taskGroupId || "")
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, "_");
+  return `task-execution.${safeId}`;
+}
+
+function normalizeTaskExecutionEnvelope(input = {}) {
+  const taskGroupId = normalizeTaskGroupId(input.taskGroupId);
+  const status = normalizeStatus(input.status);
+  const summary = String(input.summary || "").trim();
+  if (!summary) {
+    throw new Error("`task-execution` requires `--summary <text>`.");
+  }
+  const changedFiles = normalizeList(input.changedFiles);
+  const testEvidence = normalizeList(input.testEvidence);
+  const concerns = normalizeList(input.concerns);
+  const blockers = normalizeList(input.blockers);
+
+  return {
+    taskGroupId,
+    status,
+    summary,
+    changedFiles,
+    testEvidence,
+    concerns,
+    blockers,
+    recordedAt: new Date().toISOString()
+  };
+}
+
+function writeTaskExecutionEnvelope(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
+  const resolved = resolveChangeDir(projectRoot, requestedChangeId);
+  if (!resolved.changeDir || !resolved.changeId) {
+    const resolveError =
+      Array.isArray(resolved.failures) && resolved.failures.length > 0
+        ? String(resolved.failures[0] || "").trim()
+        : "";
+    throw new Error(resolveError || "Unable to resolve active change for task-execution.");
+  }
+
+  const envelope = normalizeTaskExecutionEnvelope(options);
+  const signalPath = writeExecutionSignal(projectRoot, {
+    changeId: resolved.changeId,
+    surface: buildSurface(envelope.taskGroupId),
+    status: mapImplementerStatusToSignal(envelope.status),
+    advisory: false,
+    strict: true,
+    failures: envelope.status === "BLOCKED" ? envelope.blockers : [],
+    warnings:
+      envelope.status === "DONE_WITH_CONCERNS" || envelope.status === "NEEDS_CONTEXT"
+        ? envelope.concerns
+        : [],
+    notes: [envelope.summary, ...envelope.testEvidence.map((item) => `test: ${item}`)],
+    details: {
+      type: "task_execution",
+      envelope
+    }
+  });
+
+  return {
+    status: mapImplementerStatusToSignal(envelope.status),
+    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,
+    signalPath
+  };
+}
+
+function formatTaskExecutionReport(result) {
+  const lines = [
+    "Task execution envelope",
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId}`,
+    `Task group: ${result.taskGroupId}`,
+    `Implementer status: ${result.implementerStatus}`,
+    `Signal status: ${result.status}`,
+    `Summary: ${result.summary}`,
+    `Signal path: ${result.signalPath}`
+  ];
+  if (result.changedFiles.length > 0) {
+    lines.push(`Changed files: ${result.changedFiles.join(", ")}`);
+  }
+  if (result.testEvidence.length > 0) {
+    lines.push(`Test evidence: ${result.testEvidence.join(", ")}`);
+  }
+  if (result.concerns.length > 0) {
+    lines.push(`Concerns: ${result.concerns.join(", ")}`);
+  }
+  if (result.blockers.length > 0) {
+    lines.push(`Blockers: ${result.blockers.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  VALID_IMPLEMENTER_STATUSES,
+  normalizeTaskExecutionEnvelope,
+  writeTaskExecutionEnvelope,
+  formatTaskExecutionReport
+};

package/lib/task-review.js

@@ -0,0 +1,197 @@
+const fs = require("fs");
+const path = require("path");
+const { resolveChangeDir, unique } = require("./planning-parsers");
+const { readExecutionSignals, writeExecutionSignal } = require("./execution-signals");
+const { writeFileAtomic, readTextIfExists } = require("./utils");
+
+const VALID_REVIEW_STAGES = new Set(["spec", "quality"]);
+const VALID_REVIEW_STATUSES = new Set(["PASS", "WARN", "BLOCK"]);
+
+function normalizeReviewStage(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!VALID_REVIEW_STAGES.has(normalized)) {
+    throw new Error("`task-review --stage` must be `spec` or `quality`.");
+  }
+  return normalized;
+}
+
+function normalizeReviewStatus(value) {
+  const normalized = String(value || "").trim().toUpperCase();
+  if (!VALID_REVIEW_STATUSES.has(normalized)) {
+    throw new Error("`task-review --status` must be PASS, WARN, or BLOCK.");
+  }
+  return normalized;
+}
+
+function normalizeTaskGroupId(value) {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    throw new Error("`task-review` requires `--task-group <id>`.");
+  }
+  return normalized;
+}
+
+function normalizeList(value) {
+  if (Array.isArray(value)) {
+    return unique(value.map((item) => String(item || "").trim()).filter(Boolean));
+  }
+  return unique(
+    String(value || "")
+      .split(/[,\n;]/)
+      .map((item) => item.trim())
+      .filter(Boolean)
+  );
+}
+
+function buildSafeTaskGroupId(taskGroupId) {
+  return String(taskGroupId || "")
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, "_");
+}
+
+function buildTaskReviewSurface(taskGroupId, stage) {
+  return `task-review.${buildSafeTaskGroupId(taskGroupId)}.${stage}`;
+}
+
+function mapReviewStatusToSignalStatus(status) {
+  return status;
+}
+
+function normalizeTaskReviewEnvelope(input = {}) {
+  const taskGroupId = normalizeTaskGroupId(input.taskGroupId);
+  const stage = normalizeReviewStage(input.stage);
+  const status = normalizeReviewStatus(input.status);
+  const summary = String(input.summary || "").trim();
+  if (!summary) {
+    throw new Error("`task-review` requires `--summary <text>`.");
+  }
+  const issues = normalizeList(input.issues);
+  const reviewer = String(input.reviewer || "").trim() || "unspecified";
+
+  return {
+    taskGroupId,
+    stage,
+    status,
+    summary,
+    issues,
+    reviewer,
+    recordedAt: new Date().toISOString()
+  };
+}
+
+function findLatestTaskReviewSignal(signals, taskGroupId, stage) {
+  const surface = buildTaskReviewSurface(taskGroupId, stage);
+  return (signals || [])
+    .filter((signal) => String(signal.surface || "") === surface)
+    .sort((left, right) => String(right.timestamp || "").localeCompare(String(left.timestamp || "")))[0] || null;
+}
+
+function appendTaskReviewEvidence(verificationText, envelope) {
+  const existing = String(verificationText || "").trim();
+  const section = [
+    `### Task Review ${envelope.taskGroupId} (${envelope.stage})`,
+    `- Status: ${envelope.status}`,
+    `- Reviewer: ${envelope.reviewer}`,
+    `- Summary: ${envelope.summary}`,
+    `- Issues: ${envelope.issues.length > 0 ? envelope.issues.join("; ") : "none"}`,
+    `- Recorded at: ${envelope.recordedAt}`
+  ].join("\n");
+
+  if (!existing) {
+    return `# Verification\n\n## Task Review Evidence\n\n${section}\n`;
+  }
+  if (!/^\s*##\s+Task Review Evidence\s*$/im.test(existing)) {
+    return `${existing}\n\n## Task Review Evidence\n\n${section}\n`;
+  }
+  return `${existing}\n\n${section}\n`;
+}
+
+function writeTaskReviewEnvelope(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
+  const resolved = resolveChangeDir(projectRoot, requestedChangeId);
+  if (!resolved.changeDir || !resolved.changeId) {
+    const resolveError =
+      Array.isArray(resolved.failures) && resolved.failures.length > 0
+        ? String(resolved.failures[0] || "").trim()
+        : "";
+    throw new Error(resolveError || "Unable to resolve active change for task-review.");
+  }
+
+  const envelope = normalizeTaskReviewEnvelope(options);
+  const existingSignals = readExecutionSignals(projectRoot, { changeId: resolved.changeId });
+
+  if (envelope.stage === "quality") {
+    const specSignal = findLatestTaskReviewSignal(existingSignals, envelope.taskGroupId, "spec");
+    if (!specSignal || String(specSignal.status || "").toUpperCase() !== "PASS") {
+      throw new Error(
+        `Quality review for task group ${envelope.taskGroupId} requires a prior spec review PASS.`
+      );
+    }
+  }
+
+  const signalPath = writeExecutionSignal(projectRoot, {
+    changeId: resolved.changeId,
+    surface: buildTaskReviewSurface(envelope.taskGroupId, envelope.stage),
+    status: mapReviewStatusToSignalStatus(envelope.status),
+    advisory: false,
+    strict: true,
+    failures: envelope.status === "BLOCK" ? envelope.issues : [],
+    warnings: envelope.status === "WARN" ? envelope.issues : [],
+    notes: [envelope.summary, `reviewer: ${envelope.reviewer}`],
+    details: {
+      type: "task_review",
+      envelope
+    }
+  });
+
+  let verificationPath = null;
+  if (options.writeVerification === true) {
+    verificationPath = path.join(resolved.changeDir, "verification.md");
+    fs.mkdirSync(path.dirname(verificationPath), { recursive: true });
+    const nextVerification = appendTaskReviewEvidence(readTextIfExists(verificationPath), envelope);
+    writeFileAtomic(verificationPath, nextVerification);
+  }
+
+  return {
+    status: envelope.status,
+    projectRoot,
+    changeId: resolved.changeId,
+    taskGroupId: envelope.taskGroupId,
+    stage: envelope.stage,
+    summary: envelope.summary,
+    issues: envelope.issues,
+    reviewer: envelope.reviewer,
+    signalPath,
+    verificationPath
+  };
+}
+
+function formatTaskReviewReport(result) {
+  const lines = [
+    "Task review envelope",
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId}`,
+    `Task group: ${result.taskGroupId}`,
+    `Stage: ${result.stage}`,
+    `Status: ${result.status}`,
+    `Reviewer: ${result.reviewer}`,
+    `Summary: ${result.summary}`,
+    `Signal path: ${result.signalPath}`
+  ];
+  if (result.issues.length > 0) {
+    lines.push(`Issues: ${result.issues.join("; ")}`);
+  }
+  if (result.verificationPath) {
+    lines.push(`Verification write-back: ${result.verificationPath}`);
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  VALID_REVIEW_STAGES,
+  VALID_REVIEW_STATUSES,
+  normalizeTaskReviewEnvelope,
+  writeTaskReviewEnvelope,
+  formatTaskReviewReport
+};

package/lib/verify.js

@@ -13,6 +13,7 @@ const {
   readChangeArtifacts,
   readArtifactTexts
 } = require("./planning-parsers");
+const { readExecutionSignals, summarizeSignalsBySurface } = require("./execution-signals");
 
 const CODE_FILE_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".html", ".css", ".scss"]);
 const NON_IMPLEMENTATION_DIR_NAMES = new Set([
@@ -47,6 +48,7 @@ const MAX_SCANNED_FILES = 2000;
 const MAX_SCANNED_BYTES_PER_FILE = 512 * 1024;
 const MAX_SCANNED_DIRECTORIES = 10000;
 const MAX_SCAN_DEPTH = 32;
+const DEFAULT_EVIDENCE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 
 function buildEnvelope(name, projectRoot, strict) {
   return {
@@ -226,6 +228,138 @@ function allCovered(checks) {
   return true;
 }
 
+function safeMtimeMs(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    return Number(stat.mtimeMs) || 0;
+  } catch (_error) {
+    return 0;
+  }
+}
+
+function collectFreshnessBaseline(projectRoot, resolved, artifactPaths) {
+  const baselineCandidates = [];
+  if (artifactPaths) {
+    baselineCandidates.push(
+      artifactPaths.proposalPath,
+      artifactPaths.tasksPath,
+      artifactPaths.bindingsPath,
+      artifactPaths.pencilDesignPath,
+      artifactPaths.verificationPath
+    );
+  }
+  if (resolved && resolved.changeDir) {
+    const specsRoot = path.join(resolved.changeDir, "specs");
+    if (fs.existsSync(specsRoot)) {
+      const stack = [specsRoot];
+      while (stack.length > 0) {
+        const current = stack.pop();
+        let entries = [];
+        try {
+          entries = fs.readdirSync(current, { withFileTypes: true });
+        } catch (_error) {
+          continue;
+        }
+        for (const entry of entries) {
+          const absolutePath = path.join(current, entry.name);
+          if (entry.isDirectory() && !entry.isSymbolicLink()) {
+            stack.push(absolutePath);
+            continue;
+          }
+          if (entry.isFile() && entry.name === "spec.md") {
+            baselineCandidates.push(absolutePath);
+          }
+        }
+      }
+    }
+  }
+  const baselineMs = baselineCandidates.reduce((latest, candidate) => Math.max(latest, safeMtimeMs(candidate)), 0);
+  return {
+    baselineMs,
+    baselineIso: baselineMs > 0 ? new Date(baselineMs).toISOString() : ""
+  };
+}
+
+function collectVerificationFreshness(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const changeId = options.changeId ? String(options.changeId).trim() : "";
+  if (!changeId) {
+    return {
+      fresh: false,
+      changeId: null,
+      requiredSurfaces: [],
+      surfaces: {},
+      staleReasons: ["Missing change id for verification freshness checks."],
+      baselineIso: ""
+    };
+  }
+
+  const requiredSurfaces =
+    Array.isArray(options.requiredSurfaces) && options.requiredSurfaces.length > 0
+      ? options.requiredSurfaces
+      : ["verify-bindings", "verify-implementation", "verify-structure", "verify-coverage"];
+  const maxAgeMs =
+    Number.isFinite(Number(options.maxAgeMs)) && Number(options.maxAgeMs) > 0
+      ? Number(options.maxAgeMs)
+      : DEFAULT_EVIDENCE_MAX_AGE_MS;
+  const nowMs = Date.now();
+  const signals = readExecutionSignals(projectRoot, { changeId });
+  const summary = summarizeSignalsBySurface(signals);
+  const baseline = collectFreshnessBaseline(projectRoot, options.resolved, options.artifactPaths);
+  const staleReasons = [];
+  const surfaces = {};
+
+  for (const surface of requiredSurfaces) {
+    const key = String(surface || "").toLowerCase().replace(/[^a-z0-9._-]+/g, "-");
+    const signal = summary[key];
+    if (!signal) {
+      staleReasons.push(`Missing evidence signal: ${surface}.`);
+      surfaces[surface] = {
+        present: false,
+        stale: true
+      };
+      continue;
+    }
+    const timestampMs = Date.parse(String(signal.timestamp || ""));
+    if (!Number.isFinite(timestampMs)) {
+      staleReasons.push(`Invalid evidence timestamp for ${surface}.`);
+      surfaces[surface] = {
+        present: true,
+        stale: true,
+        timestamp: signal.timestamp || ""
+      };
+      continue;
+    }
+    const olderThanBaseline = baseline.baselineMs > 0 && timestampMs < baseline.baselineMs;
+    const olderThanMaxAge = nowMs - timestampMs > maxAgeMs;
+    if (olderThanBaseline) {
+      staleReasons.push(
+        `${surface} evidence is older than current artifact baseline (${new Date(timestampMs).toISOString()} < ${baseline.baselineIso}).`
+      );
+    }
+    if (olderThanMaxAge) {
+      staleReasons.push(
+        `${surface} evidence is older than freshness window (${Math.round((nowMs - timestampMs) / 1000)}s).`
+      );
+    }
+    surfaces[surface] = {
+      present: true,
+      stale: olderThanBaseline || olderThanMaxAge,
+      status: signal.status,
+      timestamp: signal.timestamp
+    };
+  }
+
+  return {
+    fresh: staleReasons.length === 0,
+    changeId,
+    requiredSurfaces,
+    surfaces,
+    staleReasons: unique(staleReasons),
+    baselineIso: baseline.baselineIso
+  };
+}
+
 function createSharedSetup(projectPathInput, options = {}) {
   const projectRoot = path.resolve(projectPathInput || process.cwd());
   const strict = options && options.strict === true;
@@ -600,6 +734,22 @@ function verifyCoverage(projectPathInput, options = {}) {
     }
   };
 
+  const freshness = collectVerificationFreshness(projectRoot, {
+    changeId: result.changeId,
+    resolved: sharedSetup.resolved,
+    artifactPaths: sharedSetup.artifactPaths,
+    requiredSurfaces: ["verify-bindings", "verify-implementation", "verify-structure"]
+  });
+  result.freshness = freshness;
+  if (!freshness.fresh) {
+    result.warnings.push(
+      "Verification freshness is stale for completion-facing claims; re-run verify surfaces before completion wording."
+    );
+    for (const reason of freshness.staleReasons) {
+      result.warnings.push(reason);
+    }
+  }
+
   return finalize(result);
 }
 
@@ -648,5 +798,6 @@ module.exports = {
   verifyImplementation,
   verifyStructure,
   verifyCoverage,
-  formatVerifyReport
+  formatVerifyReport,
+  collectVerificationFreshness
 };

package/lib/workflow-bootstrap.js

@@ -1,8 +1,8 @@
 const fs = require("fs");
 const path = require("path");
 
-const { isPathInside } = require("./fs-safety");
 const { ensurePenFile } = require("./pen-persistence");
+const { resolvePreferredRegisteredPenPath } = require("./design-source-registry");
 const { pathExists, readTextIfExists, writeFileAtomic } = require("./utils");
 
 const DEFAULT_PROJECT_PEN_RELATIVE_PATH = ".da-vinci/designs/project-baseline.pen";
@@ -20,17 +20,6 @@ function validateChangeId(changeId) {
   return normalized;
 }
 
-function extractRegisteredPenPath(projectRoot, registryText) {
-  const matches = String(registryText || "").match(/\.da-vinci\/designs\/[^\s`]+\.pen/g) || [];
-  for (const relativePath of matches) {
-    const resolvedPath = path.resolve(projectRoot, relativePath);
-    if (isPathInside(projectRoot, resolvedPath)) {
-      return resolvedPath;
-    }
-  }
-  return "";
-}
-
 function buildProjectTemplates(preferredPenRelativePath) {
   return {
     "DA-VINCI.md": [
@@ -151,7 +140,7 @@ function bootstrapProjectArtifacts(projectPathInput, options = {}) {
   fs.mkdirSync(path.join(projectRoot, ".da-vinci", "changes"), { recursive: true });
 
   const existingRegistryText = readTextIfExists(path.join(projectRoot, ".da-vinci", "design-registry.md"));
-  const registeredPenPath = extractRegisteredPenPath(projectRoot, existingRegistryText);
+  const registeredPenPath = resolvePreferredRegisteredPenPath(projectRoot, existingRegistryText);
   const preferredPenPath = registeredPenPath || path.join(projectRoot, DEFAULT_PROJECT_PEN_RELATIVE_PATH);
   const preferredPenRelativePath = path.relative(projectRoot, preferredPenPath) || DEFAULT_PROJECT_PEN_RELATIVE_PATH;
 

package/lib/workflow-persisted-state.js

@@ -2,7 +2,7 @@ const fs = require("fs");
 const path = require("path");
 const { writeFileAtomic, pathExists, readTextIfExists } = require("./utils");
 
-const WORKFLOW_STATE_VERSION = 1;
+const WORKFLOW_STATE_VERSION = 2;
 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,
@@ -38,7 +38,9 @@ function fingerprintForPath(targetPath) {
 function buildWorkflowFingerprint(projectRoot, changeId) {
   const changeRoot = changeId ? path.join(projectRoot, ".da-vinci", "changes", changeId) : "";
   const candidates = [
+    path.join(projectRoot, "DA-VINCI.md"),
     path.join(projectRoot, ".da-vinci", "page-map.md"),
+    path.join(projectRoot, ".da-vinci", "design-registry.md"),
     path.join(changeRoot, "proposal.md"),
     path.join(changeRoot, "design.md"),
     path.join(changeRoot, "pencil-design.md"),