@rpamis/comet 0.1.1 → 0.1.3

package/README.md

@@ -89,6 +89,13 @@ After `comet init`, three groups of skills are installed to the selected platfor
 | `/comet-hotfix` | Preset: Quick bug fix (skips brainstorming) |
 | `/comet-tweak` | Preset: Small change (skips brainstorming and full plan) |
 
+### Guard Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `comet-guard.sh` | Phase transition guard — validates exit conditions before phase transitions |
+| `comet-yaml-validate.sh` | Schema validator — validates `.comet.yaml` structure and field values |
+
 ### OpenSpec Skills
 
 Spec lifecycle management: propose, explore, sync, verify, archive, and more.
@@ -102,14 +109,14 @@ Development methodology: brainstorming, TDD, subagent-driven development, code r
 ```
 /comet
   ↓ auto-detect
-/comet-open ──→ /comet-design ──→ /comet-build ──→ /comet-verify ──→ /comet-archive
+/comet-open ——→ /comet-design ——→ /comet-build ——→ /comet-verify ——→ /comet-archive
   (OpenSpec)      (Superpowers)     (Superpowers)     (Both)          (OpenSpec)
 
 /comet-hotfix (preset path, skips brainstorming)
-  open ──→ build ──→ verify ──→ archive
+  open ——→ build ——→ verify ——→ archive
 
 /comet-tweak (preset path, skips brainstorming and full plan)
-  open ──→ lightweight build ──→ light verify ──→ archive
+  open ——→ lightweight build ——→ light verify ——→ archive
 ```
 
 ### Five Phases
@@ -130,12 +137,54 @@ Development methodology: brainstorming, TDD, subagent-driven development, code r
 - **Commit frequently** — one commit per task, message reflects design intent
 - **Verify before archive** — `/comet-verify` must pass before `/comet-archive`
 
+### State Management
+
+Comet uses a decoupled state architecture with separate YAML files:
+
+| File | Owner | Purpose |
+|------|-------|---------|
+| `.openspec.yaml` | OpenSpec | Spec lifecycle, change metadata |
+| `.comet.yaml` | Comet | Workflow phase, execution mode, verification status |
+
+**Key Fields in `.comet.yaml`:**
+- `workflow`: `full`, `hotfix`, or `tweak`
+- `phase`: `design`, `build`, `verify`, `archive`
+- `design_doc`: Path to Superpowers Design Doc
+- `plan`: Path to implementation plan
+- `build_mode`: `subagent-driven-development`, `executing-plans`, or `direct`
+- `verify_mode`: `light` or `full`
+- `verify_result`: `pending`, `pass`, or `fail`
+- `archived`: Boolean indicating if change is archived
+
+### Reliability Features
+
+Comet includes three-layer defense to ensure agent execution reliability:
+
+1. **Entry Verification** — Each phase validates preconditions before execution
+   - Checks file existence, state consistency, and phase transitions
+   - Outputs `[HARD STOP]` with actionable suggestions if validation fails
+
+2. **Write-Then-Verify** — Every state write is immediately verified
+   - After updating `.comet.yaml`, agents must verify field values
+   - Automatic retry mechanism (up to 2 attempts) on mismatch
+
+3. **Schema Validation** — `comet-yaml-validate.sh` ensures data integrity
+   - Validates required fields (9 fields)
+   - Validates enum values (6 enum types)
+   - Validates referenced file paths exist
+   - Detects unknown/typos fields
+
+**Security**: Path traversal protection on all change name inputs
+
 ## Project Structure
 
 ```
 your-project/
 ├── .claude/skills/              # Platform skills dir (Comet + OpenSpec + Superpowers)
 │   ├── comet/SKILL.md
+│   │   └── scripts/
+│   │       ├── comet-guard.sh       # Phase transition guard
+│   │       └── comet-yaml-validate.sh # Schema validator
 │   ├── comet-*/SKILL.md
 │   ├── openspec-*/SKILL.md
 │   └── brainstorming/SKILL.md
@@ -143,7 +192,8 @@ your-project/
 │   ├── config.yaml
 │   └── changes/
 │       └── <name>/
-│           ├── .openspec.yaml
+│           ├── .openspec.yaml       # OpenSpec state
+│           ├── .comet.yaml          # Comet workflow state (decoupled)
 │           ├── proposal.md
 │           ├── design.md
 │           ├── specs/<capability>/spec.md
@@ -173,6 +223,8 @@ pnpm build
 pnpm test
 ```
 
+See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
+
 ## Security
 
 - Pre-publish scan for API keys, secrets, tokens, and private keys

package/assets/manifest.json

@@ -1,13 +1,15 @@
-{
-  "version": "0.1.0",
-  "skills": [
-    "comet/SKILL.md",
-    "comet-open/SKILL.md",
-    "comet-design/SKILL.md",
-    "comet-build/SKILL.md",
-    "comet-verify/SKILL.md",
-    "comet-archive/SKILL.md",
-    "comet-hotfix/SKILL.md",
-    "comet-tweak/SKILL.md"
-  ]
-}
+{
+  "version": "0.1.0",
+  "skills": [
+    "comet/SKILL.md",
+    "comet/scripts/comet-guard.sh",
+    "comet/scripts/comet-yaml-validate.sh",
+    "comet-open/SKILL.md",
+    "comet-design/SKILL.md",
+    "comet-build/SKILL.md",
+    "comet-verify/SKILL.md",
+    "comet-archive/SKILL.md",
+    "comet-hotfix/SKILL.md",
+    "comet-tweak/SKILL.md"
+  ]
+}

package/assets/skills/comet/SKILL.md

@@ -65,21 +65,20 @@ agent 不应跳过这些决策点；其他明确无歧义的阶段衔接可以
 
 ### Step 1: Comet 状态元数据读取
 
-优先读取 `openspec/changes/<name>/.openspec.yaml` 中的 `comet` 元数据。若该字段不存在，再回退到 `openspec status --change "<name>" --json`、`tasks.md` 和 `docs/superpowers/` 文件检查。
+优先读取 `openspec/changes/<name>/.comet.yaml`。若该文件不存在，再回退到 `openspec status --change "<name>" --json`、`tasks.md` 和 `docs/superpowers/` 文件检查。
 
 推荐元数据结构：
 
 ```yaml
-comet:
-  workflow: full
-  phase: build
-  design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
-  plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
-  build_mode: subagent-driven-development
-  verify_mode: light
-  verify_result: pending
-  verified_at: null
-  archived: false
+workflow: full
+phase: build
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+build_mode: subagent-driven-development
+verify_mode: light
+verify_result: pending
+verified_at: null
+archived: false
 ```
 
 字段含义：
@@ -100,14 +99,14 @@ comet:
 
 对选中的 change，按以下顺序判断当前状态：
 
-1. **`comet.archived: true` 或 change 已移入 archive** → 流程已完成
-2. **`comet.verify_result: pass` 且 `comet.archived` 不是 `true`** → 调用 `/comet-archive`
-3. **`comet.phase: verify` 或 tasks.md 全部勾选** → 调用 `/comet-verify`
-4. **`comet.phase: build` 或已有 Design Doc 但计划/执行未完成** → 调用 `/comet-build`
-5. **`comet.phase: design` 或有 change 但无 Design Doc** → 调用 `/comet-design`
+1. **`archived: true` 或 change 已移入 archive** → 流程已完成
+2. **`verify_result: pass` 且 `archived` 不是 `true`** → 调用 `/comet-archive`
+3. **`phase: verify` 或 tasks.md 全部勾选** → 调用 `/comet-verify`
+4. **`phase: build` 或已有 Design Doc 但计划/执行未完成** → 调用 `/comet-build`
+5. **`phase: design` 或有 change 但无 Design Doc** → 调用 `/comet-design`
 6. **无活跃 change 或状态无法判定** → 调用 `/comet-open`
 
-如果元数据与文件状态冲突，以可验证的文件状态为准，并在继续阶段前修正 `.openspec.yaml` 中的 `comet` 字段。
+如果元数据与文件状态冲突，以可验证的文件状态为准，并在继续阶段前修正 `.comet.yaml`。
 
 ---
 
@@ -150,7 +149,7 @@ comet:
 |------|---------|
 | `openspec list --json` 失败 | 检查 openspec 是否已安装，提示用户运行 `openspec init` |
 | 子 skill 不可用（如 `superpowers:brainstorming`） | 停止流程，提示安装或启用对应 skill |
-| `.openspec.yaml` 格式异常或缺失 | 以文件状态为准（tasks.md、docs/superpowers/），修正元数据后继续 |
+| `.comet.yaml` 格式异常或缺失 | 以文件状态为准（tasks.md、docs/superpowers/），修正元数据后继续 |
 | Maven 编译/测试失败 | 返回 build 阶段修复，不进入 verify |
 | change 目录结构不完整 | 按 `comet-open` 的产物要求补齐缺失文件 |
 
@@ -158,6 +157,18 @@ comet:
 
 ## 快速参考
 
+### 脚本定位
+
+Comet 阶段守卫脚本 `comet-guard.sh` 随 skill 包分发，位于 `comet/scripts/` 目录。
+**不硬编码平台路径**，运行时通过以下命令自定位：
+
+```bash
+COMET_GUARD=$(find . -path '*/comet/scripts/comet-guard.sh' -type f -print -quit)
+bash "$COMET_GUARD" <change-name> <phase>
+```
+
+后续文档中 `bash $COMET_GUARD <change> <phase>` 均指此命令。加载 comet 后，agent 应在 shell 环境中缓存 `COMET_GUARD` 路径，避免重复 `find`。
+
 ### 文件结构
 
 ```
@@ -166,6 +177,7 @@ openspec/                              # OpenSpec — WHAT
 ├── changes/
 │   ├── <name>/                        # 活跃 change
 │   │   ├── .openspec.yaml
+│   │   ├── .comet.yaml
 │   │   ├── proposal.md                # Why + What
 │   │   ├── design.md                  # 高层架构决策
 │   │   ├── specs/<capability>/spec.md # Delta 能力规格

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

@@ -0,0 +1,203 @@
+#!/bin/bash
+# Comet Phase Guard — validates exit conditions before phase transitions
+# Usage: comet-guard.sh <change-name> <from-phase>
+# Phases: open, design, build, verify, archive
+# Exit 0 = all checks pass, exit 1 = blocked (reasons printed to stderr)
+
+set -euo pipefail
+
+red() { echo -e "\033[31m$1\033[0m" >&2; }
+green() { echo -e "\033[32m$1\033[0m" >&2; }
+warn() { echo -e "\033[33m$1\033[0m" >&2; }
+
+# Input validation - prevent path traversal
+validate_change_name() {
+  local name="$1"
+  # Reject empty names
+  if [ -z "$name" ]; then
+    red "ERROR: Change name cannot be empty" >&2
+    exit 1
+  fi
+  # Only allow alphanumeric, hyphens, and underscores
+  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+    red "ERROR: Invalid change name: '$name'" >&2
+    red "Valid characters: a-z, A-Z, 0-9, -, _" >&2
+    exit 1
+  fi
+  # Reject path traversal attempts
+  if [[ "$name" =~ \.\. ]]; then
+    red "ERROR: Change name cannot contain '..' (path traversal not allowed)" >&2
+    exit 1
+  fi
+}
+
+validate_change_name "$1"
+
+CHANGE="$1"
+PHASE="$2"
+CHANGE_DIR="openspec/changes/$CHANGE"
+
+BLOCK=0
+check() {
+  local desc="$1"
+  shift
+  if "$@" 2>/dev/null; then
+    green "  [PASS] $desc"
+  else
+    red "  [FAIL] $desc"
+    BLOCK=1
+  fi
+}
+
+# --- Helper functions ---
+
+tasks_all_done() {
+  local tasks="$CHANGE_DIR/tasks.md"
+  [ -f "$tasks" ] || return 1
+  grep -q '\- \[x\]' "$tasks" || return 1
+  ! grep -q '\- \[ \]' "$tasks"
+}
+
+tasks_has_any() {
+  local tasks="$CHANGE_DIR/tasks.md"
+  [ -f "$tasks" ] && grep -q '\- \[' "$tasks"
+}
+
+yaml_field_value() {
+  local field="$1"
+  local yaml="$CHANGE_DIR/.comet.yaml"
+  if [ -f "$yaml" ]; then
+    grep "^${field}:" "$yaml" | sed "s/^${field}: *//" | tr -d '"' | tr -d "'"
+  fi
+}
+
+file_nonempty() {
+  [ -f "$1" ] && [ -s "$1" ]
+}
+
+preflight() {
+  local expected_phase="$1"
+
+  if [ ! -d "$CHANGE_DIR" ]; then
+    red "FATAL: change directory not found: $CHANGE_DIR"
+    exit 1
+  fi
+  if [ ! -f "$CHANGE_DIR/.comet.yaml" ]; then
+    red "FATAL: .comet.yaml not found in $CHANGE_DIR"
+    exit 1
+  fi
+
+  local actual_phase
+  actual_phase=$(yaml_field_value "phase" 2>/dev/null || true)
+  if [ "$actual_phase" != "$expected_phase" ]; then
+    red "FATAL: .comet.yaml phase is '$actual_phase', expected '$expected_phase'"
+    exit 1
+  fi
+
+  # Schema validation
+  local script_dir validate_script
+  script_dir="$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")" 2>/dev/null || dirname "$0")"
+  validate_script="$script_dir/comet-yaml-validate.sh"
+  if [ -f "$validate_script" ]; then
+    if ! bash "$validate_script" "$CHANGE" 2>/dev/null; then
+      bash "$validate_script" "$CHANGE"
+      red "FATAL: .comet.yaml schema validation failed"
+      exit 1
+    fi
+  fi
+}
+
+maven_compiles() {
+  if [ "${COMET_SKIP_BUILD:-0}" = "1" ]; then
+    return 0
+  fi
+  mvn compile -q 2>/dev/null
+}
+
+verify_result_is_pass() {
+  local result
+  result=$(yaml_field_value "verify_result" 2>/dev/null || true)
+  [ "$result" = "pass" ]
+}
+
+archived_is_true() {
+  local val
+  val=$(yaml_field_value "archived" 2>/dev/null || true)
+  [ "$val" = "true" ]
+}
+
+# --- Phase-specific checks ---
+
+guard_open() {
+  echo "=== Guard: open → design ===" >&2
+
+  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"
+  check "tasks.md exists and non-empty" file_nonempty "$CHANGE_DIR/tasks.md"
+  check "tasks.md has at least one task" tasks_has_any
+}
+
+guard_design() {
+  echo "=== Guard: design → build ===" >&2
+
+  local design_doc
+  design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
+
+  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
+  check "tasks.md exists" file_nonempty "$CHANGE_DIR/tasks.md"
+
+  if [ -n "$design_doc" ] && [ "$design_doc" != "null" ]; then
+    check "Design Doc ($design_doc) exists" file_nonempty "$design_doc"
+  else
+    warn "  [WARN] No design_doc recorded in .comet.yaml"
+  fi
+}
+
+guard_build() {
+  echo "=== Guard: build → verify ===" >&2
+
+  check "tasks.md all tasks checked" tasks_all_done
+  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
+  check "Maven compile passes" maven_compiles
+}
+
+guard_verify() {
+  echo "=== Guard: verify → archive ===" >&2
+
+  check "verify_result is pass" verify_result_is_pass
+  check "tasks.md all tasks checked" tasks_all_done
+  check "Maven compile passes" maven_compiles
+}
+
+guard_archive() {
+  echo "=== Guard: archive completeness ===" >&2
+
+  check "archived is true" archived_is_true
+  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
+  check "tasks.md all tasks checked" tasks_all_done
+}
+
+# --- Main ---
+
+case "$PHASE" in
+  open)     preflight "design"  ; guard_open ;;
+  design)   preflight "build"   ; guard_design ;;
+  build)    preflight "verify"  ; guard_build ;;
+  verify)   preflight "archive" ; guard_verify ;;
+  archive)  preflight "archive" ; guard_archive ;;
+  *)
+    red "Unknown phase: $PHASE"
+    echo "Valid phases: open, design, build, verify, archive" >&2
+    exit 1
+    ;;
+esac
+
+if [ "$BLOCK" -eq 1 ]; then
+  echo "" >&2
+  red "BLOCKED — fix failing checks before proceeding to next phase"
+  exit 1
+else
+  echo "" >&2
+  green "ALL CHECKS PASSED — ready for next phase"
+  exit 0
+fi

package/assets/skills/comet/scripts/comet-yaml-validate.sh

@@ -0,0 +1,130 @@
+#!/bin/bash
+# Comet YAML Schema Validator — validates .comet.yaml structure
+# Usage: comet-yaml-validate.sh <change-name>
+# Exit 0 = valid, exit 1 = errors found (printed to stderr)
+
+set -euo pipefail
+
+red()   { echo -e "\033[31m$1\033[0m" >&2; }
+green() { echo -e "\033[32m$1\033[0m" >&2; }
+warn()  { echo -e "\033[33m$1\033[0m" >&2; }
+
+# Input validation - prevent path traversal
+validate_change_name() {
+  local name="$1"
+  # Reject empty names
+  if [ -z "$name" ]; then
+    red "ERROR: Change name cannot be empty" >&2
+    exit 1
+  fi
+  # Only allow alphanumeric, hyphens, and underscores
+  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+    red "ERROR: Invalid change name: '$name'" >&2
+    red "Valid characters: a-z, A-Z, 0-9, -, _" >&2
+    exit 1
+  fi
+  # Reject path traversal attempts
+  if [[ "$name" =~ \.\. ]]; then
+    red "ERROR: Change name cannot contain '..' (path traversal not allowed)" >&2
+    exit 1
+  fi
+}
+
+validate_change_name "$1"
+
+CHANGE="$1"
+YAML="openspec/changes/$CHANGE/.comet.yaml"
+
+ERRORS=0
+WARNINGS=0
+
+# Helper: get value of a top-level field (handles null, empty, quoted)
+field_value() {
+  grep "^${1}:" "$YAML" 2>/dev/null | sed "s/^${1}: *//" | tr -d '"' | tr -d "'" || true
+}
+
+fail()  { red "  FAIL: $1"; ERRORS=$((ERRORS + 1)); }
+warn_msg() { warn "  WARN: $1"; WARNINGS=$((WARNINGS + 1)); }
+
+echo "[VALIDATE] $YAML" >&2
+
+# --- Required fields ---
+REQUIRED_FIELDS="workflow phase design_doc plan build_mode verify_mode verify_result verified_at archived"
+for field in $REQUIRED_FIELDS; do
+  if ! grep -q "^${field}:" "$YAML" 2>/dev/null; then
+    fail "missing required field '$field'"
+  fi
+done
+
+# --- Enum validation ---
+validate_enum() {
+  local field="$1" value="$2"
+  shift 2
+  local valid_values="$*"
+
+  # null or empty is always acceptable
+  if [ -z "$value" ] || [ "$value" = "null" ]; then
+    return 0
+  fi
+
+  for v in $valid_values; do
+    if [ "$value" = "$v" ]; then
+      return 0
+    fi
+  done
+  fail "$field='$value' is not valid. Expected: $valid_values"
+}
+
+workflow=$(field_value "workflow")
+phase=$(field_value "phase")
+build_mode=$(field_value "build_mode")
+verify_mode=$(field_value "verify_mode")
+verify_result=$(field_value "verify_result")
+archived=$(field_value "archived")
+design_doc=$(field_value "design_doc")
+plan=$(field_value "plan")
+
+validate_enum "workflow"      "$workflow"      "full hotfix tweak"
+validate_enum "phase"         "$phase"          "design build verify archive"
+validate_enum "build_mode"    "$build_mode"     "subagent-driven-development executing-plans direct"
+validate_enum "verify_mode"   "$verify_mode"    "light full"
+validate_enum "verify_result" "$verify_result"  "pending pass fail"
+validate_enum "archived"      "$archived"       "true false"
+
+# --- Path validation ---
+
+if [ -n "$design_doc" ] && [ "$design_doc" != "null" ]; then
+  if [ ! -f "$design_doc" ]; then
+    fail "design_doc='$design_doc' does not exist on disk"
+  fi
+fi
+
+if [ -n "$plan" ] && [ "$plan" != "null" ]; then
+  if [ ! -f "$plan" ]; then
+    fail "plan='$plan' does not exist on disk"
+  fi
+fi
+
+# --- Unknown keys check ---
+KNOWN_KEYS="workflow phase design_doc plan build_mode verify_mode verify_result verified_at archived"
+while IFS=: read -r key _; do
+  key="${key// /}"
+  [ -z "$key" ] && continue
+  found=0
+  for known in $KNOWN_KEYS; do
+    [ "$key" = "$known" ] && found=1 && break
+  done
+  if [ "$found" -eq 0 ]; then
+    warn_msg "unknown field '$key' found"
+  fi
+done < "$YAML"
+
+# --- Summary ---
+echo "" >&2
+if [ "$ERRORS" -gt 0 ]; then
+  red "$ERRORS error(s), $WARNINGS warning(s) — validation FAILED"
+  exit 1
+else
+  green "0 errors, $WARNINGS warning(s) — validation PASSED"
+  exit 0
+fi

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

@@ -9,13 +9,37 @@ description: "Comet 阶段 5：归档。用 /comet-archive 调用。同步 delta
 
 - 验证已通过（阶段 4 完成）
 - 分支已处理
-- `openspec/changes/<name>/.openspec.yaml` 中 `comet.verify_result: pass`
+- `openspec/changes/<name>/.comet.yaml` 中 `verify_result: pass`
 
 ## 步骤
 
+### 0. 入口状态验证（Entry Check）
+
+在执行任何操作之前，读取并验证当前状态：
+
+**检查清单：**
+1. `openspec/changes/<name>/.comet.yaml` 存在
+2. `phase` 字段的值为 `"archive"`
+3. `verify_result` 字段的值为 `"pass"`
+4. `archived` 字段为 `"false"` 或 null（尚未归档）
+
+**验证方式：**
+- `cat openspec/changes/<name>/.comet.yaml` 读取全部字段
+- 如 `verify_result` 不是 `"pass"`，必须先完成验证
+
+**失败输出：**
+```
+[HARD STOP] Entry check failed for comet-archive
+  Expected: phase=archive, verify_result=pass, archived=false|null
+  Actual:   phase=<实际值>, verify_result=<实际值>, archived=<实际值>
+  Suggestion: Run comet-verify first, or this change was already archived.
+```
+
+验证通过后才进入步骤 1。
+
 ### 1. 执行归档
 
-归档前如 `comet.verify_result` 不是 `pass`，停止归档并返回 `/comet-verify`。
+归档前如 `verify_result` 不是 `pass`，停止归档并返回 `/comet-verify`。
 
 **立即执行：** 使用 Skill 工具加载 `openspec-archive-change` 技能。禁止跳过此步骤。
 
@@ -24,6 +48,19 @@ description: "Comet 阶段 5：归档。用 /comet-archive 调用。同步 delta
 2. 所有任务已标记 `[x]`
 3. delta specs 同步状态
 
+### 1b. 移动 Comet 状态文件
+
+`openspec-archive-change` 不感知 `.comet.yaml`，因此 Comet 需要在 OpenSpec 归档完成后自行移动该文件：
+
+```bash
+mv openspec/changes/<name>/.comet.yaml openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
+```
+
+【写入验证】移动完成后必须验证：
+  test -f openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
+  确认归档目录中 .comet.yaml 存在
+  如文件不在预期位置，检查 mv 命令是否成功执行。
+
 ### 2. Delta Spec 同步
 
 归档时将 delta specs 同步到主 specs：
@@ -73,6 +110,7 @@ change 移入归档目录：
 ```
 openspec/changes/archive/YYYY-MM-DD-<name>/
 ├── .openspec.yaml
+├── .comet.yaml
 ├── proposal.md
 ├── design.md
 ├── specs/<capability>/spec.md
@@ -92,16 +130,22 @@ brainstorming → delta spec → 实施（增量修改）→ 验证 → 主 spec
 - 主 specs 已更新（delta → main 同步完成）
 - 关联 design doc 已标注归档状态
 - 关联 plan 已标注归档状态
-- `.openspec.yaml` 中 `comet.archived` 已记录为 `true`
+- `.comet.yaml` 中 `archived` 已记录为 `true`
+- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> archive`，全部 PASS 后确认归档完整
 
-归档完成后，在归档目录的 `.openspec.yaml` 中合并更新：
+归档完成后，在归档目录的 `.comet.yaml` 中更新：
 
 ```yaml
-comet:
-  phase: archive
-  archived: true
+phase: archive
+archived: true
 ```
 
+【写入验证】更新完成后必须验证：
+  cat openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
+  确认 phase 行的值为 "archive"
+  确认 archived 行的值为 "true"
+  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
 ## 完成
 
 Comet 流程全部完成。如需开始新工作，调用 `/comet` 或 `/comet-open`。