@xenonbyte/da-vinci-workflow 0.2.4 → 0.2.6

package/docs/zh-CN/skill-usage.md

@@ -2,6 +2,9 @@
 
 这份文档面向真正操作 Da Vinci 的人，而不是底层命令参考。
 
+如果你是在维护 Da Vinci 仓库本身，请先看
+[maintainer-bootstrap.md](./maintainer-bootstrap.md)，而不是这份偏 operator 的流程文档。
+
 重点讲四件事：
 
 - 第一次怎么进入 Da Vinci 工作流
@@ -18,6 +21,7 @@ Da Vinci 应该根据工件真相恢复，而不是根据聊天记忆恢复。
 - `spec.md` 以及相关需求工件是行为真相
 - 项目内 `.pen` 是设计真相
 - `tasks.md`、`verification.md` 和 execution signals 负责说明哪些东西已经实现、哪些还没实现
+- workflow memory 是 `.da-vinci/state/` 下的工件级本地状态，不是跨会话聊天记忆
 
 ## 第一次进入时怎么选入口
 
@@ -79,14 +83,20 @@ $da-vinci use continue for <existing workflow state>
 
 - `da-vinci workflow-status`
   - 先确认当前阶段和 blocker
+  - task-group focus 会综合 checklist 进度和最新 `task-execution` / `task-review` 证据
 - `da-vinci next-step`
   - 再确认下一步到底应该是 `design`、`tasks` 还是 `build`
+  - 当你需要 runtime-aware 的首要聚焦点时，优先看它而不是只看下一条未勾选 checklist
 - `da-vinci lint-spec`
   - 当运行时 spec 质量还不够确定时使用
+  - `--json` 中重点看 `gates.principleInheritance`、`gates.clarify`、`gates.scenarioQuality`
+  - 当 bounded 元数据完整时，把 `gates.clarify.bounded` 视为“可见上下文”；bounded-only clarify 默认不阻断
 - `da-vinci scope-check`
   - 当规划工件之间页面/状态传播关系还不清楚时使用
+  - `--json` 中重点看 `gates.analyze` 的跨工件一致性阻断项
 - `da-vinci lint-tasks`
   - 校验 task groups 是否包含 discipline markers、明确文件落点、执行意图与 verification 命令
+  - `--json` 中重点看 `gates.taskCheckpoint` 的 anchor/checkpoint 就绪度
 - `da-vinci lint-bindings`
   - 当 `pencil-design.md` 与 `pencil-bindings.md` 同时存在时运行，确保实现落点证据可解析
 - `da-vinci worktree-preflight`
@@ -112,6 +122,13 @@ da-vinci lint-tasks
 
 同一 task group 只有在 `spec` review 已是 `PASS` 时，`quality` review 才允许通过。
 
+兼容性说明：
+
+- `workflow-status --json` 仍保留扁平 task-group 字段：`status`、`completion`、`nextAction`、`resumeCursor`
+- `completion` 仍表示 checklist 推导的进度百分比
+- 当 implementer/review 证据更新更晚时，`status`、`nextAction`、`resumeCursor` 可能切换到 runtime-aware 值
+- 当规划 gate 阻断晋级时，`workflow-status --json` 与 `next-step --json` 会输出 `blockingGate`
+
 ## 中途退出后，下次怎么恢复
 
 最稳妥的恢复顺序是：
@@ -124,12 +141,25 @@ da-vinci lint-tasks
 6. 在终态前，跑 `da-vinci verify-bindings` 和 `da-vinci verify-coverage`
 7. 如果要做 completion 表述，确认 `verify-coverage` 的 freshness 仍然有效，并运行 `da-vinci audit --mode completion --change <id> <project-path>`
 
+严格性控制：
+
+- lint 命令严格性：使用 `--strict`
+- workflow 晋级严格性：使用 `DA_VINCI_DISCIPLINE_STRICT_PROMOTION`
+- clarify/analyze/task-checkpoint 不新增独立 strict 开关
+- 在 integrity audit 中，即使 `lint-spec` signal 顶层是 `PASS`，bounded-only clarify 上下文也应保持可见
+
 恢复时应该遵循工件，而不是旧聊天上下文：
 
 - 如果设计工件已经有了，但 `tasks.md` 还没有，下一步应该回到 `tasks`
 - 如果 `tasks.md` 已存在，但设计 gate 还没过，不要直接进 `build`
 - 只有实现就绪度已经明确时，才把 `build` 当主恢复路径
 
+当 task 执行或评审证据与 checklist 进度冲突时：
+
+- 以 `workflow-status` / `next-step` 的路由建议为准
+- 把 task-group 的 `nextAction` 视为有效续跑焦点
+- 把 checklist `completion` 视为进度可见性，不把它当成 blocker/review debt 已清空的证明
+
 ## `change-id` 到底是什么
 
 `change-id` 就是 `.da-vinci/changes/<change-id>/` 这个目录名。

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

@@ -12,11 +12,12 @@
 - 页面到设计的绑定
 - 实现与验证
 
-如果你想看 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)。
-如果你想看更偏操作手册的说明，比如第一次怎么进、暂停后怎么续跑、TUI 怎么用，请看 [skill-usage.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/skill-usage.md)。
+如果你想看 Pencil 渲染、持久化、门禁和审计的专门说明，请看 [pencil-rendering-workflow.md](./pencil-rendering-workflow.md)。
+如果你想看逐个 `dv:` 命令的职责、下一步推荐和 `verify` 回退规则，请看 [dv-command-reference.md](./dv-command-reference.md)。
+如果你想看约束文件总览（哪些字段是硬门禁、哪些是指导项），请看 [constraint-files.md](./constraint-files.md)。
+如果你想看 sidecar、enforcement、persisted-state 回退和 scaffold 约束，请看 [execution-chain-migration.md](./execution-chain-migration.md)。
+如果你想看更偏操作手册的说明，比如第一次怎么进、暂停后怎么续跑、TUI 怎么用，请看 [skill-usage.md](./skill-usage.md)。
+如果你是在维护仓库本身（不是下游项目操作），请从 [maintainer-bootstrap.md](./maintainer-bootstrap.md) 进入。
 
 ## 核心契约
 
@@ -35,6 +36,9 @@ Da Vinci 围绕一个固定契约工作：
 真相与编排边界：
 
 - 选路和 completion 真相来自工件、checkpoint、execution signals 与 `audit`
+- workflow memory 是工件驱动的本地状态，不是聊天派生记忆
+- `.da-vinci/state/workflow.json` 是 persisted route cache，不是 task-group runtime state 的 canonical owner
+- `.da-vinci/state/task-groups/<change>.json` 是 workflow snapshot 写入后的 task-group runtime state canonical owner
 - execution profile、worktree preflight 等编排信息始终是 advisory 指导，不替代真相面
 - 编排提示不能覆盖来自工件、checkpoint 或 completion audit 的明确 `BLOCK`
 
@@ -56,14 +60,23 @@ Da Vinci 围绕一个固定契约工作：
 
 - `da-vinci workflow-status --project <path> [--change <id>] [--json]`
   - 从工件真相和部分 audit 可见证据推导阶段、blocker、handoff gate 与路由建议
+  - 输出 canonical task-group runtime state，并同时保留兼容字段与 planned / implementer / review / effective 分层
 - `da-vinci next-step --project <path> [--change <id>] [--json]`
   - 基于同一 workflow-state 模型，给出优先续跑动作
+  - 与 `workflow-status` 共用同一 task-group runtime-state 模型，不再是 checklist-only 解释
+  - 当 clarify/analyze/task-checkpoint 阻断晋级时，`--json` 会输出 `blockingGate`
 - `da-vinci lint-spec --project <path> [--change <id>] [--strict] [--json]`
   - 在进入实现规划或实现前，校验运行时 `spec.md` 结构质量
+  - `--json` 中输出机器可读 gate：`gates.principleInheritance`、`gates.clarify`、`gates.scenarioQuality`
+  - 当 bounded 元数据完整时，clarify 的 bounded 歧义会保留在 `gates.clarify.bounded` 与 notes 中，默认不作为阻断
   - 默认 advisory；显式 `--strict` 才会把发现升级为阻断
 - `da-vinci scope-check --project <path> [--change <id>] [--strict] [--json]`
   - 校验 proposal、page-map、运行时 spec、pencil-design、tasks 之间页面/状态传播是否一致
+  - `--json` 中输出机器可读 gate：`gates.analyze`
   - 输出页面和状态的机器可读覆盖矩阵，供后续 verify/status 消费
+- `da-vinci lint-tasks --project <path> [--change <id>] [--strict] [--json]`
+  - 校验 task-group 规划纪律以及 task-anchor 到上游规划证据的可追溯性
+  - `--json` 中输出机器可读 gate：`gates.taskCheckpoint`
 - `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]`
@@ -79,6 +92,24 @@ Da Vinci 围绕一个固定契约工作：
 
 这些命令不替代 `da-vinci audit --mode integrity|completion`。
 `audit` 仍是 integrity/completion 的正式真相面。
+- 在 integrity 模式下，即使 `lint-spec` 顶层 signal 是 `PASS`，planning-signal notes 也会保留 bounded clarify 上下文
+
+persisted-state trust 规则：
+
+- 只要 governing artifact 内容 digest 仍匹配，即使 snapshot 很旧，persisted workflow snapshot 仍可用
+- snapshot 年龄仅是 advisory，不再单独导致 persisted route truth 失效
+- execution signals、audits、discipline、verification freshness 等 live overlay 每次读取都会重算
+
+planning-gate 严格性控制面：
+
+- 命令级 lint 严格性使用已有 `--strict`
+- workflow 晋级严格性使用 `DA_VINCI_DISCIPLINE_STRICT_PROMOTION`
+- clarify/analyze/task-checkpoint gate 不引入新的 strict flag 家族
+
+spec-kit 借鉴边界：
+
+- 只借鉴 clarify/analyze/gate 这类方法论，不搬运整套工具链模型。
+- 不采用 spec-kit 的 constitution/init/branch/toolchain 工作流。
 
 ## 标准工件骨架
 
@@ -204,6 +235,8 @@ mapping 通过后：
 - 在大范围实现前，从 `workflow-status` 或 `next-step --json` 查看 `executionProfile`
 - 如果建议 bounded parallel，先跑 `da-vinci worktree-preflight --project <path> [--change <id>]`；隔离未就绪时降级为串行
 - 通过 `task-execution` 与有序 `task-review` 记录每个 task group 的执行与审查证据
+- 当 live evidence 比 checklist 更新时，优先按 task-group `nextAction` / `resumeCursor` 读取 runtime-aware 聚焦点
+- 保持把扁平 `completion` 解释为 checklist 进度百分比，而不是 runtime 健康度
 - 验证需求漂移和设计漂移
 
 ### 8. 终态完成

package/lib/audit.js

@@ -145,6 +145,18 @@ function pushUnique(targetList, message) {
   }
 }
 
+function listClarifyBoundedFindings(signal) {
+  const gates = signal && signal.details && signal.details.gates;
+  if (!gates || typeof gates !== "object") {
+    return [];
+  }
+  const clarify = gates.clarify;
+  if (!clarify || typeof clarify !== "object" || !Array.isArray(clarify.bounded)) {
+    return [];
+  }
+  return clarify.bounded.map((item) => String(item || "").trim()).filter(Boolean);
+}
+
 function appendTraversalWarnings(projectRoot, rootDir, scan, warnings) {
   if (!scan) {
     return;
@@ -834,6 +846,13 @@ function auditProject(projectPathInput, options = {}) {
       } else if (signal.status === "WARN") {
         pushUnique(notes, `Planning signal ${surface} is WARN.`);
       }
+
+      if (surface === "lint-spec") {
+        const boundedClarifyFindings = listClarifyBoundedFindings(signal);
+        for (const finding of boundedClarifyFindings) {
+          pushUnique(notes, `Planning signal lint-spec clarify bounded context: ${finding}`);
+        }
+      }
     }
 
     if (mode === "completion" && VERIFICATION_SIGNAL_SURFACES.has(surface)) {

package/lib/cli/helpers.js

@@ -0,0 +1,104 @@
+const { writeExecutionSignal } = require("../execution-signals");
+const { STATUS } = require("../workflow-contract");
+
+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 persistExecutionSignal(projectPath, changeId, surface, result, strict = false) {
+  const normalizeStatus = (status) => {
+    const normalized = String(status || "").trim().toUpperCase();
+    if (normalized === STATUS.BLOCK || normalized === STATUS.WARN || normalized === STATUS.PASS) {
+      return normalized;
+    }
+    return "";
+  };
+  const statusRank = (status) => {
+    if (status === STATUS.BLOCK) {
+      return 2;
+    }
+    if (status === STATUS.WARN) {
+      return 1;
+    }
+    if (status === STATUS.PASS) {
+      return 0;
+    }
+    return -1;
+  };
+  const worseStatus = (left, right) => {
+    const l = normalizeStatus(left);
+    const r = normalizeStatus(right);
+    if (!l && !r) {
+      return STATUS.PASS;
+    }
+    if (!l) {
+      return r;
+    }
+    if (!r) {
+      return l;
+    }
+    return statusRank(l) >= statusRank(r) ? l : r;
+  };
+  const deriveGateStatus = (gates) => {
+    if (!gates || typeof gates !== "object") {
+      return STATUS.PASS;
+    }
+    let worst = STATUS.PASS;
+    for (const gate of Object.values(gates)) {
+      worst = worseStatus(worst, gate && gate.status);
+      if (worst === STATUS.BLOCK) {
+        break;
+      }
+    }
+    return worst;
+  };
+
+  const details = {};
+  if (result && result.gates && typeof result.gates === "object") {
+    details.gates = result.gates;
+  }
+  if (result && result.summary && typeof result.summary === "object") {
+    details.summary = result.summary;
+  }
+  const persistedStatus = worseStatus(
+    result && result.status ? result.status : STATUS.PASS,
+    deriveGateStatus(details.gates)
+  );
+
+  try {
+    writeExecutionSignal(projectPath, {
+      changeId: changeId || "global",
+      surface,
+      status: persistedStatus,
+      advisory: strict ? false : true,
+      strict,
+      failures: result.failures || [],
+      warnings: result.warnings || [],
+      notes: result.notes || [],
+      details: Object.keys(details).length > 0 ? details : null
+    });
+  } 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}`
+    );
+  }
+}
+
+module.exports = {
+  emitOrThrowOnStatus,
+  persistExecutionSignal
+};

package/lib/cli/lint-family.js

@@ -0,0 +1,56 @@
+function handleLintFamilyCommand(command, context) {
+  const lintCommands = new Set(["lint-spec", "scope-check", "lint-tasks", "lint-bindings"]);
+  if (!lintCommands.has(command)) {
+    return false;
+  }
+
+  const {
+    argv,
+    positionalArgs,
+    continueOnError,
+    getOption,
+    lintRuntimeSpecs,
+    formatLintSpecReport,
+    runScopeCheck,
+    formatScopeCheckReport,
+    lintTasks,
+    formatLintTasksReport,
+    lintBindings,
+    formatLintBindingsReport,
+    emitOrThrowOnStatus,
+    persistExecutionSignal
+  } = context;
+
+  const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+  const changeId = getOption(argv, "--change");
+  const strict = argv.includes("--strict");
+  const useJson = argv.includes("--json");
+
+  let result;
+  let output = "";
+  let surface = command;
+  if (command === "lint-spec") {
+    result = lintRuntimeSpecs(projectPath, { changeId, strict });
+    output = useJson ? JSON.stringify(result, null, 2) : formatLintSpecReport(result);
+  } else if (command === "scope-check") {
+    result = runScopeCheck(projectPath, { changeId, strict });
+    output = useJson ? JSON.stringify(result, null, 2) : formatScopeCheckReport(result);
+  } else if (command === "lint-tasks") {
+    result = lintTasks(projectPath, { changeId, strict });
+    output = useJson ? JSON.stringify(result, null, 2) : formatLintTasksReport(result);
+  } else {
+    result = lintBindings(projectPath, { changeId, strict });
+    output = useJson ? JSON.stringify(result, null, 2) : formatLintBindingsReport(result);
+  }
+
+  persistExecutionSignal(projectPath, result.changeId || changeId, surface, result, strict);
+  if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+    return true;
+  }
+  console.log(output);
+  return true;
+}
+
+module.exports = {
+  handleLintFamilyCommand
+};

package/lib/cli/verify-family.js

@@ -0,0 +1,79 @@
+function handleVerifyFamilyCommand(command, context) {
+  const verifyCommands = new Set([
+    "verify-bindings",
+    "verify-implementation",
+    "verify-structure",
+    "verify-coverage"
+  ]);
+  if (!verifyCommands.has(command)) {
+    return false;
+  }
+
+  const {
+    argv,
+    positionalArgs,
+    continueOnError,
+    getOption,
+    getCommaSeparatedOptionValues,
+    collectOptionEntries,
+    verifyBindings,
+    verifyImplementation,
+    verifyStructure,
+    verifyCoverage,
+    formatVerifyReport,
+    emitOrThrowOnStatus,
+    persistExecutionSignal
+  } = context;
+
+  const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+  const changeId = getOption(argv, "--change");
+  const strict = argv.includes("--strict");
+  const useJson = argv.includes("--json");
+  const changedFilesProvided = collectOptionEntries(argv, "--changed-files").length > 0;
+  const changedFiles = changedFilesProvided
+    ? getCommaSeparatedOptionValues(argv, "--changed-files")
+    : undefined;
+
+  let result;
+  let title = "Da Vinci verify";
+  if (command === "verify-bindings") {
+    result = verifyBindings(projectPath, { changeId, strict });
+    title = "Da Vinci verify-bindings";
+  } else if (command === "verify-implementation") {
+    result = verifyImplementation(projectPath, {
+      changeId,
+      strict,
+      changedFiles,
+      changedFilesProvided
+    });
+    title = "Da Vinci verify-implementation";
+  } else if (command === "verify-structure") {
+    result = verifyStructure(projectPath, {
+      changeId,
+      strict,
+      changedFiles,
+      changedFilesProvided
+    });
+    title = "Da Vinci verify-structure";
+  } else {
+    result = verifyCoverage(projectPath, {
+      changeId,
+      strict,
+      changedFiles,
+      changedFilesProvided
+    });
+    title = "Da Vinci verify-coverage";
+  }
+
+  persistExecutionSignal(projectPath, result.changeId || changeId, command, result, strict);
+  const output = useJson ? JSON.stringify(result, null, 2) : formatVerifyReport(result, title);
+  if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+    return true;
+  }
+  console.log(output);
+  return true;
+}
+
+module.exports = {
+  handleVerifyFamilyCommand
+};