@rpamis/comet 0.2.2 → 0.2.4

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

@@ -6,7 +6,8 @@
 #   init <change-name> <workflow>  — Initialize .comet.yaml with workflow defaults
 #   get <change-name> <field>       — Read a field value from .comet.yaml
 #   set <change-name> <field> <val> — Update a field value
-#   check <phase> <change-name>    — Verify entry requirements for a phase
+#   transition <change-name> <event> — Apply a validated state transition
+#   check <change-name> <phase>    — Verify entry requirements for a phase
 #   scale <change-name>             — Assess and set verification mode based on metrics
 #
 # Workflows: full, hotfix, tweak
@@ -77,6 +78,24 @@ file_nonempty() {
   [ -f "$1" ] && [ -s "$1" ]
 }
 
+change_dir_for() {
+  local change_name="$1"
+  if [ -d "openspec/changes/$change_name" ]; then
+    echo "openspec/changes/$change_name"
+  elif [ -d "openspec/changes/archive/$change_name" ]; then
+    echo "openspec/changes/archive/$change_name"
+  else
+    echo "openspec/changes/$change_name"
+  fi
+}
+
+yaml_file_for() {
+  local change_name="$1"
+  local change_dir
+  change_dir=$(change_dir_for "$change_name")
+  echo "$change_dir/.comet.yaml"
+}
+
 # --- Subcommands ---
 
 cmd_init() {
@@ -86,8 +105,9 @@ cmd_init() {
   validate_change_name "$change_name"
   validate_enum "$workflow" "full" "hotfix" "tweak"
 
-  local change_dir="openspec/changes/$change_name"
-  local yaml_file="$change_dir/.comet.yaml"
+  local change_dir yaml_file
+  change_dir=$(change_dir_for "$change_name")
+  yaml_file=$(yaml_file_for "$change_name")
 
   # Check if .comet.yaml already exists
   if [ -f "$yaml_file" ]; then
@@ -100,16 +120,15 @@ cmd_init() {
 
   # Set workflow-appropriate defaults
   local phase build_mode isolation verify_mode
+  phase="open"
 
   case "$workflow" in
     full)
-      phase="design"
       build_mode="null"
       isolation="null"
       verify_mode="null"
       ;;
     hotfix|tweak)
-      phase="build"
       build_mode="direct"
       isolation="branch"
       verify_mode="light"
@@ -126,6 +145,8 @@ verify_mode: $verify_mode
 design_doc: null
 plan: null
 verify_result: pending
+verification_report: null
+branch_status: pending
 verified_at: null
 archived: false
 EOF
@@ -139,8 +160,8 @@ cmd_get() {
 
   validate_change_name "$change_name"
 
-  local change_dir="openspec/changes/$change_name"
-  local yaml_file="$change_dir/.comet.yaml"
+  local yaml_file
+  yaml_file=$(yaml_file_for "$change_name")
 
   # Check if .comet.yaml exists
   if [ ! -f "$yaml_file" ]; then
@@ -161,8 +182,8 @@ cmd_set() {
 
   validate_change_name "$change_name"
 
-  local change_dir="openspec/changes/$change_name"
-  local yaml_file="$change_dir/.comet.yaml"
+  local yaml_file
+  yaml_file=$(yaml_file_for "$change_name")
 
   # Check if .comet.yaml exists
   if [ ! -f "$yaml_file" ]; then
@@ -172,12 +193,12 @@ cmd_set() {
 
   # Validate field name
   case "$field" in
-    workflow|phase|build_mode|isolation|verify_mode|verify_result|archived|design_doc|plan|verified_at)
+    workflow|phase|build_mode|isolation|verify_mode|verify_result|verification_report|branch_status|archived|design_doc|plan|verified_at)
       # Valid field
       ;;
     *)
       red "ERROR: Unknown field: '$field'" >&2
-      red "Valid fields: workflow, phase, design_doc, plan, build_mode, isolation, verify_mode, verify_result, verified_at, archived" >&2
+      red "Valid fields: workflow, phase, design_doc, plan, build_mode, isolation, verify_mode, verify_result, verification_report, branch_status, verified_at, archived" >&2
       exit 1
       ;;
   esac
@@ -188,7 +209,7 @@ cmd_set() {
       validate_enum "$value" "full" "hotfix" "tweak"
       ;;
     phase)
-      validate_enum "$value" "design" "build" "verify" "archive"
+      validate_enum "$value" "open" "design" "build" "verify" "archive"
       ;;
     build_mode)
       validate_enum "$value" "subagent-driven-development" "executing-plans" "direct"
@@ -202,10 +223,13 @@ cmd_set() {
     verify_result)
       validate_enum "$value" "pending" "pass" "fail"
       ;;
+    branch_status)
+      validate_enum "$value" "pending" "handled"
+      ;;
     archived)
       validate_enum "$value" "true" "false"
       ;;
-    design_doc|plan|verified_at)
+    design_doc|plan|verification_report|verified_at)
       # No validation for path fields and date fields
       ;;
   esac
@@ -222,6 +246,85 @@ cmd_set() {
   green "[SET] ${field}=${value}"
 }
 
+require_phase() {
+  local change_name="$1"
+  local expected="$2"
+  local actual
+  actual=$(cmd_get "$change_name" "phase")
+  if [ "$actual" != "$expected" ]; then
+    red "ERROR: Cannot transition '$change_name': expected phase ${expected}, got ${actual}" >&2
+    exit 1
+  fi
+}
+
+require_verification_evidence() {
+  local change_name="$1"
+  local report branch_status
+  report=$(cmd_get "$change_name" "verification_report")
+  branch_status=$(cmd_get "$change_name" "branch_status")
+
+  if [ -z "$report" ] || [ "$report" = "null" ] || [ ! -f "$report" ]; then
+    red "ERROR: Cannot transition '$change_name': verification_report must point to an existing report file" >&2
+    exit 1
+  fi
+
+  if [ "$branch_status" != "handled" ]; then
+    red "ERROR: Cannot transition '$change_name': branch_status must be handled" >&2
+    exit 1
+  fi
+}
+
+cmd_transition() {
+  local change_name="$1"
+  local event="$2"
+
+  validate_change_name "$change_name"
+  validate_enum "$event" "open-complete" "design-complete" "build-complete" "verify-pass" "verify-fail" "archived"
+
+  case "$event" in
+    open-complete)
+      require_phase "$change_name" "open"
+      local workflow
+      workflow=$(cmd_get "$change_name" "workflow")
+      if [ "$workflow" = "full" ]; then
+        cmd_set "$change_name" phase design
+      else
+        cmd_set "$change_name" phase build
+      fi
+      ;;
+    design-complete)
+      require_phase "$change_name" "design"
+      cmd_set "$change_name" phase build
+      ;;
+    build-complete)
+      require_phase "$change_name" "build"
+      cmd_set "$change_name" phase verify
+      cmd_set "$change_name" verify_result pending
+      cmd_set "$change_name" verification_report null
+      cmd_set "$change_name" branch_status pending
+      ;;
+    verify-pass)
+      require_phase "$change_name" "verify"
+      require_verification_evidence "$change_name"
+      cmd_set "$change_name" verify_result pass
+      cmd_set "$change_name" phase archive
+      cmd_set "$change_name" verified_at "$(date +%Y-%m-%d)"
+      ;;
+    verify-fail)
+      require_phase "$change_name" "verify"
+      cmd_set "$change_name" verify_result fail
+      cmd_set "$change_name" phase build
+      cmd_set "$change_name" branch_status pending
+      ;;
+    archived)
+      require_phase "$change_name" "archive"
+      cmd_set "$change_name" archived true
+      ;;
+  esac
+
+  green "[TRANSITION] ${event}"
+}
+
 # --- Check helpers for entry verification ---
 
 CHECK_BLOCK=0
@@ -283,8 +386,8 @@ check_file_not_exists() {
 }
 
 cmd_check() {
-  local phase="$1"
-  local change_name="$2"
+  local change_name="$1"
+  local phase="$2"
 
   validate_change_name "$change_name"
   validate_enum "$phase" "open" "design" "build" "verify" "archive"
@@ -297,21 +400,17 @@ cmd_check() {
 
   echo "=== Entry Check: comet-${phase} ==="
 
-  # For non-open phases, .comet.yaml must exist
-  if [ "$phase" != "open" ]; then
-    if [ ! -f "$yaml_file" ]; then
-      red "ERROR: .comet.yaml not found at $yaml_file"
-      exit 1
-    fi
+  # .comet.yaml must exist for all phases (state machine core)
+  if [ ! -f "$yaml_file" ]; then
+    red "ERROR: .comet.yaml not found at $yaml_file"
+    exit 1
   fi
 
   # Phase-specific checks
   case "$phase" in
     open)
-      check_file_not_exists ".comet.yaml" "$yaml_file"
-      check_nonempty "proposal.md" "$proposal_file"
-      check_nonempty "design.md" "$design_file"
-      check_nonempty "tasks.md" "$tasks_file"
+      check_pass ".comet.yaml exists"
+      check_yaml_is "phase" "open" "$change_name"
       ;;
     design)
       check_pass ".comet.yaml exists"
@@ -325,13 +424,19 @@ cmd_check() {
     build)
       check_pass ".comet.yaml exists"
       check_yaml_is "phase" "build" "$change_name"
-      # Check design_doc is non-null and file exists
-      local design_doc
-      design_doc=$(cmd_get "$change_name" "design_doc")
-      if [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -f "$change_dir/$design_doc" ]; then
-        check_pass "design_doc=${design_doc} (file exists)"
+      # design_doc required for full workflow only
+      local workflow
+      workflow=$(cmd_get "$change_name" "workflow")
+      if [ "$workflow" = "full" ]; then
+        local design_doc
+        design_doc=$(cmd_get "$change_name" "design_doc")
+        if [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -f "$design_doc" ]; then
+          check_pass "design_doc=${design_doc} (file exists)"
+        else
+          check_fail "design_doc=${design_doc} (expected: non-null and file exists)"
+        fi
       else
-        check_fail "design_doc=${design_doc} (expected: non-null and file exists)"
+        check_pass "workflow=${workflow} (design_doc not required)"
       fi
       check_nonempty "proposal.md" "$proposal_file"
       check_nonempty "tasks.md" "$tasks_file"
@@ -405,14 +510,19 @@ cmd_scale() {
     delta_spec_count=$(find "$change_dir/specs" -name "spec.md" -type f 2>/dev/null | wc -l | tr -d ' ')
   fi
 
-  # 3. Changed files: from git diff --stat HEAD
+  # 3. Changed files: prefer plan base-ref, fall back to worktree diff
   local changed_files=0
   if git rev-parse --git-dir > /dev/null 2>&1; then
-    # Extract the number before "file" in the last line
-    local stat_output
-    stat_output=$(git diff --stat HEAD 2>/dev/null | tail -1)
-    if [[ "$stat_output" =~ ([0-9]+)\ file ]]; then
-      changed_files="${BASH_REMATCH[1]}"
+    local plan_file base_ref
+    plan_file=$(cmd_get "$change_name" "plan" 2>/dev/null || true)
+    if [ -n "$plan_file" ] && [ "$plan_file" != "null" ] && [ -f "$plan_file" ]; then
+      base_ref=$(grep '^base-ref:' "$plan_file" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
+    fi
+
+    if [ -n "${base_ref:-}" ] && git rev-parse --verify "$base_ref" >/dev/null 2>&1; then
+      changed_files=$(git diff --name-only "$base_ref"...HEAD 2>/dev/null | wc -l | tr -d ' ')
+    else
+      changed_files=$(git diff --name-only HEAD 2>/dev/null | wc -l | tr -d ' ')
     fi
   fi
 
@@ -463,9 +573,17 @@ case "$SUBCOMMAND" in
     fi
     cmd_set "$@"
     ;;
+  transition)
+    if [ $# -lt 2 ]; then
+      red "Usage: comet-state.sh transition <change-name> <event>" >&2
+      red "Events: open-complete, design-complete, build-complete, verify-pass, verify-fail, archived" >&2
+      exit 1
+    fi
+    cmd_transition "$@"
+    ;;
   check)
     if [ $# -lt 2 ]; then
-      red "Usage: comet-state.sh check <phase> <change-name>" >&2
+      red "Usage: comet-state.sh check <change-name> <phase>" >&2
       red "Phases: open, design, build, verify, archive" >&2
       exit 1
     fi
@@ -487,7 +605,8 @@ case "$SUBCOMMAND" in
     echo "  init <change-name> <workflow>  — Initialize .comet.yaml with workflow defaults" >&2
     echo "  get <change-name> <field>       — Read a field value from .comet.yaml" >&2
     echo "  set <change-name> <field> <val> — Update a field value in .comet.yaml" >&2
-    echo "  check <phase> <change-name>    — Verify entry requirements for a phase" >&2
+    echo "  transition <change-name> <event> — Apply a validated state transition" >&2
+    echo "  check <change-name> <phase>    — Verify entry requirements for a phase" >&2
     echo "  scale <change-name>             — Assess and set verification mode based on metrics" >&2
     echo "" >&2
     echo "Workflows: full, hotfix, tweak" >&2

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

@@ -33,7 +33,11 @@ validate_change_name() {
 validate_change_name "$1"
 
 CHANGE="$1"
-YAML="openspec/changes/$CHANGE/.comet.yaml"
+CHANGE_DIR="openspec/changes/$CHANGE"
+if [ ! -d "$CHANGE_DIR" ] && [ -d "openspec/changes/archive/$CHANGE" ]; then
+  CHANGE_DIR="openspec/changes/archive/$CHANGE"
+fi
+YAML="$CHANGE_DIR/.comet.yaml"
 
 ERRORS=0
 WARNINGS=0
@@ -81,16 +85,18 @@ build_mode=$(field_value "build_mode")
 isolation=$(field_value "isolation")
 verify_mode=$(field_value "verify_mode")
 verify_result=$(field_value "verify_result")
+branch_status=$(field_value "branch_status")
 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 "phase"         "$phase"          "open design build verify archive"
 validate_enum "build_mode"    "$build_mode"     "subagent-driven-development executing-plans direct"
 validate_enum "isolation"     "$isolation"      "branch worktree"
 validate_enum "verify_mode"   "$verify_mode"    "light full"
 validate_enum "verify_result" "$verify_result"  "pending pass fail"
+validate_enum "branch_status" "$branch_status"  "pending handled"
 validate_enum "archived"      "$archived"       "true false"
 
 # --- Path validation ---
@@ -108,7 +114,7 @@ if [ -n "$plan" ] && [ "$plan" != "null" ]; then
 fi
 
 # --- Unknown keys check ---
-KNOWN_KEYS="workflow phase design_doc plan build_mode isolation verify_mode verify_result verified_at archived"
+KNOWN_KEYS="workflow phase design_doc plan build_mode isolation verify_mode verify_result verification_report branch_status verified_at archived"
 while IFS=: read -r key _; do
   key="${key// /}"
   [ -z "$key" ] && continue

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

@@ -18,7 +18,8 @@ description: "Comet Phase 5: Archive. Invoke with /comet-archive. Sync delta spe
 Execute entry verification:
 
 ```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)}"
 bash "$COMET_STATE" check <name> archive
 ```
 
@@ -29,7 +30,6 @@ Proceed to Step 1 after verification passes. The script outputs specific failure
 Run the archive script to automatically complete all steps:
 
 ```bash
-COMET_ARCHIVE="${COMET_ARCHIVE:-$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)}"
 bash "$COMET_ARCHIVE" "<change-name>"
 ```
 
@@ -39,7 +39,7 @@ The script automatically executes:
 3. Design doc frontmatter annotation (archived-with, status)
 4. Plan frontmatter annotation (archived-with)
 5. Move change to archive directory
-6. Update archived: true
+6. Update `archived: true` through `comet-state transition <archive-name> archived`
 
 If script returns non-zero exit code, report error and stop.
 If script returns zero exit code, archive is complete.
@@ -56,7 +56,10 @@ brainstorming → delta spec → implementation → verification → main spec o
 ## Exit Conditions
 
 - Archive script executed successfully (exit code 0)
-- **Phase guard**: Run `bash $COMET_GUARD <change-name> archive`, confirm archive complete after all PASS
+- Archive directory `openspec/changes/archive/YYYY-MM-DD-<change-name>/` exists
+- Archived `.comet.yaml` contains `archived: true`
+
+The archive script moves `openspec/changes/<name>/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`. After successful archive, do not run `bash "$COMET_GUARD" <change-name> archive` against the old active change name; the active directory no longer exists. Archive completeness is determined by the script exit code and archived directory state.
 
 ## Complete
 

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

@@ -1,6 +1,6 @@
 ---
 name: comet-build
-description: "Comet Phase 3: Plan and Build. Invoke with /comet-build. Create plans and execute implementation through subagent-driven-development."
+description: "Comet Phase 3: Plan and Build. Invoke with /comet-build. Create plans and choose execution method (subagent or direct) for implementation."
 ---
 
 # Comet Phase 3: Plan and Build (Build)
@@ -17,7 +17,9 @@ description: "Comet Phase 3: Plan and Build. Invoke with /comet-build. Create pl
 Execute entry verification:
 
 ```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> build
 ```
 
@@ -36,9 +38,16 @@ After the skill loads, follow its guidance to create a plan. Plan requirements:
 ---
 change: <openspec-change-name>
 design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
+base-ref: <git rev-parse HEAD before implementation>
 ---
 ```
 
+`base-ref` is used during verification to measure committed changes across the full implementation range. Record the current commit when creating the plan:
+
+```bash
+git rev-parse HEAD
+```
+
 ### 2. Update Plan Status
 
 Record plan path:
@@ -127,21 +136,27 @@ When the initial spec is found incomplete during implementation, handle by scale
 - Delta spec is a living document, can be modified at any time during this phase
 - Each update should be committed with commit message explaining the change reason
 - Do not sync to main spec in advance, sync uniformly during archiving
-- If incremental tasks exceed 50% of initial tasks.md total task count, consider splitting into new change
 - For small-scale incremental direct delta spec edits, note in commit message to facilitate design doc drift assessment during archiving
 
+### 6. Context Management
+
+Build is the longest phase and may span many tasks. To support resume after context compaction:
+
+- **After each task**: immediately check off tasks.md and commit code so `.comet.yaml` and file state are durable
+- **After context compaction**: read `.comet.yaml` to confirm the phase is still build, read the plan header `base-ref`, then read tasks.md to find the next unchecked task
+- **Long task split**: if a single task exceeds 200 lines of code changes, consider splitting it into multiple subtasks and commits
+
 ## Exit Conditions
 
 - All tasks.md checked
 - Code committed
-- Tests pass
-- `.comet.yaml` `phase` updated to `verify`
-- **Phase guard**: Run `bash $COMET_GUARD <change-name> build`, allow transition only after all PASS
+- Project-specific build/tests explicitly run and pass; do not rely only on guard auto-detection
+- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> build --apply`; after all PASS, state advances to `phase: verify`
 
 Before exit, run guard to auto-transition:
 
 ```bash
-bash $COMET_GUARD <change-name> build --apply
+bash "$COMET_GUARD" <change-name> build --apply
 ```
 
 State file is automatically updated to `phase: verify`, `verify_result: pending`.

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

@@ -17,7 +17,9 @@ description: "Comet Phase 2: Deep Design. Invoke with /comet-design. Produce Des
 Execute entry verification:
 
 ```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> design
 ```
 
@@ -57,32 +59,23 @@ Record design_doc path, then run guard to auto-transition:
 bash "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 
 # Auto-transition to next phase
-bash $COMET_GUARD <change-name> design --apply
+bash "$COMET_GUARD" <change-name> design --apply
 ```
 
 State file is updated automatically. No manual editing of other fields required.
 
-### 3. Dual Spec Division of Labor
-
-| Spec Type | Belongs To | Location | Definition |
-|-----------|-----------|----------|------------|
-| Capability specification | OpenSpec | `openspec/changes/<name>/specs/` | What the system should do (requirements + acceptance scenarios) |
-| Design document | Superpowers | `docs/superpowers/specs/` | How to build (technical architecture + implementation details) |
-
-### 4. Document Hierarchy Confirmation
-
-```
-proposal.md (Phase 1)              → Why + What
-design.md (Phase 1, OpenSpec)      → High-level architectural decisions
-Design document (Phase 2, Superpowers) → Deep technical design
-Capability specification (Phase 2, delta)  → Requirements + acceptance scenarios
-```
-
 ## Exit Conditions
 
 - Design Doc has been created and saved
 - Delta spec has been created if there are new capabilities
-- **Phase guard**: Run `bash $COMET_GUARD <change-name> design`, allow transition only after all PASS
+- `design_doc` written to `.comet.yaml`
+- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> design --apply`; after all PASS, state advances to `phase: build`
+
+You must use `--apply` before exiting:
+
+```bash
+bash "$COMET_GUARD" <change-name> design --apply
+```
 
 ## Automatic Transition
 

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

@@ -5,14 +5,12 @@ description: "Comet preset path: Bug fix / hotfix. Skip brainstorming, directly
 
 # Comet Preset Path: Hotfix
 
-Hotfix is a preset workflow of Comet's five-phase capabilities, not a separate parallel process. It reuses open, build, verify, archive capabilities, only skipping brainstorming and full plan.
-
-Applicable for bug fixes, hotfixes, small-scale behavior corrections. Does not involve new capability design, does not require deep brainstorming.
+Quick bug fix workflow: open → build → verify → archive. Skip brainstorming and full plan, applicable for behavior fixes not involving new capability design.
 
 **Applicable conditions** (all must be met):
 1. Fix bugs in existing functionality, no new capability
 2. No interface changes or architecture adjustments
-3. Change scope is predictable (usually < 5 files)
+3. Change scope is predictable (usually ≤ 2 files)
 
 **Not applicable**: If fix process discovers need for architecture adjustments, should upgrade to full `/comet` workflow.
 
@@ -20,19 +18,17 @@ Applicable for bug fixes, hotfixes, small-scale behavior corrections. Does not i
 
 ## Process (preset workflow, 4 phases)
 
-### 0. Entry State Verification (Entry Check)
+Execution chain: open → build → verify → archive. Hotfix provides default decisions for each phase: streamlined open, direct build, scale-based verification, archive after verification passes.
 
-Execute entry verification:
+Locate Comet scripts before starting:
 
 ```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)}"
 ```
 
-Proceed to process steps after verification passes. The script outputs specific failure reasons when verification fails.
-
-Execution chain: open → build → verify → archive. Hotfix provides default decisions for each phase: streamlined open, direct build, scale-based verification, archive after verification passes.
-
 ### 1. Quick Open (preset open)
 
 Reuse Comet open capability to create change, but use hotfix defaults: do not execute `openspec-explore` long exploration, directly enter streamlined change creation.
@@ -51,6 +47,12 @@ Initialize Comet state file:
 bash "$COMET_STATE" init <name> hotfix
 ```
 
+Run phase guard to transition open → build:
+
+```bash
+bash "$COMET_GUARD" <change-name> open --apply
+```
+
 ### 2. Direct Build (preset build)
 
 Use hotfix defaults: `build_mode: direct`. Skip `superpowers:brainstorming` and `superpowers:writing-plans` (unless tasks > 3; if exceeds 3 tasks, transfer to `/comet-build`'s plan and execution method selection).
@@ -64,30 +66,38 @@ Use hotfix defaults: `build_mode: direct`. Skip `superpowers:brainstorming` and
    - Run related tests to confirm pass
    - Check corresponding `- [ ]` to `- [x]` in tasks.md
    - Commit code, commit message format: `fix: <brief fix description>`
-3. After all tasks complete, enter verification
+3. After all tasks complete, explicitly run relevant project tests and build commands
+4. Run phase guard to transition build → verify:
+
+```bash
+bash "$COMET_GUARD" <change-name> build --apply
+```
+
+State automatically updates to `phase: verify`, `verify_result: pending`, then enter verification.
 
 **If fix affects existing spec acceptance scenarios**:
 - Create delta spec in `openspec/changes/<name>/specs/<capability>/spec.md`
 - Only include `## MODIFIED Requirements` section
 
-### 3. Verification (preset verify)
+### 3a. Hotfix-Exclusive Check: Root Cause Elimination
 
-Reuse `/comet-verify`, with comet-verify's scale assessment deciding lightweight or full verification.
+**Execute before loading comet-verify**, ensuring the fix actually eliminates the root cause:
 
-**Immediately execute:** Use the Skill tool to load the `comet-verify` skill. Skipping this step is prohibited.
+1. Read bug description and root cause in proposal.md
+2. Search and verify problem code no longer exists
+3. If root cause not eliminated, return to Step 2 to continue fix
 
-Small-scale hotfixes without delta spec usually meet lightweight verification conditions (≤ 3 tasks, ≤ 5 files), comet-verify's scale assessment will select lightweight verification path (5 quick checks). If hotfix created delta spec, enter full verification path according to comet-verify's scale assessment rules.
+**Upgrade conditions**:
+- Root cause check reveals deep architecture issues → Stop hotfix, upgrade to `/comet`
+- Fix requires additional interface changes → Stop hotfix, upgrade to `/comet`
 
-**Additional Hotfix-Exclusive Checks** (execute after comet-verify lightweight verification passes):
+### 3b. Verification (preset verify)
 
-1. **Root cause elimination**: Compare proposal.md's root cause analysis, confirm problem code eliminated
-   - Read bug description and root cause in proposal.md
-   - Search and verify problem code no longer exists
-   - If root cause not eliminated, return to Step 2 to continue fix
+After root cause elimination check passes, reuse `/comet-verify`, with comet-verify's scale assessment deciding lightweight or full verification.
 
-**Verification phase upgrade conditions**:
-- Regression testing reveals deep architecture issues → Stop hotfix, upgrade to `/comet`
-- Fix requires additional interface changes → Stop hotfix, upgrade to `/comet`
+**Immediately execute:** Use the Skill tool to load the `comet-verify` skill. Skipping this step is prohibited.
+
+Small-scale hotfixes without delta spec usually meet lightweight verification conditions (≤ 3 tasks, ≤ 2 files), comet-verify's scale assessment will select lightweight verification path (5 quick checks). If hotfix created delta spec, enter full verification path according to comet-verify's scale assessment rules.
 
 After verification passes, record `.comet.yaml` `verify_result` as `pass` according to `/comet-verify` rules, must not skip this status before archiving.
 
@@ -133,4 +143,4 @@ Upgrade method: On current change basis, supplement Design Doc (execute `/comet-
 - Bug fixed, tests pass
 - Change archived
 - If spec changes, synced to main spec
-- **Phase guard**: Before build → verify run `bash $COMET_GUARD <change-name> build`, before verify → archive run `bash $COMET_GUARD <change-name> verify`
+- **Phase guard**: Before build → verify run `bash "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `bash "$COMET_GUARD" <change-name> verify --apply`