@rpamis/comet 0.4.0-beta.1 → 0.4.0-beta.11

package/assets/skills-zh/comet-native/reference/commands.md

@@ -0,0 +1,168 @@
+# Native 命令参考
+
+只在需要主 Skill 未列出的参数、receipt、partial scope、外部角色交接或恢复命令时读取本文件。
+
+## 项目与 change
+
+```text
+comet native init [--root <artifact-root>] [--language en|zh-CN]
+comet native root show
+comet native root move <artifact-root>
+
+comet native new <change-name> [--language en|zh-CN]
+comet native list [--cursor <token>]
+comet native show <change-name>
+comet native status [--cursor <token>]
+comet native status <change-name> [--details [--acceptance-cursor <token>]]
+comet native select <change-name>
+comet native spec remove <change-name> <capability>
+comet native spec rebase <change-name> --summary <text>
+```
+
+`artifact-root` 是项目内相对路径。`new` 在配置缺失时创建默认配置和 `<project>/docs/comet/`。已有配置需要迁移根目录时使用 `root move`，不要直接改配置。
+
+`status` 和 `show` 是只读命令。`new` 和 `select` 会建立当前 Native selection。多个候选无法唯一判断时让用户选择。
+
+`status <change-name> --details` 返回详细 findings 和 acceptance 页：
+
+- `findingsTruncated` 为 true 时，先处理已返回项，再重新读取；
+- `acceptancePage.nextCursor` 非空时，用 `--acceptance-cursor` 继续读取；
+- change 集合的 `nextCursor` 非空时，用 `--cursor` 继续读取。
+
+canonical 规格发生并发变化时，先重读并改写完整目标规格，再运行 `spec rebase`。不要手改 operation 或 hash。
+
+## Checkpoint 与检查
+
+```text
+comet native checkpoint <change-name> \
+  --summary <text> \
+  --next-action <text> \
+  [--artifact <project-relative-path>]... \
+  [--expect-revision <n>]
+
+comet native check <change-name>
+comet native evidence format [--entries <path>]
+```
+
+checkpoint 只保存恢复摘要和真实产物引用，不改变 phase，也不能代替完成证据。
+
+`check` 是 Native 内置检查，不替代项目测试。发现问题或证据失效时返回退出码 `1`。
+
+`evidence format` 从 stdin 或 `--entries` 读取验收条目，输出可原样粘贴到 `verification.md` 的规范机器块。
+
+## Acceptance receipt
+
+自动验证：
+
+```text
+comet native receipt automated <change-name> \
+  [--acceptance <id>]... \
+  [--timeout-ms <milliseconds>] \
+  -- <executable> [args...]
+```
+
+人工观察：
+
+```text
+comet native receipt manual <change-name> \
+  --acceptance <id> \
+  --responsible <text> \
+  --step <text> \
+  --observation <text> \
+  --confirmed
+```
+
+只为真实执行的命令或人工观察生成 receipt。失败、跳过、阻塞或超时结果不能作为 pass。
+
+## 外部审核交接
+
+高风险 change 的 pass 可能要求 implementation attestation、independent review 或 waiver。当前 Agent 可以准备和最终导入交接产物，但不得执行外部角色的 approve/sign，也不得接收其私钥。
+
+Implementation 交接：
+
+```text
+comet native receipt implement <change-name> prepare \
+  --identity <implementation-identity> \
+  --output <preparation.json>
+
+comet native receipt implement <change-name> finalize \
+  --preparation <preparation.json> \
+  --attestation <owner-provided-attestation.json> \
+  --confirmed
+```
+
+Independent review 交接：
+
+```text
+comet native receipt review <change-name> prepare \
+  --implementation-receipt <ref> \
+  --report <verification.md> \
+  --required-receipt <ref> \
+  --identity <reviewer-identity> \
+  [--unified-io-receipt <ref> \
+   --adversarial-paths-receipt <ref> \
+   --generated-assets-receipt <ref> \
+   --lifecycle-eval-receipt <ref>] \
+  --output <preparation.json>
+
+comet native receipt review <change-name> finalize \
+  --preparation <preparation.json> \
+  --approval <reviewer-provided-approval.json> \
+  --attestation <reviewer-provided-attestation.json> \
+  --confirmed
+```
+
+外部角色根据 preparation 完成审批或签名，并只把公开产物返回当前 Agent。Runtime 要求 waiver 时，也由外部 waiver signer 执行 continuation 指定的命令；当前 Agent 只提交返回的 waiver ref。
+
+## 阶段推进
+
+```text
+comet native next <change-name> --summary <text> \
+  [--confirmed] \
+  [--artifact <project-relative-path>]... \
+  [--no-code-reason <text>] \
+  [--allow-partial-scope <sha256> --partial-reason <text> --confirmed] \
+  [--result pass|fail] \
+  [--report <change-relative-path>] \
+  [--receipt <required-receipt-ref>] \
+  [--evidence-receipt <acceptance-receipt-ref>]... \
+  [--waiver <waiver-ref>]... \
+  [--independent-review-receipt <review-receipt-ref>] \
+  [--failure-category <token>]... \
+  [--failed-check <token>]... \
+  [--override-repair <sha256> --override-summary <text>]
+
+comet native archive <change-name> --dry-run
+comet native archive <change-name> --expect-preflight <sha256> [--confirmed]
+```
+
+- Shape：只有用户确认最终共享理解后才传 `--confirmed`。
+- Build：提供真实 `--artifact`；确实没有项目文件变化时使用 `--no-code-reason`。
+- Partial scope：先向用户说明 Runtime 返回的具体缺口和风险。超出已返回明细预算的变化由 `scope-detail-overflow` 数量和内容 hash 汇总；只有用户接受后才使用完全匹配的 scope hash、理由和 `--confirmed`。
+- Verify：提供 `--result` 和完整报告。标准报告路径提交为 `comet native next <change-name> --summary <摘要> --result pass|fail --report verification.md`；pass 需要 Runtime 要求的当前 receipts，fail 使用稳定、非敏感的失败分类和检查 ID。
+- Repair override：只使用 status 返回的 signature，并且只在有一个明确新修复假设时执行。
+- Archive：先 dry-run，再使用本次预演返回的精确 preflight hash；`required` 模式还需要用户明确确认。
+
+## 诊断与恢复
+
+```text
+comet native doctor [<change-name>]
+comet native doctor [<change-name>] --repair
+comet native doctor [<change-name>] --repair [--strategy continue|rollback]
+```
+
+先运行只读 doctor。只有报告给出可修复动作时才使用 `--repair`。普通阶段 transition 只支持 `continue`；Archive 或 root move 是否允许 rollback 以 doctor 返回为准。
+
+## 输出与退出码
+
+所有命令支持 `--json`。JSON 模式返回一个包含 `command`、`exitCode`、`data`，以及失败时 `error` 的对象。
+
+| 退出码 | 含义 |
+| --- | --- |
+| `0` | 成功 |
+| `1` | 内置检查发现问题或结果失效 |
+| `64` | 参数或用法错误 |
+| `65` | 配置、状态或产物无效 |
+| `73` | 锁、事务、并发或根目录冲突 |
+| `75` | repair stagnation 或失败预算阻塞继续 |
+| `70` | 未预期的内部失败 |

package/assets/skills-zh/comet-native/reference/recovery.md

@@ -0,0 +1,96 @@
+# Native 恢复参考
+
+只在 Runtime 报告中断、失效证据、repair stop、冲突、锁、迁移或损坏状态时读取本文件。
+
+## 通用原则
+
+先停止写入并运行只读诊断：
+
+```text
+comet native doctor [<change-name>]
+```
+
+只根据 doctor 或 continuation 返回的事实采取动作。不要手改状态、hash、证据、锁或事务文件；Runtime 无法证明自动修复安全时，保留现场并等待用户。
+
+## 工作区提示
+
+`workspace-root-changed` 与 `workspace-inspection-unavailable` 只用于解释当前 root 事实的来源，不单独阻止推进或 Archive。不要把任意 `workspace-*` finding 都当作提示：未知的 workspace 完整性 finding 仍是错误。Runtime 要求修复工作区身份时，先运行只读 doctor，再按报告执行显式 `doctor --repair`。
+
+## 未完成的阶段推进
+
+status 或 doctor 报告未完成 transition 时，优先按 continuation 重试原动作。需要显式修复时：
+
+```text
+comet native doctor <change-name> --repair --strategy continue
+```
+
+普通 Shape、Build、Verify transition 只支持 continue，不支持 rollback。
+
+## Baseline 缺失或不完整
+
+`baseline-snapshot-missing` 或 `baseline-snapshot-incomplete` 不能用当前文件重建，也不能通过手改 evidence 修复。
+
+只能：
+
+1. 从可信备份恢复原 baseline；或
+2. 保留用户已写的 brief、规格和实现事实，重新创建 change。
+
+## 证据失效
+
+brief、规格、实现、报告或 receipt 改变后，旧 scope 或 Verify pass 可能失效。按 continuation 回到 Build，重新确认发生变化的用户行为、生成新 scope 并重新验证。不要复用旧 pass 或旧 preflight。
+
+## Verify fail 与 repair stop
+
+Verify fail 回到 Build 后：
+
+1. 从 status details 读取 failed/missing acceptance 和 failed check；
+2. 实际修复这些缺口；
+3. 重新运行相关验证；
+4. 再提交 Verify 结果。
+
+相同缺口重复出现或达到 `max_verify_failures` 时，Runtime 会停止自动循环。只有 status 返回允许的 repair override，并且存在一个明确的新修复假设时，才能使用该 signature 和摘要重试一次；否则保留现场并让用户决定范围、约束或是否停止。
+
+## Canonical spec 冲突
+
+Archive 报告 canonical spec 已变化时：
+
+1. 重读最新 canonical spec、brief 和拟议完整规格；
+2. 按用户意图改写完整目标规格；
+3. 运行：
+
+```text
+comet native spec rebase <change-name> --summary <摘要>
+```
+
+4. 按 Runtime 返回的 phase 重新实现、确认和验证。
+
+不要手改 `base_hash` 或覆盖并发变化。
+
+## Archive 中断
+
+先运行 doctor，确认 transaction 和允许的恢复方向：
+
+```text
+comet native doctor <change-name>
+comet native doctor <change-name> --repair --strategy continue
+comet native doctor <change-name> --repair --strategy rollback
+```
+
+- `continue`：继续完成归档；
+- `rollback`：恢复 active change；
+- doctor 未提供 rollback 时，不要自行回退。
+
+出现 journal 与实际文件不一致、路径冲突或无法证明安全时，保留所有相关目录并停止自动修复。
+
+## Artifact root 迁移中断
+
+存在 `pending_root_move` 时，普通 Native 写命令会停止。运行 doctor，并只执行报告允许的 continue 或 rollback。
+
+如果旧 root 与新 root 不一致，不删除任何一棵目录；把 doctor 返回的两条路径交给用户处理。
+
+## 锁、selection 或损坏产物
+
+- 不手动删除锁。只在 doctor 明确判断可安全接管时使用 `--repair`。
+- doctor 可以清理指向不存在 change 的 selection。
+- 损坏的 config、change 状态、brief、规格或 verification 不会被自动猜测重写。
+- doctor 无法确定 owner、事务或文件身份时，保留现场并停止。

package/assets/skills-zh/comet-open/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: comet-open
-description: "Use when Comet 需要创建新的 OpenSpec change，或 active change 缺少 proposal/design/tasks/.comet.yaml 初始化产物。"
+description: "仅在用户明确调用 /comet-open，或由 Comet 根 Skill/runtime 路由到 open 阶段时使用；创建或恢复 OpenSpec change，并补齐 proposal/design/tasks/.comet.yaml。"
 ---
 
 # Comet 阶段 1：开启（Open）
 
+开始或恢复前必须先读取并执行 `comet/reference/classic-layout.md`；本文件中的 OpenSpec CLI 调用必须使用 adapter，文件路径必须使用该协议绑定的 `<classic-*>` 逻辑根。
+
 ## 前置条件
 
 - 无活跃 change，或用户希望创建新 change
@@ -13,12 +15,39 @@ description: "Use when Comet 需要创建新的 OpenSpec change，或 active cha
 
 ### 0. 输出语言约束
 
-传递给 OpenSpec 的所有提问和产物要求都必须包含解析后的 Comet 产物语言，并使用 `en`、`zh-CN` 这类规范化 ID。`.comet.yaml` 尚不存在时读取 `.comet/config.yaml` 的 `language`；change 初始化后使用 `"$COMET_BASH" "$COMET_STATE" get <name> language` 读取。没有配置语言时才回退到当前用户请求语言。生成的 `proposal.md`、`design.md`、`tasks.md` 必须以该语言为主语言。
+传递给 OpenSpec 的所有提问和产物要求都必须包含解析后的 Comet 产物语言，并使用 `en`、`zh-CN` 这类规范化 ID。`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `classic.language`；change 初始化后使用 `comet state get <name> language` 读取。没有配置语言时才回退到当前用户请求语言。生成的 `proposal.md`、`design.md`、`tasks.md` 必须以该语言为主语言。
+
+### 0a. 当前 change 绑定
+
+恢复已有 change 时先检查 `<classic-change-dir>/.comet.yaml`：
+
+- 状态文件存在且可解析：第一项状态操作是选择 change
+- 状态文件缺失但 change 目录有效：先运行 `comet state init <change-name> full`，再选择 change
+- 状态文件格式异常：停止并报告解析错误；从版本控制、备份或可验证产物人工修复后再继续，不得用 `state set` 覆盖损坏文件
+
+```bash
+comet state select <change-name>
+```
+
+创建新 change 时，必须先完成 `.comet.yaml` 初始化，再立即运行同一命令；状态文件不存在前不得伪造选择。
+
+### 0b. OpenSpec 兼容性检查
+
+在任何 OpenSpec 状态或指令命令前运行：
+
+```bash
+comet classic openspec -- --version
+```
+
+本流程要求 **OpenSpec >= 1.5.0**。版本低于 1.5.0、无法解析版本、命令不可用或返回非零退出码时立即停止，并提示运行 `npm install -g @fission-ai/openspec@latest` 后重试；不得继续使用缺少 `applyRequires`、`artifactPaths`、`changeRoot` 或 `resolvedOutputPath` 契约的旧 CLI。
 
 ### 1. 探索想法与需求澄清
 
 **立即执行：** 使用 Skill 工具加载 `openspec-explore` 技能。禁止跳过此步骤。
 
+<!-- external-openspec-skill-override -->
+**外部 OpenSpec Skill 覆写：** 加载后只采用其探索方法；其中任何直接运行官方 CLI、切换到固定 cwd 或读写固定物理 OpenSpec 路径的指令都不得执行。所有 CLI 调用改用 `comet classic openspec -- <args...>`，所有文件路径改用本轮绑定的 `<classic-*>` 逻辑根。
+
 技能加载后，按其指引探索问题空间，但不得把一次问答视为足够澄清。必须围绕下列内容继续提问、对齐并形成澄清摘要：
 - 目标：用户真正要解决的问题和期望结果
 - 非目标：本次明确不做的内容
@@ -57,77 +86,106 @@ description: "Use when Comet 需要创建新的 OpenSpec change，或 active cha
 
 不得在用户完成 PRD 拆分选择前创建 proposal.md、design.md 或 tasks.md。若用户选择创建多个 change，当前 `/comet-open` 调用只负责完成拆分确认与调度，随后按用户确认的顺序分别进入每个拆分项的 `/comet-open`。
 
+用户确认创建多个 changes 后，必须立即把确认结果持久化到 `.comet/batches/<batch-id>.json`。`batch-id` 使用稳定的 kebab-case 标识；文件至少记录 `version`、原始目标摘要、创建时间、按顺序排列的 change 名称，以及每项的目标、范围、非目标、验收场景和 `pending|open-complete|selected` 状态。每创建或完成一个拆分项后原子更新该文件。它只是批量编排清单，不替代各 change 的 `.comet.yaml`。
+
 批量拆分模式下，进入每个拆分项的 `/comet-open` 时必须明确标注「已确认拆分项」并携带该拆分项的目标、范围、非目标和验收场景。已确认拆分项默认跳过 PRD 拆分预检，除非该拆分项本身仍明显包含多个独立 capability。
 
-批量拆分模式下，单个拆分项完成 open 阶段后不得自动流转到 `/comet-design`。拆分完毕后必须暂停询问用户开始哪一个 change；用户选择后，只推进该 change 进入 `/comet-design`，其他 change 保持 active，稍后通过 `/comet` 恢复。
+批量拆分模式下，单个拆分项完成 open 阶段后不得自动流转到 `/comet-design`。拆分完毕后必须暂停询问用户开始哪一个 change；用户选择后，只推进该 change 进入 `/comet-design`，其他 change 保持 active，稍后通过 `/comet-classic` 恢复。
 
-最小断点恢复规则：不新增专用批量状态文件。若批量拆分过程中断，恢复时先检查已创建的 active changes；已存在且包含 `.comet.yaml` 的拆分项不得重复创建，未创建的拆分项按用户已确认的拆分清单继续通过 `/comet-open` 创建。若对话中已确认的拆分清单不可恢复，必须重新向用户确认拆分清单后再继续。
+**批量完成硬性检查（不得跳过）**：全部拆分项完成各自的 open 阶段后，对用户确认清单中的每个 `<name>` 逐个运行：
 
-### 1b. 需求澄清完成确认（阻塞点）
+```bash
+comet classic openspec -- status --change "<name>" --json
+comet state check <name> design
+```
 
-创建 OpenSpec artifacts 前，必须按 `comet/reference/decision-point.md` 的协议暂停并等待用户确认需求澄清完成。
+解析 OpenSpec JSON 时必须同时确认：
+- `changeRoot` 解析后必须等于 resolver 绑定的 `<classic-change-dir>`；不匹配时停止，Classic runtime 不支持仓库外 change root
+- schema 必须包含核心 artifact ID `proposal`、`design`、`tasks`；允许存在额外 artifacts，但核心 ID 缺失时停止并报告不兼容 schema
+- `applyRequires` 列出的每个 artifact 在 `artifacts` 中都必须为 `done`
+- `artifactPaths.<artifact-id>.existingOutputPaths`（或 instructions 返回的 `resolvedOutputPath`）对应的实际输出必须存在且非空
+- `isComplete` 仅作诊断信息；不能替代 `applyRequires` 的实现就绪判定，也不能要求非必需 artifact 阻塞阶段推进
 
-暂停时必须展示澄清摘要：目标、非目标、范围边界、关键未知项、验收场景草案。
+任一拆分项未通过检查时，不得宣告拆分完成，也不得询问用户开始哪个 change；必须停止并从该 change 的第一个 `ready` 或 `blocked` artifact 恢复 `/comet-open`。OpenSpec 检查通过但 Comet state 检查失败时，必须先修复 `.comet.yaml` 初始化或 phase，再重新执行整批检查。
 
-不得在用户确认需求澄清完成前创建 proposal.md、design.md 或 tasks.md，也不得使用 Skill 工具加载 `openspec-propose` 技能一次性生成全部 artifacts。
+只有所有拆分项都通过两项 CLI 检查后，才暂停询问用户开始哪一个 change；用户选择后，把批量清单中的该项标记为 `selected`，只推进该 change 进入 `/comet-design`，其他 change 保持 active，稍后通过 `/comet-classic` 恢复。
 
-### 1c. Change 名称确认（阻塞点）
+断点恢复时先读取 `.comet/batches/<batch-id>.json`，再对清单中已创建的 active changes 运行上述 CLI 检查；已完整通过的拆分项不得重复创建，未通过的拆分项从 OpenSpec 返回的第一个 `ready` artifact 继续。未创建项按持久清单继续创建。清单缺失或损坏时停止并请求用户重建/确认，不能从目录列表猜测原始批次边界。
 
-创建 change 目录（`openspec new change`）前，必须按 `comet/reference/decision-point.md` 的协议暂停，让用户决定 change 名称。不得自动生成或静默推断 change 名称。
+### 1b. 需求与 Change 名称解析（默认不阻塞）
 
-OpenSpec change 名称必须是 **kebab-case 英文**（小写字母、数字、连字符；如 `refine-requirements-doc`）。中文或其他不合规名称无效。
+创建 OpenSpec artifacts 前，把 Step 1 的澄清结果整理为 resolved brief：目标、非目标、范围边界、关键未知项和验收场景草案，并基于它派生一个能准确表达范围的 kebab-case 英文 change 名称。
 
-暂停时必须展示：
-- 基于已确认澄清摘要派生的 **2-3 个推荐 kebab-case 英文名**，每个附一行说明其隐含范围
-- 一个让用户 **自行输入名称** 的明确选项
-- 提示：**若用户输入中文（或任何非 kebab-case 文本），会被转换为合规的 kebab-case 英文名**，转换结果必须回显给用户确认后才能使用
+- **范围与命名都明确时直接继续**，不得仅为了让用户批准摘要或名称而创建停顿点；最终审视会统一确认 change 名称、范围和产物内容
+- 用户已经提供名称时，规范化为 kebab-case 并在进度说明中回显；规范化不改变含义时无需再次确认
+- 已确认批量拆分项直接复用批量清单中的摘要与名称；检测到范围漂移或清单信息缺失时，才重新澄清
+- 只有仍存在会改变范围或目标 change 身份的互斥选择时，才按 `comet/reference/decision-point.md` 提出一个联合问题；命名偏好本身不是独立阻塞点
 
-决策选项必须包含：
-- 选择某个推荐名称
-- 「自行输入名称」——接收用户输入；若已是合规 kebab-case 英文则直接使用；若为中文或其他不合规形式，则转换为合规 kebab-case 英文并回显转换后的名称，确认后再继续
+OpenSpec change 名称必须是 kebab-case 英文（小写字母、数字、单连字符）。若名称冲突但目标仍明确，派生一个不冲突且语义稳定的名称并继续；只有无法判断应复用现有 change 还是创建新 change 时才交给用户选择。
 
-不得在用户确认最终 change 名称前运行 `openspec new change` 或创建 `.comet.yaml`。若选定/转换后的名称与已有 change 冲突，必须报告冲突并请用户另选名称。
+resolved brief 或 change 名称仍不明确时不得运行 `comet classic openspec -- new change`，也不得创建 proposal/design/tasks；继续澄清或处理真正的用户决策后再进入 Step 2。
 
 ### 2. 创建 Change 结构 + 初始化状态
 
 **立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。禁止跳过此步骤。
 
-完整 `/comet` 流程默认不得使用 Skill 工具加载 `openspec-propose` 技能；只有用户明确要求一次性生成提案和 artifacts 时才允许加载。
+<!-- external-openspec-skill-override -->
+**外部 OpenSpec Skill 覆写：** 加载后只采用其 change 创建语义；其中任何直接运行官方 CLI、切换到固定 cwd 或把 change 写到固定物理 OpenSpec 根的指令都不得执行。创建、status 与 instructions 全部改用 `comet classic openspec -- <args...>`，文件路径全部改用 `<classic-change-dir>` 等本轮逻辑根。
+
+完整 `/comet-classic` 流程默认不得使用 Skill 工具加载 `openspec-propose` 技能；只有用户明确要求一次性生成提案和 artifacts 时才允许加载。
+
+<!-- external-openspec-skill-override -->
+**外部 OpenSpec Skill 覆写：** 对 `openspec-propose` 同样不得采用其直接官方 CLI、固定 cwd 或固定物理 OpenSpec 路径；命令必须通过 adapter，产物必须写入 resolver 返回的 `<classic-*>` 逻辑根。
+
+技能加载后，按其指引创建 change 骨架；当 Step 1b 已形成范围明确的 resolved brief 时，覆盖其"STOP and wait for user direction"行为，避免重复询问。
+
+直接使用 Step 1b 的 resolved brief 填充产物内容。只有 brief 仍有会改变范围的歧义时，才回退到技能的提问流程。
+
+change 骨架创建后立即初始化可恢复状态，不能等 artifacts 全部生成后再写 `.comet.yaml`：
+
+```bash
+comet state init <name> full
+comet state select <name>
+comet state check <name> open
+```
 
-技能加载后，按其指引创建 change 骨架，但当 Step 1b 的已确认澄清摘要已存在于对话上下文时，覆盖其"STOP and wait for user direction"行为。
+任一命令失败都停止。随后运行一次 `comet classic openspec -- status --change "<name>" --json` 并执行兼容性预检：
 
-如果用户已确认澄清摘要（Step 1b），直接使用该摘要填充产物内容。如果不存在澄清摘要（边缘情况），回退到技能的默认行为，询问用户。
+- `changeRoot` 解析后必须等于 resolver 绑定的 `<classic-change-dir>`，`planningHome`（如存在）也必须位于当前仓库；不支持仓库外 artifact 路径
+- `artifacts` 必须包含核心 ID `proposal`、`design`、`tasks`，额外 artifacts 允许存在
+- `applyRequires` 必须是可解析的 artifact ID 列表，且每个 ID 都存在于 `artifacts`
+- 载荷缺字段、路径越界或核心 ID 缺失时立即停止，不能回退为猜测的固定模板
 
-change 骨架创建后，按以下标准产物循环逐个生成 `proposal`、`design`、`tasks`：
+预检通过后，按 OpenSpec CLI 返回的 schema 和依赖图生成实现所需 artifacts：
 
-**标准产物循环**（对每个 `artifact-id`：`proposal` → `design` → `tasks`）：
+**OpenSpec 状态驱动产物循环**：
 
-1. 刷新状态：`openspec status --change "<name>" --json`
-2. 获取产物指令：
+1. 运行 `comet classic openspec -- status --change "<name>" --json` 并解析完整 JSON。
+2. 若 `applyRequires` 中每一项都已是 `done`，退出循环；`isComplete` 只记录为诊断信息，不作为阶段阻塞条件。
+3. 从尚未完成且为 `status: "ready"` 的 artifacts 中，优先选择能够推进 `applyRequires` 依赖闭包的项，并按 CLI 返回顺序处理。不得硬编码生成顺序，也不得假设 schema 只有 proposal/design/tasks。
+4. 对每个 ready 的 `<artifact-id>` 获取实时指令：
 
    ```bash
-   openspec instructions proposal --change "<name>" --json
-   openspec instructions design --change "<name>" --json
-   openspec instructions tasks --change "<name>" --json
+   comet classic openspec -- instructions <artifact-id> --change "<name>" --json
    ```
 
-3. 对返回的 JSON 指令载荷，必须：
+5. 对返回的 JSON 指令载荷，必须：
    - 读取 `dependencies` 中列出的每个已完成依赖产物
    - 以 `template` 作为产物结构
    - 遵循 `instruction` 的指引
    - 将 `context` 和 `rules` 作为约束条件应用，**不得复制到 artifact 内容中**
-   - 写入 `resolvedOutputPath`
-   - 验证输出文件存在且非空
-4. 每创建一个 artifact 后，重新运行 `openspec status --change "<name>" --json` 确认状态，然后继续下一个 artifact
+   - 写入 `resolvedOutputPath`；通配输出必须按 instruction 创建每个实际文件
+   - 验证 CLI 返回的实际输出文件存在且非空
+6. 每创建一个 artifact 后，重新运行 status，并再次校验 `changeRoot`、核心 ID 和 `applyRequires`。已经变为 `done` 的项不得重复生成；新变为 `ready` 的项进入下一轮。
 
-**失败处理**：如果 `openspec instructions` 失败、返回无效 JSON、报告未满足的 `dependencies`、或未提供可用的 `resolvedOutputPath`，必须立即停止 artifact 创建并报告 OpenSpec 错误。不得回退为硬编码文档结构，因为那样会绕过项目规则。
+**阻塞与失败处理**：`applyRequires` 尚未全部完成但没有任何可推进其依赖闭包的 ready artifact 时，必须报告相关 `blocked` artifact 的 `missingDeps` 并停止，不得猜测顺序或跳过依赖。如果 adapter 的 `status` / `instructions` 调用失败、返回无效 JSON、路径逃逸仓库、或未提供可用的 `resolvedOutputPath`，也必须立即停止并报告 OpenSpec 错误。不得回退为硬编码文档结构。
 
-**命名与范围守卫**：change name 必须使用 Step 1c 中用户确认的 kebab-case 英文名，不得自动生成、推断或使用非 kebab-case（如中文）名称。变更范围必须与用户描述一致，不得自行扩大或缩小。
+**命名与范围守卫**：change name 必须使用 Step 1b 解析出的 kebab-case 英文名，不得使用非 kebab-case（如中文）名称。变更范围必须与 resolved brief 和用户描述一致，不得自行扩大或缩小。
 
 确认以下产物已创建：
 
 ```
-openspec/changes/<name>/
+<classic-change-dir>/
 ├── .openspec.yaml
 ├── .comet.yaml
 ├── proposal.md       # Why + What：问题、目标、范围
@@ -135,43 +193,45 @@ openspec/changes/<name>/
 └── tasks.md          # 任务清单（勾选框）
 ```
 
-创建 `.comet.yaml` 状态文件：
-
-先按 `comet/reference/scripts.md` 定位脚本（定位 `comet-env.mjs`），然后初始化状态：
-
-```bash
-node "$COMET_STATE" init <name> full
-```
-
 ### 3. 入口状态验证
 
 验证状态机已正确初始化：
 
 ```bash
-node "$COMET_STATE" check <name> open
+comet state check <name> open
 ```
 
 验证通过后继续 Step 4。验证失败时脚本会输出具体失败原因。
 
-**幂等性**：open 阶段所有操作可安全重复执行。如 `.comet.yaml` 已处于 `phase: open` 且三个产物文件均已存在，跳过已完成步骤，从第一个缺失步骤继续。
+**幂等恢复算法**：open 阶段所有操作可安全重复执行。恢复时按以下顺序处理：
+
+1. 状态文件缺失时先运行 `comet state init <name> full`；格式异常时停止并修复，不得覆盖。随后选择 change 并运行 `comet state check <name> open`。
+2. 运行 `comet classic openspec -- status --change "<name>" --json`，重新验证 `changeRoot`、核心 ID、`applyRequires`、`artifacts` 和 `missingDeps`。
+3. `done`：该 artifact 已完成，保持原文件不变，不重复生成。
+4. `ready`：依赖已经满足，可以生成。先运行 `comet classic openspec -- instructions <artifact-id> --change "<name>" --json`，按返回内容写入；写完后立刻重新运行 status。
+5. `blocked`：读取 `missingDeps`，先完成属于 `applyRequires` 依赖闭包的依赖 artifact；每完成一个依赖都重新运行 status，不能直接生成 blocked artifact。
+6. 重复上述处理，直到 `applyRequires` 全部为 `done`。
+
+如果必需依赖图无法推进，必须列出相关 blocked artifact 及其 `missingDeps` 后停止并报告。目录或固定三个文件存在不能替代 CLI 判定；反过来，非 `applyRequires` 的可选 artifact 也不能仅因 `isComplete: false` 阻塞进入实现阶段。
 
 ### 4. 内容完整性检查
 
-确认三个文档内容完整：
-- **proposal.md**：问题背景、目标、范围、非目标
-- **design.md**：高层架构决策、方案选型、数据流
-- **tasks.md**：任务列表，每个任务有明确描述
+再次运行 `comet classic openspec -- status --change "<name>" --json`，确认核心 ID 存在、`applyRequires` 每项均为 `done`，且这些必需 artifacts 的 `artifactPaths.<id>.existingOutputPaths` 返回的实际输出文件存在且非空。任一条件不满足时，不得进入 Step 5 或执行阶段守卫。
 
-**文件存在性验证**：逐个确认三个文件路径存在且非空。任一文件缺失或为空时，不得进入 Step 5 或执行阶段守卫，必须回到创建步骤补充。
+随后检查关键 artifact 内容：proposal 覆盖问题、目标、范围和非目标；design 覆盖高层决策与数据流；tasks 包含明确任务；schema 返回 specs 等其他 artifact 时，也必须按其 instructions 检查内容，不能因固定三件套存在而跳过。
 
 ### 5. 用户审视确认（阻塞点）
 
-三个文档创建完成且内容完整性检查通过后，**必须按 `comet/reference/decision-point.md` 的协议暂停并等待用户确认**。不得在用户确认前执行阶段守卫或自动流转。
+全部 OpenSpec artifacts 完成且内容完整性检查通过后，**必须按 `comet/reference/decision-point.md` 的协议暂停并等待用户确认**。不得在用户确认前执行阶段守卫或自动流转。
+
+最终审视同时确认 change 名称、范围和产物内容；不得因 Step 1b 已完成解析而省略，也不得在此之前再增加一次常规摘要/命名确认。
 
 用户确认问题必须以单选题形式呈现，包含以下摘要和选项：
 
 **摘要内容**：
+- **change 名称与 resolved brief**：最终名称、目标、非目标、范围边界和关键未知项
 - **proposal.md**：问题背景、目标、范围
+- **specs 等 schema artifacts**：能力、需求和关键验收场景
 - **design.md**：高层架构决策、方案选型
 - **tasks.md**：任务数量和关键任务描述
 
@@ -183,14 +243,14 @@ node "$COMET_STATE" check <name> open
 
 ## 退出条件
 
-- proposal.md、design.md、tasks.md 均已创建且内容完整
-- **用户已确认** proposal、design、tasks 内容符合预期
-- **阶段守卫**：运行 `node "$COMET_GUARD" <change-name> open --apply`，全部 PASS 后由守卫推进到下一阶段（此步骤更新 `phase` 字段，与 `auto_transition` 无关）
+- `comet classic openspec -- status --change "<name>" --json` 的兼容性预检通过，`applyRequires` 全部为 `done` 且必需输出非空
+- **用户已确认** 全部 OpenSpec artifacts 内容符合预期
+- **阶段守卫**：运行 `comet guard <change-name> open --apply`，全部 PASS 后由守卫推进到下一阶段（此步骤更新 `phase` 字段，与 `auto_transition` 无关）
 
 退出前必须使用 `--apply`，否则 `.comet.yaml` 仍停留在 `phase: open`，下一阶段入口检查会失败。
 
 ```bash
-node "$COMET_GUARD" <change-name> open --apply
+comet guard <change-name> open --apply
 ```
 
 完整流程会自动更新为 `phase: design`；hotfix/tweak 预设会自动更新为 `phase: build`。
@@ -200,11 +260,11 @@ node "$COMET_GUARD" <change-name> open --apply
 按 `comet/reference/auto-transition.md` 执行。关键命令：
 
 ```bash
-node "$COMET_STATE" next <change-name>
+comet state next <change-name>
 ```
 
 - `NEXT: auto` → 调用 `SKILL` 指向的 skill 进入下一阶段
-- `NEXT: manual` → 不要调用下一 skill，按 `HINT` 提示用户手动运行 `/<SKILL>`
+- `NEXT: manual` → 不调用下一 skill，按 `HINT` 交还控制权并结束当前调用；不再创建确认点
 - `NEXT: done` → 流程已完成，无需继续
 
 hotfix/tweak 预设由对应预设 Skill 控制后续流转（phase 直接进入 build），其 `next` 会返回对应预设 Skill。