跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

comet-verify

Comet Classic 阶段 4 —— 验证 change、记录证据并驱动修复循环。

rpamis · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add rpamis/comet --skill comet-verify

技能说明


name: comet-verify description: "Comet Classic 阶段 4 —— 验证 change、记录证据并驱动修复循环。"

Comet 阶段 4:验证(Verify)

开始或恢复前必须先读取并执行 comet-classic/reference/classic-layout.md;本文件中的 OpenSpec CLI 调用必须使用 adapter,文件路径必须使用该协议绑定的 <classic-*> 逻辑根。

前置条件

  • 代码已提交(阶段 3 完成)
  • tasks.md 全部任务已完成

步骤

0a. 输出语言约束

验证报告必须使用 comet state get <name> language 读取到的 Comet 配置产物语言。

0b. 入口状态验证(Entry Check)

按 comet-classic/reference/scripts.md 使用稳定 comet CLI,然后执行入口验证;从任意入口恢复时先按 comet-classic/reference/context-recovery.md 运行恢复检查:

comet state select <change-name>
comet state check <change-name> verify

验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。

若上述 select / check 输出 BLOCKED,且原因是 bound_branch 与当前分支不一致,立即按 comet-classic/reference/decision-point.md 暂停,让用户单选:切回绑定分支后重新运行入口验证,或在用户明确确认当前分支应接管该 change 后运行 comet state rebind <change-name> 并重新入口验证。不得自行切换分支,不得自行换绑。

幂等性:verify 阶段所有检查可安全重复执行。如 verify_result 已为 pass,说明验证已完成并应进入 archive;branch_status 在归档提交和最终分支处理完成前保持 pending。如 verify_result 为 pending,从头开始验证。

1. 改动规模评估

执行规模评估:

comet state scale <change-name>

脚本自动统计任务数、增量规格数、变更文件数,判断使用 light 或 full 验证模式,并设置 verify_mode 字段。判定规则(满足任一即 full):任务数 > 3、delta spec 能力数 > 1、变更文件数 > 8。

comet state scale 会自行从 plan 的 base-ref 解析提交基线,并在 plan 不可用时回退到状态中的 base_ref;Verify 不再重复读取 plan frontmatter 或手工拼接第二套规模评估。

验证开始前,按 comet-classic/reference/dirty-worktree.md 协议检查并处理未提交改动。verify 阶段的特殊处理:

  1. 若 dirty diff 明确属于当前 change,它就是本次验证输入;继续验证,但不在 verify 阶段修改或提交实现、测试、tasks、delta spec 或 Design Doc
  2. 若 dirty diff 只是 verify 本阶段产物(例如验证报告草稿),可继续在 verify 阶段完成并记录状态
  3. 若 dirty diff 显示实现已存在但 tasks.md 未勾选,视为 build 状态滞后;这是只有一个合法下一步的自动处理,运行 verify-fail 返回 build 核对证据并更新任务状态,不得询问是否接受未完成任务
  4. 若 dirty diff 无法归因或属于其他 change,按 dirty-worktree 协议报告停止条件;不要把归因失败伪装成“继续/忽略”决策

需要回到 build 修复或补齐状态时运行:

comet state transition <change-name> verify-fail

覆盖机制:如 agent 或用户认为自动评估结果不合适,可随时通过 comet state set <change-name> verify_mode <light|full> 手动覆盖。

1b. 验证失败自动修复与例外决策

先运行 comet state get <change-name> verify_failures 读取已持久化的连续失败次数。前 3 次可修复失败自动回到 build:报告失败项后运行 comet state transition <change-name> verify-fail,再调用 /comet-build 修复,不需要用户确认。

报告必须列出:

  • 失败项
  • 是否属于 CRITICAL 或 IMPORTANT(构建失败、测试失败、安全问题、核心验收场景失败、简化代码审查发现的正确性/安全/边界问题)
  • 推荐处理方式

不确定性原则:无法确定严重程度时使用较低级别。仅对构建失败、测试失败、安全问题使用 CRITICAL;明确影响核心验收或正确性的项使用 IMPORTANT;模糊或不确定的问题标为 WARNING 或 SUGGESTION。

按以下方式处理:

  • CRITICAL/IMPORTANT 或范围内可明确修复的问题:未达到上限时自动回到 build 修复;不得创建“是否修复”的伪决策,也不允许接受偏差
  • WARNING/SUGGESTION 且修复会引入行为、范围或风险取舍:按 comet-classic/reference/decision-point.md 让用户选择修复或接受偏差;接受时必须在验证报告中记录原因和影响范围
  • WARNING/SUGGESTION 且修复安全、局部、无取舍:未达到上限时自动修复,不因级别较低而强制停顿

只有接受 WARNING/SUGGESTION 偏差或第 4 次失败后的策略选择才是用户决策点。当前 verify_failures >= 3 时不得自动执行下一次 verify-fail;按协议只提供「继续修复」或「停止当前 workflow 并寻求外部决策」两个选项。用户选择继续后才记录下一次失败并回到 build。CRITICAL/IMPORTANT 始终不可豁免。

2. 产物上下文加载(Hash 按需读)

验证需要读取 OpenSpec 产物时,先检查产物是否自 design 阶段以来发生变化:

comet state get <change-name> handoff_hash
comet handoff <change-name> --hash-only
  • 分别读取两条命令的标准输出;若记录值与当前值相等,且均非空、非 null:OpenSpec 产物未变化,tasks.md 无需重新读取全文(解析复选框确认无未完成项即可)。proposal.md、design.md、delta spec 仍需读取用于对照检查。
  • 若 RECORDED_HASH 为空、为 null、或与 CURRENT_HASH 不一致:产物已变化或 hash 未记录,正常读取所有所需文件全文。

此优化仅跳过 tasks.md 的重复全文读取。proposal.md 和 design.md 包含验证检查项所需的完整上下文,不得因 hash 匹配而跳过。

立即执行: 使用 Skill 工具加载 Superpowers verification-before-completion 技能。禁止跳过此步骤。

Verify 负责整个 change 的唯一最终集成代码审查。Build 只保留任务级或分段审查;在按 verify_mode 分支执行前,先对包含 Build 审查修复在内的最终 diff 执行一次集成审查:

  • review_mode: off:跳过自动代码审查,并在验证报告中记录原因
  • review_mode: standard|thorough:使用 Skill 工具加载 Superpowers requesting-code-review 一次,范围覆盖整个 change,聚焦正确性、安全和边界条件;不重复派发第二次 final reviewer

集成审查发现 CRITICAL/IMPORTANT 问题时按 Step 1b 返回 Build;非 CRITICAL 偏差按 Step 1b 的取舍规则处理。然后按 verify_mode 分支执行:

2a. 轻量验证(小改动)

按以下 6 项进行检查:

  1. tasks.md 全部任务已完成 [x]
  2. 改动文件与 tasks.md 描述一致(git diff --stat / git diff --cached --stat / git diff --stat <base-ref>...HEAD 对照 tasks 内容)
  3. 编译通过(执行项目对应的构建命令,如 npm run build、mvn compile、cargo build 等)
  4. 相关测试通过
  5. 无明显安全问题(无硬编码密钥、无新增 unsafe 操作)
  6. 最终集成代码审查已通过,或 review_mode: off 的跳过原因已记录

若项目没有可自动探测的验证命令,用户或 Agent 必须先自行运行真实验证命令,再单独记录验证证据:

comet state record-check <change-name> verify --command "<实际运行的验证命令>" --exit-code 0

--command 只记录命令文本,Comet 绝不会执行该文本。verify 与 build 证据彼此独立,不能互相替代;即使兼容流程使用 COMET_SKIP_BUILD=1,也不能把该绕过标记视为可审计的验证或构建证据。

集成代码审查的输入限定为本次改动 diff、tasks.md 和必要测试结果;它不替代 spec 覆盖率、Design Doc 一致性或漂移检查。review_mode: off 只跳过自动 code review,不跳过构建、测试、安全检查或异常调试协议。

通过标准:6 项全部 OK,无 CRITICAL 或 IMPORTANT 问题。

不通过时:报告失败项并按 Step 1b 分类。未达到自动修复上限且问题必须或适合修复时,直接执行以下命令回到 build 阶段,然后调用 /comet-build:

comet state transition <change-name> verify-fail

报告格式:简表列出 6 项检查结果 + PASS/FAIL。

跳过项(不在轻量验证中检查):

  • spec scenario 覆盖率
  • design doc 一致性深度比对
  • 不影响正确性、安全、边界条件的 code pattern consistency 建议
  • delta spec 与 design doc 漂移检测

2b. 完整验证(大改动)

当规模评估结果为"大"时:

立即执行: 使用 Skill 工具加载 openspec-verify-change 技能。禁止跳过此步骤。

外部 OpenSpec Skill 覆写: 加载后只采用其验证语义;其中任何直接官方 CLI、固定 cwd 或固定物理 OpenSpec 路径都必须替换为 comet classic openspec -- <args...> 与 resolver 返回的 <classic-*> 逻辑根。

技能加载后,按其指引验证。检查项:

  1. tasks.md 全部任务已完成([x])
  2. 实现符合 <classic-change-dir>/design.md 高层设计决策
  3. 实现符合 Design Doc(docs/superpowers/specs/ 下的技术设计文档)
  4. 能力规格场景全部通过
  5. proposal.md 目标已满足
  6. delta spec 与 design doc 无矛盾(若 Build 阶段有增量修改 spec,检查 design doc 是否有对应记录)
  7. docs/superpowers/specs/ 关联的设计文档可定位(文件存在且与当前 change 相关)

验证不通过时:报告缺失项并按 Step 1b 分类。未达到自动修复上限且缺失项可在当前 change 内补齐时,直接执行以下命令回到 build 阶段,然后调用 /comet-build:

comet state transition <change-name> verify-fail

Spec 漂移处理(用户决策点):

  • 若检查项 6 发现矛盾(delta spec 有内容但 design doc 未体现),必须以单选题形式暂停、展示处理方式并等待用户选择,不得自动选择。选项:
    • 选项 A:在 design doc 追加 "Implementation Divergence" 节记录偏差原因。选项 A 属于 verify 阶段允许产物;写入后不得因该 design doc 变更再次触发 Step 1b dirty-worktree 决策
    • 选项 B:用户选择 B 后,运行 `comet state transit
阅读完整来源 ↗