@rpamis/comet 0.2.3 → 0.2.4

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

@@ -11,24 +11,13 @@ description: "Comet 阶段 1：开启。用 /comet-open 调用。通过 OpenSpec
 
 ## 步骤
 
-### 0. 入口状态验证（Entry Check）
-
-执行入口验证：
-
-```bash
-COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
-bash "$COMET_STATE" check <name> open
-```
-
-验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
-
 ### 1. 探索想法
 
 **立即执行：** 使用 Skill 工具加载 `openspec-explore` 技能。禁止跳过此步骤。
 
 技能加载后，按其指引自由探索问题空间。
 
-### 2. 创建 Change 结构
+### 2. 创建 Change 结构 + 初始化状态
 
 **立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。若用户意图未明确、需要先形成建议，改为加载 `openspec-propose`。禁止跳过此步骤。
 
@@ -43,14 +32,31 @@ openspec/changes/<name>/
 └── tasks.md          # 任务清单（勾选框）
 ```
 
-### 3. 初始化 Comet 状态
-
-初始化 Comet 状态文件：
+创建 `.comet.yaml` 状态文件：
 
 ```bash
+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)}"
+
+if [ -z "$COMET_STATE" ] || [ -z "$COMET_GUARD" ]; then
+  echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+
 bash "$COMET_STATE" init <name> full
 ```
 
+### 3. 入口状态验证
+
+验证状态机已正确初始化：
+
+```bash
+bash "$COMET_STATE" check <name> open
+```
+
+验证通过后继续 Step 4。验证失败时脚本会输出具体失败原因。
+
 ### 4. 内容完整性检查
 
 确认三个文档内容完整：
@@ -61,7 +67,15 @@ bash "$COMET_STATE" init <name> full
 ## 退出条件
 
 - proposal.md、design.md、tasks.md 均已创建且内容完整
-- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> open`，全部 PASS 后才允许流转
+- **阶段守卫**：运行 `bash "$COMET_GUARD" <change-name> open --apply`，全部 PASS 后自动流转到下一阶段
+
+退出前必须使用 `--apply`，否则 `.comet.yaml` 仍停留在 `phase: open`，下一阶段入口检查会失败。
+
+```bash
+bash "$COMET_GUARD" <change-name> open --apply
+```
+
+完整流程会自动更新为 `phase: design`；hotfix/tweak preset 会自动更新为 `phase: build`。
 
 ## 自动流转
 

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

@@ -13,7 +13,7 @@ Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
 1. 不新增 capability
 2. 不改变架构
 3. 不涉及接口变化
-4. 通常不超过 3 个 tasks、5 个文件
+4. 通常不超过 3 个 tasks、4 个文件
 
 **不适用**：如变更过程中发现需要 capability、架构或接口调整，应升级为完整 `/comet` 流程。
 
@@ -21,19 +21,17 @@ Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
 
 ## 流程（preset workflow，4 阶段）
 
-### 0. 入口状态验证（Entry Check）
+执行链路：open → lightweight build → light verify → archive。Tweak 为每个阶段提供默认决策：精简开启、轻量构建、轻量验证、验证通过后归档。
 
-执行入口验证：
+开始前先定位 Comet 脚本：
 
 ```bash
-COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
-bash "$COMET_STATE" check <name> open
+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)}"
+COMET_ARCHIVE="${COMET_ARCHIVE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-archive.sh' -type f -print -quit 2>/dev/null)}"
 ```
 
-验证通过后继续流程步骤。验证失败时脚本会输出具体失败原因。
-
-执行链路：open → lightweight build → light verify → archive。Tweak 为每个阶段提供默认决策：精简开启、轻量构建、轻量验证、验证通过后归档。
-
 ### 1. 快速开启（preset open）
 
 复用 Comet open 能力创建 change，但使用 tweak 默认值：不执行 `openspec-explore` 长探索，直接进入精简 change 创建。
@@ -52,6 +50,18 @@ bash "$COMET_STATE" check <name> open
 bash "$COMET_STATE" init <name> tweak
 ```
 
+初始化后验证状态：
+
+```bash
+bash "$COMET_STATE" check <name> open
+```
+
+阶段守卫完成 open → build 过渡：
+
+```bash
+bash "$COMET_GUARD" <change-name> open --apply
+```
+
 ### 2. 轻量构建（preset build）
 
 使用 tweak 默认值：`build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`。
@@ -65,11 +75,18 @@ bash "$COMET_STATE" init <name> tweak
    - 运行相关测试确认通过
    - 将 tasks.md 中对应 `- [ ]` 勾选为 `- [x]`
    - 提交代码，commit message 格式：`tweak: <简述变更>`
-3. 全部任务完成后进入验证
+3. 全部任务完成后，显式运行项目相关测试和构建命令
+4. 运行阶段守卫完成 build → verify 过渡：
+
+```bash
+bash "$COMET_GUARD" <change-name> build --apply
+```
+
+状态文件自动更新为 `phase: verify`、`verify_result: pending`，然后进入验证。
 
 ### 3. 轻量验证（preset verify）
 
-复用 `/comet-verify`。Tweak 必须保持轻量验证条件：≤ 3 tasks、≤ 5 files、无 delta spec、无新 capability。
+复用 `/comet-verify`。Tweak 必须保持轻量验证条件：≤ 3 tasks、≤ 4 files、无 delta spec、无新 capability。
 
 **立即执行：** 使用 Skill 工具加载 `comet-verify` 技能。禁止跳过此步骤。
 
@@ -119,4 +136,4 @@ Tweak 流程为 **一次性连续执行**。调用 `/comet-tweak` 后，agent
 - 小改动已完成，测试通过
 - change 已归档
 - 未新增 capability、架构调整或接口变化
-- **阶段守卫**：build → verify 前运行 `bash $COMET_GUARD <change-name> build`，verify → archive 前运行 `bash $COMET_GUARD <change-name> verify`
+- **阶段守卫**：build → verify 前运行 `bash "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `bash "$COMET_GUARD" <change-name> verify --apply`

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

@@ -17,7 +17,9 @@ description: "Comet 阶段 4：验证与收尾。用 /comet-verify 调用。验
 执行入口验证：
 
 ```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> verify
 ```
 
@@ -33,6 +35,20 @@ bash "$COMET_STATE" scale <name>
 
 脚本自动统计任务数、增量规格数、变更文件数，判断使用 light 或 full 验证模式，并设置 verify_mode 字段。
 
+注意：如果 build 阶段每个任务都已提交，脚本基于工作区 diff 的文件数可能低估改动规模。此时必须读取 plan 文件头的 `base-ref` 并用提交区间复核：
+
+```bash
+PLAN=$(bash "$COMET_STATE" get <name> plan)
+BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
+git diff --stat "$BASE_REF"...HEAD
+```
+
+若提交区间显示改动超过轻量阈值（> 5 个文件、跨模块协调、或 delta spec 超过 1 个 capability），手动设置为完整验证：
+
+```bash
+bash "$COMET_STATE" set <name> verify_mode full
+```
+
 ### 2a. 轻量验证（小改动）
 
 当规模评估结果为"小"时，跳过 `openspec-verify-change`，直接执行以下检查：
@@ -45,6 +61,12 @@ bash "$COMET_STATE" scale <name>
 
 **通过标准**：5 项全部 OK，无 CRITICAL 问题。
 
+**不通过时**：报告失败项，记录失败并回退到 build 阶段，然后调用 `/comet-build` 修复。
+
+```bash
+bash "$COMET_STATE" transition <name> verify-fail
+```
+
 **报告格式**：简表列出 5 项检查结果 + PASS/FAIL。
 
 **跳过项**（不在轻量验证中检查）：
@@ -68,7 +90,11 @@ bash "$COMET_STATE" scale <name>
 6. delta spec 与 design doc 无矛盾（若 Build 阶段有增量修改 spec，检查 design doc 是否有对应记录）
 7. `docs/superpowers/specs/` 关联的设计文档可定位（文件存在且与当前 change 相关）
 
-验证不通过时：报告缺失项，返回阶段 3 补充（调用 `/comet-build`）。
+验证不通过时：报告缺失项，记录失败并回退到 build 阶段，然后调用 `/comet-build` 补充。
+
+```bash
+bash "$COMET_STATE" transition <name> verify-fail
+```
 
 **Spec 漂移处理**：
 - 若检查项 6 发现矛盾（delta spec 有内容但 design doc 未体现），提示用户：
@@ -92,17 +118,31 @@ bash "$COMET_STATE" scale <name>
 - 全部测试通过
 - 无硬编码密钥或安全问题
 
+### 4. 记录验证证据
+
+验证报告必须落盘，并在 `.comet.yaml` 中记录；分支处理完成后也必须写入状态字段。不要手动设置 `verify_result: pass`，通过 guard 自动流转。
+
+```bash
+mkdir -p docs/superpowers/reports
+# 将本次验证结论写入报告文件，例如：
+# docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
+
+bash "$COMET_STATE" set <name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
+bash "$COMET_STATE" set <name> branch_status handled
+```
+
 ## 退出条件
 
 - 验证报告通过
 - 分支已处理
-- `.comet.yaml` 中 `verify_result` 已记录为 `pass`
-- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> verify`，全部 PASS 后才允许流转
+- `.comet.yaml` 中 `verification_report` 指向已存在的验证报告文件
+- `.comet.yaml` 中 `branch_status: handled`
+- **阶段守卫**：运行 `bash "$COMET_GUARD" <change-name> verify --apply`，全部 PASS 后通过 `comet-state transition verify-pass` 自动流转到 `phase: archive`
 
-退出前运行 guard 自动流转：
+验证和分支处理均完成后，运行 guard 自动流转：
 
 ```bash
-bash $COMET_GUARD <change-name> verify --apply
+bash "$COMET_GUARD" <change-name> verify --apply
 ```
 
 状态文件自动更新为 `phase: archive`、`verify_result: pass`、`verified_at: YYYY-MM-DD`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rpamis/comet",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "OpenSpec + Superpowers dual-star development workflow",
   "keywords": [
     "comet",
@@ -36,7 +36,7 @@
     "lint:fix": "eslint src/ --fix",
     "format": "prettier --write src/",
     "format:check": "prettier --check src/",
-    "test:shell": "bats test/shell/*.bats",
+    "test:shell": "node scripts/run-bats.js test/shell/*.bats",
     "prepare": "pnpm run build",
     "prepublishOnly": "node scripts/prepublish-check.js && pnpm run build",
     "postinstall": "node scripts/postinstall.js"