@rpamis/comet 0.3.7 → 0.3.9

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

@@ -10,6 +10,7 @@
 #   check <change-name> <phase>    — Verify entry requirements for a phase
 #   check <change-name> <phase> --recover — Output structured recovery context for compaction resume
 #   scale <change-name>             — Assess and set verification mode based on metrics
+#   task-checkoff <file> <task-text> — Verify one unique task is checked
 #
 # Workflows: full, hotfix, tweak
 # Phases for check: open, design, build, verify, archive
@@ -234,6 +235,33 @@ project_auto_transition_default() {
   esac
 }
 
+project_review_mode_default() {
+  local value="null"
+  local source="default"
+  if [ -n "${COMET_REVIEW_MODE:-}" ]; then
+    value="$COMET_REVIEW_MODE"
+    source="COMET_REVIEW_MODE"
+  elif [ -f ".comet/config.yaml" ]; then
+    local raw
+    raw=$(yaml_field "review_mode" ".comet/config.yaml" 2>/dev/null || true)
+    if [ -n "$raw" ]; then
+      value="$raw"
+      source=".comet/config.yaml"
+    fi
+  fi
+
+  case "$value" in
+    null|off|standard|thorough)
+      printf '%s\n' "$value"
+      ;;
+    *)
+      red "ERROR: Invalid review_mode from ${source}: '$value'" >&2
+      red "Valid values: off, standard, thorough" >&2
+      exit 1
+      ;;
+  esac
+}
+
 # --- Subcommands ---
 
 cmd_init() {
@@ -257,7 +285,7 @@ cmd_init() {
   mkdir -p "$change_dir"
 
   # Set workflow-appropriate defaults
-  local phase build_mode isolation verify_mode context_compression auto_transition
+  local phase build_mode isolation verify_mode context_compression auto_transition review_mode
   phase="open"
   context_compression=$(project_context_compression)
   auto_transition="$(project_auto_transition_default)"
@@ -266,12 +294,14 @@ cmd_init() {
     full)
       build_mode="null"
       tdd_mode="null"
+      review_mode="$(project_review_mode_default)"
       isolation="null"
       verify_mode="null"
       ;;
     hotfix|tweak)
       build_mode="direct"
       tdd_mode="direct"
+      review_mode="off"
       isolation="branch"
       verify_mode="light"
       ;;
@@ -292,6 +322,7 @@ build_mode: $build_mode
 build_pause: null
 subagent_dispatch: null
 tdd_mode: $tdd_mode
+review_mode: $review_mode
 isolation: $isolation
 verify_mode: $verify_mode
 auto_transition: $auto_transition
@@ -352,16 +383,25 @@ cmd_set() {
   # Validate field name
   case "$field" in
     phase)
-      yellow "WARNING: Setting 'phase' directly bypasses state machine constraints." >&2
-      yellow "  Consider using: comet-state.sh transition <change-name> <event>" >&2
+      # Direct phase writes bypass state-machine evidence checks (open artifacts,
+      # design_doc, build decisions, verification evidence). Block them unless the
+      # call originates from cmd_transition (dynamic-scope flag) or the operator
+      # explicitly opts into the repair escape hatch.
+      if [ "${_COMET_IN_TRANSITION:-}" != "1" ] && [ "${COMET_FORCE_PHASE:-}" != "1" ]; then
+        red "ERROR: Setting 'phase' directly is not allowed; it bypasses state machine evidence checks." >&2
+        red "  Use: comet-state.sh transition <change-name> <event>" >&2
+        red "  Repair-only escape hatch: COMET_FORCE_PHASE=1 comet-state.sh set <change-name> phase <value>" >&2
+        exit 1
+      fi
+      validate_enum "$value" "open" "design" "build" "verify" "archive"
       ;;
-    workflow|context_compression|build_mode|build_pause|subagent_dispatch|tdd_mode|isolation|verify_mode|auto_transition|verify_result|verification_report|branch_status|archived|design_doc|plan|verified_at|created_at|direct_override|build_command|verify_command|handoff_context|handoff_hash|base_ref)
+    workflow|context_compression|build_mode|build_pause|subagent_dispatch|tdd_mode|review_mode|isolation|verify_mode|auto_transition|verify_result|verification_report|branch_status|archived|design_doc|plan|verified_at|created_at|direct_override|build_command|verify_command|handoff_context|handoff_hash|base_ref)
       # Valid field
       ;;
     *)
       red "ERROR: Unknown field: '$field'" >&2
       red "Valid fields:" >&2
-      red "  workflow, phase, context_compression, design_doc, plan, build_mode, build_pause, subagent_dispatch, tdd_mode, isolation," >&2
+      red "  workflow, phase, context_compression, design_doc, plan, build_mode, build_pause, subagent_dispatch, tdd_mode, review_mode, isolation," >&2
       red "  verify_mode, auto_transition, verify_result, verification_report, branch_status," >&2
       red "  verified_at, created_at, archived, base_ref, direct_override," >&2
       red "  build_command, verify_command, handoff_context, handoff_hash" >&2
@@ -392,6 +432,9 @@ cmd_set() {
     tdd_mode)
       validate_enum "$value" "tdd" "direct"
       ;;
+    review_mode)
+      validate_enum "$value" "off" "standard" "thorough"
+      ;;
     isolation)
       validate_enum "$value" "branch" "worktree"
       ;;
@@ -443,6 +486,33 @@ require_phase() {
   fi
 }
 
+require_open_artifacts() {
+  local change_name="$1"
+  local change_dir workflow f
+  change_dir=$(change_dir_for "$change_name")
+  workflow=$(cmd_get "$change_name" "workflow")
+  for f in proposal.md tasks.md; do
+    if [ ! -s "$change_dir/$f" ]; then
+      red "ERROR: Cannot transition '$change_name': $f must exist and be non-empty before leaving open" >&2
+      exit 1
+    fi
+  done
+  if [ "$workflow" = "full" ] && [ ! -s "$change_dir/design.md" ]; then
+    red "ERROR: Cannot transition '$change_name': design.md must exist and be non-empty before leaving open" >&2
+    exit 1
+  fi
+}
+
+require_design_evidence() {
+  local change_name="$1"
+  local design_doc
+  design_doc=$(cmd_get "$change_name" "design_doc")
+  if [ -z "$design_doc" ] || [ "$design_doc" = "null" ] || [ ! -s "$design_doc" ]; then
+    red "ERROR: Cannot transition '$change_name': design_doc must point to an existing Design Doc before leaving design" >&2
+    exit 1
+  fi
+}
+
 require_verification_evidence() {
   local change_name="$1"
   local report branch_status
@@ -462,13 +532,14 @@ require_verification_evidence() {
 
 require_build_decisions() {
   local change_name="$1"
-  local workflow build_mode isolation direct_override subagent_dispatch tdd_mode
+  local workflow build_mode isolation direct_override subagent_dispatch tdd_mode review_mode
   workflow=$(cmd_get "$change_name" "workflow")
   build_mode=$(cmd_get "$change_name" "build_mode")
   isolation=$(cmd_get "$change_name" "isolation")
   direct_override=$(cmd_get "$change_name" "direct_override" 2>/dev/null || true)
   subagent_dispatch=$(cmd_get "$change_name" "subagent_dispatch" 2>/dev/null || true)
   tdd_mode=$(cmd_get "$change_name" "tdd_mode" 2>/dev/null || true)
+  review_mode=$(cmd_get "$change_name" "review_mode" 2>/dev/null || true)
 
   case "$isolation" in
     branch|worktree) ;;
@@ -500,11 +571,24 @@ require_build_decisions() {
     red "ERROR: Cannot transition '$change_name': tdd_mode must be selected before leaving build (full workflow)" >&2
     exit 1
   fi
+
+  if [ "$workflow" = "full" ]; then
+    case "$review_mode" in
+      off|standard|thorough) ;;
+      *)
+        red "ERROR: Cannot transition '$change_name': review_mode must be selected before leaving build (full workflow); review_mode must be off, standard, or thorough, got '${review_mode:-null}'" >&2
+        exit 1
+        ;;
+    esac
+  fi
 }
 
 cmd_transition() {
   local change_name="$1"
   local event="$2"
+  # Dynamic-scope flag: authorizes the internal cmd_set phase writes below while
+  # still blocking direct `set <name> phase` from the CLI.
+  local _COMET_IN_TRANSITION=1
 
   validate_change_name "$change_name"
   validate_enum "$event" "open-complete" "design-complete" "build-complete" "verify-pass" "verify-fail" "archive-reopen" "archived"
@@ -512,6 +596,7 @@ cmd_transition() {
   case "$event" in
     open-complete)
       require_phase "$change_name" "open"
+      require_open_artifacts "$change_name"
       local workflow
       workflow=$(cmd_get "$change_name" "workflow")
       if [ "$workflow" = "full" ]; then
@@ -522,6 +607,7 @@ cmd_transition() {
       ;;
     design-complete)
       require_phase "$change_name" "design"
+      require_design_evidence "$change_name"
       cmd_set "$change_name" phase build
       ;;
     build-complete)
@@ -565,6 +651,12 @@ cmd_transition() {
       ;;
     archived)
       require_phase "$change_name" "archive"
+      local archived_verify_result
+      archived_verify_result=$(cmd_get "$change_name" "verify_result")
+      if [ "$archived_verify_result" != "pass" ]; then
+        red "ERROR: Cannot transition '$change_name': verify_result must be pass before archiving" >&2
+        exit 1
+      fi
       cmd_set "$change_name" archived true
       ;;
   esac
@@ -771,7 +863,7 @@ cmd_recover() {
 
   # Read all relevant fields
   local design_doc plan verify_result verify_mode verification_report
-  local branch_status handoff_context handoff_hash isolation build_mode build_pause subagent_dispatch tdd_mode direct_override
+  local branch_status handoff_context handoff_hash isolation build_mode build_pause subagent_dispatch tdd_mode review_mode direct_override
   design_doc=$(cmd_get "$change_name" "design_doc")
   plan=$(cmd_get "$change_name" "plan")
   verify_result=$(cmd_get "$change_name" "verify_result")
@@ -785,6 +877,7 @@ cmd_recover() {
   build_pause=$(cmd_get "$change_name" "build_pause" 2>/dev/null || true)
   subagent_dispatch=$(cmd_get "$change_name" "subagent_dispatch" 2>/dev/null || true)
   tdd_mode=$(cmd_get "$change_name" "tdd_mode" 2>/dev/null || true)
+  review_mode=$(cmd_get "$change_name" "review_mode" 2>/dev/null || true)
   direct_override=$(cmd_get "$change_name" "direct_override" 2>/dev/null || true)
 
   echo "State fields:"
@@ -840,6 +933,7 @@ cmd_recover() {
       field_status "build_mode" "$build_mode"
       field_status "build_pause" "$build_pause"
       field_status "tdd_mode" "$tdd_mode"
+      field_status "review_mode" "$review_mode"
       if [ "$build_mode" = "subagent-driven-development" ] || { [ -n "$subagent_dispatch" ] && [ "$subagent_dispatch" != "null" ]; }; then
         field_status "subagent_dispatch" "$subagent_dispatch"
       fi
@@ -1024,6 +1118,59 @@ cmd_scale() {
   green "[SCALE] verify_mode=$result"
 }
 
+cmd_task_checkoff() {
+  local task_file="$1"
+  local task_text="$2"
+
+  validate_path_field "$task_file" "task file"
+
+  if [ -z "$task_text" ]; then
+    red "ERROR: Task text cannot be empty" >&2
+    exit 1
+  fi
+
+  if [ ! -f "$task_file" ]; then
+    red "ERROR: Task file not found: $task_file" >&2
+    exit 1
+  fi
+
+  local counts
+  counts=$(TASK_TEXT="$task_text" awk '
+    BEGIN {
+      task = ENVIRON["TASK_TEXT"]
+    }
+    {
+      sub(/\r$/, "")
+      if ($0 == "- [ ] " task || $0 == "- [x] " task || $0 == "- [X] " task) {
+        total++
+      }
+      if ($0 == "- [x] " task || $0 == "- [X] " task) {
+        checked++
+      }
+    }
+    END {
+      printf "%d %d\n", total + 0, checked + 0
+    }
+  ' "$task_file")
+
+  local total="${counts%% *}"
+  local checked="${counts##* }"
+
+  if [ "$total" -ne 1 ]; then
+    red "ERROR: task text must appear exactly once in $task_file (found $total): $task_text" >&2
+    exit 1
+  fi
+
+  if [ "$checked" -ne 1 ]; then
+    red "ERROR: task is not checked in $task_file: $task_text" >&2
+    exit 1
+  fi
+
+  echo "TASK_CHECKOFF: PASS"
+  echo "FILE: $task_file"
+  echo "TASK: $task_text"
+}
+
 # Resolve the next workflow step after a guard --apply phase advance.
 # Reads the (already advanced) phase, workflow, and auto_transition, then emits
 # a deterministic next-step contract so skills don't hardcode the next skill name.
@@ -1155,6 +1302,13 @@ case "$SUBCOMMAND" in
     fi
     cmd_scale "$@"
     ;;
+  task-checkoff)
+    if [ $# -lt 2 ]; then
+      red "Usage: comet-state.sh task-checkoff <file> <task-text>" >&2
+      exit 1
+    fi
+    cmd_task_checkoff "$@"
+    ;;
   next)
     if [ $# -lt 1 ]; then
       red "Usage: comet-state.sh next <change-name>" >&2
@@ -1174,6 +1328,7 @@ case "$SUBCOMMAND" in
     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 "  task-checkoff <file> <task-text> — Verify one unique task is checked" >&2
     echo "  next <change-name>              — Resolve the next workflow step (auto/manual/done)" >&2
     echo "" >&2
     echo "Workflows: full, hotfix, tweak" >&2

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

@@ -143,6 +143,7 @@ build_mode=$(field_value "build_mode")
 build_pause=$(field_value "build_pause")
 subagent_dispatch=$(field_value "subagent_dispatch")
 tdd_mode=$(field_value "tdd_mode")
+review_mode=$(field_value "review_mode")
 isolation=$(field_value "isolation")
 verify_mode=$(field_value "verify_mode")
 auto_transition=$(field_value "auto_transition")
@@ -162,6 +163,7 @@ validate_enum "build_mode"    "$build_mode"     "subagent-driven-development exe
 validate_enum "build_pause"   "$build_pause"     "null plan-ready"
 validate_enum "subagent_dispatch" "$subagent_dispatch" "null confirmed"
 validate_enum "tdd_mode"      "$tdd_mode"       "tdd direct null"
+validate_enum "review_mode"   "$review_mode"    "off standard thorough"
 validate_enum "isolation"     "$isolation"      "branch worktree"
 validate_enum "verify_mode"   "$verify_mode"    "light full"
 if grep -q "^auto_transition:" "$YAML" 2>/dev/null; then
@@ -199,7 +201,7 @@ if [ -n "$handoff_hash" ] && [ "$handoff_hash" != "null" ]; then
 fi
 
 # --- Unknown keys check ---
-KNOWN_KEYS="workflow phase context_compression design_doc plan build_mode build_pause subagent_dispatch tdd_mode isolation verify_mode auto_transition verify_result verification_report branch_status verified_at created_at archived direct_override build_command verify_command handoff_context handoff_hash base_ref"
+KNOWN_KEYS="workflow phase context_compression design_doc plan build_mode build_pause subagent_dispatch tdd_mode review_mode isolation verify_mode auto_transition verify_result verification_report branch_status verified_at created_at archived direct_override build_command verify_command handoff_context handoff_hash base_ref"
 while IFS=: read -r key _; do
   key="${key// /}"
   [ -z "$key" ] && continue

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

@@ -1,106 +1,100 @@
----
-name: comet-archive
-description: "Comet Phase 5: Archive. Invoke with /comet-archive. Merge delta specs into main specs with OpenSpec semantics, archive change."
----
-
-# Comet Phase 5: Archive (Archive)
-
-## Prerequisites
-
-- Verification passed (Phase 4 complete)
-- Branch handled
-- `verify_result: pass` in `openspec/changes/<name>/.comet.yaml`
-
-## Steps
-
-### 0. Output Language Constraint
-
-Archive summaries and lifecycle closure notes must use the language of the user request that triggered this workflow.
-
-### 0. Entry State Verification (Entry Check)
-
-Execute entry verification:
-
-```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
-if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
-  return 1
-fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <name> archive
-```
-
-Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
-
-### 1. Final Archive Confirmation (Blocking Point)
-
-After entry verification passes, **must use the current platform's available user input/confirmation mechanism to pause and wait for the user to confirm whether to archive immediately**. Must not run `"$COMET_BASH" "$COMET_ARCHIVE" "<change-name>"` before user confirmation. If the current platform has no structured question tool, ask an equivalent single-select question in the conversation, stop the workflow, and wait for the user's reply before continuing.
-
-Before confirmation, show the user a brief summary:
-- Change name
-- Verification report path and result
-- Branch handling status
-- Irreversible actions this archive will perform: merge main specs with OpenSpec delta semantics, annotate design doc / plan, and move the change to the archive directory
-
-The user confirmation question must be presented as a single-select question with these options:
-- "Confirm archive" — immediately run the archive script to complete spec merge and change movement
-- "Needs adjustment or re-verification" — do not archive; run `"$COMET_BASH" "$COMET_STATE" transition <change-name> archive-reopen` to return to `phase: verify`, then invoke `/comet-verify`. If verification confirms fixes are needed, follow `/comet-verify`'s verification-failure decision flow back to `/comet-build`
-- "Do not archive yet" — do not archive; keep the current `phase: archive` state and wait for the user to invoke `/comet-archive` again later
-
-Only after the user selects "Confirm archive" may Step 2 continue. After the user selects "Needs adjustment or re-verification", must first run the `archive-reopen` state transition; do not edit `.comet.yaml` manually.
-
-### 2. Execute Archive
-
-Run the archive script to automatically complete all steps:
-
-```bash
-"$COMET_BASH" "$COMET_ARCHIVE" "<change-name>"
-```
-
-The script automatically executes:
-1. Entry state validation (phase=archive, verify_result=pass, archived=false)
-2. Design doc frontmatter annotation (archived-with, status)
-3. Plan frontmatter annotation (archived-with)
-4. OpenSpec archive for delta-merge semantics and moving the change to the archive directory
-5. Main spec guard against leaked delta-only section headings
-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.
-The summary `X/Y steps succeeded` counts real executed steps and does not double-count delta spec sync or document annotation.
-
-The script calls OpenSpec archive to merge `ADDED/MODIFIED/REMOVED/RENAMED` delta semantics into main specs, then verifies main specs do not contain delta-only section headings.
-
-Use `--dry-run` flag to preview without executing.
-
-### 3. Lifecycle Closed Loop
-
-Spec lifecycle completes here:
-```
-brainstorming → delta spec → implementation → verification → main spec merge → design doc annotation → archive
-```
-
-## Exit Conditions
-
-- Archive script executed successfully (exit code 0)
-- 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>/`.
-
-> **WARNING**: After successful archive, **do not run** `"$COMET_BASH" "$COMET_GUARD" <change-name> archive` against the old active change name; the active directory no longer exists. Doing so will cause the guard to error with "change directory not found". Archive completeness is determined by script exit code and archived directory state.
-
-## Complete
-
-Comet workflow complete. To start new work, invoke `/comet` or `/comet-open`.
-
-## Context Compaction Recovery
-
-The archive phase may trigger context compaction during execution. On resume, first run:
-
-```bash
-"$COMET_BASH" "$COMET_STATE" check <change-name> archive --recover
-```
-
-The script outputs structured recovery context (archive status, completed steps). Follow the Recovery action to determine next steps. If `archived: true` and the archive directory exists, archiving is already complete — no need to run the archive operation again.
+---
+name: comet-archive
+description: "Comet Phase 5: Archive. Invoke with /comet-archive. Merge delta specs into main specs with OpenSpec semantics, archive change."
+---
+
+# Comet Phase 5: Archive (Archive)
+
+## Prerequisites
+
+- Verification passed (Phase 4 complete)
+- Branch handled
+- `verify_result: pass` in `openspec/changes/<name>/.comet.yaml`
+
+## Steps
+
+### 0. Output Language Constraint
+
+Archive summaries and lifecycle closure notes must use the language of the user request that triggered this workflow.
+
+### 0. Entry State Verification (Entry Check)
+
+Execute entry verification:
+
+```bash
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$COMET_ENV" ]; then
+  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+. "$COMET_ENV"
+"$COMET_BASH" "$COMET_STATE" check <name> archive
+```
+
+Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
+
+### 1. Final Archive Confirmation (Blocking Point)
+
+After entry verification passes, **must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to confirm whether to archive immediately**. Must not run `"$COMET_BASH" "$COMET_ARCHIVE" "<change-name>"` before user confirmation.
+
+Before confirmation, show the user a brief summary:
+- Change name
+- Verification report path and result
+- Branch handling status
+- Irreversible actions this archive will perform: merge main specs with OpenSpec delta semantics, annotate design doc / plan, and move the change to the archive directory
+
+The user confirmation question must be presented as a single-select question with these options:
+- "Confirm archive" — immediately run the archive script to complete spec merge and change movement
+- "Needs adjustment or re-verification" — do not archive; run `"$COMET_BASH" "$COMET_STATE" transition <change-name> archive-reopen` to return to `phase: verify`, then invoke `/comet-verify`. If verification confirms fixes are needed, follow `/comet-verify`'s verification-failure decision flow back to `/comet-build`
+- "Do not archive yet" — do not archive; keep the current `phase: archive` state and wait for the user to invoke `/comet-archive` again later
+
+Only after the user selects "Confirm archive" may Step 2 continue. After the user selects "Needs adjustment or re-verification", must first run the `archive-reopen` state transition; do not edit `.comet.yaml` manually.
+
+### 2. Execute Archive
+
+Run the archive script to automatically complete all steps:
+
+```bash
+"$COMET_BASH" "$COMET_ARCHIVE" "<change-name>"
+```
+
+The script automatically executes:
+1. Entry state validation (phase=archive, verify_result=pass, archived=false)
+2. Design doc frontmatter annotation (archived-with, status)
+3. Plan frontmatter annotation (archived-with)
+4. OpenSpec archive for delta-merge semantics and moving the change to the archive directory
+5. Main spec guard against leaked delta-only section headings
+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.
+The summary `X/Y steps succeeded` counts real executed steps and does not double-count delta spec sync or document annotation.
+
+The script calls OpenSpec archive to merge `ADDED/MODIFIED/REMOVED/RENAMED` delta semantics into main specs, then verifies main specs do not contain delta-only section headings.
+
+Use `--dry-run` flag to preview without executing.
+
+### 3. Lifecycle Closed Loop
+
+Spec lifecycle completes here:
+```
+brainstorming → delta spec → implementation → verification → main spec merge → design doc annotation → archive
+```
+
+## Exit Conditions
+
+- Archive script executed successfully (exit code 0)
+- 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>/`.
+
+> **WARNING**: After successful archive, **do not run** `"$COMET_BASH" "$COMET_GUARD" <change-name> archive` against the old active change name; the active directory no longer exists. Doing so will cause the guard to error with "change directory not found". Archive completeness is determined by script exit code and archived directory state.
+
+## Complete
+
+Comet workflow complete. To start new work, invoke `/comet` or `/comet-open`.
+
+## Context Compression Recovery
+
+Follow `comet/reference/context-recovery.md` with phase set to `archive`. If `archived: true` and archive directory exists, archival is complete — do not re-execute archive operations.