@xenonbyte/da-vinci-workflow 0.1.23 → 0.1.25

package/lib/audit.js

@@ -11,6 +11,7 @@ const {
   buildContextDeltaReferenceIndex,
   resolveSupersedesReferenceIndices,
   inspectContextDelta,
+  getConfiguredDesignSupervisorReviewers,
   hasConfiguredDesignSupervisorReview,
   isDesignSupervisorReviewRequired,
   inspectDesignSupervisorReview
@@ -195,6 +196,10 @@ function appendTraversalWarnings(projectRoot, rootDir, scan, warnings) {
   }
 }
 
+function normalizeReviewerToken(value) {
+  return String(value || "").trim().toLowerCase();
+}
+
 function auditProject(projectPathInput, options = {}) {
   const projectRoot = path.resolve(projectPathInput || process.cwd());
   const mode = options.mode || "integrity";
@@ -204,6 +209,8 @@ function auditProject(projectPathInput, options = {}) {
   const designRegistryPath = path.join(daVinciDir, "design-registry.md");
   const pencilSessionPath = getSessionStatePath(projectRoot);
   const daVinciText = readTextIfExists(path.join(projectRoot, "DA-VINCI.md"));
+  const configuredSupervisorReviewers = getConfiguredDesignSupervisorReviewers(daVinciText);
+  const configuredReviewerSet = new Set(configuredSupervisorReviewers.map((value) => normalizeReviewerToken(value)));
   const designSupervisorConfigured = hasConfiguredDesignSupervisorReview(daVinciText);
   const designSupervisorRequired = isDesignSupervisorReviewRequired(daVinciText);
 
@@ -467,6 +474,15 @@ function auditProject(projectPathInput, options = {}) {
       const enforceAsFailure =
         mode === "completion" && scopedChangeDirs.includes(changeDir) && designSupervisorRequired;
 
+      if (review.usedStructuredSectionFallback) {
+        warnings.push(
+          `Latest design-supervisor review entry in ${relativeTo(projectRoot, pencilDesignPath)} ` +
+            `is a legacy/non-structured format; gate evaluation used ${review.selectedSectionHeading}.`
+        );
+      }
+
+      let reviewRecordValid = true;
+
       if (!review.found) {
         const message =
           `DA-VINCI.md configures Design-supervisor reviewers, but ${relativeTo(projectRoot, pencilDesignPath)} ` +
@@ -476,6 +492,7 @@ function auditProject(projectPathInput, options = {}) {
         } else {
           warnings.push(message);
         }
+        reviewRecordValid = false;
       } else if (!review.status) {
         const message =
           `Design-supervisor review is recorded in ${relativeTo(projectRoot, pencilDesignPath)} ` +
@@ -485,6 +502,7 @@ function auditProject(projectPathInput, options = {}) {
         } else {
           warnings.push(message);
         }
+        reviewRecordValid = false;
       } else if (!review.hasIssueList || !review.hasRevisionOutcome) {
         const missingFields = [
           !review.hasIssueList ? "Issue list" : null,
@@ -500,7 +518,82 @@ function auditProject(projectPathInput, options = {}) {
         } else {
           warnings.push(message);
         }
-      } else if (review.status === "BLOCK") {
+        reviewRecordValid = false;
+      } else if (!review.hasConfiguredReviewers) {
+        const message =
+          `Design-supervisor review in ${relativeTo(projectRoot, pencilDesignPath)} ` +
+          "is missing required field(s): Configured reviewers.";
+        if (enforceAsFailure) {
+          failures.push(message);
+        } else {
+          warnings.push(message);
+        }
+        reviewRecordValid = false;
+      }
+
+      if (reviewRecordValid && configuredReviewerSet.size > 0) {
+        const reviewConfiguredSet = new Set(
+          review.configuredReviewers.map((value) => normalizeReviewerToken(value))
+        );
+        const missingConfiguredReviewers = configuredSupervisorReviewers.filter(
+          (reviewer) => !reviewConfiguredSet.has(normalizeReviewerToken(reviewer))
+        );
+        if (missingConfiguredReviewers.length > 0) {
+          const message =
+            `Design-supervisor review in ${relativeTo(projectRoot, pencilDesignPath)} ` +
+            `does not list configured reviewer(s): ${missingConfiguredReviewers.join(", ")}.`;
+          if (enforceAsFailure) {
+            failures.push(message);
+          } else {
+            warnings.push(message);
+          }
+          reviewRecordValid = false;
+        }
+      }
+
+      if (reviewRecordValid) {
+        if (designSupervisorRequired && review.reviewSource !== "skill") {
+          const message =
+            `Design-supervisor review in ${relativeTo(projectRoot, pencilDesignPath)} ` +
+            "must be skill-backed (`Review source: skill`) when `Require Supervisor Review: true`.";
+          if (enforceAsFailure) {
+            failures.push(message);
+          } else {
+            warnings.push(message);
+          }
+          reviewRecordValid = false;
+        } else if (designSupervisorRequired && !review.hasExecutedReviewers) {
+          const message =
+            `Design-supervisor review in ${relativeTo(projectRoot, pencilDesignPath)} ` +
+            "is missing required field(s): Executed reviewers.";
+          if (enforceAsFailure) {
+            failures.push(message);
+          } else {
+            warnings.push(message);
+          }
+          reviewRecordValid = false;
+        } else if (designSupervisorRequired && configuredReviewerSet.size > 0) {
+          const executedReviewerSet = new Set(
+            review.executedReviewers.map((value) => normalizeReviewerToken(value))
+          );
+          const missingExecuted = configuredSupervisorReviewers.filter(
+            (reviewer) => !executedReviewerSet.has(normalizeReviewerToken(reviewer))
+          );
+          if (missingExecuted.length > 0) {
+            const message =
+              `Design-supervisor review in ${relativeTo(projectRoot, pencilDesignPath)} ` +
+              `did not execute configured reviewer skill(s): ${missingExecuted.join(", ")}.`;
+            if (enforceAsFailure) {
+              failures.push(message);
+            } else {
+              warnings.push(message);
+            }
+            reviewRecordValid = false;
+          }
+        }
+      }
+
+      if (reviewRecordValid && review.status === "BLOCK") {
         const message =
           `Design-supervisor review is still BLOCK in ${relativeTo(projectRoot, pencilDesignPath)}.`;
         if (enforceAsFailure) {
@@ -508,7 +601,7 @@ function auditProject(projectPathInput, options = {}) {
         } else {
           warnings.push(message);
         }
-      } else if (review.status === "WARN" && !review.acceptedWarn) {
+      } else if (reviewRecordValid && review.status === "WARN" && !review.acceptedWarn) {
         const message =
           `Design-supervisor review is WARN in ${relativeTo(projectRoot, pencilDesignPath)} ` +
           "but the warning was not explicitly accepted.";
@@ -517,7 +610,7 @@ function auditProject(projectPathInput, options = {}) {
         } else {
           warnings.push(message);
         }
-      } else {
+      } else if (reviewRecordValid) {
         notes.push(
           `Detected design-supervisor review status ${review.status} in ${relativeTo(projectRoot, pencilDesignPath)}.`
         );

package/lib/cli.js

@@ -42,6 +42,10 @@ const {
   loadIconAliases,
   expandQueryWithAliases
 } = require("./icon-aliases");
+const {
+  runDesignSupervisorReview,
+  formatDesignSupervisorReviewReport
+} = require("./supervisor-review");
 
 function getOption(args, name) {
   const direct = args.find((arg) => arg.startsWith(`${name}=`));
@@ -105,6 +109,7 @@ function printHelp() {
       "  da-vinci audit [project-path]",
       "  da-vinci icon-sync [--output <path>] [--timeout-ms <value>] [--strict]",
       "  da-vinci icon-search --query <text> [--family <value>] [--top <value>] [--catalog <path>] [--aliases <path>] [--json]",
+      "  da-vinci supervisor-review --project <path> --change <id> [--run-reviewers] [--review-concurrency <value>] [--review-retries <value>] [--review-retry-delay-ms <value>] [--source <skill|manual|inferred>] [--executed-reviewers <csv>] [--status <PASS|WARN|BLOCK>] [--issue-list <text>] [--revision-outcome <text>] [--write] [--json]",
       "  da-vinci preflight-pencil --ops-file <path>",
       "  da-vinci ensure-pen --output <path>",
       "  da-vinci write-pen --output <path> --nodes-file <path> [--variables-file <path>]",
@@ -125,8 +130,21 @@ function printHelp() {
       "  --project <path>     override project path for audit",
       "  --catalog <path>     icon catalog path for icon-search/icon-sync (default: ~/.da-vinci/icon-catalog.json)",
       "  --aliases <path>     icon alias mapping file for icon-search (default: ~/.da-vinci/icon-aliases.json)",
+      "  --pencil-design <path> explicit pencil-design.md path for supervisor-review",
       "  --query <text>       icon-search query text",
       "  --family <value>     icon-search family filter: all, material, rounded, outlined, sharp, lucide, feather, phosphor",
+      "  --status <value>     PASS, WARN, or BLOCK for supervisor-review",
+      "  --source <value>     review source: skill, manual, inferred",
+      "  --executed-reviewers <csv> reviewer skills that executed this review",
+      "  --run-reviewers      execute configured reviewer skills through codex exec",
+      "  --review-concurrency <value> max parallel reviewer executions (default 2)",
+      "  --review-retries <value> retry count per reviewer before failing (default 1)",
+      "  --review-retry-delay-ms <value> initial retry delay in milliseconds (default 400, exponential backoff)",
+      "  --codex-bin <path>   codex executable path for --run-reviewers (default: codex)",
+      "  --max-images <value> max screenshots attached to reviewer runs (default 6)",
+      "  --review-timeout-ms <value> timeout per reviewer run in milliseconds",
+      "  --issue-list <text>  supervisor-review issue summary",
+      "  --revision-outcome <text> supervisor-review revision result summary",
       "  --top <value>        icon-search result count (1-50, default 8)",
       "  --timeout-ms <value> network timeout for icon-sync requests",
       "  --strict             fail icon-sync when any upstream source request fails",
@@ -162,6 +180,18 @@ async function runCli(argv) {
     "--top",
     "--catalog",
     "--aliases",
+    "--pencil-design",
+    "--status",
+    "--source",
+    "--executed-reviewers",
+    "--codex-bin",
+    "--max-images",
+    "--review-timeout-ms",
+    "--review-concurrency",
+    "--review-retries",
+    "--review-retry-delay-ms",
+    "--issue-list",
+    "--revision-outcome",
     "--timeout-ms",
     "--ops-file",
     "--input",
@@ -394,6 +424,73 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "supervisor-review") {
+    if (argv.includes("--help") || argv.includes("-h")) {
+      console.log(
+        [
+          "da-vinci supervisor-review",
+          "",
+          "Usage:",
+          "  da-vinci supervisor-review --project <path> --change <id> [--run-reviewers] [--review-concurrency <value>] [--review-retries <value>] [--review-retry-delay-ms <value>] [--source <skill|manual|inferred>] [--executed-reviewers <csv>] [--status <PASS|WARN|BLOCK>] [--issue-list <text>] [--revision-outcome <text>] [--write] [--json]",
+          "  da-vinci supervisor-review --project <path> --pencil-design <path> [--run-reviewers] [--review-concurrency <value>] [--review-retries <value>] [--review-retry-delay-ms <value>] [--source <skill|manual|inferred>] [--executed-reviewers <csv>] [--status <PASS|WARN|BLOCK>] [--issue-list <text>] [--revision-outcome <text>] [--write] [--json]",
+          "",
+          "Notes:",
+          "  - omit --status to infer a conservative review status from current design artifacts",
+          "  - use --run-reviewers to execute configured reviewer skills automatically via codex exec",
+          "  - `design-supervisor review` is a compatibility alias for this command"
+        ].join("\n")
+      );
+      return;
+    }
+
+    const projectPath = getOption(argv, "--project") || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const pencilDesignPath = getOption(argv, "--pencil-design");
+    const status = getOption(argv, "--status");
+    const source = getOption(argv, "--source");
+    const executedReviewers = getOption(argv, "--executed-reviewers");
+    const codexBin = getOption(argv, "--codex-bin");
+    const maxImages = getOption(argv, "--max-images");
+    const reviewerTimeoutMs = getOption(argv, "--review-timeout-ms");
+    const reviewConcurrency = getOption(argv, "--review-concurrency");
+    const reviewerRetries = getOption(argv, "--review-retries");
+    const reviewerRetryDelayMs = getOption(argv, "--review-retry-delay-ms");
+    const issueList = getOption(argv, "--issue-list");
+    const revisionOutcome = getOption(argv, "--revision-outcome");
+    const write = argv.includes("--write");
+    const acceptWarn = argv.includes("--accept-warn");
+    const runReviewers = argv.includes("--run-reviewers");
+    const jsonOutput = argv.includes("--json");
+
+    const result = await runDesignSupervisorReview({
+      projectPath,
+      changeId,
+      pencilDesignPath,
+      status,
+      source,
+      executedReviewers,
+      codexBin,
+      maxImages,
+      reviewerTimeoutMs,
+      reviewConcurrency,
+      reviewerRetries,
+      reviewerRetryDelayMs,
+      issueList,
+      revisionOutcome,
+      write,
+      acceptWarn,
+      runReviewers
+    });
+
+    if (jsonOutput) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    console.log(formatDesignSupervisorReviewReport(result));
+    return;
+  }
+
   if (command === "ensure-pen") {
     const outputPath = getOption(argv, "--output");
     const version = getOption(argv, "--version");

package/lib/pen-persistence.js

@@ -110,7 +110,52 @@ function hasTruncatedChildren(value) {
   return Object.values(value).some((item) => hasTruncatedChildren(item));
 }
 
+function looksLikePenStatePayload(payload) {
+  if (!isPlainObject(payload)) {
+    return false;
+  }
+
+  const hasLiveNodes = Array.isArray(payload.nodes);
+  if (hasLiveNodes) {
+    return false;
+  }
+
+  const hasSnapshotHash = typeof payload.snapshotHash === "string" && payload.snapshotHash.length > 0;
+  const hasPenPath = typeof payload.penPath === "string" && payload.penPath.length > 0;
+  const hasStateCounters =
+    Object.prototype.hasOwnProperty.call(payload, "topLevelCount") ||
+    Object.prototype.hasOwnProperty.call(payload, "topLevelIds");
+  return hasSnapshotHash && hasPenPath && hasStateCounters;
+}
+
+function assertNodesPayloadIsLiveSnapshot(payload, sourcePath) {
+  if (!looksLikePenStatePayload(payload)) {
+    return;
+  }
+
+  const location = sourcePath ? ` (${formatPathForError(sourcePath)})` : "";
+  throw new Error(
+    `\`--nodes-file\` payload${location} appears to be pen state metadata, not a live MCP nodes snapshot. ` +
+      "Use JSON from `batch_get` (an array or an object with `nodes`)."
+  );
+}
+
+function formatPathForError(sourcePath) {
+  const resolved = path.resolve(sourcePath);
+  const relative = path.relative(process.cwd(), resolved);
+  if (!relative || relative === "") {
+    return ".";
+  }
+
+  if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
+    return relative;
+  }
+
+  return resolved;
+}
+
 function normalizeNodesPayload(payload) {
+  assertNodesPayloadIsLiveSnapshot(payload);
   const nodes = getNodesArray(payload);
 
   if (!nodes) {
@@ -318,6 +363,7 @@ function verifyPenFileWithPencil(filePath, options = {}) {
 function writePenFromPayloadFiles(options) {
   const outputPath = path.resolve(options.outputPath);
   const nodes = readJsonPayload(options.nodesFile);
+  assertNodesPayloadIsLiveSnapshot(nodes, options.nodesFile);
   const variables = options.variablesFile ? readJsonPayload(options.variablesFile) : undefined;
   const document = buildPenDocument({
     version: options.version || DEFAULT_PEN_VERSION,
@@ -447,6 +493,7 @@ function ensurePenFile(options) {
 
 function hashPayloadFiles(options) {
   const nodes = readJsonPayload(options.nodesFile);
+  assertNodesPayloadIsLiveSnapshot(nodes, options.nodesFile);
   const variables = options.variablesFile ? readJsonPayload(options.variablesFile) : undefined;
   const document = buildPenDocument({
     version: options.version || DEFAULT_PEN_VERSION,