@rpamis/comet 0.1.2 → 0.1.4

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

@@ -6,14 +6,37 @@
 
 set -euo pipefail
 
-CHANGE="$1"
-PHASE="$2"
-CHANGE_DIR="openspec/changes/$CHANGE"
-
 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"
@@ -40,20 +63,11 @@ tasks_has_any() {
   [ -f "$tasks" ] && grep -q '\- \[' "$tasks"
 }
 
-yaml_has_field() {
-  local field="$1"
-  local yaml="$CHANGE_DIR/.openspec.yaml"
-  [ -f "$yaml" ] && grep -q "^${field}:" "$yaml"
-}
-
 yaml_field_value() {
   local field="$1"
-  local yaml="$CHANGE_DIR/.openspec.yaml"
+  local yaml="$CHANGE_DIR/.comet.yaml"
   if [ -f "$yaml" ]; then
-    # Escape dots for literal match (YAML field names contain dots)
-    local escaped
-    escaped=$(echo "$field" | sed 's/\./\\./g')
-    grep "^${escaped}:" "$yaml" | sed "s/^${escaped}: *//" | tr -d '"' | tr -d "'"
+    grep "^${field}:" "$yaml" | sed "s/^${field}: *//" | tr -d '"' | tr -d "'"
   fi
 }
 
@@ -61,16 +75,57 @@ 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 "comet.verify_result" 2>/dev/null || true)
+  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() {
@@ -86,7 +141,7 @@ guard_design() {
   echo "=== Guard: design → build ===" >&2
 
   local design_doc
-  design_doc=$(yaml_field_value "comet.design_doc" 2>/dev/null || true)
+  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"
@@ -94,7 +149,7 @@ guard_design() {
   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 .openspec.yaml"
+    warn "  [WARN] No design_doc recorded in .comet.yaml"
   fi
 }
 
@@ -117,6 +172,7 @@ guard_verify() {
 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
 }
@@ -124,11 +180,11 @@ guard_archive() {
 # --- Main ---
 
 case "$PHASE" in
-  open)     guard_open ;;
-  design)   guard_design ;;
-  build)    guard_build ;;
-  verify)   guard_verify ;;
-  archive)  guard_archive ;;
+  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

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,17 +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`。

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

@@ -12,6 +12,32 @@ description: "Comet 阶段 3：计划与构建。用 /comet-build 调用。制
 
 ## 步骤
 
+### 0. 入口状态验证（Entry Check）
+
+在执行任何操作之前，读取并验证当前状态：
+
+**检查清单：**
+1. `openspec/changes/<name>/.comet.yaml` 存在
+2. `phase` 字段的值为 `"build"`
+3. `design_doc` 字段非 null 且非空
+4. `design_doc` 引用的文件存在（例如 `docs/superpowers/specs/YYYY-MM-DD-topic-design.md`）
+5. `openspec/changes/<name>/proposal.md` 存在且非空
+6. `openspec/changes/<name>/tasks.md` 存在且非空
+
+**验证方式：**
+- `cat openspec/changes/<name>/.comet.yaml` 读取全部字段
+- 用 `ls` 或 `test -f` 确认 design_doc 文件存在
+
+**失败输出：**
+```
+[HARD STOP] Entry check failed for comet-build
+  Expected: phase=build, design_doc=<path> exists
+  Actual:   phase=<实际值>, design_doc=<实际值或文件不存在>
+  Suggestion: Run comet-design first, or verify design_doc file exists.
+```
+
+验证通过后才进入步骤 1。
+
 ### 1. 制定计划
 
 **立即执行：** 使用 Skill 工具加载 `superpowers:writing-plans` 技能。禁止跳过此步骤。
@@ -30,14 +56,18 @@ design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
 
 ### 2. 更新计划状态
 
-在 `openspec/changes/<name>/.openspec.yaml` 中合并更新：
+在 `openspec/changes/<name>/.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
 
 ```yaml
-comet:
-  phase: build
-  plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+phase: build
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
 ```
 
+【写入验证】更新完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 plan 行的值为 "docs/superpowers/plans/YYYY-MM-DD-feature.md"
+  如不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
 ### 3. 选择执行方式
 
 向用户展示计划摘要（任务数、涉及模块），然后询问执行方式：
@@ -52,7 +82,7 @@ comet:
 - 任务数 ≤ 2 且无跨模块依赖 → 推荐 B
 - 来自 hotfix 路径 → 推荐 B
 
-用户选择后，在 `openspec/changes/<name>/.openspec.yaml` 中记录实际执行方式。`build_mode` 只允许以下值之一：
+用户选择后，在 `openspec/changes/<name>/.comet.yaml` 中合并更新 `build_mode`（保留其他字段不变）。`build_mode` 只允许以下值之一：
 
 - `subagent-driven-development`
 - `executing-plans`
@@ -62,16 +92,19 @@ Few-shot 示例：
 
 ```yaml
 # 用户选择稳健模式 / A
-comet:
-  build_mode: subagent-driven-development
+build_mode: subagent-driven-development
 ```
 
 ```yaml
 # 用户选择快速模式 / B
-comet:
-  build_mode: executing-plans
+build_mode: executing-plans
 ```
 
+【写入验证】更新完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 build_mode 行的值为 "<subagent-driven-development 或 executing-plans 或 direct>"
+  如不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
 然后，**立即执行：** 使用 Skill 工具加载对应技能。禁止跳过此步骤。
 
 如所选 Superpowers 技能不可用，停止流程并提示安装或启用对应技能，不要用普通对话替代该步骤。
@@ -105,17 +138,22 @@ comet:
 - tasks.md 全部勾选
 - 代码已提交
 - 测试通过
-- `.openspec.yaml` 中 `comet.phase` 已更新为 `verify`
+- `.comet.yaml` 中 `phase` 已更新为 `verify`
 - **阶段守卫**：运行 `bash $COMET_GUARD <change-name> build`，全部 PASS 后才允许流转
 
-退出前合并更新：
+退出前在 `.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
 
 ```yaml
-comet:
-  phase: verify
-  verify_result: pending
+phase: verify
+verify_result: pending
 ```
 
+【写入验证】更新完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 phase 行的值为 "verify"
+  确认 verify_result 行的值为 "pending"
+  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
 ## 自动流转
 
 退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：

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

@@ -12,6 +12,33 @@ description: "Comet 阶段 2：深度设计。用 /comet-design 调用。通过
 
 ## 步骤
 
+### 0. 入口状态验证（Entry Check）
+
+在执行任何操作之前，读取并验证当前状态：
+
+**检查清单：**
+1. `openspec/changes/<name>/.comet.yaml` 存在
+2. `phase` 字段的值为 `"design"`
+3. `workflow` 字段的值为 `"full"`
+4. `design_doc` 字段为 `null` 或空
+5. `openspec/changes/<name>/proposal.md` 存在且非空
+6. `openspec/changes/<name>/design.md` 存在且非空
+7. `openspec/changes/<name>/tasks.md` 存在且非空
+
+**验证方式：**
+- `cat openspec/changes/<name>/.comet.yaml` 读取全部字段
+- 逐条比对检查清单
+
+**失败输出：**
+```
+[HARD STOP] Entry check failed for comet-design
+  Expected: phase=design, design_doc=<empty/null>, workflow=full
+  Actual:   phase=<实际值>, design_doc=<实际值>, workflow=<实际值>
+  Suggestion: Run comet-open first, or check if .comet.yaml was modified out of sequence.
+```
+
+验证通过后才进入步骤 1。
+
 ### 1a. 读取已有上下文
 
 读取活跃 change 下的 `proposal.md` 和 `design.md`，将核心内容整理为摘要：
@@ -39,14 +66,19 @@ Design 摘要: <design.md 架构决策>
 
 ### 2. 更新 Comet 状态
 
-在 `openspec/changes/<name>/.openspec.yaml` 中合并更新：
+在 `openspec/changes/<name>/.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
 
 ```yaml
-comet:
-  phase: build
-  design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+phase: build
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 ```
 
+【写入验证】更新完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 phase 行的值为 "build"
+  确认 design_doc 行的值为 "docs/superpowers/specs/YYYY-MM-DD-topic-design.md"
+  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
 ### 3. 双 Spec 分工
 
 | Spec 类型 | 归属 | 存放位置 | 定义 |

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

@@ -20,6 +20,28 @@ Hotfix 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
 
 ## 流程（preset workflow，4 阶段）
 
+### 0. 入口状态验证（Entry Check）
+
+在执行任何操作之前，验证当前状态：
+
+**检查清单：**
+1. `openspec/changes/<name>/` 目录不存在，或目录存在但 `.comet.yaml` 不存在（无冲突）
+
+**验证方式：**
+- `test -d openspec/changes/<name>` 检查目录
+- 如目录存在，`test -f openspec/changes/<name>/.comet.yaml` 检查配置文件
+- 如 `.comet.yaml` 已存在，读取 `phase` 检查是否为未完成的 hotfix
+
+**失败输出（有冲突）：**
+```
+[HARD STOP] Entry check failed for comet-hotfix
+  Expected: openspec/changes/<name>/.comet.yaml does not exist (new change)
+  Actual:   .comet.yaml exists with phase=<实际值>
+  Suggestion: Pick a different change name, or check if an existing hotfix is in progress.
+```
+
+验证通过后才进入流程步骤。
+
 执行链路：open → build → verify → archive。Hotfix 为每个阶段提供默认决策：精简开启、直接构建、按规模验证、验证通过后归档。
 
 ### 1. 快速开启（preset open）
@@ -34,21 +56,33 @@ Hotfix 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
   - `tasks.md` — 修复任务清单
 - **无需 delta spec**（除非修复改变了已有 spec 的验收场景）
 
-在 `openspec/changes/<name>/.openspec.yaml` 中写入或合并 hotfix 状态：
+在 `openspec/changes/<name>/` 下创建独立的 `.comet.yaml` 文件：
 
 ```yaml
-comet:
-  workflow: hotfix
-  phase: build
-  design_doc: null
-  plan: null
-  build_mode: direct
-  verify_mode: light
-  verify_result: pending
-  verified_at: null
-  archived: false
+workflow: hotfix
+phase: build
+design_doc: null
+plan: null
+build_mode: direct
+verify_mode: light
+verify_result: pending
+verified_at: null
+archived: false
 ```
 
+【写入验证】创建完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 workflow 行的值为 "hotfix"
+  确认 phase 行的值为 "build"
+  确认 design_doc 行的值为 "null"
+  确认 plan 行的值为 "null"
+  确认 build_mode 行的值为 "direct"
+  确认 verify_mode 行的值为 "light"
+  确认 verify_result 行的值为 "pending"
+  确认 verified_at 行的值为 "null"
+  确认 archived 行的值为 "false"
+  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
 ### 2. 直接构建（preset build）
 
 使用 hotfix 默认值：`build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`（除非任务 > 3 个；若超过 3 个任务，转入 `/comet-build` 的计划与执行方式选择）。
@@ -87,11 +121,11 @@ comet:
 - 回归测试揭示深层架构问题 → 停止 hotfix，升级为 `/comet`
 - 修复需要额外接口变更 → 停止 hotfix，升级为 `/comet`
 
-验证通过后，按 `/comet-verify` 的规则将 `comet.verify_result` 记录为 `pass`，归档前不得跳过该状态。
+验证通过后，按 `/comet-verify` 的规则将 `.comet.yaml` 的 `verify_result` 记录为 `pass`，归档前不得跳过该状态。
 
 ### 4. 归档（preset archive）
 
-复用 `/comet-archive`。归档前必须满足 `comet.verify_result: pass`。
+复用 `/comet-archive`。归档前必须满足 `.comet.yaml` 中 `verify_result: pass`。
 
 **立即执行：** 使用 Skill 工具加载 `comet-archive` 技能进行归档。禁止跳过此步骤。
 如有 delta spec，按 comet-archive 规则同步到 main spec，并处理关联 Design Doc 与 Plan 的归档标注。