Changelog

​

Added

• CLI i18n shared module: 将初始化时的翻译表抽取到 src/commands/i18n.ts，使 init、update 及未来的命令能够一致地共享英文字符串，而不是每个命令各自复制一份翻译表。
• Optional npm dependency prompts in init/update: comet init 和 comet update 现在对 OpenSpec CLI、Superpowers（通过 npx skills add）和 CodeGraph CLI 提供多选提示，而不是强制安装。系统上尚未检测到的项目默认勾选；已安装的项目默认不勾选，让用户可以选择升级而不被强制。Superpowers 选项还会推荐安装 v6.0.0+（速度约提升 2 倍，token 减少约 50%）。
• --language option for comet init: 新增 CLI 标志（en/zh），以非交互方式选择 skill 语言，与既有的 comet update --language 选项保持一致（#109）。
• review_mode field for code review control: 在 .comet.yaml 中新增字段 review_mode（off / standard / thorough），控制 build 和 verify 阶段的自动代码评审。comet-build 要求在执行之前由用户选择；comet-verify 和子 agent 调度根据模式调整行为；comet-hotfix 默认为 off。由 comet-state.sh、comet-guard.sh 和 comet-yaml-validate.sh 校验。
• Project-level review mode defaults: .comet/config.yaml 现在可以设置 review_mode: off|standard|thorough，该值会被快照到新的 full workflow change 中，让团队可以选择项目范围的自动评审默认值，同时保留既有的逐 change 状态行为。新生成的配置文件包含 context_compression、review_mode 和 auto_transition 的枚举注释，用户无需查阅文档即可调整支持的值。
• Uninstall by platform selection: comet uninstall 现在在检测到多个平台时显示复选框提示，允许用户选择性地卸载特定平台，而不是一次性全部移除。单目标场景使用简单的 yes/no 确认。--force 和 --json 标志保留既有的全部一次性移除行为。
• Codex plugin-installed Superpowers detection: comet init 现在能检测通过 Codex 插件缓存（~/.codex/plugins/cache/...）已安装的 Superpowers，防止重复安装——与既有的 Claude Code 和 OpenCode 插件检测平行（#115）。

​

Changed

• Tagline rebrand: 将 comet init banner 以及 package.json / CLI --description 中的 Comet 标语从 “OpenSpec + Superpowers dual-star development workflow” 改为 “Agent Skill Harness Phase-Guarded Automation From Idea To Archive”，按核心价值（阶段守卫的 agent skill 框架）而非底层 OpenSpec + Superpowers 依赖来定位 Comet。
• Change name confirmation as a blocking decision point: comet-open SKILL.md（中英文）现在新增了专门的 Step 1c，在 openspec new change 之前暂停以确认 change 名称。agent 必须从澄清摘要中推导出 2-3 个 kebab-case 英文候选名，始终提供自定义输入选项，并警告中文（或任何非 kebab-case）输入将被转换为合规的 kebab-case 英文名称并回显确认——防止 agent 自动生成不合规的中文 change 名称。
• Non-ASCII change name prevention: 在 comet-open SKILL.md（中英文）中新增了显式的 ASCII 校验规则，防止 agent 自动生成包含中文、日文、韩文字符、空格或特殊字符的不合规 change 名称。agent 现在必须向用户请求一个符合 ASCII 的名称。
• Chinese gate-term normalization: 更新了中文 Comet 措辞，避免将 gate 直译为”门”：Design Step 1e 现在使用”主动式上下文压缩”，共享的调试指引现在使用”异常调试协议”，且 CLAUDE.md / AGENTS.md 现在将其定义为未来 skill 编辑的标准中文翻译规则。
• Full i18n coverage for CLI prompts: 将翻译覆盖范围从仅 init 扩展到也覆盖 update（banner、npm 更新进度、skill 复制进度、摘要、codegraph 提示）。所有面向用户的字符串现在都有英文和中文两种变体（#109）。

​

Fixed

• Phase-skip enforcement across all guard layers: 修复了 agent 从 open 直接跳到 build（跳过 design）而未被检测到的问题。comet-state.sh 现在在每个向前转换时强制要求证据；直接 set phase 被阻止（带有 COMET_FORCE_PHASE=1 逃生口）；comet-hook-guard.sh 在 design_doc 为 null 时阻止源码写入；comet-phase-guard 规则新增阶段入口自洽检查，要求在写入源码之前具备前置产物。
• Hook guard cross-change false positives: 修复了 comet-hook-guard.sh 让一个 change 的阶段错误地阻止对另一个 change 写入的问题。写入到 openspec/changes/<name>/ 的操作现在由该 change 自己的 .comet.yaml 阶段控制，而不是由目录中找到的第一个活跃 change 控制。这涵盖了此前阻止全新 change 产物写入的两种情况：（1）一个标记为 archived: true 但尚未物理移到 archive/ 子目录的旧 change，以及（2）一个停滞在 archive 阶段且 archived: false（尚未运行归档脚本）的旧 change。此外，.comet.yaml 尚不存在的新 change 目录（在 /comet-open 期间，产物在状态文件之前写入）被视为 open，因此 proposal/design/tasks/specs 的写入是被允许的。
• CodeGraph setup detection: 修复了即使项目已有 .codegraph/ 索引，comet init 和 comet update 仍会提示进行 CodeGraph 设置的问题。现有的项目索引现在会跳过可选的 CodeGraph 提示和安装步骤，且 CodeGraph CLI 解析可以使用 pnpm 全局二进制文件，再回退到 npm 全局安装。
• Phase guard auto-transition handoff: 修复了注入的 Comet 阶段守卫规则在 guard --apply 之后硬编码下一个 skill 的问题，这可能绕过 auto_transition: false。该规则现在将守卫后的交接委托给 comet-state next <change-name>，并遵循 NEXT: auto|manual|done，从而尊重手动阶段边界。
• Executable permission loss on macOS after update: bin/comet.js 和 assets/skills/comet/scripts/ 下的所有 shell 脚本此前以 git 模式 100644（不可执行）提交。npm 更新后，macOS 用户丢失了 comet CLI 入口点的执行权限。已将所有 8 个文件在 git 中改为 100755，使 npm 安装始终保留可执行位。

​

Tests

• Phase-skip enforcement coverage: 新增了 shell 脚本测试，覆盖加固后的守卫层——当 open 产物缺失时阻止 open-complete、根据 design_doc 是否存在阻止/允许 design-complete、在 verify_result: pass 之前阻止 archived、阻止直接 set phase 同时允许 COMET_FORCE_PHASE 逃生口，以及在 design_doc 为 null 时阻止 full workflow 的 build 源码写入，同时仍允许预设工作流和带有效 design_doc 的 full workflow。
• Project review mode default coverage: 新增了回归测试覆盖 .comet/config.yaml 中 review_mode 快照到 full workflow change、拒绝无效的项目评审模式，以及生成的项目配置文件中的枚举注释。
• CodeGraph setup coverage: 新增了针对现有 .codegraph/ 索引检测、跳过冗余 CodeGraph 安装、pnpm 全局 CLI 解析，以及在项目索引已存在时抑制更新时 CodeGraph 提示的回归测试。
• Phase guard handoff coverage: 新增了 skill 规则回归覆盖测试，确保阶段守卫委托给 comet-state next，不再嵌入可能忽略 auto_transition 的固定下一步 skill 映射。
• review_mode integration coverage: 新增了回归测试，验证 review_mode 贯穿状态、守卫和校验脚本，并在 comet-build/comet-verify/comet-hotfix 中具有正确的特定模式行为。
• Uninstall platform selection coverage: 新增了针对单目标自动选择、多目标复选框选择、用户取消、--force 跳过、--json 输出以及未找到目标处理的测试。

​

Added

• Kimi Code CLI support: 新增 Kimi Code 作为第 29 个受支持的平台，包括在 .kimi-code/ 下的项目/全局 skill 安装、OpenSpec 的 kimi 工具集成、Superpowers 的 kimi-code-cli 映射、检测、文档以及跨平台回归测试覆盖（#90）。
• Version info and update check: comet init 和 comet update 现在会在命令输出开头显示当前已安装的 Comet 版本，并检查 npm registry 是否有更新版本。如果有可用更新，用户会看到升级提示；如果已是最新版本，则显示确认消息；如果无法访问 registry，则静默跳过检查而不报错（#99）。
• Official registry enforcement for update: comet update 现在在更新 @rpamis/comet 包时向 npm 传入 --registry https://registry.npmjs.org，确保无论用户的本地 .npmrc 或镜像配置如何，始终从官方 npm registry 拉取。其他包继续使用用户正常的 registry 设置。如果官方 registry 不可访问，会显示明确的错误消息指出 registry 问题（#100）。
• Subagent dispatch Comet extensions: 将 comet-build/SKILL.md 中内联的子 agent 调度协议重写为 comet/reference/subagent-dispatch.md（中英文），作为叠加在 Superpowers subagent-driven-development skill 之上的 Comet 专属扩展。该 skill 提供核心调度循环；Comet 扩展增加了真正的后台调度、持久的逐任务检查点（subagent-progress.md）、仅协调者执行源码、由后台 agent 负责 TDD、有界的评审-修复轮次（最多 3 轮）、无暂停的连续任务执行，以及从检查点阶段的精确上下文恢复。
• task-checkoff subcommand: 新增 comet-state task-checkoff <file> <task-text>，用于验证特定任务在 markdown 文件中是否被唯一勾选。供子 agent 调度协议在双重评审通过后进行针对性的完成验证。包含路径遍历防护、CRLF 处理和精确匹配校验。
• comet uninstall command: 新增 comet uninstall [path] CLI 命令，可安全地移除 Comet 分发到所有 29 个受支持 AI 编码平台的 skill、规则和 hook。支持 --scope（project/global）、--force（跳过确认）和 --json 输出。自动检测已安装的目标，仅移除 Comet 管理的产物，同时保留用户自定义的 hook 和非 Comet 配置，清理空目录和工作目录（.comet/、docs/superpowers/），并处理所有 7 种 hook 格式（Claude Code、Qwen、Qoder、Gemini、Windsurf、GitHub Copilot、Kiro）和所有 3 种规则格式（md、mdc、copilot instructions）（#95）。
• Progressive loading reference docs: 从内联 skill 内容中抽取了四份参考文档以实现按需加载，降低每次调用的 token 成本（中英文）：auto-transition.md（自动阶段推进协议，替代各子 skill 中 7 × 约 10 行的重复内容）、context-recovery.md（上下文压缩恢复，替代 4 × 约 8 行）、comet-yaml-fields.md（.comet.yaml 字段表，约 40 行）和 file-structure.md（目录结构，约 20 行）。主 comet/SKILL.md 内联保留了关键的状态机硬约束，同时指向参考文档以获取详细的字段说明。预计每次调用节省：600–1500 token（取决于 skill）；完整工作流累计节省约 4100 token。
• Pre-commit formatting hook: 新增 husky + lint-staged 的 pre-commit hook，在每次 git commit 时自动对 src/ 目录下的暂存源文件运行 prettier --write（范围与 CI 的 format:check 对齐）。与编辑器无关——对所有贡献者强制执行，无论使用何种 IDE 或 agent——防止 Prettier 格式问题进入 CI。prepare 脚本会在 pnpm install 时安装该 hook，且 .husky/ 通过 files 白名单从发布的包中排除。

​

Changed

• Skills progressive loading refactor: 中英文所有 7 个子 skill（comet-open、comet-design、comet-build、comet-verify、comet-archive、comet-hotfix、comet-tweak）现在引用共享的协议文档来处理自动阶段推进和上下文恢复，而不是内联嵌入完整内容，同时保留关键的内联命令（next 命令及输出解读）以确保安全地独立加载。
• Phase guard recovery with durable checkpoints: 更新了 comet-phase-guard.md（中英文）中的恢复步骤，重新加载 Superpowers 的 subagent-driven-development skill，读取 subagent-progress.md 进行精确的阶段恢复（实现提交、RED/GREEN 证据、已通过的评审、未解决的反馈、评审-修复轮次），并从检查点的精确阶段继续，而不是总是从第一个未勾选任务开始。.claude/rules/ 和 assets/skills/comet/rules/ 两份副本都包含一致的引用，并使用双语标识符以保证跨语言测试兼容性。
• Decision point protocol extraction: 将所有 7 个子 skill（comet-open、comet-design、comet-build、comet-verify、comet-archive、comet-hotfix、comet-tweak）和主 comet/SKILL.md 中内联的用户决策点文本抽取到共享的 comet/reference/decision-point.md（中英文）。子 skill 现在通过路径引用协议，而不是重复完整的阻塞点规则，降低每次调用的 token 成本并确保各 skill 之间的一致性。
• Debug gate protocol extraction: 将 comet-build、comet-hotfix 和 comet-tweak 中内联的 systematic-debugging 四阶段流程抽取到共享的 comet/reference/debug-gate.md（中英文）。子 skill 现在通过路径引用调试关卡协议，集中了调查、最小失败测试、修复验证和验证循环的规则。
• Lightweight verification review: 轻量验证现在要求进行一次聚焦于正确性、安全性和边界情况的 Superpowers requesting-code-review 评审，在不运行完整 spec 或设计漂移检查的情况下增加评审覆盖（#86）。

​

Fixed

• Pi slash command discovery: comet init 和 comet update 现在会生成一个 Pi 扩展，将所有内置的 /comet* 工作流注册为原生斜杠命令并转发到 /skill:*。Pi 设置以非破坏性方式合并，启用 skill 命令；全局资源现在使用 Pi 官方文档记载的 ~/.pi/agent/ 目录，会检测旧的 ~/.pi/skills/ 安装以进行更新和清理，且 comet uninstall 仅移除 Comet 管理的资源，同时保留共享设置和无关的扩展（#89）。
• OpenCode plugin-installed Superpowers detection: comet init 现在能正确检测通过 OpenCode 插件系统（在 opencode.json 中配置）已安装的 Superpowers，防止重复安装。此前只能检测直接放在 ~/.config/opencode/skills/ 下的 skill，遗漏了 ~/.config/opencode/superpowers/skills/ 的插件源目录以及 opencode.json 中的 plugin 数组。新增了 hasOpenCodePluginSuperpowers() 回退检测，类似于现有的 Claude Code 插件缓存检查（#105）。
• Lightweight verification consistency: hotfix 文档现在描述了 6 项轻量验证路径，验证失败处理将 CRITICAL 和 IMPORTANT 发现视为阻塞项，使评审通过标准和失败决策保持一致。
• Hook configuration merging during init and update: Claude Code、Codex、Amazon Q、Qwen、Qoder、Gemini 和 Windsurf 的共享 hook 配置文件，现在在 Comet 为同一 matcher 或事件安装/更新 hook 时会保留用户自定义的 hook。现有的 Comet 命令通过其清单脚本路径识别并原地替换，防止过时的安装路径、重复的 matcher 分组和重复的 hook 累积，同时不影响无关的设置。
• Subagent-driven task isolation and continuity: comet-build 现在加载成熟的 Superpowers subagent-driven-development 循环，并应用更严格的 Comet 扩展，要求每个任务使用全新的后台实现者、全新的后台评审者和修复 agent、仅协调者执行源码，以及任务之间自动连续执行而不产生进度摘要或”continue?”提示。TDD 模式要求每个实现者/修复 agent 加载 TDD skill，并在评审前返回可审计的 RED/GREEN 证据。持久的逐任务检查点在上下文压缩过程中保留实现提交、评审阶段、反馈和三轮重试预算；任务勾选在两轮评审都通过之前保持阻塞（#94、#96、#97）。
• npm shebang line ending issue on macOS: 当 npm 在 Windows 上打包项目时，bin/comet.js 的 shebang 行获得 CRLF 行尾，导致 macOS 将 #!/usr/bin/env node\r 解释为 #!/usr/bin/env node 之外的内容，在 npm install -g @rpamis/comet 后出现 “command not found”。在 .gitattributes 中为所有文本文件扩展名（.js、.mjs、.ts、.json、.md、.yaml、.yml）添加了显式的 eol=lf 规则，并为图片文件添加了二进制标记（#82）。
• CodeGraph Codex CLI skip on project scope: 项目范围的 comet init 会向 codegraph install 传入 --target 和 --location=local，导致 Codex CLI（无项目本地配置）被跳过并显示令人困惑的消息。简化为 codegraph install --yes，不传 --target 或 --location 标志，让 CodeGraph 自动检测并配置所有已安装的 agent。移除了 filterSupportedPlatforms 和 CODEGRAPH_SUPPORTED_TARGETS（#98）。
• OpenSpec CLI upgrade and —profile fallback: ensureOpenSpecCli 现在始终安装/升级 openspec 到最新版本，即使已存在旧版本，确保用户获得 --profile 支持和其他改进。新增了回退逻辑：如果 openspec init 在 stderr 中报 “unknown option —profile”，则不带该标志重试，以应对升级失败但残留旧 openspec 的边缘情况（#84）。
• Symlink resolution for skill file copies: 当 skill 目录是符号链接时（例如 ~/.claude/skills/comet -> ~/.agents/skills/comet），copyFile 和 ensureDir 会写入字面路径而不是跟随符号链接目标。损坏的符号链接会导致静默的复制失败。在 file-system.ts 中新增 resolveSymlinkPath()，沿路径树向上遍历并对损坏的符号链接跟随 readlink 目标。已应用于 ensureDir、copyFile 和 writeFile（#85）。
• comet-tweak missing debug handling: comet-tweak/SKILL.md 缺少 comet-hotfix 已有的 systematic-debugging 要求——当 tweak 执行期间测试或构建失败时，该 skill 现在明确要求在提出源码修复之前加载 systematic-debugging skill，与 hotfix 行为保持一致。
• OpenSpec per-artifact instructions compliance: 中英文 comet-open 现在对每个标准产物应用 OpenSpec 的逐产物指令（openspec instructions proposal/design/tasks --change "<name>" --json），从 JSON 载荷中加载 context、rules、template、instruction、resolvedOutputPath 和 dependencies，替代了硬编码的产物文案。在指令失败时停止产物生成，而不是静默绕过项目规则（#66）。
• CI Windows path escaping in skill verification: init-e2e 工作流的 Pi 设置验证步骤将 Windows $RUNNER_TEMP 路径（包含反斜杠）直接插入 node -e "require('...')" 的 JS 字符串字面量中，其中 \a/\_ 被解析为转义字符并破坏了路径（D:\a\_temp → D:a_temp），导致 Node 20 和 22 上 init-e2e (windows-latest) 运行器失败。现在该路径通过环境变量（process.env）传递，使其永远不进入 JS 字符串字面量；Linux/macOS 不受影响。
• OpenSpec source formatting: 重新格式化了 src/core/openspec.ts（长行换行），以满足 prettier --check，解除对 format:check CI 步骤的阻塞。
• Symlink-safe removal during uninstall: removeFile/removeDir 在删除之前不再解析符号链接。此前，符号链接的 skill、规则或 hooks 目录的解析目标会被 comet uninstall 递归删除；现在符号链接目录会被直接 unlink。isDirEmpty 也不再将不可读的目录报告为空，因此清理操作不会删除它无法检查的目录。
• comet update --json output corruption: npm 继承的 stdio 此前会混入 JSON 文档；现在在 JSON 模式下会丢弃 npm 的 stdout/stderr，使机器可读的输出保持可解析。
• comet update --json no-targets shape: 当不存在已安装目标时发出的提前返回 JSON 现在包含 codegraph: 'skipped'，与正常输出结构一致，使消费者无需对空路径做特殊处理。
• JSON-mode version-check latency: comet init 和 comet update 现在在 JSON 模式下跳过 npm registry 的版本检查，无需网络往返即可输出。
• Malformed hook settings resilience: 手工编辑的设置文件将 hook 分组存储为非数组值时，不再在 init/update 的 hook 合并期间抛出异常；格式不正确的分组会被强制转换为空。
• Markdown code-fence language tags: 在 file-structure.md 和 subagent-dispatch.md（中英文）的围栏代码块中添加了 text 语言标签，以满足 MD040 lint 检查，与现有的 OpenSpec 格式化 CI 修复保持一致。
• Skills manifest version drift: 将 assets/manifest.json 版本从 0.3.3 提升到 0.3.8，以与 package.json 保持一致。

​

Tests

• Kimi Code platform coverage: 新增了针对 Kimi Code 的检测、项目/全局安装、OpenSpec 工具映射、Superpowers agent 映射、CI 平台计数和文档的回归测试覆盖。
• Lightweight verification review regression: 新增了双语工作流防护测试，涵盖轻量代码评审要求、阻塞严重级别、限定范围的评审标准以及 hotfix 文档一致性。
• Pi command extension lifecycle coverage: 新增了项目/全局初始化、清单驱动的命令生成、参数转发、设置保留、无效设置保护、确定性覆盖和选择性卸载的回归测试覆盖，以及针对 Pi 项目和全局扩展位置的 CI 断言。
• Hook merge regression coverage: 新增了针对 Claude 风格、Qwen/Qoder、Gemini 和 Windsurf hook 格式的真实文件测试，涵盖同 matcher 用户 hook 保留、过时 Comet 命令替换、无关配置保留，以及幂等的重复安装。
• Subagent dispatch contract coverage: 新增了中英文 skill 内容回归覆盖测试，涵盖 Superpowers/Comet 组合、带跟踪文件例外的仅协调者源码执行、每个任务和角色一个全新后台 agent、提示/状态/评审者证据契约、持久恢复检查点、TDD 归属、双重评审勾选、有界停止条件、连续任务执行、Comet 专属最终交接，以及不存在 Stop hook。
• Reference doc assertions: 新增断言，验证所有引用 decision-point.md 和 debug-gate.md 的 skill 文件都包含正确的协议路径，并且内置的参考文档包含预期的核心规则和回退行为。
• OpenSpec artifact contract coverage: 新增了双语契约断言，验证 comet-open skill 包含针对 proposal、design 和 tasks 的显式 JSON 指令命令；要求应用 context、rules、template、instruction、resolvedOutputPath 和 dependencies；禁止将 context/rules 复制到产物中；在产物之间刷新状态；以及在 OpenSpec 指令失败时停止而非回退。

​

Added

• Auto-transition config: 在 .comet.yaml 和 .comet/config.yaml 项目默认配置中新增了 auto_transition（true|false），让团队可以选择 Comet 是自动推进到下一阶段 Skill，还是暂停等待手动切换。当 auto_transition: false 时，build/design/open/verify skill 在满足退出条件后会停止，并打印下一步的手动操作指引，而不是直接调用下一个 skill。包含状态机白名单、枚举校验以及 schema（comet-yaml-validate.sh）覆盖（#74）。
• Deterministic next-step resolver: 新增 comet-state next <change-name>，根据 .comet.yaml（phase、workflow、auto_transition）解析 guard 之后的路由逻辑，并输出结构化结果：NEXT: auto|manual|done、SKILL: <skill-name> 和 HINT（手动模式下）。这将下一步 skill 的路由逻辑集中到脚本中，避免在各 skill 文案中重复编写。
• Workflow output language: Comet 工作流现在通过显式的输出语言规则，将触发用户请求的语言传播到 OpenSpec 和 Superpowers 步骤中，确保生成的提案、设计、计划、验证报告和归档说明都能以用户的语言呈现，保持可读性。恢复已有的 change 时，会保留产物的主要语言，除非用户明确要求切换（#53、#37）。
• Execution benchmark (Claude Code): 新增 benchmark:execution，一个包含三个测试阶段的基准测试框架：L1（基于交接上下文生成设计文档）、L2（基于交接上下文构建 note-board 模块并运行测试）和 L3（完整工作流——根据规格实现一个 dictionary 模块并运行 10 个 vitest 测试）。调用 Claude Code（claude -p），并测量实际的测试通过率、token 用量、重试次数、耗时和成本。在小/中/大规模下对比 off 与 beta 上下文压缩模式。支持 --phase l1|l2|l3|both|all 和 --dry-run 用于确定性验证。将共享工具函数（spawnCapture、parseClaudeJson、buildClaudeArgs 等）抽取到 scripts/benchmark-utils.mjs。
• Token optimization: TDD skill single load: build skill 现在在第一个任务之前只加载一次 test-driven-development skill（而不是每个任务都加载），在 10 个任务的工作流中可减少约 44K token。包含上下文压缩后的恢复指引，恢复时重新加载一次。
• Token optimization: brainstorming checkpoint: design skill 现在在用户确认设计方案后会写入 brainstorm-summary.md，提供一个上下文压缩恢复点，在上下文窗口压缩过程中保留已确认的决策。
• Token optimization: incremental brainstorming checkpoint: design skill 现在在头脑风暴过程中增量更新 brainstorm-summary.md，在平台驱动的上下文压缩发生之前，保留已确认的事实、候选决策、风险、测试说明和待解决问题。
• Token optimization: active compaction gate: design skill 现在在 brainstorm-summary.md 定稿之后、创建设计文档之前，要求一个主动的上下文压缩检查点，优先使用宿主平台的原生压缩机制，不可用时回退为手动提示用户。
• Token optimization: plan creation subagent offload: build skill 将 writing-plans 的执行卸载给子 agent，释放主会话的上下文。子 agent 从文件中读取设计文档和 tasks.md，并返回计划文件路径。子 agent 失败时回退为内联执行。
• Token optimization: verification skill dedup: verify skill 现在在 light/full 分支判断之前只加载一次 verification-before-completion，而不是在每个分支中都加载，消除了冗余的 skill 内容。
• Token optimization: tasks.md incremental scan: build skill 现在用 grep 查找未完成的任务，而不是在每次任务完成后重新读取整个 tasks.md 文件。
• Token optimization: hash on-demand read in verify: verify skill 在重新读取 OpenSpec 产物之前先检查 handoff_hash。当哈希匹配时，仅跳过 tasks.md（proposal.md 和 design.md 仍会读取以进行比较检查）。使用新增的 comet-handoff.sh --hash-only 标志。
• --hash-only flag for comet-handoff.sh: 新增向后兼容的标志，仅输出上下文哈希而不生成交接文件，供 verify 阶段进行哈希比对使用。在计算哈希之前会校验必需的文件是否存在。
• CodeGraph integration in comet init: comet init 现在提供一个可选步骤来安装和配置 CodeGraph（@colbymchenry/codegraph），用于语义化代码智能。它会自动检测受支持的平台（Claude Code、Cursor、Codex、OpenCode、Gemini、Kiro、Antigravity），若 CLI 缺失则自动安装，运行 codegraph install 进行 agent 接线，并初始化项目索引。在 --json 模式下会优雅跳过。
• Stale PR automation: 新增了一个定时触发且可手动运行的 GitHub Actions 工作流，将 90 天未活动的 pull request 标记为 stale，再过 30 天后关闭，帮助管理长期闲置的评审队列。
• TDD mode field: 在 .comet.yaml 状态机中新增 tdd_mode（tdd|direct），让用户选择在构建时是否强制执行 TDD。当 tdd_mode: tdd 时，子 agent 调度时会注入显式的 TDD 硬约束，绕过 implementer-prompt.md 中的条件触发。解决 #67。
• subagent_dispatch field: 在 .comet.yaml 状态机中新增 subagent_dispatch（null|confirmed），确保 build_mode: subagent-driven-development 只有在平台真实的后台调度能力得到确认后，才能离开 build 阶段。
• Verify retry limit: verify skill 现在在连续 3 次验证失败循环后强制要求用户决策，防止无限自动重试。
• Manual verify_mode override: 当自动检测的模式不合适时，用户可通过 comet-state set <name> verify_mode <light|full> 覆盖自动验证规模评估。
• Local context compression benchmark: 新增 benchmark:context，一个本地 Codex 基准测试框架，会创建匹配的 context_compression: off 和 beta Comet 测试用例，针对每种模式运行 codex exec，并报告 token 节省量、规格漂移率、任务完成率、解析成功率和耗时。使用 --dry-run 进行确定性的非 Codex 验证。
• Beta-gated context compression switch: 项目安装现在会创建带有 context_compression: off 的 .comet/config.yaml，让团队可以通过设置 context_compression: beta 让新的 change 启用 beta 规格投影。此开关仅控制 OpenSpec 交接投影路径（spec-context.*）；上述工作流 token 优化默认开启，无需 beta 模式。
• Beta spec projection handoff: /comet-design 现在可以使用 beta 上下文压缩来生成 spec-context.json 和 spec-context.md，保留 OpenSpec 的需求和场景标题及源哈希，使精简的设计交接在降低 token 负担的同时不削弱验收覆盖度。

​

Changed

• executing-plans review gate: 当 build_mode 为 executing-plans 时，build 阶段现在要求在 build→verify 阶段守卫之前至少加载一次 Superpowers 的 requesting-code-review skill 并请求一次代码评审。CRITICAL 级别的问题必须在 verify 之前修复；已接受的非 CRITICAL 问题必须在持久产物中记录接受理由。build 退出检查清单会强制执行此关卡（#76、#41）。
• Phase advancement vs handoff wording: 中文和英文 Comet skill 现在一致地区分守卫驱动的阶段推进（--apply，始终更新 phase）与下一步 skill 调用控制（auto_transition）。open/design/build/verify/hotfix/tweak 的指引现在统一通过 comet-state next 来路由自动/手动交接。
• 预设连续性措辞: hotfix 和 tweak 指引现在明确记录连续执行模式下的 auto_transition: false 例外情况，移除了围绕 “always continue” 行为的矛盾措辞。
• Verify hash-skip scoped to tasks.md only: 完整验证即使哈希匹配也始终读取 proposal.md 和 design.md，确保目标满足度和设计一致性检查拥有完整上下文。
• Design Doc creation stays in main session: 设计文档以内联方式创建（不卸载给子 agent），以保留完整的头脑风暴对话上下文，防止复杂需求下信息丢失。
• Subagent failure fallback: 计划创建的子 agent 卸载包含显式的降级回退——如果子 agent 失败，主会话会内联加载 writing-plans。
• Beta spec verbatim projection: beta 上下文压缩现在按原样投影整个 spec 文件（cat），而不是按英文关键词（GIVEN/WHEN/THEN/AND/BUT）过滤。这消除了语言相关的匹配，确保中文或非英文 spec 的验收标准零漂移，并彻底移除了脆弱的 AWK 过滤器。
• JSON structural validation: comet-guard.sh 现在校验 spec-context.json 的结构（必需字段：change、phase、mode、files、context_hash）以及源文件引用覆盖度，替代了之前基于英文标题的 markdown 检查。守卫会在阶段转换之前捕获损坏或不完整的 JSON。
• JSON file roles: spec-context.json 的 files 数组现在包含 role 字段（spec 文件为 spec，proposal/design/tasks 为 supporting），彻底移除了依赖语言的 projection 数组。
• —full warning in beta mode: 在 beta 模式下运行 comet-handoff.sh --full 现在会发出明确的警告，而不是静默忽略该标志。
• CodeGraph step in comet update: comet update 现在会在更新 skill 文件的同时提示安装/更新 CodeGraph，使用与初始化相同的平台检测和 CLI 安装流程。
• Rules and hooks distribution in comet update: comet update 现在会在更新 skill 文件的同时，将防漂移阶段守卫规则和 hook 分发到所有已安装的平台，确保 Comet 升级后规则和 hook 保持同步。
• Archive confirmation gate: 中文 /comet-archive 现在在运行归档脚本之前会暂停以获取用户的明确确认，让用户在主 spec 合并和 change 归档之前有最后的机会进行调整或重新验证。
• English archive confirmation parity: 英文 Comet skill 现在与已确认的中文归档确认工作流保持一致，包括 /comet-archive、/comet-verify、/comet、hotfix 和 tweak 指引。
• Archive reopen transition: 新增 comet-state transition <change-name> archive-reopen，让拒绝最终归档确认的用户可以从 phase: archive 返回 phase: verify 进行调整或重新验证，无需手动编辑 .comet.yaml。
• OpenSpec clarification gate: 中文和英文 /comet-open 现在要求在创建 proposal、design 或 tasks 产物之前，先确认一份需求澄清摘要，防止一轮问答就立即生成完整的 OpenSpec change。
• PRD split preflight: 中文和英文 /comet-open 现在会在创建 OpenSpec 产物之前对大型 PRD 进行分拣，允许用户将独立的功能拆分为多个 Comet change，同时让每个被接受的拆分项保持在 /comet-open 的状态机路径上。解决 #62。
• Skill invocation wording guidance: 在 CLAUDE.md 中新增了仓库指引，要求新的 skill 触发描述使用既有的 “use the Skill tool to load…” 措辞，并在 skill 加载之后再放置上下文细节。
• Anti-drift phase guard rule: 新增 .claude/rules/comet-phase-guard.md，在每轮对话中重新注入 Comet 阶段感知、skill 调用要求、脚本执行要求、用户确认关卡和上下文压缩恢复指引，防止长上下文注意力漂移破坏 5 阶段工作流。在所有平台上作为软提醒生效。
• Anti-drift phase guard hook: 新增 comet-hook-guard.sh PreToolUse hook（配置在 .claude/settings.local.json），当当前 Comet change 处于 open、design 或 archive 阶段时硬性阻止文件写入，提供模型无法绕过的、平台特定的硬性执行层。将 openspec/*、docs/superpowers/*、.claude/* 和 .comet/* 路径加入白名单。
• Platform rules/hooks distribution in comet init: comet init 现在在初始化期间将防漂移阶段守卫规则和 hook-guard 脚本分发到所有受支持的平台。修正了平台定义：Cline 使用项目根目录下的 .clinerules/（而非 .cline/rules/），GitHub Copilot 使用带 applyTo frontmatter 的 .github/instructions/*.instructions.md，Kiro 使用 .kiro/steering/，Gemini CLI 没有规则目录（使用 GEMINI.md 文件）。为 8 个缺少规则配置的平台新增了 rulesDir/rulesFormat，为 7 个平台新增了 supportsHooks/hookFormat。hook 安装支持 7 种格式变体：Claude Code、Gemini、Windsurf、Copilot、Qwen、Kiro 和 Qoder。
• Systematic debugging gate: 中文和英文 build 及 hotfix skill 现在要求在实现阶段出现崩溃、意外行为、测试失败或构建失败时加载 Superpowers 的 systematic-debugging，确保在修复源码之前先进行根因分析并在当前 change 中编写回归测试。
• Verification-before-completion gate: 中文和英文 /comet-verify 现在要求在执行轻量或完整验证检查之前加载 Superpowers 的 verification-before-completion，在任何完成声明之前强制执行基于证据的确认。
• Platform-neutral confirmation gates: 中文和英文 Comet skill 及恢复消息现在引用当前平台的用户输入/确认机制，而不是硬编码 AskUserQuestion，避免 Codex 用户被指引去使用可能不存在的工具，同时保留阻塞性的用户决策。
• 预设升级路径: hotfix 和 tweak skill 现在在升级到 full workflow 时包含 set <name> phase design 步骤，避免 workflow 切换后触发 comet-design 入口检查失败。
• Build-complete conditional field reset: build-complete 转换在前一次 verify_result 为 fail 时会保留 verification_report 和 branch_status，使 verify-fail→build→build-complete 的重新验证循环不丢失数据。
• Open phase recovery granularity: open 阶段恢复现在区分三种状态（所有产物完成 / 无产物完成 / 部分完成），并为每种状态提供具体的恢复操作。
• 50% scope threshold option: build skill 现在在改动超过 50% 范围时提供”在当前 change 中继续”作为第三个选项，避免强制拆分 change。
• Worktree plan commit: build skill 现在明确指示在使用 worktree 隔离时，先提交计划文件再创建 worktree。

​

Removed

• openspec/config.yaml: 移除了未使用的示例 OpenSpec 配置文件（仅包含占位注释）。

​

Fixed

• Subagent task persistence: /comet-build 现在要求每个子 agent 调度提示在提交之前，将已完成的任务勾选持久化到 Superpowers 计划中，并在映射时更新对应的 OpenSpec tasks.md 条目。build 守卫会阻止未勾选的 Superpowers 计划任务，build 恢复在检查最近的 git 历史/diff 或调度更多工作之前，会同时报告 OpenSpec 和计划的进度，防止在打断或上下文压缩后恢复时重新运行已完成的子 agent 工作（#79）。
• skip-all skipping uninstalled components: comet init 不再将之前跳过的组件视为已安装。选择 skip-all 现在只跳过实际存在的组件，因此未安装的 OpenSpec、Superpowers、Comet 或 CodeGraph 组件仍会被提示安装，而不是被静默跳过（#73）。
• Update JSON output for rules/hooks: comet update --json 现在在 skill 更新结果之外还包含规则和 hook 的分发结果，并具有针对每个目标的错误隔离，使单个平台失败不会破坏整个更新输出。
• Duplicate YAML fields: comet-state.sh 中的 replace_yaml_field 现在在替换后对所有字段去重，仅保留每个键的最后一次出现。此前，对同一字段多次调用 cmd_set（例如在 verify-fail → 重新验证循环中）可能在 .comet.yaml 中留下重复行，干扰下游解析器。修复 #77。
• Hook config format: installClaudeCodeHooks 和 .claude/settings.local.json 现在使用正确的 matcher + hooks: [{ type, command }] 数组格式，替代了扁平的 { matcher, command, description } 格式，修复了 /doctor 的 schema 校验错误。
• Archive delta merge: comet-archive.sh 现在将归档 spec 更新委托给 OpenSpec 的 delta 合并语义，而不是将 change spec 复制覆盖主 spec，防止 ADDED/MODIFIED/REMOVED/RENAMED 章节标题泄漏到稳定 spec 中。解决 #69。
• Brainstorming depth: 中文和英文 /comet-design 不再告诉 Superpowers 的 brainstorming 跳过上下文探索，因此不清晰的目标、范围、非目标、验收场景或约束必须在创建设计文档之前得到澄清。
• Command injection prevention: comet-guard.sh 中的 run_command_string() 现在拒绝包含 shell 元字符（;、|、&、$、反引号）的 build/verify 命令，防止通过 .comet.yaml 的命令字段进行命令注入。
• Path traversal prevention: comet-state.sh cmd_set 现在在写入之前校验路径字段（design_doc、plan、verification_report、handoff_context、handoff_hash）是否包含 .. 遍历序列。
• Design guard enforcement: design 守卫现在要求 full workflow 必须有 design_doc（FAIL 而非 WARN），防止在没有设计文档的情况下推进阶段。
• branch_status preservation on verify-fail: verify-fail 转换不再重置 branch_status，在重新验证循环中保留分支处理状态。
• UTC date consistency: 所有脚本现在使用 date -u +%Y-%m-%d 来设置 created_at、verified_at 和归档命名，消除了本地/UTC 日期不一致问题。
• macOS SCRIPT_DIR resolution: 所有脚本使用可移植的 $(cd "$(dirname "$0")" && pwd -P) 替代 readlink -f，以保证跨平台兼容性。
• Archive directory resolution fallback: comet-archive.sh resolve_archive_dir() 现在在精确的基于 UTC 的路径不匹配时，按 *-$CHANGE 模式搜索，修复了不同时区下的测试可靠性问题。
• Temp file permissions: 所有 mktemp 调用现在在写入敏感数据之前对临时文件设置 chmod 600。
• Pipe hash error propagation: comet-handoff.sh 和 comet-guard.sh 中的哈希计算现在先将管道输出捕获到变量中，再管道传递给哈希流，防止在 pipefail 下静默失败。

​

Tests

• Auto-transition regression: 新增了针对 auto_transition 初始化默认值、枚举校验、.comet/config.yaml 项目默认值传播、schema 校验，以及 build/design/open/verify skill 中手动切换与自动推进分支的状态机和 skill 覆盖测试（#74）。
• comet-state next regression: 新增了 shell 脚本覆盖测试，涵盖 full/hotfix/tweak 工作流、手动交接模式、已完成归档（NEXT: done）以及缺失 .comet.yaml 时的失败行为等场景下的下一步解析。
• Skill handoff wording regression update: 更新了 skill 内容断言，以校验 next 驱动的交接措辞（NEXT: auto|manual|done），并同步了中英文期望检查。
• Output language regression: 新增了 skill 覆盖测试，验证 Comet 将触发用户请求的语言传播到 open、design、build、verify、hotfix、tweak 和 archive 各 skill 中的 OpenSpec 和 Superpowers 步骤（#53）。
• Review gate regression: 新增了 skill 覆盖测试，验证 executing-plans 构建模式在 build→verify 转换之前需要 requesting-code-review 关卡，并更新了 init-e2e 的期望（#76）。
• skip-all regression: 新增了 comet init 覆盖测试，验证 skip-all 仅跳过已安装的组件，仍会提示安装未安装的 OpenSpec/Superpowers/Comet/CodeGraph 组件（#73）。
• --hash-only flag coverage: 新增测试验证正确的哈希输出、change 目录校验、必需文件校验以及不重新生成交接文件。
• Context benchmark runner coverage: 新增测试验证基准测试的 token 节省计算、Codex JSONL 的用量/结论解析，以及在 dry-run 模式下不调用 Codex 即可生成报告。
• Flaky test timeout fix: 没有 design_doc 的 design 守卫测试现在有明确的 20 秒超时，防止 Windows bash 启动抖动。
• Chinese spec coverage: beta 交接测试使用中文 spec 内容，验证所有内容（标题、描述、非关键词步骤）无论何种语言都能按原样投影。
• JSON corruption detection: 新增测试验证当 spec-context.json 结构无效时，守卫会阻止 design 退出。
• —full beta warning: 新增测试验证警告消息，并确认在传入 --full 时仍会生成 beta 文件。
• Doctor CodeGraph check: comet doctor 现在会报告 CodeGraph CLI 的可用性和项目初始化状态（.codegraph/ 是否存在）。
• Archive confirmation regression: 新增了中文 skill 覆盖测试，验证 /comet-archive 在执行归档脚本之前需要最终确认关卡。
• English archive confirmation regression: 增加了英文 skill 覆盖，包含最终归档确认、归档重开指引和 hotfix/tweak 预设阻塞点。
• Phase write guard hook coverage: 针对 comet-hook-guard.sh 新增了 10 个测试，涵盖基于阶段的写入阻止（open/design/archive 阻止，build/verify 允许）、白名单路径（openspec、docs/superpowers、.claude）、已归档 change 的绕过，以及无活跃 change 时的放行。
• Archive reopen regression: 新增了状态机覆盖测试，涵盖将未归档的 change 从归档确认返回到验证，以及在 archived: true 之后拒绝重开尝试。
• Archive spec merge regression: 新增了 shell 脚本覆盖测试，涵盖归档 delta spec 时不将仅 delta 的需求章节标题复制到稳定主 spec 中。
• OpenSpec proposal regression: 新增了中英文 skill 覆盖测试，涵盖产物创建前的澄清关卡、对一次性 openspec-propose 的默认禁止，以及对 Superpowers brainstorming 澄清流程的保留。
• Skill authoring regression: 新增覆盖测试，验证 CLAUDE.md 中记录了必需的 skill 调用措辞模式。
• Debug gate regression: 新增了中文 skill 防护覆盖测试，涵盖 systematic-debugging 的调用、最小失败测试要求，以及将崩溃验证保持在当前 change 内。
• Confirmation mechanism regression: 新增覆盖测试，验证中文工作流决策关卡不再硬编码 AskUserQuestion，且恢复输出会指引 agent 使用平台无关的确认机制。
• PRD split workflow regression: 新增了中英文 skill 覆盖测试，涵盖 open 阶段的 PRD 拆分选择、/comet-open 状态初始化、重复分拣阻止、拆分完成选择，以及最小恢复指引。
• tdd_mode state machine regression: 新增覆盖测试，涵盖 tdd_mode 的初始化默认值（full 为 null，hotfix 为 direct）、枚举校验、build 退出守卫、hotfix 绕过，以及 schema 校验对非法值的拒绝。
• Review fix regression: 新增覆盖测试，涵盖重新验证时的条件性 verification_report 保留、verify-fail 期间的 branch_status 保留、design_doc 的路径遍历拒绝、build_command 的命令注入拒绝，以及 full workflow 无 design_doc 时的 design 守卫强制执行。
• Context compression regression: 新增覆盖测试，涵盖项目配置默认值、change 级别的 context_compression 快照、change 初始化期间的环境变量覆盖、beta spec 投影生成，以及 beta 投影缺少需求或场景标题时的守卫拒绝。

​

Added

• Plan-ready build pause state: 新增 build_pause 作为构建阶段的专用暂停标记，使 Comet 可以在生成计划后停下，而不会将该暂停与实际执行方式混淆。
• Plan-ready pause design: 新增了一份关于模型切换暂停工作流的设计文档，涵盖恢复行为、过期暂停处理和计划缺失的补救措施。

​

Changed

• Build recovery routing: /comet 和 /comet-build 现在能识别 build_pause: plan-ready，复用已有计划，并从工作区隔离和执行方式选择处恢复，而不再重新生成计划。
• Bilingual workflow documentation: 中英文 Comet skills 现在都描述了 plan-ready 暂停点，明确 build_pause 不是 build_mode，并在两份 README 中记录了相同的状态字段。

​

Fixed

• GitHub Copilot Superpowers skill names: Comet skills 现在调用由 GitHub Copilot skills 路径安装的 Superpowers 裸 skill 名，避免因无法解析的 superpowers:* 别名导致工作流阻塞。
• Windows bash resolution: Comet 现在通过 COMET_BASH 解析可用的 bash 可执行文件，拒绝 Windows WSL 启动器路径，并将解析出的可执行文件用于嵌套脚本调用，使守卫、交接和归档流程不会回退到损坏的 PATH bash。
• Shell test runner bash resolution: run-bats.js 现在通过 COMET_TEST_BASH、COMET_BASH、PATH 或 Git Bash 默认值来解析可用的 bash，避免从 Node 运行 shell 测试时使用损坏的 Windows WSL 启动器。
• Schema validation fatal output: 守卫校验现在会在打印校验器诊断信息后保留最终致命的 schema 校验消息，使无效的 .comet.yaml 失败更易于识别。

​

Tests

• Superpowers skill invocation regression: 新增测试覆盖，确保随附的 Comet skill 文本不引用带插件前缀的 Superpowers 别名。
• Comet bash execution regression: 新增测试覆盖，包括嵌套脚本调用、随附命令示例和 shell 测试运行器，确保 Comet 使用解析后的 bash 路径而非原始 PATH bash。
• Plan-ready pause regression: 新增 shell 脚本测试覆盖，包括 build_pause 初始化、schema 校验、状态更新和构建恢复输出。
• README state-field regression: 新增 README 测试覆盖，确保 build_pause 出现在中英文文档的示例和字段说明中。

​

Added

• Context compaction recovery (--recover): comet-state check <name> <phase> --recover 输出结构化的恢复上下文，包括阶段状态、字段进度、任务数量和恢复操作，用于 agent 的上下文压缩，以便快速定位断点并恢复操作。
• Red Flags Anti-Rationalization List: 在主调度 skill 中新增 5 条红旗警告（替用户做决定、跳过确认、替换历史偏好、无异议地附和、未验证即放行），帮助 agent 识别自身的越权倾向。
• Uncertainty Degradation Principles: 在 verify skill 中新增 SUGGESTION > WARNING > CRITICAL 降级规则。只有构建失败、测试失败和安全问题会被标记为 CRITICAL；模棱两可的问题必须降级。
• Anti-Automatic Selection Guardian: 在 open skill 中新增命名与范围的防自动选择规则。名称变更必须由用户指定或通过 AskUserQuestion 确认；范围不得任意扩大或缩小。
• File Existence Verification: 在进入用户确认前，open skill 会校验 proposal/design/tasks 文件不为空，防止空文件跳过检查。
• Idempotency Description: 为所有 skill 阶段（open/design/build/verify）新增幂等性说明，明确哪些操作可以安全重试、哪些字段在跳过前需要确认。

​

Changed

• AskUserQuestion Tool Clarification: 全部 7 个决策阻塞点（open 确认、头脑风暴确认、构建工作流、verify 失败决策、spec 偏移处理、分支处理、升级条件）统一要求使用 AskUserQuestion 工具；禁止使用纯文本提示。
• Decision Points Expanded from 6 to 7: open 阶段的 proposal/design/tasks 审阅确认现在成为第一个决策点。
• Spec Drift Single-Choice Question Format: verify 阶段的 spec 偏移处理改为 AskUserQuestion 单选题（A/B/C 三选一），不再有隐式默认选项。
• Completely synchronized Chinese and English skills: 7 个中文 skill 和 7 个英文 skill 的内容、结构和选项格式已完全对齐。

​

Fixed

• Crash due to unbound variables in set -u: 当 comet-state check --recover 在构建阶段缺少 tasks.md 时，pending 变量未声明会导致脚本直接退出；现已通过将 local 声明前移并在恢复操作链中增加显式分支 tasks.md MISSING 修复。
• Path truncation risk: field_status 对 design_doc 使用 ${var%% *} 可能截断含空格的路径；已改为 ${var% } 仅去除末尾空格。
• Inconsistent reading style for optional fields: direct_override 使用 || echo ""，而其他可选字段使用 || true；现已统一为 || true，与 cmd_scale 保持一致。

​

Tests

• 新增 8 个 check --recover 与边界测试用例，覆盖 open/build/verify/design/archive 五个阶段，以及缺少 tasks.md 和全部任务完成等边界场景。
• 测试总数从 34 个增加到 42 个，全部通过。

​

Changed

• Command execution security: 将 OpenSpec 和 Superpowers 安装路径中的所有命令执行从带 shell 解释的 spawn 重构为 execFileSync，消除了 shell 注入风险面并提升了跨平台可靠性 (#88bf487)

​

Fixed

• OpenSpec global install path for OpenCode: comet init --scope global 现在会将 OpenSpec skills 从硬编码的 ~/.opencode/ 目录迁移到 OpenCode 实际读取的 ~/.config/opencode/ 目录，并在源路径与目标路径相同时加入自删除守卫 (#46, @gleami)
• Windows command execution: 在 Windows 上为 execFileSync 调用添加了 shell 选项，使命令 shim（.cmd）能够正确解析
• Doctor .comet.yaml validation: comet doctor 现在会校验顶层键，而不是静默接受未知键；同时除 ENOENT 之外的 readDir 错误不再被吞掉 (@felamin)
• CI JSON parsing: CI 工作流通过查找第一个 { 字符来解析命令输出，避免非 JSON 前缀行破坏 JSON 提取 (@yicochen)
• CI warning output: CI 现在仅在某一步骤实际失败时才统计并打印警告，减少了成功运行时的噪音 (@yicochen)
• Spawn stdio noise: 将非交互式 spawn 的 stdio 从 inherit 改为 ignore，使 OpenSpec/Superpowers 安装器不再向控制台打印无关的进度信息 (@yicochen)

​

Tests

• 新增了对 OpenCode 全局 OpenSpec 路径迁移、自删除守卫和主目录 mock 的测试覆盖
• 新增了针对 .comet.yaml 顶层键校验以及非 ENOENT 的 readDir 错误传播的 doctor 测试
• 修复了基于 git 的测试 “uses plan base-ref to scale verification” 的超时问题

​

Docs

• 改进了 README 的配置指引，提供更清晰的安装说明和可折叠的参考面板（中英文均更新） (@hepeng)
• 在 README 和 README-zh 中都新增了贡献者墙 (@Joechan11)

​

New Contributors

• @felanny 在 #38 中首次贡献
• @Joechan11 在 #44 中首次贡献
• @bevishe 在 #47 中首次贡献
• @kathy32 在 #39 中首次贡献
• @gleami 在 #46 中首次贡献

​

Fixed

• OpenSpec all-workflows installation: comet init 现在除了写入隔离的 XDG_CONFIG_HOME 环境覆盖之外，还会将全工作流配置直接写入平台特定的默认配置路径（Windows 上为 %APPDATA%\openspec\，macOS/Linux 上在设置时为 $XDG_CONFIG_HOME/openspec/，否则为 ~/.config/openspec/），确保无论用户之前的 OpenSpec 配置状态如何，所有 11 个 OpenSpec 工作流始终被安装。

​

Added

• Script discovery helper: 新增 comet-env.sh，通过从其自身目录 source 同级脚本来集中化脚本路径解析，取代所有中英文 Skill 中分散的 COMET_SEARCH_ROOTS 查找逻辑。
• OpenCode global config directory: OpenCode 平台现在为全局安装支持独立的 globalSkillsDir（.config/opencode），使项目级和用户级 Skill 保持区分。
• Command error diagnostics: 新增 command-error.ts 模块，用于提取和清理失败 shell 命令的 stderr/stdout，被 OpenSpec 和 Superpowers 安装路径共同使用，以呈现可操作的失败详情。

​

Changed

• Build decision-point wording: 强化了 build Skill 中工作区隔离和执行方式选择的措辞，使 agent 不能基于推荐规则替用户做出选择。
• Hotfix/Tweak upgrade wording: 重新表述了 hotfix 和 tweak Skill 中的升级条件和验证失败暂停要求，以获得更清晰的阻断语义。
• Comet user decision numbering: 修复了中文 comet Skill 中用户决策点列表的编号顺序错乱问题。

​

Fixed

• OpenSpec workflow installation: comet init 现在使用 --profile custom 和一个启用所有工作流（propose、explore、new、continue、apply、ff、sync、archive、bulk-archive、verify、onboard）的临时配置来运行 OpenSpec，确保 Comet 安装的不仅仅是默认的核心工作流集合。
• OpenCode slash commands: comet init 现在生成 OpenCode 命令文件（commands/*.md），保留 /comet* 命令名的同时嵌入对应的 Comet 工作流内容，使 OpenCode 用户可以直接调用 /comet、/comet-open 等。
• Lingma Superpowers path: comet init 现在让 Lingma 避开不受支持的 skills --agent lingma 路径，并将暂存的 Superpowers Skill 复制到 .lingma/skills，防止整个外部安装批次失败，同时保留 Lingma 预期的目录布局。
• Lingma global directory: Lingma 的全局 Skill 目录明确为 .lingma，用户级安装匹配 ~/.lingma/skills/{skill-name}/SKILL.md，项目安装匹配 .lingma/skills/{skill-name}/SKILL.md。
• Script discovery safety: comet-env.sh 被 source 时不再改变调用者的 shell 选项，在捆绑脚本缺失时返回失败，并避免 ShellCheck 的 unreachable-command 诊断。
• comet-state.sh field whitelist: 将 created_at 和 base_ref 添加到 cmd_set 允许字段列表中，使验证与 .comet.yaml 初始化期间已写入的字段保持一致。

​

Tests

• Script discovery coverage: 添加了验证 comet-env.sh 导出所有捆绑脚本路径以及没有 Skill 文件内联 COMET_SEARCH_ROOTS 的测试。
• Script discovery safety: 为 source 时保留 shell 选项和可展开的 $HOME Skill 目录 glob 添加了回归测试覆盖。
• OpenCode Comet detection: 为 OpenCode 在报告 Comet 已安装之前需要同时具备 Skill 目录和匹配的命令文件添加了测试。
• OpenCode E2E init: 为 OpenCode 项目和全局范围安装添加了端到端测试，包括命令文件生成。
• OpenCode command content: 添加了测试，验证 OpenCode 命令文件保留 Comet 命令名，并包含完整的所选语言工作流内容，而非一个轻量的 Skill 委派桩。
• English workflow safeguards: 添加了与现有中文工作流决策点需求匹配的对等性测试。
• OpenSpec profile and diagnostics: 为自定义 profile 创建、--profile custom 标志以及安装失败时打印 stderr/stdout 详情添加了测试。
• Lingma Superpowers fallback: 添加了回归测试覆盖，验证 Lingma 被排除在不支持的 skills CLI agent 列表之外，并在将 Skill 复制到 .lingma 之前使用暂存安装。
• Lingma global install path: 为 comet init --scope global 将 Lingma Comet Skill 安装到用户 .lingma/skills 目录下添加了回归测试覆盖。

​

Added

• Workflow state metadata: .comet.yaml 初始化现在会记录 base_ref 和 created_at，使规模评估和验证能够基于稳定的变更基线进行推断。

​

Changed

• Comet decision points: 调整中英文 workflow skills，使 design 确认、build 配置、verify 失败、spec drift、分支处理和预设升级都会暂停并等待明确的用户选择，而不是依赖默认值或推荐项。
• Build workflow selection: 将工作区隔离和执行方式选择合并为一个 build 配置步骤，减少重复暂停，同时仍要求在实现继续之前确定 isolation 和 build_mode。
• Hotfix verification flow: 将 root-cause elimination 移到 build guard 之前，并要求预设升级把 workflow 切到 full，让失败的 hotfix 检查停留在 build 阶段，并让 full-flow 升级保持一致状态。
• Verification scale assessment: 规模检查现在回退到 .comet.yaml 的 base_ref，并使用四文件阈值进行完整验证，使已提交的 build 变更更不容易被漏算。
• English skill parity: 将英文 Comet Skill 与中文工作流规则同步，包括交接生成、脏工作树处理、spec drift 决策和验证失败阻断。

​

Fixed

• Windows npm update: comet update 现在通过 shell 启动 npm，使包更新路径在 Windows 命令垫片下可靠工作。
• Superpowers install diagnostics: 失败的 Superpowers 安装现在会打印清理后的 stderr 详情，使网络或 GitHub 访问失败可见，而不是隐藏可操作的原因。

​

Tests

• Workflow safeguard coverage: 为中文 Comet 决策点需求和 Superpowers 安装失败诊断添加了回归测试覆盖。

​

Added

• Dirty worktree recovery protocol: 新增共享的中英文 comet/reference/dirty-worktree.md 参考文档，使 agent 在恢复时能够一致地保护、检查并归属用户或混合来源的工作树变更。

​

Changed

• Comet resume behavior: 更新了 /comet、build、verify、hotfix 和 tweak Skill，使中断期间手动编辑的代码被视为代码证据，而非自动状态转换；agent 在继续或推进守卫之前必须对脏工作树变更进行归属。

​

Fixed

• Reference skill installation: 将脏工作树参考文件添加到 Comet 清单中，使已安装的中英文 Skill 集能够解析 comet/reference/dirty-worktree.md。

​

Changed

• Antigravity Skill 路径: 更新了平台处理方式，项目级安装使用 .agents/skills，而全局级安装使用 Antigravity 的 .gemini/antigravity/skills 位置，使 init、doctor 和 update 与 Antigravity 的目录模型保持一致
• README 信息架构: 重构了中英文 README 章节，将命令详情、平台列表、Skill 表、脚本表、.comet.yaml 字段和可靠性说明放入可折叠的参考面板中
• Spec 生命周期文档: 扩展了 README 中对 Comet Spec 生命周期管理的说明，包括 OpenSpec/Superpowers 制品关联、自动交接、状态更新、校验和归档同步
• 安全指南位置: 将仓库维护安全说明从 README 移至 CONTRIBUTING.md，使 README 聚焦于面向用户的 Comet 概念和安装配置

​

Fixed

• Antigravity 全局安装: 修复了 comet init --scope global 及相关健康检查，使 Antigravity 不再在项目风格的 .agents 目录下安装或搜索全局 Skill
• 缺失的 skills 目录: 在扫描项目级和全局级 skills 目录之前新增了显式的存在性检查，确保在平台目录存在但缺少 skills/ 时检测和更新逻辑依然稳健

​

Tests

• Antigravity 路径覆盖: 新增回归测试覆盖 Antigravity 项目级/全局级 Skill 目录的检测和 init E2E 行为
• README 结构覆盖: 使用现有 README 测试套件验证了更新后的 README 命令和参考结构

​

Added

• 设计交接脚本: 新增 comet-handoff.sh，从 OpenSpec 制品生成确定性、可溯源的上下文包（精简或完整模式）至 .comet/handoff/，并在 .comet.yaml 中记录 handoff_context 和 handoff_hash
• 交接守卫检查: 设计阶段守卫现在会校验交接上下文是否存在、哈希新鲜度（检测交接后 OpenSpec 的变更）、markdown 可追溯性标记，以及设计文档 frontmatter 字段（comet_change、role: technical-design、canonical_spec: openspec）
• handoff_context 和 handoff_hash 字段: 新增 .comet.yaml 字段，用于跟踪脚本生成的交接包，并带有 schema 校验（路径存在性、sha256 十六进制摘要格式）
• comet init --scope: 新增 --scope <global|project> CLI 标志，用于非交互式范围选择
• CI init E2E 作业: GitHub Actions 现在会在 Ubuntu、macOS 和 Windows 上运行真实的 comet init，验证 Comet Skill、Superpowers、OpenSpec 和工作目录是否落在正确的文件系统位置（项目级和全局级均覆盖）

​

Changed

• 中文 Skill 文档更新: comet-design/SKILL.md 和 comet/SKILL.md 现在记录了交接流程，用脚本生成的上下文包替代了 agent 自行撰写的摘要
• JSON 生成使用进程替换: comet-handoff.sh 中的 write_json_context 使用 < <(source_files) 替代管道子 shell，修复了变量作用域问题
• 错误信息格式化: comet-state.sh 中未知字段的错误信息从单行 270+ 字符拆分为多行，提升可读性
• CLAUDE.md 和 AGENTS.md: 新增了项目级说明，涵盖测试命令、shell 脚本约定、脚本依赖图、.comet.yaml 状态机同步规则以及 changelog 格式

​

Fixed

• YAML 和 frontmatter 解析: Comet 脚本现在会忽略 .comet.yaml 字段值中未加引号的尾部注释，并接受 UTF-8 BOM 或前导空行之后的设计文档 frontmatter，避免误判守卫和交接失败
• Init E2E 安装检查: CI 现在会验证每个支持平台目录下 Comet 拥有的 Skill 制品，并从 comet init --json 检查 OpenSpec/Superpowers 安装器状态（项目级和全局级安装均覆盖），避免因外部 CLI 专用目录布局导致的误判失败
• Windows 全局 init E2E 主目录: CI 现在会在 Windows 上全局范围 init 检查时同时设置 USERPROFILE 和 HOME，与 Node 的 os.homedir() 解析方式保持一致，避免误判 Skill 缺失
• README 状态文档: README 示例现在展示了准确的 .comet.yaml 构建状态默认值、验证证据时机、交接字段以及仅项目级创建工作目录的行为
• Windows Superpowers init 超时: Superpowers 外部安装器超时时间已增加，以容忍较慢的 Windows npx skills add 运行，减少 init E2E 的偶发失败

​

Tests

• 新增测试覆盖 --full 交接模式、缺失 OpenSpec 制品拒绝、交接后哈希不匹配检测以及设计文档 frontmatter 校验
• 新增 comet init E2E 测试，覆盖项目级安装、全局级安装、使用 --yes 跳过已存在项、使用 --overwrite 覆盖以及多平台检测
• 新增回归测试覆盖 .comet.yaml 尾部注释以及带 UTF-8 BOM 或前导空行的设计文档 frontmatter
• 新增 CI 工作流回归测试，覆盖 Comet 拥有文件和外部 OpenSpec/Superpowers 安装器状态的项目级与全局级安装检查
• 新增 CI 工作流回归测试，覆盖使用临时 USERPROFILE 主目录的 Windows 全局 init
• 新增回归测试覆盖 init 使用的更长 Superpowers 安装器超时时间

​

Fixed

• OpenSpec 全局初始化: comet init 的全局范围现在会将主目录作为 OpenSpec 的初始化目标传入，而不是使用不支持的 openspec init --global 标志
• 跨平台路径引用: OpenSpec 初始化目标针对 Windows、macOS 和 Linux 路径进行了 shell 引号处理，包括含空格的主目录
• 安装器参数引用: OpenSpec 的 --tools 值和 Superpowers 的 --agent 值现在都进行了 shell 引号处理，Windows 下 OpenSpec 路径在闭合引号前保留尾部反斜杠
• Superpowers 多平台安装: Superpowers 安装现在会传入重复的 --agent 标志，而非逗号分隔的 agent 列表，与 skills CLI 行为一致
• Superpowers agent 映射: 将 Comet 平台映射更新为有效的 skills CLI agent ID，不支持的平台专用 ID 会回退到 universal

​

Tests

• 新增回归测试覆盖 Windows、macOS 和 Linux 下的 OpenSpec 全局初始化命令构造
• 新增回归测试覆盖 OpenSpec Windows 尾部反斜杠引用和带引号的安装器参数
• 新增 Superpowers 覆盖测试：有效的 skills CLI agent 映射和多 agent 参数格式
• 在隔离的临时目录中，对所有 28 个支持平台的项目级和全局级初始化输出进行了冒烟测试

​

Added

• 构建决策强制校验: 构建守卫和 comet-state.sh transition build-complete 现在要求 isolation 和 build_mode 才能从 build 推进到 verify
• 直接模式覆盖: 完整工作流必须先设置 direct_override: true 才能使用 build_mode: direct；hotfix/tweak 默认仍然允许
• 可配置的守卫命令: 守卫脚本现在会先从变更的 .comet.yaml 或仓库根目录的 Comet 配置中读取 build_command 和 verify_command，找不到时再回退到自动检测的构建命令
• 归档差异预览: 归档同步在覆盖现有主规格（当其与 delta 规格不同时）之前，会先打印统一 diff
• 跨平台脚本冒烟 CI: 新增 Ubuntu、macOS 和 Windows 的冒烟测试覆盖，针对 Comet shell 脚本和可移植 shell 测试
• Shell 换行符策略: 新增 .gitattributes 规则，保持 shell 和 Bats 脚本使用 LF 换行符

​

Changed

• 守卫失败输出: 守卫检查现在会保留并打印命令失败输出，并附带可操作的 Next: 提示，用于缺失构建决策和未完成任务
• 命令处理: 项目命令通过 bash -lc 运行，Maven 在适当时使用 mvnw 或 mvn.cmd，shell 测试辅助工具会处理 Windows Git Bash 路径
• 归档步骤计数: Dry-run、delta 同步、标注、移动和归档状态步骤现在统计实际执行的步骤，不再对重复操作重复计数
• 英文文档和 Skill: 将英文 README 和 Comet Skill 文本与中文的构建决策、命令配置和归档行为描述保持同步

​

Fixed

• macOS shell 脚本状态更新: 将 comet-state.sh 中仅 GNU 支持的 sed -i 写入替换为可移植的临时文件更新方式，修复了 macOS 在 scale、transition 和 YAML 字段更新时的 CI 失败
• pipefail 下可选字段读取: 守卫和状态脚本现在在 set -euo pipefail 下对缺失的可选 YAML 字段具有容错性，不会提前退出
• Bash 检测回退: shell 测试辅助工具现在能处理 bash 探测失败的情况，不会因 spawnSync 输出为空而崩溃
• 配置命令持久化: comet-state.sh set 现在会转义 sed 替换元字符，确保包含 &、| 或反斜杠的命令值得以保留
• 可选 schema 字段: YAML 校验现在能识别 direct_override、build_command 和 verify_command
• 带引号的 YAML 值: 状态、守卫和校验脚本现在仅去除包裹引号，而非删除值中的所有引号字符

​

Tests

• 新增测试覆盖：缺失构建决策、直接模式覆盖的阻断与允许、配置的构建/验证命令、命令元字符保留、未完成任务补救输出、归档步骤计数、跨平台路径处理、BSD/GNU sed 可移植性、pipefail 下可选 YAML 字段读取以及 bash 探测失败处理

​

Added

• PR 标题 lint 工作流: 新增 GitHub Actions 校验，要求语义化 PR 标题并使用 Comet 专用范围（cli、commands、core、skills、assets、scripts、docs、ci、deps、release）
• 结构化 JSON 输出: comet init --json 和 comet update --json 现在输出机器可读的结果，而非混合的人类日志
• doctor --scope: comet doctor 可诊断 auto、project 或 global 范围，auto 会同时检查项目级和全局级安装
• 下一步状态提示: comet status 现在会在文本和 JSON 输出中提示下一个工作流命令（/comet-open、/comet-design、/comet-build、/comet-verify、/comet-archive）
• README 资源守卫: 新增测试和 prepublish 校验，确保 README 中的图片使用 npm 友好的绝对 URL

​

Changed

• comet update 保留已安装上下文: update 现在会检测项目级/全局级范围内已有的 Comet Skill 目标，保留已安装范围，检测中文还是英文 Skill，并仅更新已安装 Comet Skill 的平台
• comet update 自更新 npm 包: update 现在在刷新已安装 Skill 之前，会打印并运行与检测到的包范围对应的 npm 更新命令
• 更友好的 update 输出: update 会记录 npm 命令、各目标的 Skill 复制命令、最终的 npm 状态、已更新目标数、范围和语言摘要
• Init 覆盖流程: 交互式 comet init 现在会在同一平台检测到多个已有组件时，提供批量覆盖/跳过选项
• CLI 选项校验: update --language、update --scope 和 doctor --scope 现在通过 Commander 的 choices 校验接受的值
• README CLI 文档: 更新了中英文 README 命令章节，记录了 JSON 输出、doctor 范围、update 行为、status 下一步提示以及 init 覆盖行为
• CONTRIBUTING 链接: 在中英文 README 的开发章节中添加了贡献指南引用

​

Fixed

• Doctor 误报: comet doctor 现在能识别当前的 .comet.yaml 字段，包括 verification_report 和 branch_status
• npm README 图片: README 图片现在使用绝对的 GitHub URL，以便包页面能正确渲染

​

Tests

• 新增测试覆盖：update 语言/范围检测、JSON 输出、友好的命令显示、status 下一步提示、doctor 当前状态校验、README 图片 URL、init 批量覆盖选择以及 PR 标题工作流配置

​

Added

• 验证证据强制校验: verify-pass 推进现在要求 verification_report（文件必须存在）和 branch_status: handled 才允许进入下一阶段。守卫将这些作为硬性前置条件进行检查
• .comet.yaml 中的 verification_report 和 branch_status 字段: 新增状态字段，用于跟踪验证报告路径和分支处理状态
• comet-verify（中文）中的验证证据步骤: 新增第 4 步，要求在守卫应用前创建报告文件并记录分支状态
• branch_status 枚举校验: comet-state.sh set 会将 branch_status 校验为 pending 或 handled
• 守卫 verify 检查: comet-guard.sh 现在会在 verify 阶段检查 verification_report 是否存在 以及 branch_status=handled
• Bats 测试 CRLF 修复: Shell 测试在执行前会去除脚本中的 \r，修复了 Windows 兼容性
• test:shell 运行器: 用 node scripts/run-bats.js 替代直接调用 bats，以支持跨平台

​

Changed

• Hotfix 根因检查顺序调整: 将根因消除检查移至加载 comet-verify 之前（第 3a 步拆分为 3a/3b），防止在 verify 流程中被跳过
• 简化 Hotfix 标题描述: 将含糊的”非独立并行流程”替换为直接的”快速 bug 修复工作流”，明确可独立调用
• 移除 comet-design 中的非操作步骤: 删除了第 3 步（双规格划分表）和第 4 步（文档层级）——这些是纯参考资料，不包含 agent 操作
• 移除重复的脚本定位块: comet-open（第 3 步）和 comet-archive（第 1 步）在变量已缓存时不再重复完整的 COMET_SEARCH_ROOTS find 块
• 移除 comet-build 中重复的 50% 阈值: 仅在阈值判定表中提及一次，不再在表格和列表中重复
• 通用错误处理: comet 主 Skill 中的错误表将”Maven compile/test”改为”Build/test”，使用语言无关的措辞
• comet-state.sh 用法帮助: 修复了帮助文本中 check 参数顺序（check <change-name> <phase>）

​

Fixed

• comet-state.sh init 变更目录解析: cmd_init 现在会在检查 .comet.yaml 是否已存在之前解析 change_dir，修复了嵌套目录下的路径解析问题
• verify 阶段守卫死锁: verify-pass 推进现在在通过 verify-fail 回滚时会重置 verification_report 和 branch_status，防止过期的证据导致错误的推进

​

Tests

• comet-scripts.test.ts 中 +66 行: 新增测试覆盖验证证据阻断、分支状态校验以及带证据的守卫 verify
• comet-state.bats 中 +12 行: 新增测试覆盖 branch_status 枚举校验、CRLF 去除以及 init 输出中新字段的存在性

​

Added

• “Why Comet” 章节: README 现在解释了 Comet 的设计理念——它如何将 OpenSpec 的 WHAT 管理与 Superpowers 的 HOW 执行结合为统一的 5 阶段流水线
• “Screenshots” 章节: 新增三张截图，展示平台选择、初始化以及 Skill 实际执行的过程
• “What You’ll Learn” 章节: 新增章节，展示 Comet 作为稳定嵌套 Skill 触发和多阶段自动流转模式的参考实现
• State Management YAML 示例: 扩展了文档，增加了完整的 .comet.yaml 字段示例，展示所有关键配置值

​

Changed

• comet-build Skill 描述: 明确了执行模式（子 agent 还是 executing-plans）由用户根据任务复杂度选择，而非始终由子 agent 驱动
• 增强 State Management 文档: 增加了对所有状态和阶段如何通过脚本更新、并在阶段推进前进行完成性校验的说明

​

Fixed

• comet init 时 Ctrl+Z/Ctrl+C 崩溃: 用 try/catch 包裹 inquirer 提示以处理 ExitPromptError，改为显示 Cancelled. 并干净退出，而不是打印原始堆栈跟踪
• 重复安装 Superpowers: comet init 现在会检测通过 Claude Code 插件系统安装的 Superpowers（~/.claude/plugins/cache/），当 Superpowers 插件已存在时跳过冗余的 npx skills add

​

Fixed

• CI pnpm 版本: 为 pnpm/action-setup v4 添加了 packageManager 字段
• Shell 脚本: 修复了 SCRIPT_DIR 拼写错误，将 maven_compiles 重命名为 build_passes（语言无关），修复了 check_nonempty 路径 bug，修复了 cmd_set 在路径值上的 sed 分隔符问题，更正了 shellcheck 指令的位置
• Node 版本: 最低版本提升至 Node 20（vitest v4 覆盖率需要 node:inspector/promises）

​

Skill Reliability

• SKILL.md 双区结构: 全部 8 个 Skill 拆分为”决策核心”（阶段检测、升级条件、错误处理）和”参考附录”（字段参考、脚本、最佳实践）两部分
• 量化升级条件: Hotfix/tweak 现在定义了升级到完整工作流的明确阈值（文件数量、跨模块协调、架构变更等）
• 脚本位置缓存: 所有 Skill 使用 ${VAR:-$(find ...)} 环境变量缓存模式，避免重复调用 find
• manifest.json 修复: 补充了缺失的 comet-state.sh 和 comet-archive.sh 条目
• comet-state.sh init 修复: 现在会将 workflow 字段写入 .comet.yaml，修复了此前 check design 始终失败的问题

​

CLI Commands

• comet status: 显示当前活跃变更的阶段、任务进度、工作流模式、设计文档和计划（支持 --json）
• comet doctor: 诊断安装健康状况——包括 OpenSpec CLI、工作目录、各平台的 Skill 完整性、脚本是否存在、.comet.yaml 有效性（支持 --json）
• comet update: 将 comet skill 文件更新为 npm 包中的最新版本（支持 --language、--scope）
• 所有命令支持 --json: init、status、doctor、update 均可输出结构化结果

​

Engineering

• 测试套件: 54 个单元测试（5 个套件），语句覆盖率 93.8% / 函数覆盖率 100%；26 个 bats shell 测试
• GitHub Actions CI: 在推送/PR 时执行构建 + lint + 格式化 + 测试（Node 18/20/22）+ shellcheck + bats
• ESLint + Prettier: 代码质量工具，通过 pnpm lint / pnpm format 调用
• 代码组织: 将单体式的 init.ts（620 行）拆分为 5 个聚焦的核心模块 + 4 个命令模块
• 命令注入加固: 在构造 shell 命令前对平台/工具 ID 进行校验
• 逐文件错误处理: 复制循环在单个文件失败时继续执行，不会中断

​

Added

• comet-state.sh script: 统一的状态管理，含 5 个子命令 —— init（创建 .comet.yaml）、set（带枚举校验的更新）、get（读取字段）、check（入口校验）、scale（校验模式评估）
• check subcommand: 用脚本化入口校验替代全部 8 个 Skill 中的文本检查清单
• scale subcommand: 用脚本化规模评估替代 comet-verify 中的散文式决策规则

​

Changed

• All .comet.yaml writes go through comet-state.sh: 不再直接使用 sed -i —— 每次字段写入都做枚举校验
• All skill Step 0 checklists replaced with check subcommand: 单条命令替代基于文本的入口校验
• comet-guard.sh and comet-archive.sh use state.sh internally: 所有状态变更都通过统一接口
• Removed write-verification blocks: hotfix 和 tweak 预设不再包含手动验证循环

​

Added

• comet-archive.sh script: 一键归档自动化 —— 校验入口状态、将 delta spec 同步到主 spec（覆盖）、为 design doc 和 plan 的 frontmatter 添加标注、将 change 移动到 archive 目录、更新 archived: true。支持 --dry-run 预览
• --apply mode for comet-guard.sh: 可选标志，在所有 guard 检查通过后自动更新 .comet.yaml 状态字段。阶段转换时无需手动编辑状态
• Idempotent frontmatter annotation: annotate_frontmatter() 会跳过已存在的 archived-with: 行，可安全重复执行

​

Changed

• Removed manual state editing: 所有阶段转换（design → build → verify → archive）现在改用 guard --apply，不再手动更新 .comet.yaml 字段和写入校验循环
• Removed write-verification blocks: 从 comet-open、comet-design、comet-build、comet-verify 和 comet-archive 这些 Skill 中移除了所有 【写入验证】 / 【Write verification】 模式
• Removed ## ADDED/## MODIFIED/## REMOVED delta format: delta spec 现在是完整的 spec；归档时直接覆盖主 spec，而不是合并片段
• Removed step 2b from comet-open: 对已有能力的增量修改就是一次新的 /comet-open —— brainstorming 会自然地把已有 spec 作为上下文读入
• Simplified archive skill: 第 1b–5 步替换为一次 comet-archive.sh 调用
• Updated comet/SKILL.md: 脚本位置章节现在同时记录了 --apply 模式和归档脚本

​

Removed

• isolation、build_mode、verify_mode 字段的 few-shot YAML 示例（与 agent 判断重复）
• comet-archive 对 openspec-archive-change skill 的依赖（归档脚本已处理所有步骤）

​

Added

• Workspace Isolation Selection: comet-build 现在会在执行开始前提示用户在创建分支或 worktree 之间选择（第 3 步：工作区隔离）
• isolation field in .comet.yaml: 新增必填字段（branch 或 worktree），用于记录用户的工作区隔离选择
• isolation enum validation: comet-yaml-validate.sh 现在将 isolation 作为必填字段校验，允许值为 branch/worktree

​

Changed

• comet-build 步骤编号调整：第 3 步（选择执行方式）→ 第 4 步，第 4 步（Spec 增量更新）→ 第 5 步
• Hotfix 和 tweak 预设默认使用 isolation: branch，不再提示用户
• comet-yaml-validate.sh 的 REQUIRED_FIELDS 和 KNOWN_KEYS 已更新，包含 isolation

​

Added

• Bilingual Comet skills: comet init 现在会提示选择语言（English / 中文），并部署对应的 SKILL.md 文件
• Language-aware asset structure: 英文 Skill 放在 assets/skills/，中文 Skill 放在 assets/skills-zh/
• languages field in manifest.json: 将语言 ID 映射到资源目录，便于未来扩展

​

Changed

• assets/skills/ 下的全部 8 个 Comet SKILL.md 文件现在为英文（中文原始版本保留在 assets/skills-zh/）
• copyCometSkillsForPlatform 接受 languageSkillsDir 参数；脚本文件始终从默认的 skills/ 目录获取
• --yes 模式默认选择英文

​

Fixed

• Superpowers redundant project-level install: comet init 现在会在安装 Superpowers 前先检查用户所选所有平台的全局目录（~/{platform}/skills/）。如果某个所选平台已全局安装 Superpowers，则跳过该平台的项目级安装
• Unwanted .agents/ directory creation: comet init 现在会向 skills add 传递 --agent 标志，只针对用户选择的平台。这避免了 skills CLI 自动检测并安装到所有平台，从而不再创建多余的 .agents/ 目录
• OpenSpec global detection: 对 OpenSpec 检测应用相同的全局目录回退逻辑，避免在所选平台已全局存在时重复安装

​

Changed

• hasSkills() 接受 selectedPlatforms 参数，将全局检测范围限定为用户选择的平台
• installSuperpowersForPlatform() 被 installSuperpowersForPlatforms() 替代，后者接受平台 ID 并通过 SKILLS_AGENT_MAP 映射到 skills CLI 的 agent 名称

​

Added

• State File Separation: Comet 工作流状态现在存储在独立的 .comet.yaml 文件中，不再放在 .openspec.yaml 的子树里
• Three-Layer Reliability Defense:
  • 所有阶段的入口校验，带 [HARD STOP] 诊断
  • 所有状态变更采用先写入后校验的模式
  • schema 校验脚本（comet-yaml-validate.sh），支持字段、枚举和路径校验
• Path Traversal Protection: 对 change 名称做输入校验，防止目录穿越攻击
• Guard Script Integration: 在阶段转换时自动进行 schema 校验

​

Changed

• 更新全部 9 个 Comet Skill，使用 .comet.yaml 替代 .openspec.yaml 的 comet: 子树
• 改进错误信息，使用具体字段值替代通用占位符
• 完善项目结构文档

​

Security

• 修复了通过未校验的 change 名称输入导致的路径穿越漏洞
• schema 校验现在能在入口处捕获拼写错误和无效的枚举值