@rpamis/comet 0.3.8 → 0.3.9

package/README.md

@@ -40,13 +40,11 @@ Superpowers handles **HOW** (technical design, planning, execution, wrap-up).
 Comet chains both into a five-phase automated pipeline.
 
 > [!IMPORTANT]
-> **0.3.7 Highlights** — One-step [CodeGraph](https://github.com/colbymchenry/codegraph) semantic code indexing (official: cost **↓16%**, tool calls **↓58%**); 
+> **0.3.9** — Review mode (`off|standard|thorough`) controls Build/Verify code review with project defaults; init/update now use optional dependency prompts, broader CLI i18n, stronger phase guards, and macOS executable bits.
 >
-> New **Beta context compression** cutting Build-phase input tokens by **25–30%**; 
-> New active context compression mechanism to release context consumed by reading specs and brainstorming, preserving window space for the subsequent Build phase.
-> 6 default-on workflow token optimizations; New `auto_transition` config for automatic or manual phase handoff; 
-> Hook+Rule anti-drift phase guard; Optional TDD mode and subagent dispatch confirmation; 
-> Large PRD split into multiple changes; Pre-archive confirmation with reopen, verify retry limit, systematic debugging interception, and verification completion check.
+> **0.3.8** — Adds Kimi Code support, safe multi-platform `comet uninstall`, extended subagent dispatch, shared progressive-loading references, update checks, and pre-commit formatting.
+>
+> **0.3.7** — Adds CodeGraph semantic indexing, Beta context compression, active context compression, token optimizations, `auto_transition`, phase guards, optional TDD, and safer archive/verification flow.
 >
 > See [NEWS.md](NEWS.md) for details.
 
@@ -134,15 +132,14 @@ comet init
 1. Prompt you to select AI platforms (auto-detects existing configs)
 2. Choose install scope: project-level (current directory) or global (home directory)
 3. Select language for Comet skills: English or 中文
-4. Install [OpenSpec](https://github.com/Fission-AI/OpenSpec) skills
-5. Install [Superpowers](https://github.com/obra/superpowers) skills
+4. Select npm dependencies to install/upgrade — [OpenSpec](https://github.com/Fission-AI/OpenSpec) CLI, [Superpowers](https://github.com/obra/superpowers) (via `npx skills add`), and [CodeGraph](https://github.com/colbymchenry/codegraph) CLI. Items not yet detected default to checked; already-installed items default to unchecked so you can opt in to upgrades.
+5. Install the selected dependencies and deploy their skills
 6. Deploy Comet skills (in your chosen language) to selected platforms
 7. Create `docs/superpowers/specs/` and `docs/superpowers/plans/` working directories for project-scope installs
 
 > [!TIP]
-> update version
->
-> `comet update` or `npm install -g @rpamis/comet@latest` to get the latest features and fixes.
+> Superpowers v6.0.0+ is recommended — about 2× faster and ~50% fewer tokens than older versions.
+> To upgrade Comet itself later: `comet update` or `npm install -g @rpamis/comet@latest`.
 
 ## Support for OpenClaw and Hermes, and other AI platforms
 
@@ -168,13 +165,14 @@ npx skills add rpamis/comet
 
 Initializes OpenSpec, Superpowers, and Comet skills for selected AI coding platforms.
 
-| Option            | Description                                                                    |
-|-------------------|--------------------------------------------------------------------------------|
-| `--yes`           | Non-interactive mode, auto-select detected platforms (or all if none detected) |
-| `--scope <scope>` | Install scope: `project` or `global`                                           |
-| `--skip-existing` | Skip already installed components                                              |
-| `--overwrite`     | Overwrite already installed components                                         |
-| `--json`          | Output structured JSON                                                         |
+| Option              | Description                                                                    |
+|---------------------|--------------------------------------------------------------------------------|
+| `--yes`             | Non-interactive mode, auto-select detected platforms (or all if none detected) |
+| `--scope <scope>`   | Install scope: `project` or `global`                                           |
+| `--language <lang>` | Skill language: `en` or `zh` (skips interactive language prompt)              |
+| `--skip-existing`   | Skip already installed components                                              |
+| `--overwrite`       | Overwrite already installed components                                         |
+| `--json`            | Output structured JSON                                                         |
 
 When multiple existing components are found on the same platform, interactive init offers one bulk choice: overwrite
 all, skip all, or choose per component.

package/assets/skills/comet/reference/dirty-worktree.md

@@ -1,59 +1,59 @@
-# Dirty Worktree Protocol
-
-Canonical path: `comet/reference/dirty-worktree.md`
-
-This protocol is shared by all Comet sub-skills that may modify code. When an agent resumes context or continues execution, it must handle uncommitted working tree changes through this protocol.
-
-## 1. Checks
-
-Before continuing or starting code changes, run:
-
-```bash
-git status --short
-git diff --stat
-git diff --cached --stat
-git ls-files --others --exclude-standard
-```
-
-When needed, inspect `git diff`, `git diff --cached`, and newly created file contents.
-
-## 2. Core Rules
-
-- The user may not say which files they changed. If the worktree is dirty, including new files shown as `??` in Git status, assume changes may come from the user or mixed sources.
-- **Build artifact exclusion**: `??` files matching `.gitignore` patterns (e.g., `node_modules/`, `dist/`, `__pycache__/`, `*.o`, `target/`, `build/`) are automatically skipped during attribution and not treated as user changes.
-- A dirty worktree is code evidence only. It does not automatically advance `.comet.yaml` `phase` or check off `tasks.md`; Comet state may advance only after attribution, verification, required document synchronization, and the relevant phase guard.
-
-## 3. Attribution
-
-Classify dirty diffs into three groups:
-
-1. **Belongs to the current change**: Files and content match the current change goal, tasks.md, plan, or delta spec. Incorporate the diff into the current task and avoid redoing the same work.
-2. **Does not belong to the current change**: Files or content are unrelated. Pause and ask whether to include it in the current change, split it into a new change, leave it alone, or discard it with explicit authorization.
-3. **Unclear source**: The diff and documents are not enough to determine ownership. Pause, report the file list and reasoning, and do not advance the phase.
-
-## 4. Common Patterns
-
-### Implemented But tasks.md Is Not Checked
-
-Verify the implementation with build and tests. If it passes, check off the task. Do not redo work just because the task is unchecked, and do not ignore code evidence because state files lag behind. If the current sub-skill defines a phase-specific rule, follow that sub-skill.
-
-### Plan Or Scope Changed
-
-Follow the current sub-skill's escalation, incremental-update, or rollback rules. This protocol does not repeat phase-specific details.
-
-### Ambiguous Resume Intent
-
-When the user says things like "continue", "keep going", "I changed a bit", "I wasn't happy with it", "redo it", "code changed", or "use what is there", follow this protocol. Do not require the user to remember exactly what they changed.
-
-### Code Changes During open/design
-
-If the current phase is still `open` or `design` but the dirty worktree already contains code changes, first attribute the changes through this protocol and do not advance the phase directly:
-
-- If the changes belong to the current change, treat them as requirements or design input and record them in proposal/design/spec/design doc/tasks as appropriate. The current phase guard must still pass before entering build.
-- If the changes do not belong to the current change or ownership is unclear, pause and ask whether to include them, split them into a new change, leave them alone, or discard them with explicit authorization.
-- Do not treat code changes made during open/design as completed implementation ready for verify.
-
-## 5. Prohibitions
-
-- Do not overwrite, revert, reformat over, or ignore user changes before understanding the dirty diff source.
-- Do not mark verification as passed while dirty diff remains unexplained.
+# Dirty Worktree Protocol
+
+Canonical path: `comet/reference/dirty-worktree.md`
+
+This protocol is shared by all Comet sub-skills that may modify code. When an agent resumes context or continues execution, it must handle uncommitted working tree changes through this protocol.
+
+## 1. Checks
+
+Before continuing or starting code changes, run:
+
+```bash
+git status --short
+git diff --stat
+git diff --cached --stat
+git ls-files --others --exclude-standard
+```
+
+When needed, inspect `git diff`, `git diff --cached`, and newly created file contents.
+
+## 2. Core Rules
+
+- The user may not say which files they changed. If the worktree is dirty, including new files shown as `??` in Git status, assume changes may come from the user or mixed sources.
+- **Build artifact exclusion**: `??` files matching `.gitignore` patterns (e.g., `node_modules/`, `dist/`, `__pycache__/`, `*.o`, `target/`, `build/`) are automatically skipped during attribution and not treated as user changes.
+- A dirty worktree is code evidence only. It does not automatically advance `.comet.yaml` `phase` or check off `tasks.md`; Comet state may advance only after attribution, verification, required document synchronization, and the relevant phase guard.
+
+## 3. Attribution
+
+Classify dirty diffs into three groups:
+
+1. **Belongs to the current change**: Files and content match the current change goal, tasks.md, plan, or delta spec. Incorporate the diff into the current task and avoid redoing the same work.
+2. **Does not belong to the current change**: Files or content are unrelated. Pause and ask whether to include it in the current change, split it into a new change, leave it alone, or discard it with explicit authorization.
+3. **Unclear source**: The diff and documents are not enough to determine ownership. Pause, report the file list and reasoning, and do not advance the phase.
+
+## 4. Common Patterns
+
+### Implemented But tasks.md Is Not Checked
+
+Verify the implementation with build and tests. If it passes, check off the task. Do not redo work just because the task is unchecked, and do not ignore code evidence because state files lag behind. If the current sub-skill defines a phase-specific rule, follow that sub-skill.
+
+### Plan Or Scope Changed
+
+Follow the current sub-skill's escalation, incremental-update, or rollback rules. This protocol does not repeat phase-specific details.
+
+### Ambiguous Resume Intent
+
+When the user says things like "continue", "keep going", "I changed a bit", "I wasn't happy with it", "redo it", "code changed", or "use what is there", follow this protocol. Do not require the user to remember exactly what they changed.
+
+### Code Changes During open/design
+
+If the current phase is still `open` or `design` but the dirty worktree already contains code changes, first attribute the changes through this protocol and do not advance the phase directly:
+
+- If the changes belong to the current change, treat them as requirements or design input and record them in proposal/design/spec/design doc/tasks as appropriate. The current phase guard must still pass before entering build.
+- If the changes do not belong to the current change or ownership is unclear, pause and ask whether to include them, split them into a new change, leave them alone, or discard them with explicit authorization.
+- Do not treat code changes made during open/design as completed implementation ready for verify.
+
+## 5. Prohibitions
+
+- Do not overwrite, revert, reformat over, or ignore user changes before understanding the dirty diff source.
+- Do not mark verification as passed while dirty diff remains unexplained.

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

@@ -19,7 +19,17 @@ When there is an active comet change (`openspec/changes/<name>/.comet.yaml` exis
 | `build` | Write source code, tests, execute plans | Skip user confirmation points |
 | `verify` | Verification, branch handling | Skip failure handling |
 | `archive` | Confirm archive, run archive script | Write source code |
+### Phase-Entry Self-Consistency Check (Before Writing Source Code)
 
+Reading the `phase` field alone is not enough — you must also confirm **how** that phase was reached. Before writing any source code, self-check whether `.comet.yaml` is in an **illegal jump** state (a prior phase was skipped) using the table below. If any row matches, immediately stop writing source code, go back to the corresponding phase to fill the missing artifact, and do not trust the `phase` field to keep going.
+
+| Detected | Verdict | Action |
+|----------|---------|--------|
+| `phase: build` + `workflow: full` + `design_doc` empty/null | Skipped design | Stop writing source; run `/comet-design` to create the Design Doc and pass guard |
+| `phase: build/verify` + any of proposal/design/tasks missing or empty | Skipped open | Return to `/comet-open` to fill the three artifacts |
+| `phase: archive` + `verify_result` ≠ `pass` | Skipped verify | Return to `/comet-verify` to complete verification |
+
+Exception: `workflow: hotfix/tweak` intentionally skips design, so an empty `design_doc` is normal and not an illegal jump.
 ### Skill Invocation (Cannot Replace with Normal Conversation)
 
 The following operations must be loaded through the Skill tool. When Skill is unavailable, stop the workflow and prompt to install:
@@ -37,6 +47,7 @@ The following operations must be loaded through the Skill tool. When Skill is un
 - **Phase exit**: `comet-guard <name> <phase> --apply` (must see ALL CHECKS PASSED)
 - **Compression recovery**: `comet-state check <name> <phase> --recover`
 - **State update**: After key operations, update fields through `comet-state set`; manually editing .comet.yaml is prohibited
+- **Phase advancement only via guard/transition**: directly running `comet-state set <name> phase <value>` to jump phases is prohibited (it bypasses evidence checks and the script now hard-blocks it); use the `COMET_FORCE_PHASE=1` escape hatch only to repair a malformed state
 - **handoff generation**: `comet-handoff <name> design --write` (handwriting summaries is prohibited)
 
 ### User Confirmation (Cannot Auto-Skip)
@@ -80,6 +91,8 @@ If context compression is suspected (previous conversation was summarized, previ
 
 Decide next step according to the script's **Recovery action** output.
 
+After recovery, first re-run the "Phase-Entry Self-Consistency Check" table: if `phase` is inconsistent with the artifacts (design_doc / three artifacts / verify_result mismatch), treat it as an illegal jump, return to the corresponding phase to fill the gap, and do not trust the `phase` field to keep going.
+
 **Special attention to `build_mode`**: If recovery script outputs `build_mode: subagent-driven-development`, you are the coordinator, not the executor. Must:
 1. Use the Skill tool to reload the Superpowers `subagent-driven-development` skill
 2. Re-read `comet/reference/subagent-dispatch.md` for Comet-specific extensions
@@ -91,9 +104,20 @@ Decide next step according to the script's **Recovery action** output.
 
 ## Automatic Transition After Phase Exit
 
-After guard `--apply` succeeds, must invoke the next phase's skill:
+After guard `--apply` succeeds, do not hardcode the next skill in this rule. First run:
+
+```bash
+comet-state next <change-name>
+```
+
+If `comet-env.sh` has already located the scripts, the equivalent command is:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
+
+Decide the next step from the script output:
 
-- open → `comet-design` (full) / `comet-build` (hotfix/tweak)
-- design → `comet-build`
-- build → `comet-verify`
-- verify → `comet-archive`
+- `NEXT: auto` → use the Skill tool to load the skill named by `SKILL`
+- `NEXT: manual` → do not load the next skill; show `HINT` so the user can continue manually
+- `NEXT: done` → the workflow is complete; no further action is needed

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

@@ -20,6 +20,18 @@
 | `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 不可用时应停止流程并提示安装：
@@ -37,6 +49,7 @@
 - **阶段退出**: `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`（禁止手写摘要）
 
 ### 用户确认（不可自动跳过）
@@ -80,6 +93,8 @@
 
 按脚本输出的 **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)
@@ -91,9 +106,20 @@
 
 ## 阶段退出后自动过渡
 
-guard `--apply` 成功后，必须调用下一阶段的 skill：
+guard `--apply` 成功后，不得在本规则中硬编码下一阶段 skill。必须先运行：
+
+```bash
+comet-state next <change-name>
+```
+
+若已通过 `comet-env.sh` 定位脚本，等价运行：
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
+
+按脚本输出决定下一步：
 
-- open → `comet-design`（full）/ `comet-build`（hotfix/tweak）
-- design → `comet-build`
-- build → `comet-verify`
-- verify → `comet-archive`
+- `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