@xenonbyte/da-vinci-workflow 0.1.25 → 0.2.1

package/docs/zh-CN/workflow-overview.md

@@ -15,6 +15,7 @@
 如果你想看 Pencil 渲染、持久化、门禁和审计的专门说明，请看 [pencil-rendering-workflow.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/pencil-rendering-workflow.md)。
 如果你想看逐个 `dv:` 命令的职责、下一步推荐和 `verify` 回退规则，请看 [dv-command-reference.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/dv-command-reference.md)。
 如果你想看约束文件总览（哪些字段是硬门禁、哪些是指导项），请看 [constraint-files.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/constraint-files.md)。
+如果你想看 sidecar、enforcement、persisted-state 回退和 scaffold 约束，请看 [execution-chain-migration.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/execution-chain-migration.md)。
 
 ## 核心契约
 
@@ -42,6 +43,30 @@ Da Vinci 围绕一个固定契约工作：
 8. 实现。
 9. 验证需求漂移和设计漂移。
 
+## Workflow-State 命令面
+
+在选择下一步 `dv:` 路由前，可先使用这些命令判断当前阶段就绪度：
+
+- `da-vinci workflow-status --project <path> [--change <id>] [--json]`
+  - 从工件真相和部分 audit 可见证据推导阶段、blocker、handoff gate 与路由建议
+- `da-vinci next-step --project <path> [--change <id>] [--json]`
+  - 基于同一 workflow-state 模型，给出优先续跑动作
+- `da-vinci lint-spec --project <path> [--change <id>] [--strict] [--json]`
+  - 在进入实现规划或实现前，校验运行时 `spec.md` 结构质量
+  - 默认 advisory；显式 `--strict` 才会把发现升级为阻断
+- `da-vinci scope-check --project <path> [--change <id>] [--strict] [--json]`
+  - 校验 proposal、page-map、运行时 spec、pencil-design、tasks 之间页面/状态传播是否一致
+  - 输出页面和状态的机器可读覆盖矩阵，供后续 verify/status 消费
+- `da-vinci generate-sidecars --project <path> [--change <id>] [--json]`
+  - 显式生成确定性的 planning sidecars，供 diff 和下游工具消费
+- `da-vinci verify-bindings|verify-implementation|verify-structure|verify-coverage --project <path> [--change <id>] [--strict] [--json]`
+  - 校验从 bindings 到实现与结构覆盖的执行链证据
+- `da-vinci diff-spec --project <path> [--change <id>] [--from <sidecars-dir>] [--json]`
+  - 报告 spec/tasks/page-map/bindings sidecars 的规范化差异，支持安全续跑
+
+这些命令不替代 `da-vinci audit --mode integrity|completion`。
+`audit` 仍是 integrity/completion 的正式真相面。
+
 ## 标准工件骨架
 
 根据 mode 的不同，Da Vinci 一般会围绕这组工件推进：
@@ -60,6 +85,8 @@ Da Vinci 围绕一个固定契约工作：
 
 `DA-VINCI.md` 仍然是项目级工作流和视觉约束文件。
 
+如果你是从空仓库、文档示例、或只水合到一半的工作区开始，先执行 `da-vinci bootstrap-project --project <project-path> --change <change-id>`，再跑严格 audit。这个命令会补齐最小项目骨架，并 seed 一个工作流管理的项目内 `.pen` 基线。
+
 ## 分阶段说明
 
 ### 1. Intake 与 Mode 选择

package/examples/greenfield-spec-markupflow/README.md

@@ -1,6 +1,11 @@
 # MarkupFlow Forward Test
 
-This example is a repo-local end-to-end forward test for Da Vinci.
+This example is a repo-local forward-test reference for Da Vinci.
+
+Important:
+
+- this walkthrough is documentation-first and keeps the narrative artifacts at the repository root for readability
+- it is not intended to pass `da-vinci audit` directly until those artifacts are materialized into the current `.da-vinci/` audit layout with persisted `.pen` session/state metadata
 
 Mode:
 

package/lib/artifact-parsers.js

@@ -0,0 +1,120 @@
+const { getMarkdownSection, hasMarkdownHeading } = require("./audit-parsers");
+
+const RUNTIME_SPEC_SECTION_DEFS = [
+  {
+    id: "capability",
+    heading: "Capability",
+    required: false
+  },
+  {
+    id: "behavior",
+    heading: "Behavior",
+    required: true
+  },
+  {
+    id: "states",
+    heading: "States",
+    required: true
+  },
+  {
+    id: "inputs",
+    heading: "Inputs",
+    required: true
+  },
+  {
+    id: "outputs",
+    heading: "Outputs",
+    required: true
+  },
+  {
+    id: "acceptance",
+    heading: "Acceptance",
+    required: true
+  },
+  {
+    id: "edgeCases",
+    heading: "Edge Cases",
+    required: true
+  }
+];
+
+const LIST_ITEM_PATTERN = /^\s*(?:[-*+]|\d+[.)])\s+(.+?)\s*$/;
+
+function extractSectionItems(sectionText) {
+  const normalized = String(sectionText || "").replace(/\r\n?/g, "\n").trim();
+  if (!normalized) {
+    return [];
+  }
+
+  const lines = normalized.split("\n");
+  const listItems = [];
+  for (const line of lines) {
+    const match = line.match(LIST_ITEM_PATTERN);
+    if (!match) {
+      continue;
+    }
+    const value = String(match[1] || "").trim();
+    if (value) {
+      listItems.push(value);
+    }
+  }
+
+  if (listItems.length > 0) {
+    return listItems;
+  }
+
+  return normalized
+    .split(/\n\s*\n/g)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function parseRuntimeSpecMarkdown(markdownText) {
+  const source = String(markdownText || "");
+  const sections = {};
+  const missingSections = [];
+  const emptySections = [];
+
+  for (const sectionDef of RUNTIME_SPEC_SECTION_DEFS) {
+    const present = hasMarkdownHeading(source, sectionDef.heading, {
+      allowParentheticalSuffix: true
+    });
+    const raw = getMarkdownSection(source, sectionDef.heading, {
+      allowParentheticalSuffix: true
+    });
+    const empty = present && String(raw || "").trim() === "";
+    const items = extractSectionItems(raw);
+
+    sections[sectionDef.id] = {
+      heading: sectionDef.heading,
+      required: sectionDef.required,
+      present,
+      empty,
+      raw,
+      items
+    };
+
+    if (!sectionDef.required) {
+      continue;
+    }
+
+    if (!present) {
+      missingSections.push(sectionDef.heading);
+      continue;
+    }
+    if (empty) {
+      emptySections.push(sectionDef.heading);
+    }
+  }
+
+  return {
+    sections,
+    missingSections,
+    emptySections
+  };
+}
+
+module.exports = {
+  RUNTIME_SPEC_SECTION_DEFS,
+  parseRuntimeSpecMarkdown
+};

package/lib/async-offload-worker.js

@@ -0,0 +1,26 @@
+const { parentPort, workerData } = require("worker_threads");
+
+(async () => {
+  try {
+    const loaded = require(workerData.modulePath);
+    const fn = loaded[workerData.exportName];
+    if (typeof fn !== "function") {
+      throw new Error(`Export "${workerData.exportName}" is not a function.`);
+    }
+
+    const result = await fn(...workerData.args);
+    parentPort.postMessage({ ok: true, result });
+  } catch (error) {
+    parentPort.postMessage({
+      ok: false,
+      error: {
+        message: error && error.message ? error.message : String(error),
+        stack: error && error.stack ? error.stack : "",
+        code: error && error.code ? error.code : "",
+        name: error && error.name ? error.name : "",
+        cause:
+          error && Object.prototype.hasOwnProperty.call(error, "cause") ? error.cause : undefined
+      }
+    });
+  }
+})();

package/lib/async-offload.js

@@ -0,0 +1,82 @@
+const { Worker } = require("worker_threads");
+const path = require("path");
+
+const WORKER_SCRIPT_PATH = path.join(__dirname, "async-offload-worker.js");
+
+function normalizeError(error) {
+  if (!error || typeof error !== "object") {
+    return new Error(String(error));
+  }
+  const message = error.message || String(error);
+  const wrapped = new Error(message);
+  if (typeof error.name === "string" && error.name) {
+    wrapped.name = error.name;
+  }
+  if (error.stack) {
+    wrapped.stack = error.stack;
+  }
+  if (error.code) {
+    wrapped.code = error.code;
+  }
+  if (Object.prototype.hasOwnProperty.call(error, "cause")) {
+    wrapped.cause = error.cause;
+  }
+  return wrapped;
+}
+
+function runModuleExportInWorker(modulePath, exportName, args = []) {
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(WORKER_SCRIPT_PATH, {
+      workerData: {
+        modulePath: path.resolve(modulePath),
+        exportName,
+        args
+      }
+    });
+
+    let settled = false;
+    function settle(callback, value) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+
+      const termination = worker.terminate();
+      if (termination && typeof termination.then === "function") {
+        termination
+          .catch(() => {})
+          .finally(() => {
+            callback(value);
+          });
+        return;
+      }
+
+      callback(value);
+    }
+
+    worker.once("message", (message) => {
+      if (message && message.ok) {
+        settle(resolve, message.result);
+      } else {
+        settle(reject, normalizeError(message ? message.error : "Worker execution failed."));
+      }
+    });
+    worker.once("error", (error) => {
+      settle(reject, normalizeError(error));
+    });
+    worker.once("exit", (code) => {
+      if (settled) {
+        return;
+      }
+      if (code !== 0) {
+        settle(reject, new Error(`Worker exited with code ${code}.`));
+        return;
+      }
+      settle(reject, new Error("Worker exited without returning a result."));
+    });
+  });
+}
+
+module.exports = {
+  runModuleExportInWorker
+};

package/lib/audit-parsers.js

@@ -1,32 +1,70 @@
-function escapeRegExp(value) {
-  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const { escapeRegExp } = require("./utils");
+
+function getMarkdownLines(text) {
+  return String(text || "").replace(/\r\n?/g, "\n").split("\n");
+}
+
+function getMarkdownHeadingLevel(line) {
+  const match = String(line || "").match(/^\s{0,3}(#{1,6})\s+/);
+  return match ? match[1].length : 0;
+}
+
+function getMarkdownHeadingMatch(line, heading, options = {}) {
+  const escapedHeading = escapeRegExp(heading);
+  const allowParentheticalSuffix = options.allowParentheticalSuffix === true;
+  const suffixPattern = allowParentheticalSuffix
+    ? String.raw`(?:\s*[（(][^)）\n]*[)）])?`
+    : "";
+  const headingPattern = new RegExp(
+    String.raw`^\s{0,3}(#{1,6})\s+${escapedHeading}${suffixPattern}\s*$`,
+    "i"
+  );
+  const match = String(line || "").match(headingPattern);
+  if (!match) {
+    return null;
+  }
+
+  return {
+    level: match[1].length
+  };
 }
 
-function getMarkdownSection(text, heading) {
+function hasMarkdownHeading(text, heading, options = {}) {
+  return getMarkdownLines(text).some((line) => Boolean(getMarkdownHeadingMatch(line, heading, options)));
+}
+
+function isMarkdownSectionHeading(line) {
+  return getMarkdownHeadingLevel(line) > 0;
+}
+
+function getMarkdownSection(text, heading, options = {}) {
   if (!text) {
     return "";
   }
 
-  const escapedHeading = escapeRegExp(heading);
-  const headingPattern = new RegExp(`^##\\s+${escapedHeading}\\s*$`, "i");
-  const anyHeadingPattern = /^##\s+/;
-  const lines = String(text).replace(/\r\n?/g, "\n").split("\n");
+  const lines = getMarkdownLines(text);
   const sectionLines = [];
   let capturing = false;
+  let sectionLevel = 0;
 
   for (const line of lines) {
-    if (capturing && anyHeadingPattern.test(line)) {
+    const headingLevel = getMarkdownHeadingLevel(line);
+
+    if (capturing && headingLevel > 0 && headingLevel <= sectionLevel) {
       break;
     }
 
-    if (!capturing && headingPattern.test(line)) {
+    if (!capturing) {
+      const headingMatch = getMarkdownHeadingMatch(line, heading, options);
+      if (!headingMatch) {
+        continue;
+      }
       capturing = true;
+      sectionLevel = headingMatch.level;
       continue;
     }
 
-    if (capturing) {
-      sectionLines.push(line);
-    }
+    sectionLines.push(line);
   }
 
   return sectionLines.join("\n").trim();
@@ -37,17 +75,11 @@ function getMarkdownSectionsByHeading(text, heading, options = {}) {
     return [];
   }
 
-  const escapedHeading = escapeRegExp(heading);
-  const allowParentheticalSuffix = options.allowParentheticalSuffix === true;
-  const suffixPattern = allowParentheticalSuffix
-    ? String.raw`(?:\s*[（(][^)）\n]*[)）])?`
-    : "";
-  const headingPattern = new RegExp(`^##\\s+${escapedHeading}${suffixPattern}\\s*$`, "i");
-  const anyHeadingPattern = /^##\s+/;
-  const lines = String(text).replace(/\r\n?/g, "\n").split("\n");
+  const lines = getMarkdownLines(text);
   const sections = [];
   let capturing = false;
   let currentHeading = "";
+  let currentLevel = 0;
   let sectionLines = [];
 
   function flushSection() {
@@ -61,30 +93,70 @@ function getMarkdownSectionsByHeading(text, heading, options = {}) {
     });
     capturing = false;
     currentHeading = "";
+    currentLevel = 0;
     sectionLines = [];
   }
 
   for (const line of lines) {
-    if (capturing && anyHeadingPattern.test(line)) {
+    const headingLevel = getMarkdownHeadingLevel(line);
+
+    if (capturing && headingLevel > 0 && headingLevel <= currentLevel) {
       flushSection();
     }
 
-    if (!capturing && headingPattern.test(line)) {
+    if (!capturing) {
+      const headingMatch = getMarkdownHeadingMatch(line, heading, options);
+      if (!headingMatch) {
+        continue;
+      }
       capturing = true;
       currentHeading = line.trim();
+      currentLevel = headingMatch.level;
       sectionLines = [];
       continue;
     }
 
-    if (capturing) {
-      sectionLines.push(line);
-    }
+    sectionLines.push(line);
   }
 
   flushSection();
   return sections;
 }
 
+const ACCEPTED_WARN_NEGATIVE_PATTERNS = [
+  /\bnot\s+accepted\b/i,
+  /\bnot\s+yet\s+accepted\b/i,
+  /\bunaccepted\b/i,
+  /\bstill\s+blocked\b/i,
+  /未接受/u,
+  /不接受/u,
+  /尚未接受/u,
+  /仍然?阻塞/u
+];
+
+const ACCEPTED_WARN_POSITIVE_PATTERNS = [
+  /\baccepted(?:\s+with\s+follow-?up)?\b/i,
+  /\baccepted\s+warning\b/i,
+  /\bwarn(?:ing)?\s+accepted\b/i,
+  /已接受/u,
+  /接受警告/u,
+  /警告已接受/u,
+  /(?:^|[\s:：,，(（])接受(?:$|[\s,，.。!！;；)）])/u
+];
+
+function isAcceptedWarnOutcome(revisionOutcome) {
+  const normalized = String(revisionOutcome || "").trim();
+  if (!normalized) {
+    return false;
+  }
+
+  if (ACCEPTED_WARN_NEGATIVE_PATTERNS.some((pattern) => pattern.test(normalized))) {
+    return false;
+  }
+
+  return ACCEPTED_WARN_POSITIVE_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+
 function extractReviewFieldValue(section, fieldNames) {
   const lines = String(section || "").replace(/\r\n?/g, "\n").split("\n");
   const escapedFieldNames = fieldNames.map((fieldName) => escapeRegExp(fieldName)).join("|");
@@ -96,7 +168,7 @@ function extractReviewFieldValue(section, fieldNames) {
   let capturing = false;
 
   for (const rawLine of lines) {
-    if (/^##\s+/.test(rawLine)) {
+    if (isMarkdownSectionHeading(rawLine)) {
       if (capturing) {
         break;
       }
@@ -192,7 +264,8 @@ function parseCheckpointStatusMap(markdownText) {
 function hasContextDeltaExpectationSignals(markdownText) {
   const text = String(markdownText || "");
   return (
-    /##\s+(Checkpoint Status|MCP Runtime Gate)\b/i.test(text) ||
+    hasMarkdownHeading(text, "Checkpoint Status") ||
+    hasMarkdownHeading(text, "MCP Runtime Gate") ||
     /(?:^|\n)\s*(?:[-*]\s*)?`?Context Delta Required`?\s*:\s*(?:true|yes|on|1)\b/i.test(text)
   );
 }
@@ -204,6 +277,50 @@ function parseSupersedesTokens(value) {
     .filter(Boolean);
 }
 
+function isValidIsoLikeDateCandidate(value) {
+  const match = String(value || "").match(
+    /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(\.\d{1,3})?)?)?(?:Z|([+-])(\d{2}):?(\d{2}))?$/i
+  );
+  if (!match) {
+    return true;
+  }
+
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  if (month < 1 || month > 12) {
+    return false;
+  }
+
+  const daysInMonth = new Date(Date.UTC(year, month, 0)).getUTCDate();
+  if (day < 1 || day > daysInMonth) {
+    return false;
+  }
+
+  if (match[8] && !match[4]) {
+    return false;
+  }
+
+  if (match[4]) {
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = match[6] ? Number(match[6]) : 0;
+    if (hour < 0 || hour > 23 || minute < 0 || minute > 59 || second < 0 || second > 59) {
+      return false;
+    }
+  }
+
+  if (match[8]) {
+    const offsetHour = Number(match[9]);
+    const offsetMinute = Number(match[10]);
+    if (offsetHour < 0 || offsetHour > 23 || offsetMinute < 0 || offsetMinute > 59) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
 function normalizeTimeToken(value) {
   const raw = String(value || "").trim();
   if (!raw) {
@@ -222,6 +339,9 @@ function normalizeTimeToken(value) {
   parseCandidates.push(raw);
 
   for (const candidate of parseCandidates) {
+    if (!isValidIsoLikeDateCandidate(candidate)) {
+      continue;
+    }
     const timestamp = Date.parse(candidate);
     if (!Number.isFinite(timestamp)) {
       continue;
@@ -582,11 +702,7 @@ function inspectDesignSupervisorReview(pencilDesignText) {
     const hasExecutedField = /(?:^|\n)\s*-\s*(?:Executed reviewers|Executed reviewer skills|执行评审)\s*:/i.test(section);
     const hasReviewSourceField = /(?:^|\n)\s*-\s*(?:Review source|评审来源)\s*:/i.test(section);
     const structuredFieldPresent = hasConfiguredField || hasExecutedField || hasReviewSourceField;
-    const acceptedWarn =
-      status === "WARN" &&
-      /(accepted|accepted with follow-up|accepted warning|warn accepted|接受|已接受|接受警告)/i.test(
-        revisionOutcome
-      );
+    const acceptedWarn = status === "WARN" && isAcceptedWarnOutcome(revisionOutcome);
     return {
       index,
       heading: sectionRecord.heading,
@@ -636,6 +752,10 @@ function inspectDesignSupervisorReview(pencilDesignText) {
 }
 
 module.exports = {
+  hasMarkdownHeading,
+  getMarkdownSection,
+  isAcceptedWarnOutcome,
+  normalizeTimeToken,
   normalizeCheckpointLabel,
   parseCheckpointStatusMap,
   hasContextDeltaExpectationSignals,