@xenonbyte/da-vinci-workflow 0.1.26 → 0.2.1

package/docs/zh-CN/dv-command-reference.md

@@ -39,6 +39,36 @@ Da Vinci 期望它们遵循工作流状态。
 
 这些命令不会替代 `dv:` 选路，但能显著提升设计执行质量：
 
+- `da-vinci workflow-status --project <path> [--change <id>] [--json]`
+  - 从工件和 checkpoint 真相推导当前 workflow 阶段
+  - 报告 blocker、warning、handoff gate 状态，以及主推荐路由
+  - 它和 `audit` 职责不同：它负责选路，不是终态审计真相
+- `da-vinci next-step --project <path> [--change <id>] [--json]`
+  - 基于同一套 workflow-state 推导，给出 route-first 的续跑建议
+  - 在自由扫描工件之前，优先把它作为第一路由信号
+- `da-vinci lint-spec --project <path> [--change <id>] [--strict] [--json]`
+  - 校验 Da Vinci 运行时 `spec.md` 的核心章节（`Behavior`、`States`、`Inputs`、`Outputs`、`Acceptance`、`Edge Cases`）
+  - 默认 advisory（有发现给 `WARN` 且不阻断）；显式 `--strict` 才升级为阻断
+  - 不会把 OpenSpec 规划用的 `ADDED Requirements` 结构当成运行时 spec 合法结构
+- `da-vinci scope-check --project <path> [--change <id>] [--strict] [--json]`
+  - 检查 proposal、page-map、运行时 spec、pencil-design 状态和 tasks 之间的 scope 传播一致性
+  - 输出页面与状态两条线的机器可读覆盖矩阵
+  - 默认 advisory（有发现给 `WARN` 且不阻断）；显式 `--strict` 才升级为阻断
+- `da-vinci lint-tasks --project <path> [--change <id>] [--strict] [--json]`
+  - 校验顶层 task groups、编号顺序、verification 动作和 behavior 覆盖提示
+  - 默认 advisory（有发现给 `WARN` 且不阻断）；显式 `--strict` 才升级为阻断
+- `da-vinci lint-bindings --project <path> [--change <id>] [--strict] [--json]`
+  - 校验实现到 Pencil 的映射是否可解析、source 形态是否合理、实现落点是否可定位
+  - 默认 advisory（有发现给 `WARN` 且不阻断）；显式 `--strict` 才升级为阻断
+- `da-vinci generate-sidecars --project <path> [--change <id>] [--json]`
+  - 显式生成确定性的 planning sidecars：`spec.index.json`、`tasks.index.json`、`page-map.index.json`、`bindings.index.json`
+  - sidecar 只允许通过这个命令写入；lint/status/verify 不应静默重写
+- `da-vinci verify-bindings|verify-implementation|verify-structure|verify-coverage --project <path> [--change <id>] [--strict] [--json]`
+  - 校验代码落点、计划状态实现证据、以及绑定驱动的结构一致性
+  - `verify-structure` 会明确报告是 markup-backed 还是 heuristic fallback，并给出置信度
+- `da-vinci diff-spec --project <path> [--change <id>] [--from <sidecars-dir>] [--json]`
+  - 比较规范化 planning sidecars，报告新增/删除/修改的规划项
+  - 在同一 surface 下提供 spec 差异以及 tasks/page-map/bindings 摘要差异
 - `da-vinci icon-sync`
   - 同步官方图标名（Material Symbols、Lucide、Feather、Phosphor）到 `~/.da-vinci/icon-catalog.json`
   - 默认是用户级范围（当前 HOME），同一用户可跨项目复用
@@ -116,6 +146,7 @@ Da Vinci 期望它们遵循工作流状态。
 
 重要规则：
 
+- 有 shell 能力时，先跑 `da-vinci workflow-status --project <path> [--change <id>] --json`，再用 `da-vinci next-step --project <path> [--change <id>]` 作为第一选路信号
 - 如果设计已经有了，但 `tasks.md` 还没有，`continue` 通常应该把你送到 `tasks`
 - 这时候不应该把 `build` 当成同级主推荐
 - 选路必须先基于工件和 checkpoint 真相，再参考 Context Delta

package/docs/zh-CN/execution-chain-migration.md

@@ -0,0 +1,46 @@
+# Execution-Chain 升级迁移指南
+
+当你要在已有项目上启用 execution-chain 升级能力时，使用这份指南。
+
+## 1. Sidecar 生成生命周期
+
+Planning sidecar 是显式工件，不是隐式副产物。
+
+- 用 `da-vinci generate-sidecars --project <path> [--change <id>]` 生成
+- sidecar 写入 `.da-vinci/changes/<change-id>/sidecars/`
+- lint/status/verify 不应静默改写 sidecar
+- proposal/spec/page-map/tasks/bindings 有实质改动后应重新生成
+
+## 2. Advisory 与 Strict 推广策略
+
+默认策略：
+
+- `lint-spec`、`scope-check`、`lint-tasks`、`lint-bindings` 默认 advisory（`WARN` 不硬阻断）
+- 传 `--strict` 才把 warning 升级为阻断退出
+- 只有在 warning 基线稳定后，才在 CI 打开 strict
+
+Audit 集成：
+
+- integrity audit 把 planning-signal 的 `BLOCK` 当 warning 级信号
+- completion audit 把 verification-signal 的 `BLOCK` 当 failure 级信号
+
+## 3. 持久化工作流状态回退
+
+`workflow-status` 只有在以下条件全部满足时才会使用 `.da-vinci/state/workflow.json`：
+
+- schema 版本可识别
+- change 条目存在
+- 时间戳未过期
+- 指纹与当前工件真相一致
+
+任一条件不满足时，会自动回退到基于工件的派生状态，并记录 reconciliation 说明。
+
+## 4. Scaffold 约束
+
+`da-vinci scaffold` 是 MVP 脚手架能力，约束如下：
+
+- 输出只用于 TODO 标记和人工审阅
+- 不是最终代码生成
+- MVP 不做多框架扩展
+- scaffold 边界来自 `pencil-bindings.md` 映射
+- 接受前需跑 `verify-bindings`、`verify-implementation`、`verify-structure`

package/docs/zh-CN/prompt-entrypoints.md

@@ -65,6 +65,12 @@
 
 继续规则优先级：
 
+- 有 shell 能力时，先运行 `da-vinci workflow-status --project <path> [--change <id>] --json`
+- 再用 `da-vinci next-step --project <path> [--change <id>]` 作为第一续跑路由信号
+- 如果运行时 spec 质量还不确定，进入 `build` 前先运行 `da-vinci lint-spec --project <path> [--change <id>]`
+- 如果页面或状态在规划工件中的传播关系不确定，进入 `build` 前先运行 `da-vinci scope-check --project <path> [--change <id>]`
+- 进入终态前先运行 `da-vinci verify-bindings --project <path> [--change <id>]` 与 `da-vinci verify-coverage --project <path> [--change <id>]`
+- 当规划切片有改动且需要恢复判断时，运行 `da-vinci diff-spec --project <path> [--change <id>]`
 - 先根据工件和 checkpoint 真相决定路由
 - Context Delta 只用于恢复和解释，不用于覆盖选路
 - 如果 Context Delta 与当前工件冲突，选路时忽略冲突内容并标记冲突

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

@@ -19,6 +19,16 @@
 - `continue` 选路先看工件/checkpoint 真相，再把 Context Delta 当作辅助恢复信息
 - 如果 Context Delta 与当前工件冲突，选路时应忽略冲突内容并记录冲突
 
+execution-chain 命令组合（终态前建议）：
+
+- `da-vinci workflow-status --project <path> [--change <id>] --json`
+- `da-vinci next-step --project <path> [--change <id>]`
+- `da-vinci lint-spec|lint-tasks|lint-bindings --project <path> [--change <id>]`
+- `da-vinci scope-check --project <path> [--change <id>]`
+- `da-vinci generate-sidecars --project <path> [--change <id>]`
+- `da-vinci verify-bindings|verify-implementation|verify-structure|verify-coverage --project <path> [--change <id>]`
+- `da-vinci diff-spec --project <path> [--change <id>]`
+
 ## 1. `greenfield-spec`
 
 适用：

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 一般会围绕这组工件推进：

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/audit.js

@@ -11,6 +11,7 @@ const { getSessionStatePath, readSessionState } = require("./pencil-session");
 const { isPathInside, listFilesRecursiveSafe } = require("./fs-safety");
 const { pathExists, readTextIfExists } = require("./utils");
 const { runModuleExportInWorker } = require("./async-offload");
+const { readExecutionSignals, summarizeSignalsBySurface } = require("./execution-signals");
 const {
   normalizeCheckpointLabel,
   parseCheckpointStatusMap,
@@ -38,6 +39,13 @@ const EXPORT_SCAN_LIMITS = Object.freeze({
   maxDepth: 4,
   maxEntries: 1200
 });
+const PLANNING_SIGNAL_SURFACES = new Set(["lint-spec", "scope-check", "lint-tasks", "lint-bindings"]);
+const VERIFICATION_SIGNAL_SURFACES = new Set([
+  "verify-bindings",
+  "verify-implementation",
+  "verify-structure",
+  "verify-coverage"
+]);
 
 function listFilesRecursive(rootDir, limits = {}) {
   return listFilesRecursiveSafe(rootDir, {
@@ -253,6 +261,17 @@ function auditProject(projectPathInput, options = {}) {
 
   if (!pathExists(daVinciDir)) {
     failures.push("Missing `.da-vinci/` directory.");
+    addMissingArtifacts(projectRoot, [path.join(projectRoot, "DA-VINCI.md"), designsDir], failures);
+    const missingWorkflowArtifacts = [
+      path.join(daVinciDir, "project-inventory.md"),
+      path.join(daVinciDir, "page-map.md"),
+      designRegistryPath
+    ];
+    if (mode === "completion") {
+      addMissingArtifacts(projectRoot, missingWorkflowArtifacts, failures);
+    } else {
+      addMissingArtifacts(projectRoot, missingWorkflowArtifacts, warnings);
+    }
     notes.push(
       `Hint: scaffold the required workflow files with \`${buildBootstrapCommand(projectRoot, mode, options.changeId || null)}\`.`
     );
@@ -814,6 +833,48 @@ function auditProject(projectPathInput, options = {}) {
     }
   }
 
+  const signalSummary =
+    options && options.preloadedSignalSummary && typeof options.preloadedSignalSummary === "object"
+      ? options.preloadedSignalSummary
+      : summarizeSignalsBySurface(
+          readExecutionSignals(projectRoot, {
+            changeId: options.changeId || ""
+          })
+        );
+  for (const [surface, signal] of Object.entries(signalSummary)) {
+    if (surface === "signal-file-parse") {
+      const warningMessage =
+        Array.isArray(signal.warnings) && signal.warnings[0]
+          ? String(signal.warnings[0])
+          : "Malformed execution signal files were detected.";
+      pushUnique(warnings, warningMessage);
+      continue;
+    }
+
+    if (mode === "integrity" && PLANNING_SIGNAL_SURFACES.has(surface)) {
+      if (signal.status === "BLOCK") {
+        pushUnique(warnings, `Planning signal ${surface} is BLOCK (advisory in integrity mode).`);
+      } else if (signal.status === "WARN") {
+        pushUnique(notes, `Planning signal ${surface} is WARN.`);
+      }
+    }
+
+    if (mode === "completion" && VERIFICATION_SIGNAL_SURFACES.has(surface)) {
+      if (signal.status === "BLOCK") {
+        failures.push(`Verification signal ${surface} is BLOCK.`);
+      } else if (signal.status === "WARN") {
+        pushUnique(warnings, `Verification signal ${surface} is WARN.`);
+      }
+    }
+
+    if (surface === "diff-spec" && signal.status !== "PASS") {
+      pushUnique(warnings, `Planning diff signal ${surface} reports ${signal.status}.`);
+    }
+  }
+  notes.push(
+    "Execution-chain signal integration uses advisory planning semantics in integrity mode and blocking verification semantics in completion mode."
+  );
+
   const status = failures.length > 0 ? "FAIL" : warnings.length > 0 ? "WARN" : "PASS";
 
   return {