> ## Documentation Index > Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt > Use this file to discover all available pages before exploring further. # Changelog > Comet 发布记录。 本页默认展开当前版本，历史版本按版本逐个折叠。日常升级时先看最新版本的重点变化、破坏性调整和修复项；只有排查旧版本行为时才需要展开对应版本。 Beta 14 修复项目级更新、初始化与卸载中的配置兼容性和作用域问题，使现有项目更容易安全维护。 ### Fixed（修复） * **不完整项目配置**：`comet update` 和 Classic 根目录命令会补齐缺失的 Native 默认字段，而不是拒绝其他配置仍可用的项目。 * **更新作用域**：选择“仅当前项目”后，`comet update` 只刷新该项目；没有可更新的索引项目时会明确说明，而不会改动全局安装。 * **Classic 初始化兼容性**：为已有 Native 项目添加 Classic 时会保留已有根目录 `openspec/` 布局；在不支持硬链接的 exFAT 等文件系统上也能完成初始化。 * **Codex OpenSpec Skills**：项目初始化会将为 Codex 生成的 OpenSpec Skills 安装到其规范的 `.agents/skills/` 目录。 * **卸载选择与完成状态**：项目级卸载采用与初始化一致的平台批量选择；未选择的平台会被保留。选中的 Superpowers 配套 Skills 会被清理，保留用户工作目录内容不会再被误报为卸载失败，真实清理失败会显示原因，并按所选语言输出。 Beta 13 让日常工作流操作更快，并让卸载和 Dashboard 状态更容易判断。 ### Added（新增） * **Native 验证回执刷新**：新增 `comet native receipt refresh [--apply]`，可检查失效的验证回执，并在可安全更新时重新生成手工回执；需要真实重跑的自动检查会明确列出，不会被误标为已通过。 ### Changed（变更） * **选择性工作流卸载**：交互式 `comet uninstall` 现在可按安装目标选择移除 Native、Classic 或两者。移除其中一个时会保留另一个工作流及其共用配置；移除 Classic 时可选是否清理 OpenSpec 与 Superpowers Skill，默认保留它们。 * **日常操作响应**：CLI 启动、Classic 与 Native 工作流命令、写入前检查以及 Native 快照更新均更快；Native 会优先复用未变化文件的已有结果，同时继续检查实际变更。 * **高频公共工作流命令**：高频 Native、Classic 与工作流解析命令保持稳定的 `comet` CLI 接口，同时在内部转入包内 runtime bundle；无需依赖宿主特有的 Skill 路径即可降低冷启动开销。 * **Dashboard 工作区**：Dashboard 提供更清晰的项目切换、搜索和 change 详情查看体验；从仓库子目录启动时能发现项目，并在独立、只读的 Native 工作区旁呈现 legacy 与 docs 布局中的 Classic change。 ### Fixed（修复） * **Classic 配置兼容性**：初始化和更新能够保留已有 Classic 项目的目录选择，并在旧项目配置不完整时更可靠地识别可继续使用的目录。 * **可移植的工作流执行**：Native 与 Classic Skill 现在调用公共 `comet` CLI，而不再搜索特定平台的 Skill 目录或调用内部 bundle。未安装 CLI 时会清晰停止；工作流路由仍会立即通过 Skill 工具加载选中的 Skill。 * **Classic 执行选择**：Classic 现在展示工作流支持的全部隔离与执行选择；用户选定后直接运行对应动作，失败时报告原错误，不再预先筛除选项。 * **Dashboard 状态提示**：Classic change 的验证状态现在使用通过（绿）、失败（红）、待验证（琥珀）和中性颜色区分；无效端口会在启动前给出明确错误。 ### Security（安全） * **Classic 阶段保护**：宿主配置目录和 worktree 不再绕过 Classic 阶段限制，避免在非 Build 阶段通过 `.claude/` 等路径隐藏源码写入。 * **Dashboard 构建依赖**：更新 Dashboard 的 CSS 构建依赖，修复可能经由不可信 source map 引用读取非预期映射文件的风险。 Beta 12 简化 Classic 目录迁移与 Dashboard 定位，并收敛 Native 的验证证据、修复交互和恢复指引。 ### Changed（变更） * **Classic 根目录迁移**：`comet classic root move docs --dry-run` 直接报告当前状态、冲突与阻塞项，不再生成 plan ID；`--apply` 无需 plan ID 即可迁移完整 `openspec/` 目录，包括活跃和未完整归档的 change。输出遵循 `classic.language`，已使用 `docs/openspec/` 的项目会得到明确的无需操作结果。 * **Native 工作流指引**：Native 会先识别当前 change 与阶段，再加载对应阶段的参考；进入实现前始终完成 Shape 分类、静默假设检查与共享理解确认。Build 中出现新的用户决定时，会暂停实现、重新澄清并确认更新后的需求，再继续推进。项目级和 change 级命令按任务组织，减少与当前阶段无关的信息。 * **Native 验证与修复**：Verify 通过时自动运行并绑定内置必需检查。验收证据可以来自人工观察或由 Runtime 执行的项目命令；命令执行支持 Windows shim，并在保存摘要前清理疑似凭据。Runtime 从失败证据推导修复缺口；仍有一次 override 时由 Agent 提出新的具体修复假设，override 或验证预算耗尽后才返回一次明确的用户决策。 ### Fixed（修复） * **Classic Dashboard 定位**：从仓库子目录启动 Dashboard 时会自动定位项目根目录，并按 `classic.artifact_layout` 读取 Classic change；采集失败会显示错误，不再伪装为空工作区。 * **显式 Comet Skill 路由**：`/comet` 只在你明确调用它，或明确要求使用 Comet 但未指定 Native 或 Classic 时进入。入口会直接按项目配置进入 Native 或 Classic，并保留原始请求，不再重新判断任务是否相关或按任务规模改选工作流。 * **失效的当前 change 选择**：当当前选择指向已不存在或已归档的 change 时，Comet 会重新检查活跃 change：没有候选时可正常处理其他工作；唯一候选仅用于只读恢复；多个候选时仍要求你明确选择。 * **Native baseline 恢复提示**：baseline 不完整时的诊断会同时提示 `native.snapshot.max_files`、总字节与时长预算，文件数超限可以直接定位到对应配置。 ### Removed（移除） * **Native 密码学审查**：移除 controller trust、签名身份、实现声明、独立审查和 waiver receipt 及其 CLI/Eval 交接路径。Native 现在只依赖绑定到当前 revision、contract、scope、snapshot 与产物的完整验收证据和内置必需检查。 * **冗余 Native CLI 输入**：移除 `comet native list` 别名、manual receipt 的 `--responsible` 与 `--confirmed`，以及由调用方传入的 `next --receipt`、`--evidence-receipt`、`--failure-category` 和 `--failed-check`。使用不带 change 名称的 `status` 查看列表，并在 `verification.md` 中引用验收 receipt；仍持有 v2 receipt 的 active change 需要重新记录 schema v3 证据。 Beta 11 简化 Native change 创建，并补齐项目配置的默认值和升级迁移。 ### Changed（变更） * **项目配置默认值**：新 Classic 配置默认使用 `classic.artifact_layout: docs`。`comet update` 会补齐缺失的 Native 与 Classic 托管字段；只有检测到需要保留的根目录 `openspec/` 项目时才继续写入 `legacy`。 * **按风险触发 Native 审核**：独立审核由真实 implementation scope 与风险决定，不再由 change 创建时的签名模式决定。普通 change 可以直接开始，高风险验证仍保持失败闭合。 ### Removed（移除） * **Native 创建授权**：`comet native new` 不再要求 `--creation-authorization`；`signed-v2` 创建协议和 `comet native trust authorize` 已删除。 Beta 10 重点引入 Native Loop，为 Classic 提供可选择、可迁移的文档目录布局，并修复本地 workflow Eval 与 Creator Bundle 的兼容链路。 ### Added（新增） * **定向平台安装与更新**：`comet init` 和 `comet update` 新增 `--platform `。需要修复或刷新单个平台时，不必重新处理项目中的其他平台；未指定该参数时，仍沿用现有的自动检测与回退行为。 * **CodeGraph 索引生命周期**：非交互项目初始化可以显式选择 `comet init --codegraph init|skip`。`comet doctor` 会区分 CLI 缺失、索引缺失、不完整、过期和可用状态；只有经过授权的 `comet doctor --repair --yes` 才会执行初始化、重建或同步（[#245](https://github.com/rpamis/comet/issues/245)）。 * **Classic 可配置目录布局**：项目可通过 `classic.artifact_layout: legacy|docs` 在 `openspec/` 与 `docs/openspec/` 两种布局间选择。`comet classic root show` 可以查看当前布局；已有项目使用 `comet classic root move docs --dry-run` 和 `--apply` 安全迁移产物及配置（[#173](https://github.com/rpamis/comet/issues/173)）。 * **Native 证据化验收**：每条强制验收项都必须绑定当前 snapshot 和 scope 下的有效证据。Native 可以分别记录自动检查、人工观察、实现声明、独立审查和经批准的结构化豁免；失败、跳过、阻塞、过期或覆盖不完整的证据不能产生通过结果，高风险变更还需要独立复核（[#240](https://github.com/rpamis/comet/issues/240)）。 ### Changed（变更） * **Classic 文档目录**：新建的 Classic 或双工作流项目默认把 OpenSpec 产物放在 `docs/openspec/`，与 `docs/comet/`、`docs/superpowers/` 组成统一文档目录。已有项目继续使用当前的根目录 `openspec/`，除非显式迁移；所有 Classic 命令都会遵循所选布局（[#173](https://github.com/rpamis/comet/issues/173)）。 * **Native Loop**：Verify 不通过时，Runtime 会把 failed/missing acceptance 和失败检查稳定回灌到 Build。实现者按缺口分批修复并重新验证；只有完整验收通过后才进入 Archive。一次 Agent turn 或代码发生变化不代表完成，只有缺口减少、检查转绿或证据补全才算进展；达到停滞条件或失败预算后会停止并等待用户决定（[#209](https://github.com/rpamis/comet/issues/209)、[#242](https://github.com/rpamis/comet/issues/242)）。 * **Native 归档确认**：`native.archive_confirmation: required` 会在最终 Archive 候选上要求一次明确决定；保持默认配置时继续自动归档。中间修复轮次不会触发归档确认，选择暂不归档也会保留当前 active change（[#238](https://github.com/rpamis/comet/issues/238)）。 * **Native 渐进式指引**：Native 入口优先呈现当前阶段、验收缺口和下一动作，只有在需要时才加载澄清、命令、产物与恢复细节。 ### Fixed（修复） * **Classic 归档引用**：归档时会把 change 内的 handoff 和相关产物引用更新为带日期的归档位置，并在完成前验证引用；成功归档后不再需要手工修正 `.comet.yaml`（[#244](https://github.com/rpamis/comet/issues/244)）。 * **辅助 worktree 诊断**：`comet doctor` 会区分当前 worktree 资产、仅主 worktree 可见的资产和可用的全局兜底，不再把辅助 worktree 中有意未复制的忽略文件误报为损坏（[#246](https://github.com/rpamis/comet/issues/246)）。 * **本地 Eval 执行环境**：本地任务镜像现在包含评估所需的 Claude Code，并以非 root 用户运行，quick 和 full Eval 可以稳定识别执行环境并启动 runner（[#229](https://github.com/rpamis/comet/issues/229)）。 * **本地 Eval 校验器**：复制到任务中的轻量校验器可以可靠加载随附的 scaffold runtime；workflow Eval 只使用与工作流契约匹配的任务，无 Skill 的 CONTROL 结果保留为对照数据，不再错误阻断有效的 Dynamic Skill 结果（[#229](https://github.com/rpamis/comet/issues/229)）。 * **Creator Bundle 可移植性**：Creator 生成的工作流 Bundle 使用项目相对的证据路径和平台无关的创作说明，不再把 Claude 专用自定义 Agent 声明为 Codex 发布所必需的运行能力；成功的本地 Eval 结果会写回当前 Bundle 的评估证据（[#229](https://github.com/rpamis/comet/issues/229)）。 ### Security（安全） * **Native 审批隔离**：签名工作流的审批凭据保存在项目和实现者之外，项目内的变更不能自行取得批准权限（[#240](https://github.com/rpamis/comet/issues/240)）。 ### Added（新增） * **Sequential 澄清评估**：新增可重复运行的 Native 多轮评估，用于检查 Sequential 是否先调查仓库事实、逐个解决相互依赖且应由用户决定的问题、记录每次答案、在进入 Build 前确认完整共享理解，并完成经过验证的实现。任务定义的回复序列让每条决策路径都可复现，不再允许模拟用户自行补充选择。 * **`comet native evidence format`**：新增命令，可将验收证据条目序列化为 `verification.md` 所要求的规范 Markdown 区块。用户不再需要手动调整证据格式，也不会再因字节级格式差异触发错误的“规范序列化”拒绝。 ### Changed（变更） * **Native 澄清模式**：Sequential 现在会在每次回答后重新计算剩余的用户可见决定，每轮只提出一个最上游决定并说明推荐与影响。Batch 会按前置关系维护用户可见结果的决策树，每轮询问整个 ready frontier；支持并行能力时，环境事实调查不会阻塞其他已具备条件的问题。两种模式都要求最终共享理解摘要中的每项行为可追溯，并由 Runtime 强制取得明确确认后才能进入 Build；旧的 `implicit` change 在离开 Build 前也必须确认。 ### Fixed（修复） * **大型仓库的 Native baseline**：Native 内容快照现在支持绑定到 baseline 的 include/exclude 策略，以及 `.comet/config.yaml` 中可配置的文件数量、总字节数和执行时长预算；默认总预算为 256 MiB，不再有独立的 5 MiB 单文件上限。Runtime 继续使用流式 SHA-256 哈希真实工作区内容，记录实际策略与限制供审计，并在无法取得完整 baseline 时给出可执行的配置修复方法（[#226](https://github.com/rpamis/comet/issues/226)）。 * **全局工作流选择**：`comet init` 现在会在 global 安装时提供 Native、Classic 或两者，并接受 `--scope global --workflow native|classic|both`；全局 Skill 安装因此与项目级提供相同的工作流选择，未显式指定 workflow 的非交互 global 安装仍默认使用 Classic（[#234](https://github.com/rpamis/comet/issues/234)）。 * **显式调用 Comet Skill**：Ambient Resume 项目指令现在会让宿主识别出的手动 Comet Skill 调用优先于恢复探测，避免当前没有 active change 时，`none` 或 `out_of_scope` 结果错误跳过 `/comet`（[#235](https://github.com/rpamis/comet/issues/235)）。 * **Classic 归档最终状态**：Classic 现在会在不可逆归档前确认立即远端交付，在唯一归档提交前写入 `branch_status: handled`，并只推送这份完整提交一次。成功归档后不再遗留未提交的 `.comet.yaml`，远端归档状态也不会停留在 `pending`（[#237](https://github.com/rpamis/comet/issues/237)）。 * **插件市场 Superpowers 检测**：当 `~/.claude/plugins/cache/`（或对应的 Codex 路径）中，本应为 marketplace 目录的位置出现普通文件时，`comet init` 不再因 `ENOTDIR` 错误崩溃。 ### Security（安全） * **防竞态文件读取**：读取 `.comet/current-change.json`（每次 Hook Router 调用、`comet doctor` 和 `comet resume-probe` 都会使用）、Native 锁文件及 `comet native evidence format --entries` 输入时，现在会在打开前拒绝非普通文件，并在打开后及读取后验证文件身份没有变化。中途将文件替换为符号链接会使读取失败，而不会泄露链接目标内容；锁路径上的 FIFO 也不再导致进程挂起。Windows 缺少 `O_NOFOLLOW` 时，会通过相同的文件身份检查获得等效保护。 Beta 8 是一个修复与安全加固版本。它不新增命令、配置或工作流行为。 ### Fixed（修复） * **Windows Native 文件校验**：Windows 路径元数据与文件句柄元数据对设备或 inode 标识的可用性不一致时，`comet status`、`comet doctor` 和其他 Native 读取不再把稳定文件误报为 `changed while opening`。文件替换与写入期间变更的检测仍然保留。 ### Security（安全） * **开发依赖加固**：npm 和 pnpm 依赖解析统一锁定到已修复的 `brace-expansion` 5.0.7，避免恶意 brace 模式让开发工具链出现指数级 CPU 消耗。 * **Classic handoff 校验**：运行时改用精确行匹配校验已记录的 handoff 来源路径，不再把项目可控的 spec 目录名当作正则表达式，避免异常目录名导致 Classic design guard 崩溃或长时间阻塞。 如果你从 Beta 6 升级，最明显的变化是新增了 Comet Native。它面向能够自行完成复杂代码推理、但仍需要需求澄清、状态、验证和归档证据的强模型。Classic 没有被替代；你可以继续使用 Classic，也可以在同一项目中安装两套工作流。 ### Added（新增） * **Comet Native 工作流**：新增独立的 `/comet-native` 工作流，不依赖 OpenSpec、Superpowers 或其他外部 Skill。它使用 Shape、Build、Verify、Archive 四个阶段，支持可恢复 checkpoint、完整目标规格和独立的 change 状态。需求澄清默认使用 `sequential`，每轮只处理一个最上游问题；你也可以切换到 `batch`，一次回答当前所有独立问题。参见 [Native 工作流](https://docs.comet.rpamis.com/zh/concepts/native-workflow)和 [Native 快速开始](https://docs.comet.rpamis.com/zh/native/quickstart)。 * **Native 与 Classic 真实评估**：两套工作流使用相同的 **16 个业务任务**，每个任务重复 3 次，共 **96 次运行**。Native 的 **strict pass\@1 为 95.83%**，Classic 为 **89.58%**；两者的 **pass\@3 都是 100%**，Native 的 **pass^3 为 87.5%**，Classic 为 **75%**。Native 的**修正平均模型耗时低 47.8%**。在双方都严格通过的 **41 组配对样本**中，Native 的**总 Token 少 76.8%**，**模型成本低 75.1%**。耗时数据来自不同运行时段，因此只作为方向性证据。参见 [完整对比报告](https://docs.comet.rpamis.com/zh/eval/comet-native-vs-040-experiment)。 * **Native 澄清模式评估**：在同一个任务上，Batch 与 Sequential 各运行 **10 次**。Batch 的平均外层交互轮次从 **4.5 降到 2.7（减少 40%）**；平均累计模型耗时从 **712 秒降到 617 秒（减少 13.3%）**。但 Batch 的 **strict pass\@1 为 60%**，低于 Sequential 的 **70%**。这是单任务小样本，说明两种模式存在效率与可靠性的取舍，不能据此认定 Batch 更可靠。参见 [澄清模式评估](https://docs.comet.rpamis.com/zh/eval/comet-native-clarification-experiment)。 * **可选 Eval suite**：`comet eval --suite local|langsmith` 可以选择本地或 LangSmith 评估。Local 仍是默认值；LangSmith 使用同一套任务和评分逻辑，并自动选择 tracing runner、报告目录和 Claude Code tracing plugin。 ### Changed（变更） * **项目工作流选择**：项目级 `comet init` 现在提供 Native、Classic 和 Both 三种选择。新项目默认让 `/comet` 进入 Native，Native 产物默认写入 `docs/comet/`。Both 会安装两套独立工作流，但不会混合它们的 change、状态和产物。 * **入口、状态与恢复分离**：`/comet-native` 和 `/comet-classic` 是固定入口，`/comet` 只按项目配置选择其中一个。`comet status`、`comet resume-probe` 和 Dashboard 会分别显示与恢复 Native、Classic 和未托管 OpenSpec change，双工作流项目不会对同一次写入重复拦截。 * **Native 执行与恢复边界**：Native 在开始修改前记录完整项目基线，并把实现范围、验收条件和验证报告绑定到 change。快照不完整时不会推断文件已删除；验证连续失败且没有真实代码进展时会停止重试。中断后可以恢复状态、归档和产物根移动。 * **Node.js 运行时要求**：Beta 7 要求 Node.js 22 或更高版本。升级前请先确认本地、CI 和 Docker 环境的 Node.js 版本。 * **更新命令不再隐式升级 npm 包**：在当前项目运行 `comet update` 时，只刷新 Comet 托管的项目资产。需要同时更新 CLI 时使用 `comet update --self-update`。更新会校验完整预发布版本、拒绝降级，并在安装失败时尝试恢复原版本。Classic 的配置会迁入 `.comet/config.yaml` 的 `classic:` 块，现有明确配置会被保留。 ### Fixed（修复） * **初始化与更新结果**：`comet init` 和 `comet update` 在工作未完整完成时返回非零退出码，并保留 npm 诊断。批量更新会区分失败项目和未尝试项目；组件失败后不再显示成功横幅。 * **OpenSpec 版本诊断**：如果已安装的 OpenSpec CLI 版本过旧且你没有选择升级，初始化会直接说明版本不满足要求，不再误报为 CLI 不可用。 * **Windows 与并行 Eval**：Windows Docker 交互评估优先使用 Git Bash，保留容器内 prompt 路径，并按真实 driver turn 计数。并行 worker 会等待共享 Docker build lock，不再把正常并发误报为资源死锁。 ### Added（新增） * **`comet state rebind`**：用户明确确认当前分支应接管 change 后，可以用新命令重新绑定工作分支并记录审计事件；尚未建立首次绑定或处于 detached HEAD 时会拒绝执行。 ### Changed（变更） * **工作区分支绑定**：`current`、`branch` 和 `worktree` 三种隔离方式都会记录建立时的 Git 分支。后续切换分支会被 build、verify、archive 入口检查和源码写入守卫阻止；选择漂移的 change 也会失败，而不会静默覆盖绑定。旧 change 会在下一次 select 或 check 时补齐绑定，非 Git worktree 项目不受影响。 * **工作区隔离选择**：full、hotfix 和 tweak 都会让用户显式选择继续使用当前分支、创建新分支或创建 worktree，不再替用户静默决定。full workflow 现在也支持 `isolation: current`（[#190](https://github.com/rpamis/comet/issues/190)）。 * **状态与归档提示**：`comet status` 的文本和 JSON 输出会显示隔离方式与绑定分支；`current` 隔离归档时只询问推送当前分支或保留本地，不再提供面向功能分支的合并/PR 选项。 ### Fixed（修复） * **Skill 发现容错**：无关本地 Skill 的 YAML frontmatter 格式错误不再中断 Bundle Factory 指引或候选发现，Comet 会跳过损坏的描述并继续扫描。 ### Changed（变更） * **Skill 触发与决策创作**：内置阶段 Skill 和 Creator 生成的内部 Node Skill 明确入口与 Runtime 边界；Creator 在生成暂停点前区分自动处理、停止条件和人工交接，减少不必要的内部 Skill 调用与用户提问。 * **工作流 checkpoint**：清晰请求跳过多余命名确认；Build 预检可执行能力并合并相邻配置决定；大型 PRD 使用可恢复批次 manifest，恢复不再依赖未写入磁盘的对话状态。 * **验证修复与归档归属**：前三次可执行验证失败自动返回 Build，并跨恢复保存连续失败次数；Verify 只记录证据，Archive 在分支处理前只提交归属路径，确保最终分支包含规格和归档元数据。 * **Preset 执行语义**：Hotfix/Tweak 会如实记录当前工作区隔离，直接模式仍保留回归测试，升级完整工作流后清除轻量执行设置。 * **Dashboard 产物预览**：Markdown 预览支持表格、引用、任务列表、语法高亮和 Mermaid；全屏目录、重复标题锚点、长路径复制以及 YAML/JSON 结构化表格也得到统一处理。 ### Fixed（修复） * **OpenSpec 兼容性**：要求 OpenSpec 1.5+，并从 live schema 驱动 `/comet-open`，校验项目相对路径与具体输出，恢复 split batch 时不重建已完成 change。 * **Codex Hook 配置**：项目级和全局 Codex 安装写入受支持的 `.codex/hooks.json`，并安全迁移旧的 Comet 管理配置（[#199](https://github.com/rpamis/comet/issues/199)）。 * **标准 Superpowers 产物**：Classic 写入守卫接受标准目录中的首次设计、计划和验证产物，同时保留阶段、选择和重复占位检查。 * **Skill 生命周期完整性**：初始化、更新、Doctor 和卸载会一致报告 Skill、Rule、Hook 失败，保留损坏的用户 Hook 配置，并避免把部分安装登记成成功。 ### Security（安全） * **Dashboard 预览 XSS 防护**：Markdown/YAML/JSON 预览使用 DOMPurify，阻止危险 URL 与属性注入；Mermaid 使用严格安全模式，避免不可信产物执行脚本。 ### Added（新增） * **自然语言恢复探测**：新增低噪声的恢复探测机制和项目说明。继续处理已有工作时，即使没有显式输入 `/comet`，Agent 也可以先探测当前请求是否适合恢复活跃 workflow；存在歧义、未提交改动或需要用户决策时仍会暂停确认。 * **项目安装索引**：项目级安装会登记到用户级索引。交互式 `comet update` 和 `comet uninstall` 可以在当前项目与所有已登记项目之间选择；`--json` 或显式 `--current-project` 会限定当前项目，`comet uninstall --force` 也保持当前项目，跨项目操作需要显式使用 `--all-projects`。 * **稳定的 Classic 命令**：新增顶层 `comet state`、`comet guard`、`comet handoff` 和 `comet archive` 命令，Agent 和自动化不再需要依赖安装目录中的内部脚本路径（[#186](https://github.com/rpamis/comet/issues/186)）。 * **自定义项目命令证据**：无法自动推断 npm、Maven 或 Cargo 命令的项目，现在可以记录真实执行的 build/verify 命令及退出结果，形成可审计证据，而不必使用未文档化的跳过路径（[#192](https://github.com/rpamis/comet/issues/192)）。 * **CodeBuddy Hook 支持**：CodeBuddy Code 的项目级和全局安装现在会把 Comet PreToolUse hook 非破坏性合并到 `.codebuddy/settings.json`，保留用户已有插件、设置和 hook；配置无效时会保持原文件不变并明确报告失败（[#193](https://github.com/rpamis/comet/issues/193)）。 ### Changed（变更） * **混合 change 状态**：`comet status` 现在区分 Comet 管理的 change 与普通 OpenSpec change，并只为已就绪的条目推荐对应归档命令（[#187](https://github.com/rpamis/comet/issues/187)）。 ### Fixed（修复） * **并行 active change 守卫**：当多个 change 同时活跃时，源码写入会绑定到显式选择的当前 change。合法的 build 工作不再被另一个处于 open、design 或 archive 的 change 误阻塞；选择不明确时会给出可执行的选择提示（[#196](https://github.com/rpamis/comet/issues/196)）。 * **Codex CLI Skill 发现路径**：Codex 的项目级和全局安装现在把 Comet Skill 放在当前的 `.agents/skills` 发现目录中，Codex 专属配置仍保留在 `.codex`。更新和卸载会迁移 Comet 管理的旧 `.codex/skills` 内容，并保留无关 Skill。 * **生成式 Eval manifest**：`comet eval` 会在运行时把 Skill Factory manifest 中的 `draftHash` 占位值解析为当前版本绑定值，因此 `/comet-any` 的产物可以直接评估，且不会改写生成的 Bundle 文件（[#183](https://github.com/rpamis/comet/issues/183)）。 * **Eval harness 定位**：通过 npm 安装的 `comet eval` 现在默认使用同版本随包分发的 harness，并把“harness 缺失”与“`uv` 不可用”分别报告，便于准确定位环境问题。 * **跨项目更新结果**：`comet update --all-projects` 会把 npm 包更新失败计入对应项目的失败结果；项目索引不可读时会明确失败，不再把问题报告成成功或空索引。 * **Dashboard 响应式工作区**：`comet dashboard` 在显示左侧导航时会把 change 工作区保持在视口内；打开 artifact preview 会保留滚动位置，已归档 change 会显示为完成状态，而不是再次建议 verify（[#170](https://github.com/rpamis/comet/issues/170)）。 * **已有 Skill 目录的符号链接安装**：`comet init` 与 `comet update --install-mode symlink` 会保留平台现有的 `skills/` 目录，并只链接 Comet 管理的 Skill，本地或第三方 Skill 不再导致安装失败（[#171](https://github.com/rpamis/comet/issues/171)）。 * **OpenSpec CLI 安装范围**：即使选择项目级 Comet 安装，`comet init` 也会把 OpenSpec CLI 作为全局工具安装或升级，不再因为该选择在项目中创建 `node_modules/`（[#175](https://github.com/rpamis/comet/issues/175)）。 * **已归档 Dashboard 产物**：Dashboard 会从已归档 change 正确回到项目根解析 `docs/superpowers/` 路径，归档后的设计、计划和验证报告仍可查看（[#176](https://github.com/rpamis/comet/issues/176)）。 * **归档最终确认**：`/comet-archive` 会把用户最终批准记录到机器管理的 Classic 状态；在确认 transition 成功前，真实归档命令拒绝修改，避免直接调用脚本绕过确认。 * **归档注释格式**：Classic 归档注释会保留正常的 Markdown 文件结尾，并可安全重复执行，避免产生 `git diff --check` 格式错误（[#185](https://github.com/rpamis/comet/issues/185)）。 * **全局产物语言**：全局 `comet init` 和 `comet update` 会把所选产物语言保存到 `~/.comet/config.yaml`。Classic workflow 优先读取项目配置，再回退到全局默认；项目仍可覆盖该设置（[#174](https://github.com/rpamis/comet/issues/174)）。 ### Fixed（修复） * **Doctor 范围诊断**：`comet doctor` 现在会报告 auto scope 行为、Node/平台环境信息；当全局 Comet 安装可用但当前项目没有本地 Skill 副本时，会给出不惊扰的项目级提示，让用户区分"项目级安装可选"和"安装损坏"。 * **PowerShell 初始化输出**：`comet-state.mjs init` 现在把成功初始化信息写到 stdout，Windows PowerShell 不再把成功创建 `.comet.yaml` 误报成 `NativeCommandError`（[#167](https://github.com/rpamis/comet/issues/167)）。 * **版本短参数**：`comet -v` 现在等同于 `comet --version`，符合常见 CLI 习惯（[#167](https://github.com/rpamis/comet/issues/167)）。 * **Classic runtime 兜底**：Classic 阶段脚本现在保留内嵌 runtime 包兜底，即使某个平台安装缺少内部 `runtime/classic` 资产，`comet-guard.mjs`、handoff 和 archive 流程仍能运行（[#168](https://github.com/rpamis/comet/issues/168)）。 * **项目配置查找**：Classic guard 现在只从 `.comet/config.yaml` 读取项目默认配置；工作流状态仍只属于每个 change 的 `.comet.yaml`，根目录 `.comet.yaml` / `comet.yaml` 不再参与配置或状态解析（[#158](https://github.com/rpamis/comet/issues/158)）。 ### Removed（移除） * **自定义 guard 命令字段**：Classic 工作流状态不再接受 `build_command` 和 `verify_command`。guard 改为使用内置项目构建探测路径，旧字段会作为未知字段被拒绝。 ### Fixed（修复） * **单语言规则安装**：`comet init` 和 `comet update` 现在只安装与所选/检测到的 Skill 语言匹配的 Comet 阶段守卫规则文件（例如 `.claude/rules/comet-phase-guard.md`），不再无论语言选择都同时安装中英文两个规则变体。 * **符号链接安装安全性**：`comet init` 和 `comet update` 在符号链接安装模式下，如果目标平台的 `skills/` 目录包含 Comet 管理清单之外的文件，现在会拒绝把该目录替换成符号链接，避免删除本地或第三方 Skill（[#159](https://github.com/rpamis/comet/issues/159)）。 * **并行 change 的产物写入**：Classic 阶段守卫现在会把 `docs/superpowers/` 写入路由到匹配的 design/build/verify change，不再因为另一个更早创建的活跃 change 阻塞共享的 Design Doc 和计划产物（[#160](https://github.com/rpamis/comet/issues/160)）。 这是 0.4.0 线的第一个 beta。相对于 0.3.9，Comet 从一个依赖 Bash 的 `/comet` 工作流包，变成了一个跨平台 Node 运行时，覆盖工作流、Skill 创建、评估和可视化四大能力。下面的条目描述的是最终用户可见的发布形态，不是分支开发历史。 ### 重点变化 * **纯 Node 运行时**：所有 Comet 脚本通过 Node.js 运行，macOS、Linux、Windows 用同一套命令，不再需要 Bash、Git Bash 或 WSL。 * **`/comet-any` Skill Creator**：从"生成一个 `SKILL.md`"升级为生成稳定的组合 Skill Bundle，带可评审的创作内容、发布证据链和平台原生文件。 * **`comet eval` 评估系统**：可量化任意本地 Skill 和 Comet 工作流的质量，含 pass\@k/pass^k 可靠性指标和 HTML 报告。 * **配置化产物语言**：`comet init` 现在记录项目级产物语言，OpenSpec 和 Superpowers 产物按配置语言输出。 * **`comet dashboard`**：本地只读浏览器面板，可视化每个变更的阶段、产物、任务和风险。 * **路由上下文**：`/comet` 用结构化路由上下文做可解释路由，风险信号优先于口头流程。 ### Added（新增） * **跨平台 Classic 运行时**：随包分发的 `/comet` 工作流脚本现在通过 Node `.mjs` 启动器运行，背后由 TypeScript Classic 运行时支撑。同一套工作流在 Windows、macOS 和 Linux 上运行，不再需要 Git Bash、WSL 或兼容 shell 的脚本。 * **`comet dashboard`**：新增本地只读浏览器面板，展示进行中和已归档的变更，包括阶段进度、产物分组、任务进度、verify 状态、下一步指引、风险信号、Git 上下文、带元数据的产物预览，以及亮色/暗色 UI。`--json`、`--port`、`--no-open` 和 `GET /api/dashboard` 把同一份快照暴露给脚本和 CI。 * **`/comet-any` Skill Creator**：新增创建或升级可复用 Skill 的主流程。流程覆盖候选发现、可确认的方案、生成的 Skill Bundle、创作决策/指导区、创作车道、当前 draft 的评估就绪、评审批准、发布、分发，以及 Claude Code custom agents 等平台原生文件。 * **Skill Creator CLI**：新增 `comet creator` 用于常规创建/恢复指引，`comet publish` 用于评审、批准、发布和分发预览，后端 Bundle 命令保留为高级工具。 * **本地 Skill 工具**：新增 `comet skill add|show|run|continue|check`，用于安装、检查、运行、恢复和确定性校验本地 Skill 包（带快照）。 * **`comet eval` harness**：新增仓库本地评估，支持 Comet 工作流和任意本地 Skill，含 task profile、生成的 manifest、HTML 报告、token/cost 归因、pass\@k/pass^k 可靠性指标、工作流专用评分、Skill 调用证据检查、可配置的模拟器提示词、Anthropic 兼容代理认证、Windows/WSL 友好执行、UTF-8 日志和回归门禁。 * **Comet workflow 评估任务**：内置 Comet workflow benchmark 扩展到 20 个任务，新增 dependency-confusion、layered streaming、persistence、approval、noise-resistance、cross-file refactor、observability config、graph execution review、agent memory routing、framework selection 等场景，用于更稳地比较 CONTROL、0.3.9 和 0.4.0。 * **Hotfix/tweak 范围决策**：为 hotfix 和 tweak 工作流新增定性升级信号；文件数量阈值现在会暂停询问用户确认，而不是强制自动升级到完整工作流（[#121](https://github.com/rpamis/comet/issues/121)）。 * **支持的平台**：新增 ZCode、MimoCode、Trae CN 和 Antigravity 2.0 支持。Antigravity 2.0 全局安装在 `~/.gemini/config/skills/`；ZCode 和 MimoCode 使用 OpenCode 兼容布局；Trae CN 使用 `.trae-cn/skills`。 * **符号链接安装模式**：`comet init` 和 `comet update` 现在可以选择用复制或符号链接/junction（从共享的 `.comet/skills/` 存储）安装 Skill。 * **项目 Skill 偏好**：新增 `.comet/skill-preferences.yaml`，让项目可以引导首选 Skill、排序和 Skill Creator 方案，而不必手改 bundle 文件。 * **配置化产物语言**：`comet init` 现在把项目级产物语言（`en` 或 `zh-CN`）写入 `.comet/config.yaml`，每个新 change 会把该语言快照到 `.comet.yaml`。OpenSpec 和 Superpowers 产物按配置语言输出，不再按触发请求临时判断；Comet guard 会拒绝明显主语言不匹配的工作流产物，对无效 `language` fail closed，并忽略 fenced code block，避免命令、路径或 hash 干扰判断。 ### Changed（变更） * **Comet 产品定位**：README、CLI 帮助和 Skill 指引现在把 Comet 呈现为一个工作流和 Skill 平台：运行引导式工作流、创建 Skill、评估它们、发布它们，以及诊断卡住的变更。 * **Comet Skill 语言指令**：中英文 Comet Skill 现在读取配置化产物语言（仅 `en` / `zh-CN`，不接受别名）来约束 OpenSpec prompt、Superpowers 参数、subagent 调度、验证报告和归档说明，而不是从触发请求语言推断。 * **Eval judge provider**：LLM-as-judge 现在必须显式设置 `BENCH_JUDGE_MODEL`，并使用独立的 `BENCH_JUDGE_*` provider 配置；配置 judge endpoint 和凭证时优先走 Anthropic 兼容 HTTP。配置不完整时报告 skipped，不再静默复用被测模型、endpoint 或凭证。 * **LangSmith eval 配置**：LangSmith eval 现在从主要 `LANGSMITH_*` 配置派生 Claude Code tracing plugin 设置，trace 保持在配置的 base project，hook logs 保存到 artifacts，并可按需自动构建官方 Claude Code tracing plugin 到 eval cache。 * **Eval 对比报告**：报告现在区分 raw、analysis-set、flagged、excluded runs；把 CONTROL 作为 business-only baseline；拆分 overall、business、workflow 的 pass\@k/pass^k；并输出论文风格 Markdown/HTML，含指标说明、rubric 维度说明、证据、失败归因、居中表格、中英文切换、Python 优先图表和 inline SVG fallback。 * **README eval 证据**：README 现在直接展示 pass\@5/pass^5 以及核心 rubric/judge 指标的论文风格 baseline 图，让 no-Comet、0.3.9 和 0.4.0 的对比不必打开完整报告也能看到。 * **README 格式化策略**：根 README 文件从 Prettier 检查中排除，避免 formatter 改写用户可见 prose 和精确文档措辞。 * **Classic 工作流状态**：机器管理的运行检查点从 `.comet.yaml` 移到 `.comet/run-state.json`，而用户可编辑的工作流字段保持 YAML 可读。Classic 阶段转换现在还会写入 `.comet/state-events.jsonl`，形成可审计的状态历史。 * **Classic 运行时打包**：Classic 控制元数据现在放在 `comet/runtime/classic` 下，命令启动器拆成独立的 Node bundle（`comet-state.mjs`、`comet-guard.mjs`、`comet-archive.mjs` 等），同时保持现有 `/comet*` 命令行为不变。 * **工作流诊断**：`comet status` 和 `comet doctor` 现在共享同一条运行时证据路径，报告当前步骤、运行时模式、畸形状态、缺失证据和推荐恢复动作。 * **工作流路由**：`/comet` 现在对 full、hotfix、tweak、resume 和歧义请求使用显式的路由上下文模型。`/comet-tweak` 现在是 tweak 专用的 OpenSpec action 路径，而完整 `/comet` 仍走 Superpowers 的 design/plan/build 路径。 * **评审工作流**：`review_mode` 现在对 full 工作流默认为 `standard`。`off`、`standard`、`thorough` 形成更清晰的评审梯度，由 Comet 接管评审派发策略，用户不必为重叠的 Superpowers 和 Comet 评审循环买单。 * **交互式决策点**：Comet 决策点现在在可用时优先使用 Claude Code 的结构化提问 UI，其他平台降级为文本。 * **调试工作流**：Debug Gate 可以在按配置的评审流串行应用修复之前，先并行调查独立的失败组。 * **仓库布局**：源码移入 `app/`、`domains/`、`platform/` 和 `scripts/`，测试移到对应的 `test/app/`、`test/domains/`、`test/platform/`、`test/scripts/` 和 `test/repository/` 根目录，让贡献者的职责边界更清晰。 ### Fixed（修复） * **Windows 路径处理**：修复 OpenSpec init/update 在 Windows 上对含空格目录的路径引用，`comet init` 不再因为项目路径含空格而失败。 * **Git 子模块脚本查找**：当 agent 在 Git 子模块内工作时，Comet hook 和运行时脚本解析现在使用所在项目根，子模块内的编辑不再因为 `.claude/skills/comet/scripts/*` 只在父项目级别存在而失败（[#136](https://github.com/rpamis/comet/issues/136)）。 * **Superpowers 工作区写入**：Comet 阶段写入守卫现在允许 Superpowers 在受保护阶段写入 `.superpowers/` workspace，不再把 Superpowers 进度文件误判为被阻止的源码编辑（[#154](https://github.com/rpamis/comet/issues/154)）。 * **Doctor 诊断**：`comet doctor` 现在给出更清晰的版本、项目/全局范围、畸形状态、缺失证据和恢复指引，让用户能区分"真的缺少项目安装"和"有效的全局安装"，并理解当前 `.comet.yaml` 的状态问题（[#135](https://github.com/rpamis/comet/issues/135)）。 * **评审模式一致性**：英文、中文、共享规则和恢复指引现在对 `review_mode` 达成一致，已安装的 Skill 不再描述一个与运行时 guard/state 检查冲突的旧双评审流程（[#126](https://github.com/rpamis/comet/issues/126)）。 * **init/update 的项目配置合并**：`comet init` 和 `comet update` 现在对 `.comet/config.yaml` 做字段级合并，而不是文件存在就跳过。保留现有用户值、补齐缺失的管理字段、刷新注释、保留额外用户字段；损坏的 YAML 优雅回退到全部默认。 * **init 结果汇总**：`comet init` 现在把有任何组件失败的平台排除出 `Installed` 列表并点名失败组件，OpenCode 等平台不再同时显示为已安装和失败（[#128](https://github.com/rpamis/comet/issues/128)）。 * **`.husky/pre-commit` 可执行位**：修复 pre-commit hook 文件以非可执行模式提交的问题；此前 clone 或 checkout 后 Git 会静默跳过 hook，导致 `format:check` / lint-staged 自动化失效。现在以可执行位分发。 ### Removed（移除） * **Bash 优先的 Classic 脚本**：移除了随包分发的 Classic 工作流脚本必须通过 Bash 兼容 shell 脚本运行的要求。 ### Security（安全） * **Dependabot 依赖告警**：把测试工具钉到打过补丁的 Vite 和 esbuild 版本（覆盖 npm 和 pnpm lockfile），清除了待处理的 Vite 路径穿越、launch-editor 和 esbuild dev-server 告警，且不改变 Comet 运行时依赖。 ### 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](https://github.com/rpamis/comet/pull/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](https://github.com/rpamis/comet/pull/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](https://github.com/rpamis/comet/pull/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//` 的操作现在由该 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 `，并遵循 `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](https://github.com/rpamis/comet/pull/90)）。 * **Version info and update check**: `comet init` 和 `comet update` 现在会在命令输出开头显示当前已安装的 Comet 版本，并检查 npm registry 是否有更新版本。如果有可用更新，用户会看到升级提示；如果已是最新版本，则显示确认消息；如果无法访问 registry，则静默跳过检查而不报错（[#99](https://github.com/rpamis/comet/issues/99)）。 * **Official registry enforcement for update**: `comet update` 现在在更新 `@rpamis/comet` 包时向 npm 传入 `--registry https://registry.npmjs.org`，确保无论用户的本地 `.npmrc` 或镜像配置如何，始终从官方 npm registry 拉取。其他包继续使用用户正常的 registry 设置。如果官方 registry 不可访问，会显示明确的错误消息指出 registry 问题（[#100](https://github.com/rpamis/comet/issues/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 `，用于验证特定任务在 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](https://github.com/rpamis/comet/issues/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](https://github.com/rpamis/comet/pull/86)）。 ### Fixed * **Pi slash command discovery**: `comet init` 和 `comet update` 现在会生成一个 Pi 扩展，将所有内置的 `/comet*` 工作流注册为原生斜杠命令并转发到 `/skill:*`。Pi 设置以非破坏性方式合并，启用 skill 命令；全局资源现在使用 Pi 官方文档记载的 `~/.pi/agent/` 目录，会检测旧的 `~/.pi/skills/` 安装以进行更新和清理，且 `comet uninstall` 仅移除 Comet 管理的资源，同时保留共享设置和无关的扩展（[#89](https://github.com/rpamis/comet/issues/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](https://github.com/rpamis/comet/issues/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](https://github.com/rpamis/comet/issues/94)、[#96](https://github.com/rpamis/comet/issues/96)、[#97](https://github.com/rpamis/comet/issues/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](https://github.com/rpamis/comet/issues/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](https://github.com/rpamis/comet/issues/98)）。 * **OpenSpec CLI upgrade and --profile fallback**: `ensureOpenSpecCli` 现在始终安装/升级 openspec 到最新版本，即使已存在旧版本，确保用户获得 `--profile` 支持和其他改进。新增了回退逻辑：如果 `openspec init` 在 stderr 中报 "unknown option --profile"，则不带该标志重试，以应对升级失败但残留旧 openspec 的边缘情况（[#84](https://github.com/rpamis/comet/issues/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](https://github.com/rpamis/comet/issues/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 "" --json`），从 JSON 载荷中加载 `context`、`rules`、`template`、`instruction`、`resolvedOutputPath` 和 `dependencies`，替代了硬编码的产物文案。在指令失败时停止产物生成，而不是静默绕过项目规则（[#66](https://github.com/rpamis/comet/issues/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](https://github.com/rpamis/comet/pull/74)）。 * **Deterministic next-step resolver**: 新增 `comet-state next `，根据 `.comet.yaml`（`phase`、`workflow`、`auto_transition`）解析 guard 之后的路由逻辑，并输出结构化结果：`NEXT: auto|manual|done`、`SKILL: ` 和 `HINT`（手动模式下）。这将下一步 skill 的路由逻辑集中到脚本中，避免在各 skill 文案中重复编写。 * **Workflow output language**: Comet 工作流现在通过显式的输出语言规则，将触发用户请求的语言传播到 OpenSpec 和 Superpowers 步骤中，确保生成的提案、设计、计划、验证报告和归档说明都能以用户的语言呈现，保持可读性。恢复已有的 change 时，会保留产物的主要语言，除非用户明确要求切换（[#53](https://github.com/rpamis/comet/pull/53)、[#37](https://github.com/rpamis/comet/issues/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](https://github.com/rpamis/comet/issues/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 verify_mode ` 覆盖自动验证规模评估。 * **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](https://github.com/rpamis/comet/pull/76)、[#41](https://github.com/rpamis/comet/issues/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 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](https://github.com/rpamis/comet/issues/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 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](https://github.com/rpamis/comet/issues/79)）。 * **skip-all skipping uninstalled components**: `comet init` 不再将之前跳过的组件视为已安装。选择 skip-all 现在只跳过实际存在的组件，因此未安装的 OpenSpec、Superpowers、Comet 或 CodeGraph 组件仍会被提示安装，而不是被静默跳过（[#73](https://github.com/rpamis/comet/pull/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](https://github.com/rpamis/comet/issues/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](https://github.com/rpamis/comet/issues/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](https://github.com/rpamis/comet/pull/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](https://github.com/rpamis/comet/pull/53)）。 * **Review gate regression**: 新增了 skill 覆盖测试，验证 `executing-plans` 构建模式在 build→verify 转换之前需要 `requesting-code-review` 关卡，并更新了 init-e2e 的期望（[#76](https://github.com/rpamis/comet/pull/76)）。 * **skip-all regression**: 新增了 `comet init` 覆盖测试，验证 skip-all 仅跳过已安装的组件，仍会提示安装未安装的 OpenSpec/Superpowers/Comet/CodeGraph 组件（[#73](https://github.com/rpamis/comet/pull/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 --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 ` 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 `） ### 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`） Comet 0.2.0 是一次综合性优化版本：涵盖 Skill 可靠性、CLI 完整性以及工程质量。 ### 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 校验现在能在入口处捕获拼写错误和无效的枚举值