feat: core issues in comet state machine and enhance workflows

Author: benym

CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to @rpamis/comet will be documented in this file.
 
+## What's Changed [0.2.4] - 2026-05-21
+
+### Added
+
+- **Verification evidence enforcement**: `verify-pass` transition now requires `verification_report` (file must exist) and `branch_status: handled` before allowing phase advance. Guard checks these as hard prerequisites
+- **`verification_report` and `branch_status` fields** in `.comet.yaml`: New state fields track verification report path and branch handling status
+- **Verification evidence step** in comet-verify (zh): New Step 4 requiring report file creation and branch status recording before guard apply
+- **`branch_status` enum validation**: `comet-state.sh set` validates `branch_status` as `pending` or `handled`
+- **Guard verify checks**: `comet-guard.sh` now checks `verification_report exists` and `branch_status=handled` during verify phase
+- **Bats test CRLF fix**: Shell tests strip `\r` from scripts before execution, fixing Windows compatibility
+- **`test:shell` runner**: Replaced direct `bats` call with `node scripts/run-bats.js` for cross-platform support
+
+### Changed
+
+- **Hotfix root cause check reordered**: Moved root cause elimination check **before** comet-verify loading (Step 3a → 3b split), preventing it from being skipped during verify flow
+- **Hotfix header description simplified**: Replaced ambiguous "not a separate parallel process" with direct "Quick bug fix workflow" for standalone invocation clarity
+- **Removed non-action steps from comet-design**: Deleted Step 3 (Dual Spec Division table) and Step 4 (Document Hierarchy) — pure reference material with no agent actions
+- **Removed duplicate script location blocks**: comet-open (Step 3) and comet-archive (Step 1) no longer repeat the full `COMET_SEARCH_ROOTS` find block when variables already cached
+- **Removed duplicate 50% threshold in comet-build**: Single mention in threshold determination table instead of table + bullet repetition
+- **Generic error handling**: Error table in comet main skill changed "Maven compile/test" → "Build/test" for language-agnostic wording
+- **comet-state.sh usage help**: Fixed `check` parameter order in help text (`check <change-name> <phase>`)
+
+### Fixed
+
+- **comet-state.sh `init` change directory resolution**: `cmd_init` now resolves `change_dir` before checking if `.comet.yaml` already exists, fixing path resolution for nested directories
+- **Guard deadlock on verify**: `verify-pass` transition now resets `verification_report` and `branch_status` when rolling back via `verify-fail`, preventing stale evidence from allowing false transitions
+
+### Tests
+
+- **+66 lines** in `comet-scripts.test.ts`: New tests for verification evidence blocking, branch status validation, and guard verify with evidence
+- **+12 lines** in `comet-state.bats`: New tests for `branch_status` enum validation, CRLF stripping, and new field presence in init output
+
 ## What's Changed [0.2.3] - 2026-05-19
 
 ### Added

README-zh.md

@@ -1,3 +1,19 @@
+<p align="center">
+  <a href="https://github.com/rpamis/comet">
+    <picture>
+      <source srcset="img/title-log.png">
+      <img src="img/title-log.png" alt="Comet logo">
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/rpamis/comet/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/rpamis/comet/actions/workflows/ci.yml/badge.svg" /></a>
+  <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm version" src="https://img.shields.io/npm/v/@rpamis/comet?style=flat-square" /></a>
+  <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm download count" src="https://img.shields.io/npm/dm/@rpamis/comet?style=flat-square&label=Downloads/mo" /></a>
+  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
+</p>
+
 # @rpamis/comet
 
 ```
@@ -48,12 +64,12 @@ comet init
 6. 将 Comet 技能（你选择的语言）部署到所选平台
 7. 创建 `docs/superpowers/specs/` 和 `docs/superpowers/plans/` 工作目录
 
-## 运行截图
+> [!TIP]
+> 更新版本号
+>
+> 执行 comet update 或者 `npm install -g @rpamis/comet@latest` 即可更新到最新版本。
 
-<p align="center">
-  <img src="img/select-platform.png" alt="平台选择" width="600">
-</p>
-<p align="center">支持分发中文、英文 Skill 版本，支持 28 个 AI Coding 平台</p>
+## 运行截图
 
 <p align="center">
   <img src="img/init.png" alt="初始化" width="600">
@@ -201,6 +217,8 @@ build_mode: subagent-driven-development
 isolation: branch
 verify_mode: light
 verify_result: pending
+verification_report: docs/superpowers/reports/YYYY-MM-DD-change-verify.md
+branch_status: pending
 verified_at: null
 archived: false
 ```
@@ -222,12 +240,18 @@ Comet 通过自动化状态转换确保 agent 执行可靠性：
    - Guard 和 archive 脚本内部使用 `comet-state.sh` 进行状态管理
 
 3. **模式校验** — `comet-yaml-validate.sh` 确保数据完整性
-   - 校验必填字段（10 个字段）
-   - 校验枚举值（7 种枚举类型）
+   - 校验必填字段（12 个字段）
+   - 校验枚举值（8 种枚举类型）
    - 校验引用文件路径存在
    - 检测未知/拼写错误字段
 
-4. **归档自动化** — `comet-archive.sh` 一键处理完整归档流程
+4. **验证证据强制** — Guard 在阶段流转前强制要求验证凭证
+   - `verify-pass` 转换要求 `verification_report` 指向已存在的验证报告文件
+   - `branch_status` 必须为 `handled` 才能通过验证
+   - Guard 检查 `verification_report exists` 和 `branch_status=handled` 作为硬性前提
+   - 防止验证或分支处理被跳过时产生虚假的阶段推进
+
+5. **归档自动化** — `comet-archive.sh` 一键处理完整归档流程
    - 验证入口状态、同步 delta specs 到 main specs
    - 标注设计文档和计划文档的 frontmatter
    - 将变更移至归档目录并更新 `archived: true`
@@ -310,4 +334,4 @@ pnpm format
 
 ## License
 
-MIT
+[MIT](LICENSE.md)

README.md

@@ -1,3 +1,19 @@
+<p align="center">
+  <a href="https://github.com/rpamis/comet">
+    <picture>
+      <source srcset="img/title-log.png">
+      <img src="img/title-log.png" alt="Comet logo">
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/rpamis/comet/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/rpamis/comet/actions/workflows/ci.yml/badge.svg" /></a>
+  <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm version" src="https://img.shields.io/npm/v/@rpamis/comet?style=flat-square" /></a>
+  <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm download count" src="https://img.shields.io/npm/dm/@rpamis/comet?style=flat-square&label=Downloads/mo" /></a>
+  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
+</p>
+
 # @rpamis/comet
 
 ```
@@ -48,12 +64,12 @@ comet init
 6. Deploy Comet skills (in your chosen language) to selected platforms
 7. Create `docs/superpowers/specs/` and `docs/superpowers/plans/` working directories
 
-## Screenshots
+> [!TIP]
+> update version
+>
+> comet update or `npm install -g @rpamis/comet@latest` to get the latest features and fixes.
 
-<p align="center">
-  <img src="img/select-platform.png" alt="Platform Selection" width="600">
-</p>
-<p align="center">Supports Chinese & English Skill distribution, 28 AI Coding platforms</p>
+## Screenshots
 
 <p align="center">
   <img src="img/init.png" alt="Initialization" width="600">
@@ -201,6 +217,8 @@ build_mode: subagent-driven-development
 isolation: branch
 verify_mode: light
 verify_result: pending
+verification_report: docs/superpowers/reports/YYYY-MM-DD-change-verify.md
+branch_status: pending
 verified_at: null
 archived: false
 ```
@@ -222,12 +240,18 @@ Comet ensures agent execution reliability through automated state transitions:
    - Guard and archive scripts use `comet-state.sh` internally for state management
 
 3. **Schema Validation** — `comet-yaml-validate.sh` ensures data integrity
-   - Validates required fields (10 fields)
-   - Validates enum values (7 enum types)
+   - Validates required fields (12 fields)
+   - Validates enum values (8 enum types)
    - Validates referenced file paths exist
    - Detects unknown/typos fields
 
-4. **Archive Automation** — `comet-archive.sh` handles the full archive flow in one command
+4. **Verification Evidence** — Guard enforces proof before phase advance
+   - `verify-pass` transition requires `verification_report` pointing to an existing report file
+   - `branch_status` must be `handled` before verify can pass
+   - Guard checks `verification_report exists` and `branch_status=handled` as hard prerequisites
+   - Prevents false phase advances when verification or branch handling was skipped
+
+5. **Archive Automation** — `comet-archive.sh` handles the full archive flow in one command
    - Validates entry state, syncs delta specs to main specs
    - Annotates design doc and plan frontmatter
    - Moves change to archive directory and updates `archived: true`
@@ -310,4 +334,4 @@ See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
 
 ## License
 
-MIT
+[MIT](LICENSE.md)

assets/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.3",
+  "version": "0.2.4",
   "skills": [
     "comet/SKILL.md",
     "comet/scripts/comet-guard.sh",

assets/skills-zh/comet-archive/SKILL.md

@@ -18,7 +18,8 @@ description: "Comet 阶段 5：归档。用 /comet-archive 调用。同步 delta
 执行入口验证：
 
 ```bash
-COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
+COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
 bash "$COMET_STATE" check <name> archive
 ```
 
@@ -29,7 +30,6 @@ bash "$COMET_STATE" check <name> archive
 运行归档脚本，自动完成以下全部步骤：
 
 ```bash
-COMET_ARCHIVE="${COMET_ARCHIVE:-$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)}"
 bash "$COMET_ARCHIVE" "<change-name>"
 ```
 
@@ -39,7 +39,7 @@ bash "$COMET_ARCHIVE" "<change-name>"
 3. Design doc 前置元数据标注（archived-with, status）
 4. Plan 前置元数据标注（archived-with）
 5. 移动 change 到归档目录
-6. 更新 archived: true
+6. 通过 `comet-state transition <archive-name> archived` 更新 `archived: true`
 
 如脚本返回非零退出码，报告错误并停止。
 如脚本返回零退出码，归档完成。
@@ -56,7 +56,10 @@ brainstorming → delta spec → 实施 → 验证 → 主 spec 覆盖 → desig
 ## 退出条件
 
 - 归档脚本执行成功（退出码 0）
-- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> archive`，全部 PASS 后确认归档完整
+- 归档目录 `openspec/changes/archive/YYYY-MM-DD-<change-name>/` 存在
+- 归档后的 `.comet.yaml` 中 `archived: true`
+
+归档脚本会把 `openspec/changes/<name>/` 移动到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。归档成功后**不要再对原 change 名运行** `bash "$COMET_GUARD" <change-name> archive`，因为原活跃目录已经不存在。归档完整性以脚本退出码和归档目录状态为准。
 
 ## 完成
 

assets/skills-zh/comet-build/SKILL.md

@@ -17,7 +17,9 @@ description: "Comet 阶段 3：计划与构建。用 /comet-build 调用。制
 执行入口验证：
 
 ```bash
-COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
+COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
+COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
 bash "$COMET_STATE" check <name> build
 ```
 
@@ -36,9 +38,16 @@ bash "$COMET_STATE" check <name> build
 ---
 change: <openspec-change-name>
 design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
+base-ref: <git rev-parse HEAD before implementation>
 ---
 ```
 
+`base-ref` 用于验证阶段跨提交统计改动规模。创建计划时先记录当前提交：
+
+```bash
+git rev-parse HEAD
+```
+
 ### 2. 更新计划状态
 
 先记录 plan 路径：
@@ -127,21 +136,27 @@ bash "$COMET_STATE" set <name> build_mode <value>
 - delta spec 是活文档，本阶段期间随时可修改
 - 每次更新应提交，commit message 说明变更原因
 - 不提前同步到 main spec，归档时统一同步
-- 如增量任务超过原 tasks.md 初始任务总数 50%，考虑拆分为新 change
 - 小规模增量直接改 delta spec 时，应在 commit message 中注明，便于归档时判断 design doc 漂移
 
+### 6. 上下文管理
+
+Build 是最长阶段，可能跨越大量任务。为支持上下文压缩后断点恢复：
+
+- **每完成一个 task**：立即勾选 tasks.md 并提交代码，确保 `.comet.yaml` 和文件状态持久化
+- **上下文压缩后恢复**：读取 `.comet.yaml` 的 `phase` 字段确认仍在 build 阶段，读取 plan 文件头的 `base-ref`，再读取 tasks.md 找到下一个未勾选任务继续执行
+- **长任务拆分**：单任务超过 200 行代码变更时，考虑拆分为多个子任务分别提交
+
 ## 退出条件
 
 - tasks.md 全部勾选
 - 代码已提交
-- 测试通过
-- `.comet.yaml` 中 `phase` 已更新为 `verify`
-- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> build`，全部 PASS 后才允许流转
+- 已显式运行项目对应的构建/测试命令并通过（不要只依赖 guard 自动猜测）
+- **阶段守卫**：运行 `bash "$COMET_GUARD" <change-name> build --apply`，全部 PASS 后自动流转到 `phase: verify`
 
 退出前运行 guard 自动流转：
 
 ```bash
-bash $COMET_GUARD <change-name> build --apply
+bash "$COMET_GUARD" <change-name> build --apply
 ```
 
 状态文件自动更新为 `phase: verify`、`verify_result: pending`。

assets/skills-zh/comet-design/SKILL.md

@@ -17,7 +17,9 @@ description: "Comet 阶段 2：深度设计。用 /comet-design 调用。通过
 执行入口验证：
 
 ```bash
-COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
+COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
+COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
 bash "$COMET_STATE" check <name> design
 ```
 
@@ -57,32 +59,23 @@ Design 摘要: <design.md 架构决策>
 bash "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 
 # 自动流转到下一阶段
-bash $COMET_GUARD <change-name> design --apply
+bash "$COMET_GUARD" <change-name> design --apply
 ```
 
 状态文件自动更新，无需手动编辑其他字段。
 
-### 3. 双 Spec 分工
-
-| Spec 类型 | 归属 | 存放位置 | 定义 |
-|-----------|------|---------|------|
-| 能力规格 | OpenSpec | `openspec/changes/<name>/specs/` | 系统应该做什么（需求 + 验收场景） |
-| 设计文档 | Superpowers | `docs/superpowers/specs/` | 怎么构建（技术架构 + 实现细节） |
-
-### 4. 文档层级确认
-
-```
-proposal.md（阶段 1）              → Why + What
-design.md（阶段 1，OpenSpec）      → 高层架构决策
-设计文档（阶段 2，Superpowers）     → 深度技术设计
-能力规格（阶段 2，delta）           → 需求 + 验收场景
-```
-
 ## 退出条件
 
 - Design Doc 已创建并保存
 - 如有新能力则 delta spec 已创建
-- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> design`，全部 PASS 后才允许流转
+- `design_doc` 已写入 `.comet.yaml`
+- **阶段守卫**：运行 `bash "$COMET_GUARD" <change-name> design --apply`，全部 PASS 后自动流转到 `phase: build`
+
+退出前必须使用 `--apply`：
+
+```bash
+bash "$COMET_GUARD" <change-name> design --apply
+```
 
 ## 自动流转