@xenonbyte/da-vinci-workflow 0.2.5 → 0.2.6

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;
@@ -459,6 +464,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 +544,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]",
@@ -955,6 +1018,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 +1105,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,

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
+};

package/lib/install.js

@@ -18,6 +18,7 @@ const REQUIRED_FILES = [
   ...listFiles(path.join(REPO_ROOT, "docs")).map((filePath) => path.relative(REPO_ROOT, filePath)),
   ...listFiles(path.join(REPO_ROOT, "examples")).map((filePath) => path.relative(REPO_ROOT, filePath))
 ];
+const SUPPORTED_PLATFORMS = ["codex", "claude", "gemini"];
 
 const CODEX_PROMPT_TARGET_PAIRS = listFiles(path.join(REPO_ROOT, "commands", "codex", "prompts")).map(
   (filePath) => ({
@@ -90,7 +91,7 @@ function resolveHome(homeDir) {
 
 function parsePlatforms(raw) {
   if (!raw || raw === "all") {
-    return ["codex", "claude", "gemini"];
+    return SUPPORTED_PLATFORMS.slice();
   }
 
   const platforms = raw
@@ -99,7 +100,7 @@ function parsePlatforms(raw) {
     .filter(Boolean);
 
   const unique = [...new Set(platforms)];
-  const invalid = unique.filter((value) => !["codex", "claude", "gemini"].includes(value));
+  const invalid = unique.filter((value) => !SUPPORTED_PLATFORMS.includes(value));
 
   if (invalid.length > 0) {
     throw new Error(`Unsupported platform value: ${invalid.join(", ")}`);
@@ -108,6 +109,129 @@ function parsePlatforms(raw) {
   return unique;
 }
 
+function summarizePlatformInstallConfidence(statusPayload) {
+  const status = statusPayload && typeof statusPayload === "object" ? statusPayload : {};
+  const codex = status.codex && typeof status.codex === "object" ? status.codex : {};
+  const claude = status.claude && typeof status.claude === "object" ? status.claude : {};
+  const gemini = status.gemini && typeof status.gemini === "object" ? status.gemini : {};
+
+  return {
+    codex: {
+      checks: {
+        prompt: codex.prompt === true,
+        skill: codex.skill === true
+      },
+      missing: [...(codex.promptMissing || []), ...(codex.skillMissing || [])],
+      mismatched: [...(codex.promptMismatched || []), ...(codex.skillMismatched || [])],
+      unreadable: [...(codex.promptUnreadable || []), ...(codex.skillUnreadable || [])]
+    },
+    claude: {
+      checks: {
+        command: claude.command === true,
+        actionSet: claude.actionSet === true
+      },
+      missing: [...(claude.commandMissing || []), ...(claude.actionSetMissing || [])],
+      mismatched: [...(claude.commandMismatched || []), ...(claude.actionSetMismatched || [])],
+      unreadable: [...(claude.commandUnreadable || []), ...(claude.actionSetUnreadable || [])]
+    },
+    gemini: {
+      checks: {
+        command: gemini.command === true,
+        actionSet: gemini.actionSet === true
+      },
+      missing: [...(gemini.commandMissing || []), ...(gemini.actionSetMissing || [])],
+      mismatched: [...(gemini.commandMismatched || []), ...(gemini.actionSetMismatched || [])],
+      unreadable: [...(gemini.commandUnreadable || []), ...(gemini.actionSetUnreadable || [])]
+    }
+  };
+}
+
+function verifyInstall(options = {}) {
+  const homeDir = resolveHome(options.homeDir);
+  const explicitScopeRaw = String(options.platforms || "").trim();
+  const scopeKnown = explicitScopeRaw.length > 0;
+  const selectedPlatforms = scopeKnown ? parsePlatforms(explicitScopeRaw) : [];
+  const status = getStatus({ homeDir });
+  const confidence = summarizePlatformInstallConfidence(status);
+  const platformCoverage = {};
+  const failures = [];
+  const warnings = [];
+  const notes = [];
+
+  for (const platform of SUPPORTED_PLATFORMS) {
+    const selected = selectedPlatforms.includes(platform);
+    const scope = scopeKnown ? (selected ? "selected" : "out_of_scope") : "unknown";
+    const platformConfidence = confidence[platform];
+    const failedChecks = Object.keys(platformConfidence.checks).filter(
+      (checkKey) => platformConfidence.checks[checkKey] !== true
+    );
+    const healthy = failedChecks.length === 0;
+    platformCoverage[platform] = {
+      scope,
+      healthy,
+      checks: platformConfidence.checks,
+      missing: platformConfidence.missing,
+      mismatched: platformConfidence.mismatched,
+      unreadable: platformConfidence.unreadable
+    };
+
+    if (scope === "selected" && !healthy) {
+      failures.push(
+        `${platform} install verification failed for selected scope (${failedChecks.join(
+          ", "
+        )}). Run \`da-vinci install --platform ${platform}\` and re-run verify-install.`
+      );
+    }
+    if (scope === "unknown" && !healthy) {
+      warnings.push(
+        `${platform} install verification is incomplete, but selected platform scope is unknown.`
+      );
+    }
+    if (scope === "out_of_scope" && !healthy) {
+      notes.push(
+        `${platform} is out-of-scope for this verify-install run and is reported as degraded coverage.`
+      );
+    }
+  }
+
+  if (!scopeKnown) {
+    warnings.push(
+      "Selected platform scope is unknown; pass `--platform <value>` so verify-install can evaluate selected targets explicitly."
+    );
+  }
+
+  const statusToken = failures.length > 0 ? "BLOCK" : warnings.length > 0 ? "WARN" : "PASS";
+  const nextSteps = [];
+  if (failures.length > 0) {
+    nextSteps.push("Fix selected-platform install failures, then rerun `da-vinci verify-install`.");
+  }
+  if (!scopeKnown) {
+    nextSteps.push(
+      "Rerun with explicit scope, for example `da-vinci verify-install --platform codex`, to avoid unknown-scope coverage."
+    );
+  }
+  if (statusToken === "PASS") {
+    nextSteps.push(
+      "Continue with repository readiness checks (for example `da-vinci maintainer-readiness`)."
+    );
+  }
+
+  return {
+    status: statusToken,
+    homeDir,
+    scope: {
+      known: scopeKnown,
+      selectedPlatforms,
+      supportedPlatforms: SUPPORTED_PLATFORMS.slice()
+    },
+    platformCoverage,
+    failures: failures,
+    warnings: warnings,
+    notes: notes,
+    nextSteps
+  };
+}
+
 function ensureDir(targetPath) {
   fs.mkdirSync(targetPath, { recursive: true });
 }
@@ -407,25 +531,29 @@ function getStatus(options = {}) {
   };
 }
 
-function validateAssets() {
+function validateAssets(options = {}) {
+  const repoRoot = options.repoRoot ? path.resolve(String(options.repoRoot)) : REPO_ROOT;
   const missing = REQUIRED_FILES.filter((relativePath) => {
-    return !fs.existsSync(path.join(REPO_ROOT, relativePath));
+    return !fs.existsSync(path.join(repoRoot, relativePath));
   });
 
   if (missing.length > 0) {
-    throw new Error(`Missing required assets:\n${missing.join("\n")}`);
+    throw new Error(`Missing required assets under ${repoRoot}:\n${missing.join("\n")}`);
   }
 
   return {
     version: VERSION,
-    requiredAssets: REQUIRED_FILES.length
+    requiredAssets: REQUIRED_FILES.length,
+    repoRoot
   };
 }
 
 module.exports = {
   VERSION,
+  SUPPORTED_PLATFORMS,
   installPlatforms,
   uninstallPlatforms,
   getStatus,
+  verifyInstall,
   validateAssets
 };