comet-dsh-plugin 0.0.0-stage → 0.5.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.en.md +176 -0
- package/README.md +152 -2
- package/client.js +349 -0
- package/cordis.patch.yml +4 -0
- package/icon.png +0 -0
- package/index.js +183 -0
- package/locale/en.json +7 -0
- package/locale/zh.json +7 -0
- package/package.json +57 -4
- package/rules/comet-workflow-guard.md +63 -0
- package/rules/migration-assets.json +218 -0
- package/server/comet-plugin-setup.mjs +192 -0
- package/skills/comet/SKILL.md +37 -0
- package/skills/comet/agents/openai.yaml +3 -0
- package/skills/comet/reference/change-walkthrough.md +77 -0
- package/skills/comet/reference/edit-review.md +26 -0
- package/skills/comet/reference/host-check.md +11 -0
- package/skills/comet/reference/platform-execution.md +34 -0
- package/skills/comet/reference/task-learning.md +39 -0
- package/skills/comet/runtime/classic/checks.yaml +6 -0
- package/skills/comet/runtime/classic/guardrails.yaml +13 -0
- package/skills/comet/runtime/classic/skill.yaml +122 -0
- package/skills/comet/scripts/comet-archive.mjs +310 -0
- package/skills/comet/scripts/comet-check.mjs +179 -0
- package/skills/comet/scripts/comet-entry-runtime.mjs +151 -0
- package/skills/comet/scripts/comet-env.mjs +15 -0
- package/skills/comet/scripts/comet-guard.mjs +335 -0
- package/skills/comet/scripts/comet-handoff.mjs +289 -0
- package/skills/comet/scripts/comet-hook-guard.mjs +294 -0
- package/skills/comet/scripts/comet-hook-router-guard.mjs +628 -0
- package/skills/comet/scripts/comet-hook-router.mjs +17 -0
- package/skills/comet/scripts/comet-intent.mjs +181 -0
- package/skills/comet/scripts/comet-plugin-hook.mjs +213 -0
- package/skills/comet/scripts/comet-resume-probe.mjs +205 -0
- package/skills/comet/scripts/comet-runtime.mjs +571 -0
- package/skills/comet/scripts/comet-state.mjs +381 -0
- package/skills/comet/scripts/comet-yaml-validate.mjs +182 -0
- package/skills/comet-any/SKILL.md +47 -0
- package/skills/comet-any/agents/openai.yaml +5 -0
- package/skills/comet-any/reference/sdk-creation.md +100 -0
- package/skills/comet-archive/SKILL.md +28 -0
- package/skills/comet-archive/agents/openai.yaml +5 -0
- package/skills/comet-archive/reference/compat.md +188 -0
- package/skills/comet-build/SKILL.md +35 -0
- package/skills/comet-build/agents/openai.yaml +5 -0
- package/skills/comet-build/reference/compat.md +191 -0
- package/skills/comet-classic/SKILL.md +98 -0
- package/skills/comet-classic/agents/openai.yaml +3 -0
- package/skills/comet-classic/reference/auto-transition.md +34 -0
- package/skills/comet-classic/reference/classic-layout.md +36 -0
- package/skills/comet-classic/reference/comet-yaml-fields.md +82 -0
- package/skills/comet-classic/reference/context-recovery.md +128 -0
- package/skills/comet-classic/reference/debug-gate.md +30 -0
- package/skills/comet-classic/reference/decision-point.md +109 -0
- package/skills/comet-classic/reference/dirty-worktree.md +59 -0
- package/skills/comet-classic/reference/file-structure.md +32 -0
- package/skills/comet-classic/reference/intent-frame.md +132 -0
- package/skills/comet-classic/reference/scripts.md +144 -0
- package/skills/comet-classic/reference/sdk-methods.md +136 -0
- package/skills/comet-classic/reference/subagent-dispatch.md +75 -0
- package/skills/comet-classic/reference/workspace.md +23 -0
- package/skills/comet-design/SKILL.md +25 -0
- package/skills/comet-design/agents/openai.yaml +5 -0
- package/skills/comet-design/reference/compat.md +191 -0
- package/skills/comet-hotfix/SKILL.md +46 -0
- package/skills/comet-hotfix/agents/openai.yaml +5 -0
- package/skills/comet-hotfix/reference/compat.md +240 -0
- package/skills/comet-memory/SKILL.md +68 -0
- package/skills/comet-memory/agents/openai.yaml +5 -0
- package/skills/comet-native/SKILL.md +139 -0
- package/skills/comet-native/agents/openai.yaml +3 -0
- package/skills/comet-native/reference/artifacts.md +118 -0
- package/skills/comet-native/reference/clarification.md +120 -0
- package/skills/comet-native/reference/commands.md +321 -0
- package/skills/comet-native/reference/edit-review.md +26 -0
- package/skills/comet-native/reference/recovery.md +64 -0
- package/skills/comet-native/reference/workspace.md +70 -0
- package/skills/comet-native/scripts/comet-native-archive.mjs +475 -0
- package/skills/comet-native/scripts/comet-native-cancel.mjs +461 -0
- package/skills/comet-native/scripts/comet-native-doctor.mjs +475 -0
- package/skills/comet-native/scripts/comet-native-hook-guard.mjs +470 -0
- package/skills/comet-native/scripts/comet-native-init.mjs +465 -0
- package/skills/comet-native/scripts/comet-native-new.mjs +478 -0
- package/skills/comet-native/scripts/comet-native-next.mjs +464 -0
- package/skills/comet-native/scripts/comet-native-root.mjs +472 -0
- package/skills/comet-native/scripts/comet-native-runtime.mjs +525 -0
- package/skills/comet-native/scripts/comet-native-select.mjs +468 -0
- package/skills/comet-native/scripts/comet-native-show.mjs +462 -0
- package/skills/comet-native/scripts/comet-native-spec.mjs +468 -0
- package/skills/comet-native/scripts/comet-native-status.mjs +467 -0
- package/skills/comet-native/scripts/comet-native-transfer.mjs +466 -0
- package/skills/comet-open/SKILL.md +265 -0
- package/skills/comet-open/agents/openai.yaml +5 -0
- package/skills/comet-open/reference/batch-changes.md +51 -0
- package/skills/comet-review/SKILL.md +121 -0
- package/skills/comet-review/agents/openai.yaml +5 -0
- package/skills/comet-tweak/SKILL.md +49 -0
- package/skills/comet-tweak/agents/openai.yaml +5 -0
- package/skills/comet-tweak/reference/compat.md +232 -0
- package/skills/comet-verify/SKILL.md +30 -0
- package/skills/comet-verify/agents/openai.yaml +5 -0
- package/skills/comet-verify/reference/compat.md +202 -0
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
# comet-tweak Compat 操作
|
|
2
|
+
|
|
3
|
+
仅在 `runtimeFormat: compat` 时读取。SDK 使用主 Skill 与 SDK 方法参考。
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 流程(预设流程,4 阶段)
|
|
8
|
+
|
|
9
|
+
### 0. 设置输出语言
|
|
10
|
+
|
|
11
|
+
精简版 OpenSpec 产物必须使用 Comet 配置产物语言。`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `classic.language`,初始化后使用 `comet state get <name> language` 读取。
|
|
12
|
+
|
|
13
|
+
执行顺序:open → OpenSpec apply → verify → archive。Tweak 预设各阶段的执行方式:创建必要文档,通过 OpenSpec apply 直接构建,根据改动规模和 delta spec 选择轻量或完整验证,验证通过后进入归档前的最终确认。
|
|
14
|
+
|
|
15
|
+
开始前,按 `comet-classic/reference/scripts.md` 使用正式支持的 Comet CLI;从任意入口恢复任务时,先按 `comet-classic/reference/context-recovery.md` 检查 phase/workflow。
|
|
16
|
+
|
|
17
|
+
恢复已有 tweak change 时,第一项状态操作必须是 `comet state select <change-name>`;创建新 change 时,在 `.comet.yaml` 初始化成功后立即运行该命令,再进入源码写入步骤。
|
|
18
|
+
|
|
19
|
+
进入工作区并读取当前阶段后,以及阶段切换、换 Agent 或上下文恢复时,按 `comet-classic/reference/scripts.md` 的任务上下文协议使用当前 `contextRequest`;没有描述时运行 `comet task <project-root> --task "<用户原始请求>" --phase "<phase>" --session "<接收方稳定会话标识>" --context-mode snapshot --json`。
|
|
20
|
+
|
|
21
|
+
- 将 `context[].text` 加入上下文。Context Manifest(`manifest` / `<context_manifest>`)只含摘要、原因和稳定 ID;需要正文、来源或验证方式时增加 `--expand-context "<id>"`。同一阶段连续执行不重复获取;路径或操作变化时用同一会话和 `--context-mode incremental`。派发子任务时交付上下文请求和有效配置,由接收方用自己的会话获取,偏好不能跳过配置确认或必需审查。
|
|
22
|
+
- 用户明确要求长期记住时,调用 `comet memory remember ... --scope global|project`。对于用户未明确要求记忆、但可重复采用且相对稳定的协作方式,才调用 `comet memory observe`;不得保存任务摘要、进展、命令输出或测试结果。
|
|
23
|
+
- 任务结束前,将本次验证过且未来任务仍可复用的项目经验写入项目记忆:`comet knowledge remember <project-root> --title "<简明标题>" --text "<现象、做法、验证结果>" --type <fact|decision|pattern|procedure|constraint|failure-resolution> --workflow classic --change <change-id> --json`。同一标题默认更新已有条目;没有可复用经验时跳过,任务摘要、一次性命令输出和未验证的猜测不得写入项目记忆。
|
|
24
|
+
- 实际使用某条记录、且使用结果已经明确后,取 `applications[].applicationId`(Hook 文本中的 `application_id`),运行 `comet task <project-root> --task "<用户原始请求>" --application "<application-id>" --outcome used-successfully|ignored|overridden|corrected|contributed-to-failure --json`,记录使用结果。
|
|
25
|
+
- 任务结束前完成一次学习检查:有明确后续复用条件的用户纠正、偏好或协作习惯先调用 `comet memory observe`,再在完成命令中传 `--learning-check submitted`;确认没有合格观察时传 `--learning-check no-observation`,没有执行检查时传 `--learning-check not-run`。观察 JSON 的 `learning.result` 和 `status.learning.lastCheck` 用于区分候选、晋级、去重和跳过;不要提交任务摘要或测试结果。
|
|
26
|
+
- 任务结束时,仍须运行带 `--complete --workflow <workflow> --change <change-id> --learning-check submitted|no-observation|not-run` 的 `comet task`。按 `comet-classic/reference/scripts.md` 独立执行项目学习检查,并传 `--project-learning-check submitted|no-observation|not-run`;保存过项目经验时附带 `--memory <返回的 slug>`,核对 `projectLearning.submissionVerified` 和待评审数量。没有 Hook 时,由本 Skill 调用相同接口;`comet memory context` 只作为兼容入口。插件失败不阻断本次变更。
|
|
27
|
+
|
|
28
|
+
### 1. 快速开启(预设 open)
|
|
29
|
+
|
|
30
|
+
复用 Comet open 创建 change,并采用 tweak 默认配置:不执行 `openspec-explore` 的完整探索,直接创建本次变更所需的文档。
|
|
31
|
+
|
|
32
|
+
**立即执行:** 使用 Skill 工具加载 `openspec-new-change` 技能。禁止跳过此步骤。
|
|
33
|
+
|
|
34
|
+
<!-- external-openspec-skill-override -->
|
|
35
|
+
|
|
36
|
+
**外部 OpenSpec Skill 适配规则:** 加载后,不执行其中直接运行官方 CLI、采用固定 cwd 或读写固定 OpenSpec 目录的指令。所有 OpenSpec 命令改用 `comet classic openspec -- <args...>`,所有 change 与产物路径改用本轮绑定的 `<classic-*>` 逻辑根目录。
|
|
37
|
+
|
|
38
|
+
技能加载后,按其指引创建精简版产物:
|
|
39
|
+
|
|
40
|
+
- `proposal.md` — 变更动机 + 目标 + 范围
|
|
41
|
+
- `design.md` — 简短实现说明(无需方案对比)
|
|
42
|
+
- `tasks.md` — 任务清单(建议控制在合理规模,数量本身不触发升级,见「升级判定」)
|
|
43
|
+
- `delta spec`(可选)— 变更影响已有 spec 的验收场景时,正常创建 delta spec(仅含 `## MODIFIED Requirements` 或 `## ADDED Requirements`)。OpenSpec 使用 delta spec 描述对现有系统的增量变更,不能仅因为需要这份产物就要求升级流程
|
|
44
|
+
|
|
45
|
+
开始工作前先由用户选择工作区隔离方式,不能默认写入 `current`(选 worktree 必须在初始化状态前决定——change 目录在初始化后才存在,事后补选会失败)。按 `comet-classic/reference/decision-point.md` 暂停,以单选题让用户选择:
|
|
46
|
+
|
|
47
|
+
- A. 当前分支直接工作(`--isolation current`,如实绑定当前分支)
|
|
48
|
+
- B. 创建分支:先创建并切换到 `tweak/YYYYMMDD/<change-name>`(`--isolation branch`)
|
|
49
|
+
- C. 创建 worktree:必须先使用 Skill 工具加载 Superpowers `using-git-worktrees` 技能,由该技能创建隔离工作区(`--isolation worktree`)
|
|
50
|
+
|
|
51
|
+
随后准备工作区并在返回的 `projectRoot` 中初始化与选中 change:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
comet classic workspace prepare <name> --isolation <selected-isolation> --json
|
|
55
|
+
cd <返回的 projectRoot>
|
|
56
|
+
comet state init <name> tweak --isolation <selected-isolation>
|
|
57
|
+
comet state select <name>
|
|
58
|
+
comet state check <name> open
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
若上述 `select` / `check` 输出 `BLOCKED`,且原因是 `bound_branch` 与当前分支不一致,立即按 `comet-classic/reference/decision-point.md` 暂停,让用户单选:切回绑定分支后重新运行入口验证,或在用户明确确认当前分支应接管该 change 后运行 `comet state rebind <change-name>` 并重新入口验证。不得自行切换分支,不得自行换绑。
|
|
62
|
+
|
|
63
|
+
阶段守卫完成 open → build 过渡:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
comet guard <change-name> open --apply
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### 2. OpenSpec apply 构建(tweak 专用预设 build)
|
|
70
|
+
|
|
71
|
+
使用 tweak 默认值:`build_mode: direct`。`isolation` 必须沿用 Step 1 中用户已确认的工作区隔离方式,不得自行改回 `current`。跳过 Superpowers `brainstorming` 和 `writing-plans`,由 OpenSpec 的 apply action 执行当前 change 的任务。
|
|
72
|
+
|
|
73
|
+
<IMPORTANT>
|
|
74
|
+
这条 apply 路径只属于 tweak。完整 `/comet-classic` 或 `workflow: full` 不得套用 tweak 的 `openspec-apply-change` 构建路径。full 仍必须先通过 `/comet-design` 生成 Design Doc,再由 `/comet-build` 按已确认的策略制定计划并实施;autonomous 无需加载 `writing-plans`,其他策略按 `/comet-build` 的要求使用相应规划与执行 Skill。
|
|
75
|
+
</IMPORTANT>
|
|
76
|
+
|
|
77
|
+
开始或继续修改前,按 `comet-classic/reference/dirty-worktree.md` 处理未提交改动。确认改动归属后,如发现下文列出的升级条件,或改动文件数超过提示阈值,按本文件「升级判定」处理。
|
|
78
|
+
|
|
79
|
+
**立即执行:** 使用 Skill 工具加载 `openspec-apply-change` 技能。禁止跳过此步骤。
|
|
80
|
+
|
|
81
|
+
<!-- external-openspec-skill-override -->
|
|
82
|
+
|
|
83
|
+
**外部 OpenSpec Skill 适配规则:** 加载后只采用其 apply 方法。直接运行官方 CLI、采用固定 cwd 或读写固定 OpenSpec 目录的指令,都必须改为通过 `comet classic openspec -- <args...>` 执行,并使用 `<classic-*>` 逻辑根目录。
|
|
84
|
+
|
|
85
|
+
技能加载后,以当前 `<change-name>` 作为输入,按 `openspec-apply-change` 的指引执行 OpenSpec apply 流程:
|
|
86
|
+
|
|
87
|
+
1. 运行 `comet classic openspec -- status --change "<name>" --json`,或使用该命令仍然有效的结果,确认 schema 和任务产物
|
|
88
|
+
2. 运行 `comet classic openspec -- instructions apply --change "<name>" --json`,或使用该命令仍然有效的结果,读取 OpenSpec 返回的 apply 指令、`contextFiles`、任务进度和本次生成的 instruction
|
|
89
|
+
3. 读取 apply 指令列出的全部上下文文件,不能只凭旧对话,或自行遍历 tasks 就开始实现
|
|
90
|
+
4. 按 apply 指令逐个完成未勾选任务,保持改动最小且聚焦
|
|
91
|
+
5. 每完成一个任务后:
|
|
92
|
+
- 运行项目格式化命令(如 `mvn spotless:apply`、`npm run format` 等)
|
|
93
|
+
- 运行相关测试确认通过
|
|
94
|
+
- 按 `openspec-apply-change` 规则将对应 task 勾选为完成
|
|
95
|
+
- 提交代码,commit message 格式:`tweak: <简述变更>`
|
|
96
|
+
6. 全部任务完成后,显式运行项目相关测试和构建命令
|
|
97
|
+
7. 运行阶段守卫完成 build → verify 过渡
|
|
98
|
+
|
|
99
|
+
执行 tweak 期间,只要运行程序、测试、构建或手动验证时出现崩溃、异常行为、测试失败或构建失败,必须使用 Skill 工具加载 Superpowers `systematic-debugging` 技能。在完成根因调查前,不得提出或实施源码修复。
|
|
100
|
+
|
|
101
|
+
根因调查、最小失败测试、修复后的验证,以及如何在当前 change 中完成这些步骤,均按 `comet-classic/reference/debug-gate.md` 执行。
|
|
102
|
+
|
|
103
|
+
**升级判定检查**:在整个 build 阶段持续判断是否仍适合 tweak,并在运行 build→verify 守卫前集中复核一次。具体按「升级判定」章节处理:
|
|
104
|
+
|
|
105
|
+
- Agent 根据改动内容,判断是否出现需要重新评估流程的变化。
|
|
106
|
+
- 文件数量只用于提示用户复核范围;超过阈值且没有有效授权时,由用户决定是否升级。
|
|
107
|
+
- scale 脚本只建议采用轻量还是完整验证,不决定是否升级流程。
|
|
108
|
+
|
|
109
|
+
出现升级条件,或文件数超过提示阈值且没有有效授权时,**不得自行升级,也不得自行决定继续使用 tweak**。必须按 `comet-classic/reference/decision-point.md` 暂停,让用户选择继续 tweak 轻量流程,还是改用完整 `/comet-classic`;命中有效授权时按下方报告要求继续,不重新提问。
|
|
110
|
+
|
|
111
|
+
运行阶段守卫完成 build → verify 过渡:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
comet guard <change-name> build --apply
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
状态文件自动更新为 `phase: verify`、`verify_result: pending`,然后进入验证。
|
|
118
|
+
|
|
119
|
+
### 3. 验证(预设 verify)
|
|
120
|
+
|
|
121
|
+
复用 `/comet-verify`,由 comet-verify 的规模评估决定轻量或完整验证。
|
|
122
|
+
|
|
123
|
+
**立即执行:** 使用 Skill 工具加载 `comet-verify` 技能。禁止跳过此步骤。
|
|
124
|
+
|
|
125
|
+
**带 delta spec 的验证分流**:tweak 接受 delta spec 作为正常产物。若本次 change 创建了 delta spec,进入 comet-verify 前显式设置完整验证模式,走 OpenSpec 原生验证(`openspec-verify-change`)以覆盖 delta spec 一致性:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
comet state set <change-name> verify_mode full
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
无 delta spec 的 tweak 通常满足轻量验证条件(≤ 3 tasks、改动文件数低于 scale 阈值),按 comet-verify 的轻量验证清单逐项检查。若用户希望增加审查,可在验证前运行 `comet state set <name> review_mode standard` 或 `thorough`。
|
|
132
|
+
|
|
133
|
+
验证及报告完成后,由 `/comet-verify` 执行 `comet guard <change-name> verify --apply`;复用它成功返回的 archive 状态和 `agent.continuation`,不再手动设置 `verify_result: pass` 或重复运行 Guard。Guard 未通过时按其原因处理,不能宣告验收通过。进入 `/comet-archive` 后仍须完成归档前最终确认,不得自动运行归档脚本。
|
|
134
|
+
|
|
135
|
+
### 4. 归档(预设 archive)
|
|
136
|
+
|
|
137
|
+
复用 `/comet-archive`。归档前必须满足 `.comet.yaml` 中 `verify_result: pass`,并等待 `/comet-archive` 的归档前最终确认。
|
|
138
|
+
|
|
139
|
+
**立即执行:** 使用 Skill 工具加载 `comet-archive` 技能进行归档。禁止跳过此步骤。
|
|
140
|
+
|
|
141
|
+
---
|
|
142
|
+
|
|
143
|
+
## 连续执行模式
|
|
144
|
+
|
|
145
|
+
<IMPORTANT>
|
|
146
|
+
Tweak 默认连续执行。调用 `/comet-tweak` 后,Agent 自动推进 tweak 的各个步骤,不额外暂停。若 `auto_transition: false`,则在阶段之间(build/verify/archive)结束当前调用,按 `HINT` 提示用户稍后手动运行下一阶段命令,不再追加确认问题。无论 `auto_transition` 取何值,遇到以下情况仍须暂停,请用户决定:
|
|
147
|
+
|
|
148
|
+
1. 遇到升级判定信号(见「升级判定」章节),**必须暂停、展示选择并等待用户明确选择**:继续 tweak 轻量流程,还是升级为完整 `/comet-classic` 流程
|
|
149
|
+
2. 验证阶段(comet-verify)需要接受 WARNING/SUGGESTION 偏差、处理 Spec 不一致,或决定达到自动修复上限后如何继续;前 3 次明确可修复的失败自动修复并重新验证
|
|
150
|
+
3. 归档前在一个最终确认中选择是否归档及归档提交的交付方式
|
|
151
|
+
|
|
152
|
+
执行顺序:快速开启 → 构建(含升级判定检查)→ 验证 → 归档 → 完成
|
|
153
|
+
|
|
154
|
+
每个阶段完成后立即进入下一阶段。阶段内部仍必须按上文要求调用对应 Comet/OpenSpec/Superpowers skill,被调用的 skill 如有自己的用户决策点,按该 skill 规则执行。
|
|
155
|
+
</IMPORTANT>
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## 升级判定
|
|
160
|
+
|
|
161
|
+
tweak 的升级判定只决定是否从轻量预设转为 full。需要 delta spec 或文件数量较多,都不会自动触发升级。`comet state scale` 只建议采用轻量还是完整验证,不写入配置;最终由 Verify 根据实际风险选择。
|
|
162
|
+
|
|
163
|
+
如果 `/comet-classic` 入口已传入需求意图摘要(intent frame),tweak 在 build 前只复核 `risk_signal`,以及是否新增功能、引入公共 API、修改结构化数据格式(schema)、需要跨模块协调或涉及深层架构问题。出现这些情况时,按本节请用户决定是否升级。delta spec 仍是 tweak 正常支持的产物,不能因为它存在就自动升级;不重新判断入口已经识别的用户意图。
|
|
164
|
+
|
|
165
|
+
实施过程中,持续检查是否出现以下需要重新评估流程的变化:
|
|
166
|
+
|
|
167
|
+
- 需要协调修改多个模块
|
|
168
|
+
- 需要新增功能
|
|
169
|
+
- 需要修改数据库 schema
|
|
170
|
+
- 需要引入新的公共 API
|
|
171
|
+
- 涉及深层架构问题
|
|
172
|
+
- 当前 tweak 需要拆分为多个 OpenSpec changes
|
|
173
|
+
|
|
174
|
+
出现任一情况时,Agent **不得自行升级,也不得自行决定继续使用 tweak**。
|
|
175
|
+
|
|
176
|
+
文件数量只触发范围复核,不等同于实质升级信号。改动文件数超过提示阈值(如 > 6 个文件)时,先统计当前 change 的交付文件,再按下文检查是否存在有效的用户授权;文件多不代表一定需要完整流程。Tweak 常包含 delta spec 或配置调整,通常比缺陷修复涉及更多文件,因此提示阈值高于 hotfix。
|
|
177
|
+
|
|
178
|
+
交付文件只包括源码、测试、用户文档、配置和生成物。统计覆盖确认基线之后已提交的变更、暂存、未暂存和未跟踪文件,并按路径去重;排除当前 change 目录中的 OpenSpec 产物、`.comet` 元数据以及与当前 change 无关的脏文件。不能把 OpenSpec 产物或无关脏文件计入阈值,也不能因为文件数量较少而跳过实质升级信号检查。
|
|
179
|
+
|
|
180
|
+
### 文件数超限时复用当前 change 的明确授权
|
|
181
|
+
|
|
182
|
+
只有当前 change 的用户明确授权“范围、风险不变且仅文件数超限时继续”,才能建立或复用授权。普通开始修复、调用 Skill、历史偏好或 Personal Memory 都不是授权。授权记录只写入 `<classic-change-dir>/.comet/rulings.md`,并使用以下稳定结构;change 目录尚未初始化时,先保留待写入状态,不能假定授权已经成立:
|
|
183
|
+
|
|
184
|
+
```text
|
|
185
|
+
### Preset file-count authorization
|
|
186
|
+
- status: active|invalidated
|
|
187
|
+
- workflow: tweak
|
|
188
|
+
- decision: continue-on-file-count-only
|
|
189
|
+
- scope: <当前 change 已确认的范围>
|
|
190
|
+
- allowed-file-categories: implementation, tests, user-docs, config, generated
|
|
191
|
+
- authorization-basis: user-explicit
|
|
192
|
+
- reason: <用户授权依据和继续理由>
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
没有有效 ruling 的首次超过阈值时,仍按 `comet-classic/reference/decision-point.md` 暂停并让用户选择继续 tweak(选项 A)或升级 full(选项 B)。只有用户明确选择 A,并明确说明范围、风险不变且仅文件数超限,才写入上述 ruling;后续同一范围内的文件增长可以复用 `status: active` 的记录而不重复提问。已有有效授权时不提问,但必须先报告文件总数、分类、与确认范围的对应关系、ruling 记录位置,以及没有命中实质升级信号的依据,然后继续 tweak;验证深度仍按实际风险和 `comet state scale` 的建议决定。
|
|
196
|
+
|
|
197
|
+
恢复任务时,先读取当前 change 的 ruling。有效的 `status: active` 记录按同样条件继续;`status: invalidated`、缺失、不可读、含糊或与当前 scope 不匹配时,必须暂停并重新提供继续 tweak 或升级 full 的选择。
|
|
198
|
+
|
|
199
|
+
只有同时满足以下条件,`status: active` 才有效:`workflow` 与当前 tweak 匹配,scope、验收和风险假设没有变化,所有新增交付文件仍在 `allowed-file-categories` 内,且当前触发原因只有文件数超限。用户撤销授权、切换 workflow、范围或验收变化、出现新的模块/API/schema/capability/架构问题(例如新增公共 API、修改结构化数据格式(schema)),或文件落到授权类别之外时,必须把记录标为 `status: invalidated` 并回到暂停流程。`rulings.md` 缺失、不可读、含糊或已失效时,无有效授权时必须暂停;升级到 full 时也将记录标为 `status: invalidated`,之后不得继续复用该授权。
|
|
200
|
+
|
|
201
|
+
因此,出现任何实质升级信号,或没有有效授权而改动文件数超过提示阈值时,必须按 `comet-classic/reference/decision-point.md` 暂停并等待用户明确选择。不得直接进入 `/comet-design`,也不得自动补充 Design Doc。
|
|
202
|
+
|
|
203
|
+
用户选择升级(选项 B)后,运行状态机提供的升级命令,将预设流程转为 full,并回到 design 阶段:
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
comet state transition <name> preset-escalate
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
该命令会原子地将 `workflow`/`classic_profile` 设为 `full`、将 `phase` 改为 `design`、清空 `design_doc`,并清除预设专属的 `build_mode`、`tdd_mode`、`review_mode`、`isolation` 和 `verify_mode`。然后,**立即使用 Skill 工具加载 `comet-design` skill**,在当前 change 的基础上补充 Design Doc。进入 build 后,必须在同一轮提问中重新确认完整的工作方式配置。
|
|
210
|
+
|
|
211
|
+
用户选择继续(选项 A)时,只有在用户明确确认范围和风险不变且仅文件数超限时,才继续 tweak,并按上述结构记录用户授权依据和继续理由;仅说“开始修复”或“继续”而没有这项授权语义时,仍按暂停流程等待澄清。
|
|
212
|
+
|
|
213
|
+
---
|
|
214
|
+
|
|
215
|
+
## 退出条件
|
|
216
|
+
|
|
217
|
+
- 变更已完成,测试通过
|
|
218
|
+
- change 已归档
|
|
219
|
+
- 如有 spec 变更,已同步到 main spec
|
|
220
|
+
- **阶段守卫**:build → verify 前运行 `comet guard <change-name> build --apply`,verify → archive 前按 `/comet-verify` 规则运行 `comet guard <change-name> verify --apply`
|
|
221
|
+
|
|
222
|
+
## 自动衔接下一阶段
|
|
223
|
+
|
|
224
|
+
按 `comet-classic/reference/auto-transition.md` 和成功结果中的 `agent.continuation` 继续。已有仍然有效的状态信息时,不重复 next、select 或 check。只有丢失上下文后恢复任务、外部状态变化,或旧结果未提供这些信息时,才运行:
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
comet state next <name>
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
- `NEXT: auto` → 调用 `SKILL` 指向的 skill 继续 tweak 流程(`phase: build` 返回 `comet-tweak`,`verify` 返回 `comet-verify`,`archive` 返回 `comet-archive`)
|
|
231
|
+
- `NEXT: manual` → 不调用下一 skill,按 `HINT` 交还控制权并结束当前调用;不再创建确认点
|
|
232
|
+
- `NEXT: done` → 流程已完成,无需继续
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: comet-verify
|
|
3
|
+
description: '验证 Classic change 并记录结果。在用户调用 /comet-verify,或 Classic Runtime 进入 Verify 时使用。'
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Comet 阶段 4:验证(Verify)
|
|
7
|
+
|
|
8
|
+
首次进入阶段、交接给新 Agent 或上下文恢复后,读取并执行 [任务上下文与产物语言](../comet-classic/reference/scripts.md#任务上下文与产物语言),优先采用当前 continuation 或已领取 Action 的 `contextRequest`;同一阶段连续执行不重复获取。
|
|
9
|
+
|
|
10
|
+
收到入口返回的 layout 后,首次接收阶段或绑定变化时执行[阶段共用入口](../comet-classic/reference/scripts.md#阶段共用入口),复用仍有效的 [layout](../comet-classic/reference/classic-layout.md),无需先额外运行 root show;遇编辑判断时按共用入口加载编辑后续行协议。
|
|
11
|
+
|
|
12
|
+
## SDK Run 路径
|
|
13
|
+
|
|
14
|
+
先读取并执行[普通命令与检查](../comet/reference/platform-execution.md)。新旧 Run 均使用平台工具执行普通命令,在原 Run 提交实际检查报告;自动升级不恢复旧检查执行器。阶段准备、用户选择、任务完成和验收要求继续有效。
|
|
15
|
+
|
|
16
|
+
首次进入当前 SDK 阶段、换 Agent 或恢复上下文时,读取[阶段入口与恢复](../comet-classic/reference/sdk-methods.md#阶段入口与恢复)及该参考的当前阶段章节;本会话已有且仍有效时直接复用。下文按当前阶段执行;`nextAction.kind` 的恢复路由只适用于没有 continuation mode 的旧响应。
|
|
17
|
+
|
|
18
|
+
优先复用同一 change、工作区和 Run 的最新有效响应中的 `agent.continuation`、`data.nextAction`、phase、revision 和路径摘要。只有冷恢复、工作区或外部状态变化、响应版本已过期或缺少当前步骤必要信息时,才运行 `comet state next <change-name> --json`;不要因加载下一 Skill 再读一次。后续写操作仍由 Runtime 校验当前版本与证据,不能用缓存跳过检查或批准。确认 `data.runtimeFormat: sdk`、`data.phase: verify` 和 `nextAction.kind`,在已绑定的 `projectRoot` 执行。路径缺失或绑定发生变化时才运行 `comet classic workspace resolve <change-name> --json`;缺少当前任务、工作区或证据摘要时才运行 `comet state check <change-name> verify --json`。`reconcile` 时改用 `comet state check <change-name> verify --recover --json` 查明原 Action 和检查结果;结果未明时停止,不重复执行外部检查。
|
|
19
|
+
|
|
20
|
+
1. 按 SDK 方法参考的风险评估、最终集成审查和 light/full 验证方法检查当前 change,但以 SDK Run 的状态和证据为准;不调用旧 `state scale`、`state set`、`comet handoff` 或旧 `comet check` 证据路径。实施或任务记录需要修复时,先报告具体失败项;只有当前待执行的是 `<profile>.verify.run`(`<profile>` 为 full、hotfix 或 tweak),才运行 `comet state transition <change-name> verify-fail --reason "<failure-reason>"`。此命令将失败原因作为同一 Run 的 Verify Action 结果并返回 Build;按同次响应的当前 Build Action 继续;缺少续行信息时才读取 `state next --json`。已有检查失败或结果未明时先读取其 Action,不另报一次 Verify 失败。
|
|
21
|
+
2. 验证结论合格后,将实际检查项、证据引用、审查结论及可接受偏差写入仓库内的验证报告 `<report-ref>`,运行 `comet guard <change-name> verify --report <report-ref> --apply --checks <checks-json-file>` 提交。Guard 核对同一 Run 的报告和验收要求,不重复执行命令。失败或结果未明时使用返回的当前 Action 核对原任务;缺少续行时才读 `state next --json`,不把失败解释为通过。
|
|
22
|
+
3. Guard 通过后直接使用同次响应;缺少 phase 或 nextAction 时才运行 `comet state next <change-name> --json`。只有 phase 为 `archive` 且 `nextAction.kind` 指向 Archive,才加载 `/comet-archive`。Verify 通过不等于用户已经授权归档;由 Archive Skill 获取并记录当前交付决定。
|
|
23
|
+
|
|
24
|
+
## Compat 路径
|
|
25
|
+
|
|
26
|
+
以下旧 Runtime 步骤仅用于 `runtimeFormat: compat`。必须读取 [Compat 操作](reference/compat.md),按其中当前阶段继续;SDK 不加载该参考。
|
|
27
|
+
|
|
28
|
+
## 可选变更说明
|
|
29
|
+
|
|
30
|
+
Build 收尾和 Verify 展示结果前,先核对项目 `.comet/config.yaml` 的 `change_walkthrough`(默认开启;仅显式 `false` 关闭)。开启时读取并执行[变更说明](../comet/reference/change-walkthrough.md),用共享模板生成或更新同一 `walkthrough.html` 并给出打开链接;关闭时跳过额外讲解、详细指引和渲染,保留原有摘要。Archive 只随现有材料保存已有页面并提供实际归档链接,不补生成、不新增确认、不为页面更新重跑代码检查。
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
# comet-verify Compat 操作
|
|
2
|
+
|
|
3
|
+
仅在 `runtimeFormat: compat` 时读取。SDK 使用主 Skill 与 SDK 方法参考。
|
|
4
|
+
|
|
5
|
+
## 前置条件
|
|
6
|
+
|
|
7
|
+
- 代码已提交(阶段 3 完成)
|
|
8
|
+
- tasks.md 全部任务已完成
|
|
9
|
+
|
|
10
|
+
## 步骤
|
|
11
|
+
|
|
12
|
+
### 0a. 设置输出语言
|
|
13
|
+
|
|
14
|
+
验证报告使用本轮入口返回的 configuration.language,不再单独查询语言字段。
|
|
15
|
+
|
|
16
|
+
### 0b. 入口状态验证(Entry Check)
|
|
17
|
+
|
|
18
|
+
按 `comet-classic/reference/scripts.md` 使用正式支持的 `comet` CLI,执行以下入口验证。从任意入口恢复任务时,先按 `comet-classic/reference/context-recovery.md` 检查恢复状态:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
comet state select <change-name>
|
|
22
|
+
comet state check <change-name> verify --json
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
上一阶段 guard 已成功返回本阶段状态信息时,直接使用其中的状态与 `agent.continuation` 继续,不重复 select/check;恢复任务、工作区变化或外部状态变化时,才执行上述入口验证。根据入口返回的 layout、configuration、nextAction、任务信息和协作进度摘要继续。已有检查结果和集成审查仍然有效时,只补未完成的工作,不重新执行整个阶段。丢失上下文后恢复任务,需要完整记录时,使用 --recover --details --json。验证失败时,处理返回的具体原因。
|
|
26
|
+
|
|
27
|
+
若上述 `select` / `check` 输出 `BLOCKED` 或分支绑定 `ERROR`,且原因是 `bound_branch` 与当前分支不一致,立即按 `comet-classic/reference/decision-point.md` 暂停,让用户单选:切回绑定分支后重新运行入口验证,或在用户明确确认当前分支应接管该 change 后运行 `comet state rebind <change-name>` 并重新入口验证。不得自行切换分支,不得自行换绑。
|
|
28
|
+
|
|
29
|
+
**按已记录结果继续**:`verify_result` 已为 `pass` 时,进入 archive;在归档提交和最终分支处理完成前,`branch_status` 保持 `pending`。`verify_result` 为 `pending` 时,先核对已有报告和检查结果,再从未完成的检查继续。
|
|
30
|
+
|
|
31
|
+
丢失上下文后恢复任务时,按 `evidence.scopes` 处理:标记为 `revalidated` 的本地结果可以复用;标记为 `rerun-required` 的部分需要重新检查。已经完成且仍然有效的需求分析与审查,不重复执行。外部检查不能假定具有幂等性,也不能假定其环境一直不变。
|
|
32
|
+
|
|
33
|
+
### 1. 改动规模评估
|
|
34
|
+
|
|
35
|
+
执行规模评估:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
comet state scale <change-name>
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
脚本统计任务数、增量规格数和变更文件数,只返回 light/full 建议,不修改 `verify_mode`。使用 `--json` 读取 `data.recommendation`、`data.selected` 和 `data.metrics`。已有验证模式时保留;尚未选择时,根据风险确定模式,再用 `comet state set <change-name> verify_mode <light|full>` 明确记录。满足以下任一条件时,规模评估建议 full:任务数 > 3、delta spec 能力数 > 1、变更文件数 > 8。
|
|
42
|
+
|
|
43
|
+
`comet state scale` 会自行从 plan 的 `base-ref` 解析提交基线,并在 plan 不可用时回退到状态中的 `base_ref`;Verify 不再重复读取 plan frontmatter 或手工拼接第二套规模评估。
|
|
44
|
+
|
|
45
|
+
验证开始前,按 `comet-classic/reference/dirty-worktree.md` 协议检查并处理未提交改动。verify 阶段的特殊处理:
|
|
46
|
+
|
|
47
|
+
1. 未提交改动明确属于当前 change 时,将这些改动纳入本次验证;继续验证,但不在 verify 阶段修改或提交实现、测试、tasks、delta spec 或 Design Doc。纯文档编辑(comet-build 定义的中性文档集:仓库根目录的 Markdown 与 `LICENSE`/`NOTICE`/`AUTHORS`,以及 `docs/`、`doc/`、`documentation/`、`.github/` 下的 Markdown/`.txt`/`.rst`,OpenSpec 与 Superpowers 产物除外)可以在 verify 阶段正常完成——它们不是实现写入,默认不作废检查证据,也不需要 `verify-fail`
|
|
48
|
+
2. 未提交改动只是 verify 本阶段的产物时,例如验证报告草稿,可以继续在 verify 阶段完成并记录状态
|
|
49
|
+
3. 未提交改动表明代码已经实现、但 tasks.md 尚未勾选时,说明 build 的任务记录落后于实现;直接运行 `verify-fail` 返回 build,核对已有结果并更新任务状态,不得询问是否接受未完成任务
|
|
50
|
+
4. 无法确认未提交改动的归属,或改动属于其他 change 时,按 dirty-worktree 协议说明为何需要停止;不要在尚未确定归属时让用户选择“继续/忽略”
|
|
51
|
+
|
|
52
|
+
需要回到 build 修复或补齐状态时运行:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
comet state transition <change-name> verify-fail
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**调整验证模式**:如 Agent 或用户认为自动评估结果不合适,可随时通过 `comet state set <change-name> verify_mode <light|full>` 修改验证模式。
|
|
59
|
+
|
|
60
|
+
不能因为改动小就省略风险检查。涉及认证授权、数据迁移、并发、公共 API 或跨模块接口约定时,必须验证对应的风险场景;轻量验证无法覆盖时,改用 full。
|
|
61
|
+
|
|
62
|
+
### 1b. 验证失败自动修复与例外决策
|
|
63
|
+
|
|
64
|
+
验证失败时,读取最新入口返回的连续失败次数和 nextAction;只有字段缺失时,才查询 `comet state get <change-name> verify_failures`,不能把缺失当作零。前 3 次可修复的失败自动回到 build:先报告失败项,再运行 `comet state transition <change-name> verify-fail`,然后调用 `/comet-build`,只补未完成的实现、检查、审查或任务勾选,不重复已经完成的实施。
|
|
65
|
+
|
|
66
|
+
报告必须列出:
|
|
67
|
+
|
|
68
|
+
- 失败项
|
|
69
|
+
- 是否属于 CRITICAL 或 IMPORTANT(构建失败、测试失败、安全问题、核心验收场景失败、简化代码审查发现的正确性/安全/边界问题)
|
|
70
|
+
- 推荐处理方式
|
|
71
|
+
|
|
72
|
+
**无法确定严重程度时**,使用较低级别。仅对构建失败、测试失败、安全问题使用 CRITICAL;明确影响核心验收或正确性的项使用 IMPORTANT;模糊或不确定的问题标为 WARNING 或 SUGGESTION。
|
|
73
|
+
|
|
74
|
+
按以下方式处理:
|
|
75
|
+
|
|
76
|
+
- **CRITICAL/IMPORTANT 或范围内可明确修复的问题**:未达到上限时,自动回到 build 修复;不额外询问“是否修复”,也不允许接受偏差
|
|
77
|
+
- **WARNING/SUGGESTION 且修复会引入行为、范围或风险取舍**:按 `comet-classic/reference/decision-point.md` 让用户选择修复或接受偏差;接受时必须在验证报告中记录原因和影响范围
|
|
78
|
+
- **WARNING/SUGGESTION 且修复安全、范围局部、不涉及取舍**:未达到上限时自动修复,不因级别较低而强制停顿
|
|
79
|
+
|
|
80
|
+
只有接受 WARNING/SUGGESTION 偏差或第 4 次失败后的策略选择才是用户决策点。当前 `verify_failures >= 3` 时不得自动执行下一次 `verify-fail`;按协议只提供「继续修复」或「停止当前 workflow 并寻求外部决策」两个选项。用户选择继续后才记录下一次失败并回到 build。CRITICAL/IMPORTANT 始终不可豁免。
|
|
81
|
+
|
|
82
|
+
### 2. 读取验证所需的产物
|
|
83
|
+
|
|
84
|
+
按当前验收项读取需要的 OpenSpec 源文件和交接上下文。由 Agent 对照实际修改判断哪些检查仍然适用;文件变化不自动撤回验收。上下文缺失时补读源文件,不使用 hash、FRESH/STALE 或编辑复核记录证明内容。
|
|
85
|
+
|
|
86
|
+
autonomous 直接按本 Skill 执行实际检查并记录结果,不强制加载外部验证 Skill;其他策略使用 Skill 工具加载 Superpowers `verification-before-completion`。任何策略都不能仅凭自评宣布验证通过。
|
|
87
|
+
|
|
88
|
+
Verify 负责整个 change 的唯一最终集成代码审查。Build 只保留任务级或分段审查;在按 `verify_mode` 分支执行前,先对包含 Build 审查修复在内的最终 diff 执行一次集成审查:
|
|
89
|
+
|
|
90
|
+
- `review_mode: off`:跳过自动代码审查,并在验证报告中记录原因
|
|
91
|
+
- `review_mode: standard|thorough`:安排独立审查者(reviewer)审查整个 change,核对需求、实际代码差异、检查结果和修复情况,重点检查正确性、安全和边界条件。autonomous 无需外部审查 Skill,其他策略加载一次 requesting-code-review。已有审查覆盖当前最终 diff 且仍然有效时,直接复用;输入变化后只补查受影响的部分,不无条件重做整轮。无法进行独立审查时停止,不能用实现代理(implementer)的自评代替
|
|
92
|
+
|
|
93
|
+
集成审查发现 CRITICAL/IMPORTANT 问题时按 Step 1b 返回 Build;非 CRITICAL 偏差按 Step 1b 的取舍规则处理。然后按 `verify_mode` 分支执行:
|
|
94
|
+
|
|
95
|
+
### 2a. 轻量验证(小改动)
|
|
96
|
+
|
|
97
|
+
按以下 7 项进行检查:
|
|
98
|
+
|
|
99
|
+
1. tasks.md 全部任务已完成 `[x]`
|
|
100
|
+
2. 改动文件与 tasks.md 描述一致(`git diff --stat` / `git diff --cached --stat` / `git diff --stat <base-ref>...HEAD` 对照 tasks 内容);中性文档集内的纯文档编辑在对照结果旁说明即可,不作为实现不一致处理
|
|
101
|
+
3. 编译通过(由 Agent 核对已有 Build 结果是否适用;失效时补跑)
|
|
102
|
+
4. 相关测试通过
|
|
103
|
+
5. 无明显安全问题(无硬编码密钥、无新增 unsafe 操作)
|
|
104
|
+
6. 最终集成代码审查已通过,或非 full autonomous 的 `review_mode: off` 跳过原因已记录;full autonomous 不允许跳过独立审查
|
|
105
|
+
7. 核心成功场景、关键失败和边界场景,以及本次涉及的高风险功能要求均已验证通过;小改动也不可省略
|
|
106
|
+
|
|
107
|
+
按[普通命令与检查](../../comet/reference/platform-execution.md)使用平台工具执行普通命令、核对原任务与副作用、判断结果是否适用,并提交实际报告。Comet 不重复执行检查,不维护普通命令的内容快照、进程监管或恢复机制。 light/full 均覆盖各自验收要求。Build 结果仍适用时直接引用,不凭旧对话中的“通过”跳过。失败、超时、未执行和未知结果分别说明。报告路径用 `comet state set <change-name> verification_report <report-ref>` 登记。
|
|
108
|
+
|
|
109
|
+
集成代码审查的输入限定为本次改动 diff、tasks.md 和必要测试结果;它不替代 spec 覆盖率、Design Doc 一致性或漂移检查。`review_mode: off` 只跳过自动 code review,不跳过构建、测试、安全检查或异常调试协议。
|
|
110
|
+
|
|
111
|
+
**通过标准**:7 项全部 OK,无 CRITICAL 或 IMPORTANT 问题。
|
|
112
|
+
|
|
113
|
+
**不通过时**:报告失败项并按 Step 1b 分类。未达到自动修复上限且问题必须或适合修复时,直接执行以下命令回到 build 阶段,然后调用 `/comet-build`:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
comet state transition <change-name> verify-fail
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
**报告格式**:简表列出 7 项检查结果、证据引用及 PASS/FAIL。
|
|
120
|
+
|
|
121
|
+
**跳过项**(不在轻量验证中检查):
|
|
122
|
+
|
|
123
|
+
- 逐条统计全部规格场景的覆盖情况(核心和高风险场景仍必查)
|
|
124
|
+
- 深入比对实现与 Design Doc 的一致性
|
|
125
|
+
- 不影响正确性、安全或边界条件的代码写法一致性建议
|
|
126
|
+
- 检查 delta spec 与 Design Doc 是否已不一致
|
|
127
|
+
|
|
128
|
+
### 2b. 完整验证(大改动)
|
|
129
|
+
|
|
130
|
+
当规模评估结果为"大"时:
|
|
131
|
+
|
|
132
|
+
**立即执行:** 使用 Skill 工具加载 `openspec-verify-change` 技能。禁止跳过此步骤。
|
|
133
|
+
|
|
134
|
+
<!-- external-openspec-skill-override -->
|
|
135
|
+
|
|
136
|
+
**外部 OpenSpec Skill 适配规则:** 加载后只采用其验证方法。直接运行官方 CLI、采用固定 cwd 或读写固定 OpenSpec 目录的指令,都必须改为通过 `comet classic openspec -- <args...>` 执行,并使用路径解析器返回的 `<classic-*>` 逻辑根目录。
|
|
137
|
+
|
|
138
|
+
技能加载后,按其指引验证。检查项:
|
|
139
|
+
|
|
140
|
+
1. tasks.md 全部任务已完成(`[x]`)
|
|
141
|
+
2. 实现符合 `<classic-change-dir>/design.md` 高层设计决策
|
|
142
|
+
3. 实现符合 Design Doc(`docs/superpowers/specs/` 下的技术设计文档)
|
|
143
|
+
4. 能力规格场景全部通过
|
|
144
|
+
5. proposal.md 目标已满足
|
|
145
|
+
6. delta spec 与 design doc 无矛盾(若 Build 阶段有增量修改 spec,检查 design doc 是否有对应记录)
|
|
146
|
+
7. `docs/superpowers/specs/` 关联的设计文档可定位(文件存在且与当前 change 相关)
|
|
147
|
+
|
|
148
|
+
验证不通过时:报告缺失项并按 Step 1b 分类。未达到自动修复上限且缺失项可在当前 change 内补齐时,直接执行以下命令回到 build 阶段,然后调用 `/comet-build`:
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
comet state transition <change-name> verify-fail
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
**Spec 漂移处理**(用户决策点):
|
|
155
|
+
|
|
156
|
+
- 若检查项 6 发现矛盾(delta spec 有内容但 design doc 未体现),**必须以单选题形式暂停、展示处理方式并等待用户选择**,不得自动选择。选项:
|
|
157
|
+
- 选项 A:在 design doc 追加 "Implementation Divergence" 节记录偏差原因。选项 A 属于 verify 阶段允许产物;写入后不得因该 design doc 变更再次触发 Step 1b dirty-worktree 决策。由 Agent 判断该文档变化是否影响既有结果,只补必要检查、记录实际结果,再运行 `comet guard <change-name> verify --apply`
|
|
158
|
+
- 选项 B:用户选择 B 后,运行 `comet state transition <change-name> verify-fail`,然后调用 `/comet-build`;由 `/comet-build` 的 Spec 增量更新规则加载 Superpowers `brainstorming` 更新 Design Doc + delta spec
|
|
159
|
+
- 选项 C:确认偏差可接受,继续验证(归档时 design doc 将标记为 `superseded-by-main-spec`)
|
|
160
|
+
|
|
161
|
+
### 3. 记录验证证据
|
|
162
|
+
|
|
163
|
+
验证报告必须保存为文件,并在 `.comet.yaml` 中记录路径。verify 阶段不处理、合并或丢弃分支,也不写入 `branch_status: handled`。归档还会修改 spec 和元数据,这些修改必须包含在最终提交中,因此分支收尾统一由 `/comet-archive` 在归档提交后执行。不要手动设置 `verify_result: pass`,由阶段守卫 `--apply` 更新状态并推进阶段。
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
comet state set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
使用文件工具创建 `docs/superpowers/reports/` 和报告文件,不依赖 POSIX 专用目录命令。
|
|
170
|
+
|
|
171
|
+
## 退出条件
|
|
172
|
+
|
|
173
|
+
- 验证报告通过
|
|
174
|
+
- `.comet.yaml` 中 `verification_report` 指向已存在的验证报告文件
|
|
175
|
+
- `.comet.yaml` 中 `branch_status` 仍为 `pending`
|
|
176
|
+
- **阶段守卫**:运行 `comet guard <change-name> verify --apply`,全部 PASS 后由守卫通过 `comet state transition verify-pass` 推进到 `phase: archive`(此步骤更新 `phase` 字段,与 `auto_transition` 无关)
|
|
177
|
+
|
|
178
|
+
验证证据完成后,运行阶段守卫推进 phase(此步骤与 `auto_transition` 无关):
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
comet guard <change-name> verify --apply
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
状态文件自动更新为 `phase: archive`、`verify_result: pass`、`verified_at: YYYY-MM-DD`。
|
|
185
|
+
|
|
186
|
+
## 上下文压缩恢复
|
|
187
|
+
|
|
188
|
+
按 `comet-classic/reference/context-recovery.md` 执行,phase 参数为 `verify`。
|
|
189
|
+
|
|
190
|
+
## 自动衔接下一阶段
|
|
191
|
+
|
|
192
|
+
按 `comet-classic/reference/auto-transition.md` 和成功结果中的 `agent.continuation` 继续。已有仍然有效的状态信息时,不重复 next、select 或 check。只有丢失上下文后恢复任务、外部状态变化,或旧结果未提供这些信息时,才运行:
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
comet state next <change-name>
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
- `NEXT: auto` → 调用 `SKILL` 指向的 skill 进入下一阶段
|
|
199
|
+
- `NEXT: manual` → 不调用下一 skill,按 `HINT` 交还控制权并结束当前调用;不再创建确认点
|
|
200
|
+
- `NEXT: done` → 流程已完成,无需继续
|
|
201
|
+
|
|
202
|
+
注意:无论 NEXT 为 auto 还是 manual,归档都必须有用户的明确授权。首次归档时,按 comet-archive 请用户确认;恢复时,核对已保存的 delivery 记录,已有选择仍然有效就不重复询问。验证通过本身不代表用户已授权归档。
|