@xenonbyte/da-vinci-workflow 0.2.5 → 0.2.7

package/docs/zh-CN/maintainer-bootstrap.md

@@ -0,0 +1,101 @@
+# Maintainer Bootstrap 指南
+
+这份文档是“维护 Da Vinci 仓库本身”的 canonical 入口。
+
+## 先划边界
+
+- 仓库维护者 bootstrap：准备修改这个仓库。
+- 下游项目 bootstrap：`da-vinci bootstrap-project` 用于给其他项目初始化 `.da-vinci/` 工件。
+- 安装状态：`da-vinci status` / `da-vinci verify-install` 只校验安装置信度，不等于仓库就绪度。
+- operator 工作流执行：下游项目操作请看 operator 文档，不要把它当维护者 bootstrap 入口。
+
+## Clone 后前 10 分钟
+
+1. 安装依赖：`npm install`
+2. 校验打包资产：`npm run validate-assets`
+3. 显式校验安装范围（推荐）：`da-vinci verify-install --platform codex`
+4. 运行维护者 canonical 就绪检查：`da-vinci maintainer-readiness --platform codex`
+
+如果你维护多个环境，请显式传入多个平台：
+
+- `da-vinci verify-install --platform codex,claude`
+- `da-vinci maintainer-readiness --platform codex,claude`
+
+这些命令应在你要维护的仓库根目录执行。需要时可用 `--project <path>` 显式指定目标仓库。
+
+## 入口面分层
+
+- Canonical 入口：
+  - 本文档 + `da-vinci maintainer-readiness`
+- Secondary/advanced 维护者面：
+  - `npm run quality:ci:contracts`
+  - `npm run quality:ci:e2e`
+  - `npm run quality:ci`
+  - 针对回归的 `scripts/test-*.js`
+- 下游项目面（非仓库维护 bootstrap）：
+  - `da-vinci bootstrap-project`
+  - 项目 `.da-vinci/` 工件工作流
+- bootstrap 相邻的安装面：
+  - `da-vinci status`
+  - `da-vinci verify-install`
+
+## Bootstrap 与 Diagnosis
+
+- Bootstrap/setup 回答的是：“我如何准备好在这里工作？”
+- Diagnosis/readiness 回答的是：“当前仓库 + 本地环境是否足够健康以推进本次改动？”
+
+Canonical diagnosis 面：
+
+- `da-vinci maintainer-readiness`
+
+该命令刻意比 full CI 更窄，并提供可执行的下一步。默认包含：
+
+- 打包资产校验
+- selected-platform 的 verify-install 置信度
+- 聚焦质量 lane：`npm run quality:ci:contracts`
+
+## Selected Platform 语义
+
+- 显式 `--platform`：只有选中的平台是阻断项。
+- 未选平台仍可见，但会标为 `out_of_scope` / degraded coverage。
+- 未传 `--platform`：按 unknown scope 报告 degraded coverage，不会硬失败。
+
+## Use This / Do Not Use This
+
+- Use this：
+  - `da-vinci verify-install --platform codex`，然后 `da-vinci maintainer-readiness --platform codex`
+- Do not use this：
+  - 只跑 `da-vinci status` 就判断仓库就绪
+- Use this：
+  - 用本指南做仓库维护者入门
+- Do not use this：
+  - 把 `da-vinci bootstrap-project` 当成这个仓库的维护者 bootstrap
+- Use this：
+  - 只有在下游项目操作时才看 operator 文档
+- Do not use this：
+  - 把 operator 工作流文档当成维护者首入口
+
+## 常见排错
+
+- 现象：`verify-install` 是 WARN 且 scope unknown。
+  - 处理：补 `--platform <value>` 显式声明 selected scope。
+- 现象：`maintainer-readiness` 在 verify-install 上 BLOCK。
+  - 处理：先修 selected-platform 安装问题，再重跑 readiness。
+- 现象：安装检查都通过，但对改动仍缺乏信心。
+  - 处理：升级跑更深的 lanes（`quality:ci:e2e` 或 `quality:ci`）和目标脚本。
+- 现象：混淆仓库 bootstrap 与下游项目 bootstrap。
+  - 处理：仓库维护按本指南，下游仓库才使用 `bootstrap-project`。
+
+## 更深层验证 Lane
+
+高风险或范围较大的改动前建议执行：
+
+- `npm run quality:ci:e2e`
+- `npm run quality:ci`
+
+## Operator 工作流参考
+
+operator 文档与维护者 bootstrap 保持分离：
+
+- [skill-usage.md](./skill-usage.md)
+- [workflow-overview.md](./workflow-overview.md)

package/docs/zh-CN/pencil-rendering-workflow.md

@@ -12,7 +12,7 @@
 - screenshot review
 - runtime gate 和 filesystem audit
 
-如果你想看 `design`、`tasks`、`build`、`verify` 这些 `dv:` 路由之间怎么衔接，以及 `verify` 出问题后退回哪一层，请看 [dv-command-reference.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/dv-command-reference.md)。
+如果你想看 `design`、`tasks`、`build`、`verify` 这些 `dv:` 路由之间怎么衔接，以及 `verify` 出问题后退回哪一层，请看 [dv-command-reference.md](./dv-command-reference.md)。
 
 ## 渲染真相模型
 

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

@@ -1,4 +1,5 @@
 const { writeExecutionSignal } = require("../execution-signals");
+const { STATUS } = require("../workflow-contract");
 
 function emitOrThrowOnStatus(status, blockedStatuses, output, continueOnError) {
   if (!Array.isArray(blockedStatuses) || !blockedStatuses.includes(status)) {
@@ -12,16 +13,76 @@ function emitOrThrowOnStatus(status, blockedStatuses, output, continueOnError) {
 }
 
 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: result.status,
+      status: persistedStatus,
       advisory: strict ? false : true,
       strict,
       failures: result.failures || [],
       warnings: result.warnings || [],
-      notes: result.notes || []
+      notes: result.notes || [],
+      details: Object.keys(details).length > 0 ? details : null
     });
   } catch (error) {
     // Signals are advisory metadata and should not break command execution.

package/lib/cli.js

@@ -4,6 +4,7 @@ const {
   installPlatforms,
   uninstallPlatforms,
   getStatus,
+  verifyInstall,
   validateAssets
 } = require("./install");
 const { auditProject, formatAuditReport } = require("./audit");
@@ -94,6 +95,10 @@ const {
   formatWorktreePreflightReport
 } = require("./worktree-preflight");
 const { formatTuiHelp, launchTui } = require("../tui");
+const {
+  runMaintainerReadinessCheck,
+  formatMaintainerReadinessReport
+} = require("./maintainer-readiness");
 
 const DEFAULT_MAX_PREFLIGHT_STDIN_BYTES = 1024 * 1024;
 const DEFAULT_MAX_STDIN_TRANSIENT_RETRIES = 2000;
@@ -120,8 +125,10 @@ const OPTION_FLAGS_WITH_VALUES = new Set([
   "--task-group",
   "--changed-files",
   "--test-evidence",
+  "--pending-test-evidence",
   "--concerns",
   "--blockers",
+  "--out-of-scope-writes",
   "--issues",
   "--reviewer",
   "--source",
@@ -194,8 +201,21 @@ const HELP_OPTION_SPECS = [
     description: "comma-separated changed files for verify-implementation/verify-structure/verify-coverage/task-execution"
   },
   { flag: "--test-evidence <csv>", description: "comma-separated test evidence commands for task-execution" },
+  {
+    flag: "--pending-test-evidence <csv>",
+    description: "comma-separated planned-but-not-executed test commands for task-execution"
+  },
+  {
+    flag: "--confirm-test-evidence-executed",
+    description: "required when providing --test-evidence; confirms listed commands actually ran"
+  },
   { flag: "--concerns <csv>", description: "comma-separated concern text for task-execution" },
   { flag: "--blockers <csv>", description: "comma-separated blocker text for task-execution" },
+  {
+    flag: "--out-of-scope-writes <csv>",
+    description: "comma-separated out-of-scope write paths for task-execution safety visibility"
+  },
+  { flag: "--partial", description: "mark task-execution payload as non-final progress evidence" },
   { flag: "--issues <csv>", description: "comma-separated issue text for task-review" },
   { flag: "--reviewer <name>", description: "reviewer identifier for task-review" },
   { flag: "--write-verification", description: "append task-review evidence into verification.md" },
@@ -459,6 +479,60 @@ function formatStatus(status) {
   return lines.join("\n");
 }
 
+function formatVerifyInstallReport(result) {
+  const scopeLabel = result.scope && result.scope.known
+    ? result.scope.selectedPlatforms.join(", ")
+    : "unknown";
+  const lines = [
+    "Da Vinci verify-install",
+    `Status: ${result.status}`,
+    `Home: ${result.homeDir}`,
+    "Surface: install verification (bootstrap-adjacent), not full repository readiness",
+    `Selected platform scope: ${scopeLabel}`,
+    "Platform coverage:"
+  ];
+
+  for (const platform of result.scope.supportedPlatforms || []) {
+    const coverage = result.platformCoverage && result.platformCoverage[platform];
+    if (!coverage) {
+      continue;
+    }
+    const checkSummary = Object.entries(coverage.checks || {})
+      .map(([name, ok]) => `${name}=${ok ? "yes" : "no"}`)
+      .join(" ");
+    lines.push(
+      `- ${platform}: scope=${coverage.scope} healthy=${coverage.healthy ? "yes" : "no"}${checkSummary ? ` ${checkSummary}` : ""}`
+    );
+  }
+
+  if (Array.isArray(result.failures) && result.failures.length > 0) {
+    lines.push("Failures:");
+    for (const message of result.failures) {
+      lines.push(`- ${message}`);
+    }
+  }
+  if (Array.isArray(result.warnings) && result.warnings.length > 0) {
+    lines.push("Warnings:");
+    for (const message of result.warnings) {
+      lines.push(`- ${message}`);
+    }
+  }
+  if (Array.isArray(result.notes) && result.notes.length > 0) {
+    lines.push("Notes:");
+    for (const message of result.notes) {
+      lines.push(`- ${message}`);
+    }
+  }
+  if (Array.isArray(result.nextSteps) && result.nextSteps.length > 0) {
+    lines.push("Next steps:");
+    for (const step of result.nextSteps) {
+      lines.push(`- ${step}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
 function appendStatusIssues(lines, label, missing = [], mismatched = [], unreadable = []) {
   if (missing.length > 0) {
     lines.push(`  ${label} missing: ${missing.join(", ")}`);
@@ -485,6 +559,10 @@ function printHelp() {
       "  da-vinci install --platform codex,claude,gemini",
       "  da-vinci uninstall --platform codex,claude,gemini",
       "  da-vinci status",
+      "  da-vinci verify-install [--platform <value>] [--json]",
+      "    (bootstrap-adjacent install verification for selected maintainer platforms)",
+      "  da-vinci maintainer-readiness [--platform <value>] [--project <path>] [--json]",
+      "    (canonical repository maintainer diagnosis/readiness; not downstream bootstrap)",
       "  da-vinci tui [--project <path>] [--change <id>] [--lang en|zh] [--strict] [--json] [--continue-on-error] [--tui-width <cols>] [--alt-screen|--no-alt-screen]",
       "  da-vinci workflow-status [--project <path>] [--change <id>] [--json]",
       "  da-vinci next-step [--project <path>] [--change <id>] [--json]",
@@ -497,7 +575,7 @@ function printHelp() {
       "  da-vinci verify-implementation [--project <path>] [--change <id>] [--changed-files <csv>] [--strict] [--json]",
       "  da-vinci verify-structure [--project <path>] [--change <id>] [--changed-files <csv>] [--strict] [--json]",
       "  da-vinci verify-coverage [--project <path>] [--change <id>] [--changed-files <csv>] [--strict] [--json]",
-      "  da-vinci task-execution --project <path> --change <id> --task-group <id> --status <DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED> --summary <text> [--changed-files <csv>] [--test-evidence <csv>] [--concerns <csv>] [--blockers <csv>] [--json]",
+      "  da-vinci task-execution --project <path> --change <id> --task-group <id> --status <DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED> --summary <text> [--changed-files <csv>] [--test-evidence <csv> --confirm-test-evidence-executed] [--pending-test-evidence <csv>] [--concerns <csv>] [--blockers <csv>] [--out-of-scope-writes <csv>] [--partial] [--json]",
       "  da-vinci task-review --project <path> --change <id> --task-group <id> --stage <spec|quality> --status <PASS|WARN|BLOCK> --summary <text> [--issues <csv>] [--reviewer <name>] [--write-verification] [--json]",
       "  da-vinci worktree-preflight --project <path> [--change <id>] [--json]",
       "  da-vinci diff-spec [--project <path>] [--change <id>] [--from <sidecars-dir>] [--json]",
@@ -955,6 +1033,40 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "verify-install") {
+    const platformValue = getOption(argv, "--platform") || "";
+    const result = verifyInstall({
+      homeDir,
+      platforms: platformValue
+    });
+    const output = argv.includes("--json")
+      ? JSON.stringify(result, null, 2)
+      : formatVerifyInstallReport(result);
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+    console.log(output);
+    return;
+  }
+
+  if (command === "maintainer-readiness") {
+    const platformValue = getOption(argv, "--platform") || "";
+    const repoRoot = getOption(argv, "--project") || process.cwd();
+    const result = runMaintainerReadinessCheck({
+      repoRoot,
+      homeDir,
+      platforms: platformValue
+    });
+    const output = argv.includes("--json")
+      ? JSON.stringify(result, null, 2)
+      : formatMaintainerReadinessReport(result);
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+    console.log(output);
+    return;
+  }
+
   if (command === "tui") {
     const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
     const changeId = getOption(argv, "--change");
@@ -1008,6 +1120,7 @@ async function runCli(argv) {
             stage: result.stage,
             checkpointState: result.checkpointState,
             nextStep: result.nextStep || null,
+            blockingGate: result.blockingGate || null,
             discipline: result.discipline || null,
             executionProfile: result.executionProfile || null,
             worktreePreflight: result.worktreePreflight || null,
@@ -1091,8 +1204,12 @@ async function runCli(argv) {
       summary: getOption(argv, "--summary"),
       changedFiles: getCommaSeparatedOptionValues(argv, "--changed-files"),
       testEvidence: getCommaSeparatedOptionValues(argv, "--test-evidence"),
+      pendingTestEvidence: getCommaSeparatedOptionValues(argv, "--pending-test-evidence"),
+      confirmTestEvidenceExecuted: argv.includes("--confirm-test-evidence-executed"),
       concerns: getCommaSeparatedOptionValues(argv, "--concerns"),
-      blockers: getCommaSeparatedOptionValues(argv, "--blockers")
+      blockers: getCommaSeparatedOptionValues(argv, "--blockers"),
+      outOfScopeWrites: getCommaSeparatedOptionValues(argv, "--out-of-scope-writes"),
+      partial: argv.includes("--partial")
     });
     const useJson = argv.includes("--json");
     const output = useJson ? JSON.stringify(result, null, 2) : formatTaskExecutionReport(result);

package/lib/gate-utils.js

@@ -0,0 +1,56 @@
+const { STATUS } = require("./workflow-contract");
+const { unique } = require("./planning-parsers");
+
+function dedupe(values) {
+  return unique(values);
+}
+
+function buildGateEnvelope(id, options = {}) {
+  const gate = {
+    id,
+    status: STATUS.PASS,
+    blocking: [],
+    advisory: [],
+    compatibility: [],
+    evidence: []
+  };
+  if (options.includeBounded) {
+    gate.bounded = [];
+  }
+  return gate;
+}
+
+function finalizeGateEnvelope(gate, options = {}) {
+  const strict = options.strict === true;
+  const includeBounded = options.includeBounded === true;
+  const warnOnBounded = options.warnOnBounded === true;
+  const warnOnCompatibility = options.warnOnCompatibility !== false;
+  const normalized = {
+    ...gate,
+    blocking: dedupe(gate && gate.blocking),
+    advisory: dedupe(gate && gate.advisory),
+    compatibility: dedupe(gate && gate.compatibility),
+    evidence: dedupe(gate && gate.evidence)
+  };
+  if (includeBounded || Array.isArray(gate && gate.bounded)) {
+    normalized.bounded = dedupe(gate && gate.bounded);
+  }
+
+  if (normalized.blocking.length > 0) {
+    normalized.status = strict ? STATUS.BLOCK : STATUS.WARN;
+    return normalized;
+  }
+
+  const hasWarnLevelFindings =
+    normalized.advisory.length > 0 ||
+    (warnOnCompatibility && normalized.compatibility.length > 0) ||
+    (warnOnBounded && Array.isArray(normalized.bounded) && normalized.bounded.length > 0);
+  normalized.status = hasWarnLevelFindings ? STATUS.WARN : STATUS.PASS;
+  return normalized;
+}
+
+module.exports = {
+  dedupe,
+  buildGateEnvelope,
+  finalizeGateEnvelope
+};