@rpamis/comet 0.3.7 → 0.3.9

package/assets/skills/comet/rules/comet-phase-guard.md

@@ -1,90 +1,125 @@
-# Comet 阶段感知（防漂移规则）
-
-> 此规则每轮注入，防止长上下文时遗忘 Comet 流程状态。
-> Hook 平台额外执行 `comet-hook-guard.sh` 进行硬性拦截；
-> 此 Rule 是所有平台通用的软性防线。
-
-## 全局规则
-
-### 阶段感知（最高优先级）
-
-有活跃 comet change 时（`openspec/changes/<name>/.comet.yaml` 存在），**每次开始执行操作前**必须读取 `phase` 字段确认当前阶段。
-
-**阶段与允许操作：**
-
-| 阶段 | 允许 | 禁止 |
-|------|------|------|
-| `open` | 创建 proposal/design/tasks, 运行 guard | 写源代码 |
-| `design` | brainstorming, 创建 Design Doc, 运行 guard | 写源代码 |
-| `build` | 写源代码、测试、执行计划 | 跳过用户确认点 |
-| `verify` | 验证、branch handling | 跳过失败处理 |
-| `archive` | 确认归档、运行归档脚本 | 写源代码 |
-
-### Skill 调用（不可用普通对话替代）
-
-以下操作必须通过 Skill 工具加载，Skill 不可用时应停止流程并提示安装：
-
-- **brainstorming** — design 阶段、build 阶段中等规模 spec 变更
-- **writing-plans** — build 阶段创建实现计划
-- **executing-plans** / **subagent-driven-development** — build 阶段执行
-- **test-driven-development** — build 阶段 `tdd_mode: tdd` 时，第一个 task 前
-- **systematic-debugging** — 遇到崩溃/测试失败/构建失败时
-- **verification-before-completion** — verify 阶段
-- **using-git-worktrees** — build 阶段选择 worktree 隔离时
-
-### 脚本执行（不可跳过）
-
-- **阶段退出**: `comet-guard <name> <phase> --apply`（必须看到 ALL CHECKS PASSED）
-- **压缩恢复**: `comet-state check <name> <phase> --recover`
-- **状态更新**: 关键操作后通过 `comet-state set` 更新字段，禁止手工编辑 .comet.yaml
-- **handoff 生成**: `comet-handoff <name> design --write`（禁止手写摘要）
-
-### 用户确认（不可自动跳过）
-
-以下决策点必须暂停等待用户明确选择，不得根据推荐规则自动填写：
-
-- **open**: 需求澄清完成确认、artifact 评审确认
-- **design**: brainstorming 方案确认（确认前不得创建 Design Doc）
-- **build**: plan-ready 暂停、isolation/build_mode/tdd_mode 选择、spec 大规模变更确认
-- **verify**: 验证失败处理策略、branch handling 选择
-- **archive**: 归档前最终确认
-
-## Design 阶段专项
-
-1. 第一个脚本操作 = `comet-handoff <name> design --write`（未生成 handoff 禁止加载 brainstorming）
-2. brainstorming in progress: incrementally update brainstorm-summary.md（每轮澄清或方案迭代后增量更新恢复检查点，未确认内容标注为待确认/候选）
-3. brainstorming 完成后下一步 = brainstorm-summary.md 定稿 → Design Doc → guard
-4. active compaction gate: brainstorm-summary.md 定稿后、创建 Design Doc 前，优先触发宿主平台原生上下文压缩；无法程序化触发时暂停提示用户手动压缩或确认继续
-5. **绝对不能直接开始写实现代码** — 必须先创建 Design Doc 并通过 guard
-
-## Build 阶段专项
-
-1. plan 创建后必须询问用户选择继续或暂停（`build_pause` 机制）
-2. 每个 task 完成后必须: tasks.md 打勾 → git commit（不得积攒）
-3. 遇到失败必须加载 **systematic-debugging** skill，根因未定位前不得提出源码修复
-4. spec 变更分级: 小改直接编辑 | 中改加载 brainstorming | 大改暂停等用户确认拆分
-
-## Verify 阶段专项
-
-1. 第一步运行 `comet-state scale <name>` 确定验证级别
-2. 验证失败后列出失败项等用户选择，CRITICAL 必须修
-3. 连续 3 次失败后必须让用户选择接受偏差或继续修
-
-## 上下文压缩恢复
-
-如果怀疑发生上下文压缩（之前对话被摘要、找不到之前讨论的内容），立即运行：
-
-```bash
-"$COMET_BASH" "$COMET_STATE" check <name> <phase> --recover
-```
-
-按脚本输出的 **Recovery action** 决定下一步。
-
-## 阶段退出后自动过渡
-
-guard `--apply` 成功后，必须调用下一阶段的 skill：
-
-- open → `comet-design`（full）/ `comet-build`（hotfix/tweak）
-- design → `comet-build`
-- build → `comet-verify`
-- verify → `comet-archive`
+# Comet 阶段感知（防漂移规则）
+
+> 此规则每轮注入，防止长上下文时遗忘 Comet 流程状态。
+> Hook 平台额外执行 `comet-hook-guard.sh` 进行硬性拦截；
+> 此 Rule 是所有平台通用的软性防线。
+
+## 全局规则
+
+### 阶段感知（最高优先级）
+
+有活跃 comet change 时（`openspec/changes/<name>/.comet.yaml` 存在），**每次开始执行操作前**必须读取 `phase` 字段确认当前阶段。
+
+**阶段与允许操作：**
+
+| 阶段 | 允许 | 禁止 |
+|------|------|------|
+| `open` | 创建 proposal/design/tasks, 运行 guard | 写源代码 |
+| `design` | brainstorming, 创建 Design Doc, 运行 guard | 写源代码 |
+| `build` | 写源代码、测试、执行计划 | 跳过用户确认点 |
+| `verify` | 验证、branch handling | 跳过失败处理 |
+| `archive` | 确认归档、运行归档脚本 | 写源代码 |
+
+### 阶段进入自洽性校验（写源代码前必查）
+
+仅看 `phase` 字段不够——还必须确认"是如何到达这个阶段的"。每次准备写源代码前，先用下表自检 `.comet.yaml` 是否处于**非法空跳**状态（绕过了前置阶段）。命中任一行，立即停止写源代码，按动作回到对应阶段补齐产物，不得信任 `phase` 字段直接续跑。
+
+| 检测到 | 判定 | 动作 |
+|--------|------|------|
+| `phase: build` + `workflow: full` + `design_doc` 为空/null | 绕过 design 空跳 | 停止写源代码，运行 `/comet-design` 补 Design Doc 并过 guard |
+| `phase: build/verify` + proposal/design/tasks 任一缺失或为空 | 绕过 open 空跳 | 回 `/comet-open` 补齐三件套 |
+| `phase: archive` + `verify_result` ≠ `pass` | 绕过 verify 空跳 | 回 `/comet-verify` 完成验证 |
+
+预设例外：`workflow: hotfix/tweak` 本就跳过 design，`design_doc` 为空属正常，不算非法。
+
+### Skill 调用（不可用普通对话替代）
+
+以下操作必须通过 Skill 工具加载，Skill 不可用时应停止流程并提示安装：
+
+- **brainstorming** — design 阶段、build 阶段中等规模 spec 变更
+- **writing-plans** — build 阶段创建实现计划
+- **executing-plans** / **subagent-driven-development** — build 阶段执行
+- **test-driven-development** — `executing-plans` 由主会话在第一个 task 前加载；`subagent-driven-development` 由每个后台 implementer 和修复 agent 加载
+- **systematic-debugging** — 遇到崩溃/测试失败/构建失败时
+- **verification-before-completion** — verify 阶段
+- **using-git-worktrees** — build 阶段选择 worktree 隔离时
+
+### 脚本执行（不可跳过）
+
+- **阶段退出**: `comet-guard <name> <phase> --apply`（必须看到 ALL CHECKS PASSED）
+- **压缩恢复**: `comet-state check <name> <phase> --recover`
+- **状态更新**: 关键操作后通过 `comet-state set` 更新字段，禁止手工编辑 .comet.yaml
+- **阶段推进只能经 guard/transition**: 禁止用 `comet-state set <name> phase <值>` 手动跳阶段（会绕过证据校验，脚本已硬拦截）；确需修复畸形状态时才用 `COMET_FORCE_PHASE=1` 逃生阀
+- **handoff 生成**: `comet-handoff <name> design --write`（禁止手写摘要）
+
+### 用户确认（不可自动跳过）
+
+以下决策点必须暂停等待用户明确选择，不得根据推荐规则自动填写：
+
+- **open**: 需求澄清完成确认、artifact 评审确认
+- **design**: brainstorming 方案确认（确认前不得创建 Design Doc）
+- **build**: plan-ready 暂停、isolation/build_mode/tdd_mode 选择、spec 大规模变更确认
+- **verify**: 验证失败处理策略、branch handling 选择
+- **archive**: 归档前最终确认
+
+## Design 阶段专项
+
+1. 第一个脚本操作 = `comet-handoff <name> design --write`（未生成 handoff 禁止加载 brainstorming）
+2. brainstorming in progress: incrementally update brainstorm-summary.md（每轮澄清或方案迭代后增量更新恢复检查点，未确认内容标注为待确认/候选）
+3. brainstorming 完成后下一步 = brainstorm-summary.md 定稿 → Design Doc → guard
+4. active compaction gate: brainstorm-summary.md 定稿后、创建 Design Doc 前，优先触发宿主平台原生上下文压缩；无法程序化触发时暂停提示用户手动压缩或确认继续
+5. **绝对不能直接开始写实现代码** — 必须先创建 Design Doc 并通过 guard
+
+## Build 阶段专项
+
+1. plan 创建后必须询问用户选择继续或暂停（`build_pause` 机制）
+2. 每个 task 验收后必须: tasks.md 打勾 → git commit（不得积攒）。`subagent-driven-development` 必须等 spec compliance 与 code quality 两个审查都通过，再由协调者按任务唯一文本定向勾选和验证；不得用未完成任务总表代替当前任务验证
+3. 遇到失败必须加载 **systematic-debugging** skill，根因未定位前不得提出源码修复
+4. spec 变更分级: 小改直接编辑 | 中改加载 brainstorming | 大改暂停等用户确认拆分
+
+## Verify 阶段专项
+
+1. 第一步运行 `comet-state scale <name>` 确定验证级别
+2. 验证失败后列出失败项等用户选择，CRITICAL 必须修
+3. 连续 3 次失败后必须让用户选择接受偏差或继续修
+
+## 上下文压缩恢复
+
+如果怀疑发生上下文压缩（之前对话被摘要、找不到之前讨论的内容），立即运行：
+
+```bash
+"$COMET_BASH" "$COMET_STATE" check <name> <phase> --recover
+```
+
+按脚本输出的 **Recovery action** 决定下一步。
+
+恢复后必须先用「阶段进入自洽性校验」表复查一遍：若发现 `phase` 与产物不自洽（design_doc/三件套/verify_result 任一不匹配），按非法空跳处理，回对应阶段补齐，不得信任 `phase` 字段直接续跑。
+
+**特别注意 `build_mode`**：若恢复脚本输出 `build_mode: subagent-driven-development`，你是协调者，不是执行者。必须：
+1. 使用 Skill 工具重新加载 Superpowers `subagent-driven-development` 技能 (Use the Skill tool to reload the Superpowers `subagent-driven-development` skill)
+2. 读取 `comet/reference/subagent-dispatch.md` 获取 Comet 专属扩展 (re-read `comet/reference/subagent-dispatch.md` for Comet-specific extensions)
+3. 读取 `openspec/changes/<name>/.comet/subagent-progress.md` 恢复精确阶段、证据和审查-修复轮次 (Read `openspec/changes/<name>/.comet/subagent-progress.md` to recover the exact stage, evidence, and review-fix round)
+4. 禁止在主会话中直接执行 task (Do not execute the pending task directly in the main window)
+5. 按检查点恢复；缺失或不匹配时才从第一个未勾选 task 开始
+6. 已提交但未通过双审查的 task 保持未勾选，继续审查/修复循环
+7. task 通过双审查和定向勾选验证后立即继续下一个 task，不得总结或询问是否继续
+
+## 阶段退出后自动过渡
+
+guard `--apply` 成功后，不得在本规则中硬编码下一阶段 skill。必须先运行：
+
+```bash
+comet-state next <change-name>
+```
+
+若已通过 `comet-env.sh` 定位脚本，等价运行：
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
+
+按脚本输出决定下一步：
+
+- `NEXT: auto` → 使用 Skill 工具加载 `SKILL` 指向的 skill
+- `NEXT: manual` → 不加载下一 skill，按 `HINT` 提示用户手动继续
+- `NEXT: done` → 流程已完成，无需继续

package/assets/skills/comet/scripts/comet-guard.sh

@@ -427,6 +427,26 @@ tdd_mode_selected() {
   esac
 }
 
+review_mode_selected() {
+  local workflow review_mode
+  workflow=$(yaml_field_value "workflow" 2>/dev/null || true)
+  review_mode=$(yaml_field_value "review_mode" 2>/dev/null || true)
+
+  case "$workflow" in
+    hotfix|tweak) return 0 ;;
+  esac
+
+  case "$review_mode" in
+    off|standard|thorough) return 0 ;;
+    *)
+      echo "review_mode must be off, standard, or thorough before leaving build, got '${review_mode:-null}'" >&2
+      echo "Next: ask the user to choose code review mode, then run:" >&2
+      echo "  \"\$COMET_BASH\" \"\$COMET_STATE\" set $CHANGE review_mode <off|standard|thorough>" >&2
+      return 1
+      ;;
+  esac
+}
+
 verify_result_is_pass() {
   local result
   result=$(yaml_field_value "verify_result" 2>/dev/null || true)
@@ -609,8 +629,13 @@ archived_is_true() {
 guard_open() {
   echo "=== Guard: open → next ===" >&2
 
+  local workflow
+  workflow=$(yaml_field_value "workflow" 2>/dev/null || true)
+
   check "proposal.md exists and non-empty" file_nonempty "$CHANGE_DIR/proposal.md"
-  check "design.md exists and non-empty" file_nonempty "$CHANGE_DIR/design.md"
+  if [ "$workflow" = "full" ]; then
+    check "design.md exists and non-empty" file_nonempty "$CHANGE_DIR/design.md"
+  fi
   check "tasks.md exists and non-empty" file_nonempty "$CHANGE_DIR/tasks.md"
   check "tasks.md has at least one task" tasks_has_any
 }
@@ -665,6 +690,7 @@ guard_build() {
   check "build_mode allowed for workflow" build_mode_allowed_for_workflow
   check "subagent dispatch confirmed" subagent_dispatch_confirmed
   check "tdd_mode selected" tdd_mode_selected
+  check "review_mode selected" review_mode_selected
   check "tasks.md all tasks checked" tasks_all_done
   check "Superpowers plan all tasks checked" plan_tasks_all_done
   check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"

package/assets/skills/comet/scripts/comet-hook-guard.sh

@@ -50,41 +50,6 @@ fi
 # Normalize to forward slashes, collapse doubles from JSON escaping (\\ → //)
 TARGET=$(printf '%s' "$TARGET" | sed 's|\\|/|g' | sed 's|///*|/|g')
 
-# ── Find active Comet change ─────────────────────────────────────
-
-YAML_FILE=""
-if [ -d "openspec/changes" ]; then
-  for dir in openspec/changes/*/; do
-    [ -d "$dir" ] || continue
-    # Skip archived changes
-    case "$dir" in
-      */archive/*) continue ;;
-    esac
-    if [ -f "${dir}.comet.yaml" ]; then
-      YAML_FILE="${dir}.comet.yaml"
-      break
-    fi
-  done
-fi
-
-# No active change — allow all writes
-if [ -z "$YAML_FILE" ]; then
-  echo "[COMET-HOOK] allowed: no active comet change" >&2
-  exit 0
-fi
-
-# ── Read current phase ───────────────────────────────────────────
-
-PHASE=$(grep "^phase:" "$YAML_FILE" 2>/dev/null \
-  | awk '{print $2}' \
-  | tr -d '[:space:][:cntrl:]' \
-  || true)
-
-if [ -z "$PHASE" ]; then
-  echo "[COMET-HOOK] allowed: no phase in .comet.yaml" >&2
-  exit 0
-fi
-
 # ── Resolve to project-relative path ─────────────────────────────
 
 # Normalize helper: forward slashes only
@@ -120,6 +85,95 @@ case "$RELPATH" in
     ;;
 esac
 
+# ── Helpers to read .comet.yaml fields ───────────────────────────
+
+is_archived() {
+  grep "^archived:" "$1" 2>/dev/null \
+    | awk '{print $2}' | tr -d '[:space:][:cntrl:]' || true
+}
+
+read_phase() {
+  grep "^phase:" "$1" 2>/dev/null \
+    | awk '{print $2}' | tr -d '[:space:][:cntrl:]' || true
+}
+
+read_field() {
+  grep "^$1:" "$2" 2>/dev/null \
+    | head -1 | awk '{print $2}' | tr -d '[:space:][:cntrl:]' || true
+}
+
+# ── Determine the governing Comet change + phase ─────────────────
+#
+# A write targeting a specific change directory (openspec/changes/<name>/...)
+# must be governed by THAT change's own phase — never by an unrelated
+# active change. Otherwise a change left in the `archive` phase would
+# wrongly block artifact writes for a brand-new change created alongside it.
+
+PHASE=""
+# Path to the .comet.yaml that governs this write (used for deeper invariant checks)
+GOV_YAML=""
+
+case "$RELPATH" in
+  openspec/changes/*/*)
+    _rest="${RELPATH#openspec/changes/}"
+    _own_change="${_rest%%/*}"
+    if [ -n "$_own_change" ] && [ "$_own_change" != "archive" ]; then
+      _own_yaml="openspec/changes/${_own_change}/.comet.yaml"
+      if [ -f "$_own_yaml" ]; then
+        if [ "$(is_archived "$_own_yaml")" = "true" ]; then
+          # This change is already archived — its own writes are unrestricted
+          echo "[COMET-HOOK] allowed: $RELPATH (own change archived)" >&2
+          exit 0
+        fi
+        PHASE=$(read_phase "$_own_yaml")
+        GOV_YAML="$_own_yaml"
+      else
+        # Change directory exists but state file not yet written
+        # (artifacts are created before .comet.yaml during /comet-open).
+        # Treat as `open` so proposal/design/tasks/specs are allowed.
+        PHASE="open"
+      fi
+    fi
+    ;;
+esac
+
+# Fallback: writes outside a specific change directory are governed by
+# the first active (non-archived) change.
+if [ -z "$PHASE" ]; then
+  YAML_FILE=""
+  if [ -d "openspec/changes" ]; then
+    for dir in openspec/changes/*/; do
+      [ -d "$dir" ] || continue
+      # Skip archived changes directory
+      case "$dir" in
+        */archive/*) continue ;;
+      esac
+      if [ -f "${dir}.comet.yaml" ]; then
+        # Skip changes already marked as archived
+        if [ "$(is_archived "${dir}.comet.yaml")" = "true" ]; then
+          continue
+        fi
+        YAML_FILE="${dir}.comet.yaml"
+        break
+      fi
+    done
+  fi
+
+  # No active change — allow all writes
+  if [ -z "$YAML_FILE" ]; then
+    echo "[COMET-HOOK] allowed: no active comet change" >&2
+    exit 0
+  fi
+
+  PHASE=$(read_phase "$YAML_FILE")
+  GOV_YAML="$YAML_FILE"
+fi
+
+if [ -z "$PHASE" ]; then
+  echo "[COMET-HOOK] allowed: no phase in .comet.yaml" >&2
+  exit 0
+fi
+
 # ── Whitelist: phase-aware allowed paths ─────────────────────────
 
 case "$RELPATH" in
@@ -222,6 +276,28 @@ esac
 
 case "$PHASE" in
   build|verify)
+    # Full workflow must have a Design Doc before any source write in build/verify.
+    # Catches illegal open→build / design→build jumps that skipped the design phase
+    # (e.g. misclassified preset, direct `set phase`, or bare transition).
+    if [ -n "$GOV_YAML" ]; then
+      _wf=$(read_field "workflow" "$GOV_YAML")
+      _dd=$(read_field "design_doc" "$GOV_YAML")
+      if [ "$_wf" = "full" ] && { [ -z "$_dd" ] || [ "$_dd" = "null" ]; }; then
+        echo "" >&2
+        echo "╔══════════════════════════════════════════╗" >&2
+        echo "║     COMET PHASE GUARD — WRITE BLOCKED    ║" >&2
+        echo "╚══════════════════════════════════════════╝" >&2
+        echo "" >&2
+        echo "  Current phase: $PHASE (workflow: full), but design_doc is empty" >&2
+        echo "  Target file: $RELPATH" >&2
+        echo "" >&2
+        echo "  ❌ Illegal phase jump detected: full workflow entered $PHASE without a Design Doc" >&2
+        echo "  ✅ Correct flow: create the Design Doc in design phase, then run comet-guard design --apply" >&2
+        echo "  💡 Run /comet-design to fill the missing design; for repair, set design_doc with comet-state" >&2
+        echo "" >&2
+        exit 2
+      fi
+    fi
     # Code writes allowed in build and verify
     echo "[COMET-HOOK] allowed: $RELPATH (phase: $PHASE)" >&2
     exit 0
@@ -232,23 +308,23 @@ case "$PHASE" in
     echo "║     COMET PHASE GUARD — WRITE BLOCKED    ║" >&2
     echo "╚══════════════════════════════════════════╝" >&2
     echo "" >&2
-    echo "  当前阶段: $PHASE" >&2
-    echo "  目标文件: $RELPATH" >&2
+    echo "  Current phase: $PHASE" >&2
+    echo "  Target file: $RELPATH" >&2
     echo "" >&2
     case "$PHASE" in
       open)
-        echo "  ❌ open 阶段不允许写源代码" >&2
-        echo "  ✅ 允许: 创建 proposal/design/tasks, 运行 guard" >&2
-        echo "  💡 完成需求澄清和 artifact 创建后运行 guard --apply" >&2
+        echo "  ❌ open phase does not allow source code writes" >&2
+        echo "  ✅ Allowed: create proposal/design/tasks and run guard" >&2
+        echo "  💡 After clarification and artifact creation, run guard --apply" >&2
         ;;
       design)
-        echo "  ❌ design 阶段不允许写源代码" >&2
-        echo "  ✅ 允许: brainstorming, 创建 Design Doc, 运行 guard" >&2
-        echo "  💡 完成 Design Doc 后运行 comet-guard design --apply 进入 build" >&2
+        echo "  ❌ design phase does not allow source code writes" >&2
+        echo "  ✅ Allowed: brainstorming, create the Design Doc, and run guard" >&2
+        echo "  💡 After the Design Doc is ready, run comet-guard design --apply to enter build" >&2
         ;;
       archive)
-        echo "  ❌ archive 阶段不允许写源代码" >&2
-        echo "  ✅ 允许: 确认归档, 运行归档脚本" >&2
+        echo "  ❌ archive phase does not allow source code writes" >&2
+        echo "  ✅ Allowed: confirm archive intent and run the archive script" >&2
         ;;
     esac
     echo "" >&2