@xenonbyte/da-vinci-workflow 0.1.26 → 0.2.1

package/lib/cli.js

@@ -54,8 +54,30 @@ const {
   bootstrapProjectArtifacts,
   formatBootstrapProjectReport
 } = require("./workflow-bootstrap");
+const {
+  deriveWorkflowStatus,
+  formatWorkflowStatusReport,
+  formatNextStepReport
+} = require("./workflow-state");
+const { lintRuntimeSpecs, formatLintSpecReport } = require("./lint-spec");
+const { runScopeCheck, formatScopeCheckReport } = require("./scope-check");
+const { lintTasks, formatLintTasksReport } = require("./lint-tasks");
+const { lintBindings, formatLintBindingsReport } = require("./lint-bindings");
+const { generatePlanningSidecars, formatGenerateSidecarsReport } = require("./sidecars");
+const {
+  verifyBindings,
+  verifyImplementation,
+  verifyStructure,
+  verifyCoverage,
+  formatVerifyReport
+} = require("./verify");
+const { diffSpec, formatDiffSpecReport } = require("./diff-spec");
+const { scaffoldFromBindings, formatScaffoldReport } = require("./scaffold");
+const { writeExecutionSignal } = require("./execution-signals");
 
 const DEFAULT_MAX_PREFLIGHT_STDIN_BYTES = 1024 * 1024;
+const DEFAULT_MAX_STDIN_TRANSIENT_RETRIES = 2000;
+const DEFAULT_MAX_STDIN_TRANSIENT_BACKOFF_MS = 25;
 const OPTION_FLAGS_WITH_VALUES = new Set([
   "--home",
   "--platform",
@@ -159,10 +181,20 @@ const HELP_OPTION_SPECS = [
   { flag: "--revision-outcome <text>", description: "supervisor-review revision result summary" },
   { flag: "--top <value>", description: "icon-search result count (1-50, default 8)" },
   { flag: "--timeout-ms <value>", description: "network timeout for icon-sync requests" },
-  { flag: "--strict", description: "fail icon-sync when any upstream source request fails" },
-  { flag: "--json", description: "print structured JSON for icon-search" },
+  {
+    flag: "--strict",
+    description: "enable strict failure mode for commands that support advisory defaults (for example icon-sync, lint-spec)"
+  },
+  {
+    flag: "--continue-on-error",
+    description: "print BLOCK/FAIL command results without throwing process errors"
+  },
+  { flag: "--json", description: "print structured JSON output when supported by the command" },
   { flag: "--pen <path>", description: "registered .pen path for sync checks" },
-  { flag: "--from <path>", description: "source .pen path for sync-pen-source" },
+  {
+    flag: "--from <path>",
+    description: "source path for sync-pen-source, or baseline sidecars directory for diff-spec"
+  },
   { flag: "--to <path>", description: "destination .pen path for sync-pen-source" },
   { flag: "--ops-file <path>", description: "Pencil batch operations file for preflight" },
   { flag: "--input <path>", description: "input .pen file for snapshot-pen" },
@@ -178,11 +210,19 @@ const HELP_OPTION_SPECS = [
   { flag: "--force", description: "overwrite bootstrap placeholders or force commands that explicitly support it" }
 ];
 
-function readLimitedStdin(maxBytes = DEFAULT_MAX_PREFLIGHT_STDIN_BYTES) {
+function readLimitedStdin(maxBytes = DEFAULT_MAX_PREFLIGHT_STDIN_BYTES, options = {}) {
   const limit =
     Number.isFinite(Number(maxBytes)) && Number(maxBytes) > 0
       ? Number(maxBytes)
       : DEFAULT_MAX_PREFLIGHT_STDIN_BYTES;
+  const maxTransientRetries =
+    Number.isFinite(Number(options.maxTransientRetries)) && Number(options.maxTransientRetries) >= 0
+      ? Number(options.maxTransientRetries)
+      : DEFAULT_MAX_STDIN_TRANSIENT_RETRIES;
+  const maxBackoffMs =
+    Number.isFinite(Number(options.maxBackoffMs)) && Number(options.maxBackoffMs) > 0
+      ? Number(options.maxBackoffMs)
+      : DEFAULT_MAX_STDIN_TRANSIENT_BACKOFF_MS;
   const chunks = [];
   let totalBytes = 0;
   let transientReadRetries = 0;
@@ -195,7 +235,12 @@ function readLimitedStdin(maxBytes = DEFAULT_MAX_PREFLIGHT_STDIN_BYTES) {
     } catch (error) {
       if (error && (error.code === "EAGAIN" || error.code === "EINTR")) {
         transientReadRetries += 1;
-        sleepSyncMs(Math.min(5 * transientReadRetries, 25));
+        if (transientReadRetries > maxTransientRetries) {
+          throw new Error(
+            `Unable to read stdin after ${transientReadRetries} transient retry attempts (${error.code}).`
+          );
+        }
+        sleepSyncMs(Math.min(5 * transientReadRetries, maxBackoffMs));
         continue;
       }
       throw error;
@@ -285,6 +330,21 @@ function getOptionValues(args, name) {
     .map((entry) => entry.value);
 }
 
+function shouldContinueOnError(args) {
+  return Array.isArray(args) && args.includes("--continue-on-error");
+}
+
+function emitOrThrowOnStatus(status, blockedStatuses, output, continueOnError) {
+  if (!Array.isArray(blockedStatuses) || !blockedStatuses.includes(status)) {
+    return false;
+  }
+  if (continueOnError) {
+    console.log(output);
+    return true;
+  }
+  throw new Error(output);
+}
+
 function getIntegerOption(args, name, options = {}) {
   const raw = getOption(args, name);
   if (raw === undefined) {
@@ -372,6 +432,32 @@ function appendStatusIssues(lines, label, missing = [], mismatched = [], unreada
   }
 }
 
+function persistExecutionSignal(projectPath, changeId, surface, result, strict = false) {
+  try {
+    writeExecutionSignal(projectPath, {
+      changeId: changeId || "global",
+      surface,
+      status: result.status,
+      advisory: strict ? false : true,
+      strict,
+      failures: result.failures || [],
+      warnings: result.warnings || [],
+      notes: result.notes || []
+    });
+  } catch (error) {
+    // Signals are advisory metadata and should not break command execution.
+    const code = error && error.code ? String(error.code).toUpperCase() : "";
+    if (code === "EACCES" || code === "ENOSPC") {
+      return;
+    }
+
+    const message = error && error.message ? error.message : String(error);
+    console.error(
+      `Warning: failed to persist execution signal (${surface}) for change ${changeId || "global"}: ${message}`
+    );
+  }
+}
+
 function printHelp() {
   const optionLines = HELP_OPTION_SPECS.map((optionSpec) => {
     const paddedFlag = optionSpec.flag.padEnd(30, " ");
@@ -386,6 +472,19 @@ function printHelp() {
       "  da-vinci install --platform codex,claude,gemini",
       "  da-vinci uninstall --platform codex,claude,gemini",
       "  da-vinci status",
+      "  da-vinci workflow-status [--project <path>] [--change <id>] [--json]",
+      "  da-vinci next-step [--project <path>] [--change <id>] [--json]",
+      "  da-vinci lint-spec [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci scope-check [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci lint-tasks [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci lint-bindings [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci generate-sidecars [--project <path>] [--change <id>] [--json]",
+      "  da-vinci verify-bindings [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci verify-implementation [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci verify-structure [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci verify-coverage [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci diff-spec [--project <path>] [--change <id>] [--from <sidecars-dir>] [--json]",
+      "  da-vinci scaffold [--project <path>] [--change <id>] [--output <path>] [--json]",
       "  da-vinci validate-assets",
       "  da-vinci bootstrap-project --project <path> [--change <id>] [--force]",
       "  da-vinci audit [project-path]",
@@ -803,6 +902,7 @@ async function runCli(argv) {
   const [command] = argv;
   const homeDir = getOption(argv, "--home");
   const positionalArgs = getPositionalArgs(argv.slice(1), OPTION_FLAGS_WITH_VALUES);
+  const continueOnError = shouldContinueOnError(argv);
 
   if (!command || command === "help" || command === "--help" || command === "-h") {
     printHelp();
@@ -837,6 +937,216 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "workflow-status") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const result = deriveWorkflowStatus(projectPath, { changeId });
+
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    console.log(formatWorkflowStatusReport(result));
+    return;
+  }
+
+  if (command === "next-step") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const result = deriveWorkflowStatus(projectPath, { changeId });
+
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(result.nextStep || null, null, 2));
+      return;
+    }
+
+    console.log(formatNextStepReport(result));
+    return;
+  }
+
+  if (command === "lint-spec") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const strict = argv.includes("--strict");
+    const result = lintRuntimeSpecs(projectPath, { changeId, strict });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "lint-spec", result, strict);
+    const useJson = argv.includes("--json");
+    const output = useJson ? JSON.stringify(result, null, 2) : formatLintSpecReport(result);
+
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+
+    console.log(output);
+    return;
+  }
+
+  if (command === "scope-check") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const strict = argv.includes("--strict");
+    const result = runScopeCheck(projectPath, { changeId, strict });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "scope-check", result, strict);
+    const useJson = argv.includes("--json");
+    const output = useJson ? JSON.stringify(result, null, 2) : formatScopeCheckReport(result);
+
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+
+    console.log(output);
+    return;
+  }
+
+  if (command === "lint-tasks") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const strict = argv.includes("--strict");
+    const result = lintTasks(projectPath, { changeId, strict });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "lint-tasks", result, strict);
+    const useJson = argv.includes("--json");
+    const output = useJson ? JSON.stringify(result, null, 2) : formatLintTasksReport(result);
+
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+
+    console.log(output);
+    return;
+  }
+
+  if (command === "lint-bindings") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const strict = argv.includes("--strict");
+    const result = lintBindings(projectPath, { changeId, strict });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "lint-bindings", result, strict);
+    const useJson = argv.includes("--json");
+    const output = useJson ? JSON.stringify(result, null, 2) : formatLintBindingsReport(result);
+
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+
+    console.log(output);
+    return;
+  }
+
+  if (command === "generate-sidecars") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const result = generatePlanningSidecars(projectPath, { changeId, write: true });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "generate-sidecars", result, false);
+    const useJson = argv.includes("--json");
+    const output = useJson ? JSON.stringify(result, null, 2) : formatGenerateSidecarsReport(result);
+
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+
+    console.log(output);
+    return;
+  }
+
+  if (command === "verify-bindings") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const strict = argv.includes("--strict");
+    const result = verifyBindings(projectPath, { changeId, strict });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "verify-bindings", result, strict);
+    const useJson = argv.includes("--json");
+    const output = useJson
+      ? JSON.stringify(result, null, 2)
+      : formatVerifyReport(result, "Da Vinci verify-bindings");
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+    console.log(output);
+    return;
+  }
+
+  if (command === "verify-implementation") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const strict = argv.includes("--strict");
+    const result = verifyImplementation(projectPath, { changeId, strict });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "verify-implementation", result, strict);
+    const useJson = argv.includes("--json");
+    const output = useJson
+      ? JSON.stringify(result, null, 2)
+      : formatVerifyReport(result, "Da Vinci verify-implementation");
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+    console.log(output);
+    return;
+  }
+
+  if (command === "verify-structure") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const strict = argv.includes("--strict");
+    const result = verifyStructure(projectPath, { changeId, strict });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "verify-structure", result, strict);
+    const useJson = argv.includes("--json");
+    const output = useJson
+      ? JSON.stringify(result, null, 2)
+      : formatVerifyReport(result, "Da Vinci verify-structure");
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+    console.log(output);
+    return;
+  }
+
+  if (command === "verify-coverage") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const strict = argv.includes("--strict");
+    const result = verifyCoverage(projectPath, { changeId, strict });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "verify-coverage", result, strict);
+    const useJson = argv.includes("--json");
+    const output = useJson
+      ? JSON.stringify(result, null, 2)
+      : formatVerifyReport(result, "Da Vinci verify-coverage");
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+    console.log(output);
+    return;
+  }
+
+  if (command === "diff-spec") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const fromDir = getOption(argv, "--from");
+    const result = diffSpec(projectPath, { changeId, fromDir });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "diff-spec", result, false);
+    const useJson = argv.includes("--json");
+    const output = useJson ? JSON.stringify(result, null, 2) : formatDiffSpecReport(result);
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+    console.log(output);
+    return;
+  }
+
+  if (command === "scaffold") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const outputDir = getOption(argv, "--output");
+    const result = scaffoldFromBindings(projectPath, { changeId, outputDir });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "scaffold", result, false);
+    const useJson = argv.includes("--json");
+    const output = useJson ? JSON.stringify(result, null, 2) : formatScaffoldReport(result);
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+    console.log(output);
+    return;
+  }
+
   if (command === "validate-assets") {
     const result = validateAssets();
     console.log(`Da Vinci v${result.version} assets are complete (${result.requiredAssets} required files).`);
@@ -850,8 +1160,8 @@ async function runCli(argv) {
     const result = auditProject(projectPath, { mode, changeId });
     const report = formatAuditReport(result);
 
-    if (result.status === "FAIL") {
-      throw new Error(report);
+    if (emitOrThrowOnStatus(result.status, ["FAIL"], report, continueOnError)) {
+      return;
     }
 
     console.log(report);
@@ -903,8 +1213,8 @@ async function runCli(argv) {
     const result = preflightPencilBatch(operations);
     const report = formatPencilPreflightReport(result);
 
-    if (result.status === "FAIL") {
-      throw new Error(report);
+    if (emitOrThrowOnStatus(result.status, ["FAIL"], report, continueOnError)) {
+      return;
     }
 
     console.log(report);
@@ -1028,13 +1338,18 @@ async function runCli(argv) {
       preferredSource
     });
 
-    if (result.status === "BLOCK") {
-      throw new Error(
+    if (
+      emitOrThrowOnStatus(
+        result.status,
+        ["BLOCK"],
         [
           "Baseline alignment check failed.",
           formatPenBaselineAlignmentReport(result)
-        ].join("\n")
-      );
+        ].join("\n"),
+        continueOnError
+      )
+    ) {
+      return;
     }
 
     console.log(formatPenBaselineAlignmentReport(result));

package/lib/diff-spec.js

@@ -0,0 +1,242 @@
+const fs = require("fs");
+const path = require("path");
+const { STATUS } = require("./workflow-contract");
+const { pathExists } = require("./utils");
+const { generatePlanningSidecars } = require("./sidecars");
+const { digestObject } = require("./planning-parsers");
+
+function keyByText(items) {
+  const map = new Map();
+  for (const item of items || []) {
+    const text = String(item && item.text ? item.text : item || "").trim();
+    if (!text) {
+      continue;
+    }
+    map.set(text, item);
+  }
+  return map;
+}
+
+function readJsonFileIfExists(filePath) {
+  if (!filePath || !pathExists(filePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (_error) {
+    return null;
+  }
+}
+
+function diffTextCollection(baseItems, headItems) {
+  const baseMap = keyByText(baseItems);
+  const headMap = keyByText(headItems);
+  const added = [];
+  const removed = [];
+  const modified = [];
+
+  for (const text of headMap.keys()) {
+    if (!baseMap.has(text)) {
+      added.push(text);
+    }
+  }
+  for (const text of baseMap.keys()) {
+    if (!headMap.has(text)) {
+      removed.push(text);
+    }
+  }
+
+  for (const text of headMap.keys()) {
+    if (!baseMap.has(text)) {
+      continue;
+    }
+    const baseRecord = baseMap.get(text) || {};
+    const headRecord = headMap.get(text) || {};
+    if (String(baseRecord.specPath || "") !== String(headRecord.specPath || "")) {
+      modified.push({
+        text,
+        from: String(baseRecord.specPath || ""),
+        to: String(headRecord.specPath || "")
+      });
+    }
+  }
+
+  return {
+    added: added.sort((a, b) => a.localeCompare(b)),
+    removed: removed.sort((a, b) => a.localeCompare(b)),
+    modified
+  };
+}
+
+function hasAnyDiff(diff) {
+  return (
+    (diff.added && diff.added.length > 0) ||
+    (diff.removed && diff.removed.length > 0) ||
+    (diff.modified && diff.modified.length > 0)
+  );
+}
+
+function chooseBaseSidecars(projectRoot, changeId, fromDir) {
+  const sidecarDir = fromDir || path.join(projectRoot, ".da-vinci", "changes", changeId, "sidecars");
+  return {
+    spec: readJsonFileIfExists(path.join(sidecarDir, "spec.index.json")),
+    tasks: readJsonFileIfExists(path.join(sidecarDir, "tasks.index.json")),
+    pageMap: readJsonFileIfExists(path.join(sidecarDir, "page-map.index.json")),
+    bindings: readJsonFileIfExists(path.join(sidecarDir, "bindings.index.json")),
+    sidecarDir
+  };
+}
+
+function diffSpec(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
+  const sidecarResult = generatePlanningSidecars(projectRoot, {
+    changeId: requestedChangeId,
+    write: false
+  });
+  if (sidecarResult.failures.length > 0 || !sidecarResult.changeId) {
+    return {
+      status: STATUS.BLOCK,
+      failures: sidecarResult.failures,
+      warnings: sidecarResult.warnings,
+      notes: sidecarResult.notes,
+      projectRoot,
+      changeId: sidecarResult.changeId || null,
+      diff: null
+    };
+  }
+
+  const changeId = sidecarResult.changeId;
+  const baseSidecars = chooseBaseSidecars(projectRoot, changeId, options.fromDir);
+  const headSidecars = sidecarResult.sidecars;
+
+  if (!baseSidecars.spec) {
+    return {
+      status: STATUS.WARN,
+      failures: [],
+      warnings: [
+        `No baseline sidecars found in ${baseSidecars.sidecarDir}. Run \`da-vinci generate-sidecars\` before diff-spec.`
+      ],
+      notes: [
+        "diff-spec currently stays under the `diff-spec` surface and includes broader planning summaries for page-map/bindings/tasks."
+      ],
+      projectRoot,
+      changeId,
+      diff: {
+        spec: null,
+        tasks: null,
+        pageMap: null,
+        bindings: null
+      }
+    };
+  }
+
+  const baseSpecCollections = baseSidecars.spec.collections || {};
+  const headSpecCollections = headSidecars["spec.index.json"].collections || {};
+  const baseSpecDigest = digestObject(baseSidecars.spec);
+  const headSpecDigest = digestObject(headSidecars["spec.index.json"]);
+  const specDiff = {
+    behavior: diffTextCollection(baseSpecCollections.behavior || [], headSpecCollections.behavior || []),
+    states: diffTextCollection(baseSpecCollections.states || [], headSpecCollections.states || []),
+    inputs: diffTextCollection(baseSpecCollections.inputs || [], headSpecCollections.inputs || []),
+    outputs: diffTextCollection(baseSpecCollections.outputs || [], headSpecCollections.outputs || []),
+    acceptance: diffTextCollection(baseSpecCollections.acceptance || [], headSpecCollections.acceptance || [])
+  };
+
+  const tasksDiff = {
+    taskGroups: diffTextCollection(
+      (baseSidecars.tasks && baseSidecars.tasks.taskGroups
+        ? baseSidecars.tasks.taskGroups.map((item) => ({ text: `${item.id}: ${item.title}` }))
+        : []),
+      headSidecars["tasks.index.json"].taskGroups.map((item) => ({ text: `${item.id}: ${item.title}` }))
+    )
+  };
+
+  const pageMapDiff = {
+    pages: diffTextCollection(
+      (baseSidecars.pageMap && baseSidecars.pageMap.pages
+        ? baseSidecars.pageMap.pages.map((page) => ({ text: page }))
+        : []),
+      headSidecars["page-map.index.json"].pages.map((page) => ({ text: page }))
+    )
+  };
+
+  const bindingsDiff = {
+    mappings: diffTextCollection(
+      (baseSidecars.bindings && baseSidecars.bindings.mappings
+        ? baseSidecars.bindings.mappings.map((item) => ({
+            text: `${item.implementation} -> ${item.designPage}`
+          }))
+        : []),
+      headSidecars["bindings.index.json"].mappings.map((item) => ({
+        text: `${item.implementation} -> ${item.designPage}`
+      }))
+    )
+  };
+
+  const hasChanges =
+    Object.values(specDiff).some((entry) => hasAnyDiff(entry)) ||
+    baseSpecDigest !== headSpecDigest ||
+    hasAnyDiff(tasksDiff.taskGroups) ||
+    hasAnyDiff(pageMapDiff.pages) ||
+    hasAnyDiff(bindingsDiff.mappings);
+
+  return {
+    status: hasChanges ? STATUS.WARN : STATUS.PASS,
+    failures: [],
+    warnings: hasChanges ? ["Planning sidecar differences detected."] : [],
+    notes: [
+      "diff-spec includes normalized spec deltas and broader planning summaries (tasks/page-map/bindings)."
+    ],
+    projectRoot,
+    changeId,
+    diff: {
+      spec: specDiff,
+      specDigestChanged: baseSpecDigest !== headSpecDigest,
+      tasks: tasksDiff,
+      pageMap: pageMapDiff,
+      bindings: bindingsDiff
+    }
+  };
+}
+
+function formatDiffSpecReport(result) {
+  const lines = [
+    "Da Vinci diff-spec",
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId || "(not selected)"}`,
+    `Status: ${result.status}`
+  ];
+  if (result.failures && result.failures.length > 0) {
+    lines.push("", "Failures:");
+    for (const failure of result.failures) {
+      lines.push(`- ${failure}`);
+    }
+  }
+  if (result.warnings && result.warnings.length > 0) {
+    lines.push("", "Warnings:");
+    for (const warning of result.warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
+  if (result.diff && result.diff.spec) {
+    lines.push("", "Spec deltas:");
+    for (const [section, entry] of Object.entries(result.diff.spec)) {
+      lines.push(
+        `- ${section}: +${entry.added.length} / -${entry.removed.length} / ~${entry.modified.length}`
+      );
+    }
+  }
+  if (result.notes && result.notes.length > 0) {
+    lines.push("", "Notes:");
+    for (const note of result.notes) {
+      lines.push(`- ${note}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  diffSpec,
+  formatDiffSpecReport
+};