@rpamis/comet 0.1.6 → 0.1.8

package/README.md

@@ -90,12 +90,14 @@ 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
+### Guard & Automation Scripts
 
 | Script | Purpose |
 |--------|---------|
-| `comet-guard.sh` | Phase transition guard — validates exit conditions before phase transitions |
+| `comet-guard.sh` | Phase transition guard — validates exit conditions, `--apply` auto-updates `.comet.yaml` |
+| `comet-archive.sh` | One-command archive — validates state, syncs specs, moves to archive, updates status |
 | `comet-yaml-validate.sh` | Schema validator — validates `.comet.yaml` structure and field values |
+| `comet-state.sh` | Unified state management — init/set/get/check/scale, agents' exclusive YAML interface |
 
 ### OpenSpec Skills
 
@@ -153,28 +155,37 @@ Comet uses a decoupled state architecture with separate YAML files:
 - `design_doc`: Path to Superpowers Design Doc
 - `plan`: Path to implementation plan
 - `build_mode`: `subagent-driven-development`, `executing-plans`, or `direct`
+- `isolation`: `branch` or `worktree`, workspace isolation method
 - `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:
+Comet ensures agent execution reliability through automated state transitions:
 
 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
+2. **Automated State Transitions** — `comet-guard.sh --apply` updates `.comet.yaml` automatically
+   - All phase transitions (design → build → verify → archive) use `guard --apply`
+   - No manual state editing required — eliminates write-verification errors
+   - `comet-state.sh` is the agents' exclusive interface for state operations
+   - Guard and archive scripts use `comet-state.sh` internally for state management
 
 3. **Schema Validation** — `comet-yaml-validate.sh` ensures data integrity
-   - Validates required fields (9 fields)
-   - Validates enum values (6 enum types)
+   - Validates required fields (10 fields)
+   - Validates enum values (7 enum types)
    - Validates referenced file paths exist
    - Detects unknown/typos fields
 
+4. **Archive Automation** — `comet-archive.sh` handles the full archive flow in one command
+   - Validates entry state, syncs delta specs to main specs
+   - Annotates design doc and plan frontmatter
+   - Moves change to archive directory and updates `archived: true`
+   - Supports `--dry-run` for preview
+
 **Security**: Path traversal protection on all change name inputs
 
 ## Project Structure
@@ -184,8 +195,10 @@ 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-guard.sh       # Phase transition guard (--apply auto-updates state)
+│   │       ├── comet-archive.sh     # One-command archive automation
+│   │       ├── comet-yaml-validate.sh # Schema validator
+│   │       └── comet-state.sh       # Unified state management (init/set/get/check/scale)
 │   ├── comet-*/SKILL.md
 │   ├── openspec-*/SKILL.md
 │   └── brainstorming/SKILL.md
@@ -208,7 +221,7 @@ your-project/
 
 ```bash
 # Clone
-git clone https://github.com/benym/comet.git
+git clone https://github.com/rpamis/comet
 cd comet
 
 # Install dependencies

package/assets/skills/comet/SKILL.md

@@ -161,7 +161,7 @@ If metadata conflicts with file state, use verifiable file state as source of tr
 
 ### Script Location
 
-Comet phase guard script `comet-guard.sh` is distributed with the skill package, located in `comet/scripts/` directory.
+Comet phase guard script `comet-guard.sh` and archive script `comet-archive.sh` are distributed with the skill package, located in `comet/scripts/` directory.
 **Do not hardcode platform paths**, self-locate at runtime with:
 
 ```bash
@@ -169,6 +169,19 @@ COMET_GUARD=$(find . -path '*/comet/scripts/comet-guard.sh' -type f -print -quit
 bash "$COMET_GUARD" <change-name> <phase>
 ```
 
+**Auto state update**: Guard supports `--apply` flag, automatically updating `.comet.yaml` state fields after checks pass:
+
+```bash
+bash "$COMET_GUARD" <change-name> <phase> --apply
+```
+
+**Archive script**: Complete all archive steps in one command:
+
+```bash
+COMET_ARCHIVE=$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)
+bash "$COMET_ARCHIVE" <change-name>
+```
+
 In subsequent documentation, `bash $COMET_GUARD <change> <phase>` refers to this command. After loading comet, agents should cache `COMET_GUARD` path in shell environment to avoid repeated `find`.
 
 ### File Structure
@@ -185,7 +198,7 @@ openspec/                              # OpenSpec — WHAT
 │   │   ├── specs/<capability>/spec.md # Delta capability spec
 │   │   └── tasks.md                   # Task checklist
 │   └── archive/YYYY-MM-DD-<name>/     # Archived
-└── specs/<capability>/spec.md         # Main specs (sync from delta at archive)
+└── specs/<capability>/spec.md         # Main specs (overwritten from delta at archive)
 
 docs/superpowers/                      # Superpowers — HOW
 ├── specs/YYYY-MM-DD-<topic>-design.md # Design doc (technical RFC, mark status at archive)
@@ -202,5 +215,5 @@ docs/superpowers/                      # Superpowers — HOW
 6. **Classify incremental updates** — Small edits, medium brainstorming, large new changes
 7. **Plan must associate with change** — File header contains `change:` and `design-doc:` metadata
 8. **Archive closure** — design doc and plan must mark `archived-with` status
-9. **Incremental modification of existing features** — Create delta spec baseline based on main spec, not from scratch
+9. **Modifying existing features** — Just open a new change; brainstorming reads existing specs as context naturally
 10. **Preset has limits** — Switch to full workflow promptly when hotfix/tweak meet upgrade conditions

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

@@ -0,0 +1,258 @@
+#!/bin/bash
+# Comet Archive — automates the archive phase in one command
+# Usage: comet-archive.sh <change-name> [--dry-run]
+# Exit 0 = archive complete, exit 1 = fatal error
+
+set -euo pipefail
+
+red() { echo -e "\033[31m$1\033[0m" >&2; }
+green() { echo -e "\033[32m$1\033[0m" >&2; }
+yellow() { echo -e "\033[33m$1\033[0m" >&2; }
+
+DRY_RUN=0
+if [[ "${2:-}" == "--dry-run" ]]; then
+  DRY_RUN=1
+fi
+
+# Input validation
+validate_change_name() {
+  local name="$1"
+  if [ -z "$name" ]; then
+    red "FATAL: Change name cannot be empty"
+    exit 1
+  fi
+  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+    red "FATAL: Invalid change name: '$name'"
+    red "Valid characters: a-z, A-Z, 0-9, -, _"
+    exit 1
+  fi
+  if [[ "$name" =~ \.\. ]]; then
+    red "FATAL: Change name cannot contain '..'"
+    exit 1
+  fi
+}
+
+CHANGE="$1"
+validate_change_name "$CHANGE"
+
+CHANGE_DIR="openspec/changes/$CHANGE"
+YAML="$CHANGE_DIR/.comet.yaml"
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")" 2>/dev/null || dirname "$0")" && pwd)"
+STATE_SH="$SCRIPT_DIR/comet-state.sh"
+TODAY=$(date +%Y-%m-%d)
+ARCHIVE_NAME="${TODAY}-${CHANGE}"
+ARCHIVE_DIR="openspec/changes/archive/${ARCHIVE_NAME}"
+
+STEPS_OK=0
+STEPS_TOTAL=0
+
+step_ok() {
+  green "  [OK] $1"
+  STEPS_OK=$((STEPS_OK + 1))
+  STEPS_TOTAL=$((STEPS_TOTAL + 1))
+}
+
+step_fail() {
+  red "  [FAIL] $1"
+  STEPS_TOTAL=$((STEPS_TOTAL + 1))
+}
+
+echo "=== Comet Archive: $CHANGE ===" >&2
+
+# --- Step 1: Read .comet.yaml, extract paths ---
+
+yaml_field() {
+  local field="$1"
+  if [ -f "$STATE_SH" ]; then
+    bash "$STATE_SH" get "$CHANGE" "$field" 2>/dev/null
+  else
+    if [ -f "$YAML" ]; then
+      grep "^${field}:" "$YAML" | sed "s/^${field}: *//" | tr -d '"' | tr -d "'"
+    fi
+  fi
+}
+
+if [ ! -f "$YAML" ]; then
+  red "FATAL: .comet.yaml not found in $CHANGE_DIR/"
+  exit 1
+fi
+
+DESIGN_DOC=$(yaml_field "design_doc")
+PLAN_PATH=$(yaml_field "plan")
+
+# --- Step 2: Validate entry state ---
+
+PHASE_VAL=$(yaml_field "phase")
+VERIFY_VAL=$(yaml_field "verify_result")
+ARCHIVED_VAL=$(yaml_field "archived")
+
+if [ "$PHASE_VAL" != "archive" ]; then
+  red "FATAL: phase is '$PHASE_VAL', expected 'archive'"
+  exit 1
+fi
+
+if [ "$VERIFY_VAL" != "pass" ]; then
+  red "FATAL: verify_result is '$VERIFY_VAL', expected 'pass'. Run comet-verify first."
+  exit 1
+fi
+
+if [ "$ARCHIVED_VAL" = "true" ]; then
+  red "FATAL: change already archived"
+  exit 1
+fi
+
+step_ok "Entry state verified"
+
+# --- Step 3: Check archive target ---
+
+if [ -d "$ARCHIVE_DIR" ]; then
+  red "FATAL: archive target already exists: $ARCHIVE_DIR"
+  exit 1
+fi
+
+step_ok "Archive target available"
+
+# --- Step 4: Sync delta specs → main specs ---
+
+sync_delta_specs() {
+  local delta_root="$CHANGE_DIR/specs"
+  if [ ! -d "$delta_root" ]; then
+    return 0
+  fi
+
+  for delta_spec_dir in "$delta_root"/*/; do
+    [ -d "$delta_spec_dir" ] || continue
+    local capability
+    capability=$(basename "$delta_spec_dir")
+    local delta_spec="$delta_spec_dir/spec.md"
+    local main_spec="openspec/specs/$capability/spec.md"
+
+    if [ ! -f "$delta_spec" ]; then
+      continue
+    fi
+
+    STEPS_TOTAL=$((STEPS_TOTAL + 1))
+
+    if [ "$DRY_RUN" -eq 1 ]; then
+      yellow "  [DRY-RUN] Would sync: $capability → $main_spec"
+      STEPS_OK=$((STEPS_OK + 1))
+      continue
+    fi
+
+    if [ ! -f "$main_spec" ]; then
+      mkdir -p "openspec/specs/$capability"
+    fi
+    cp "$delta_spec" "$main_spec"
+
+    step_ok "Delta spec synced: $capability → openspec/specs/$capability/spec.md"
+  done
+}
+
+sync_delta_specs
+
+# --- Step 5: Annotate design doc frontmatter ---
+
+annotate_frontmatter() {
+  local file="$1"
+  local extra_fields="$2"
+
+  if [ ! -f "$file" ]; then
+    return 0
+  fi
+
+  STEPS_TOTAL=$((STEPS_TOTAL + 1))
+
+  if [ "$DRY_RUN" -eq 1 ]; then
+    yellow "  [DRY-RUN] Would annotate: $file"
+    STEPS_OK=$((STEPS_OK + 1))
+    return 0
+  fi
+
+  if head -1 "$file" | grep -q '^---'; then
+    local tmp_file
+    tmp_file=$(mktemp)
+    awk -v archive="$ARCHIVE_NAME" -v extra="$extra_fields" '
+      /^archived-with:/ { next }
+      NR==1 && /^---/ { print; next }
+      /^---/ && NR>1 {
+        print "archived-with: " archive
+        if (extra != "") print extra
+        print; next
+      }
+      { print }
+    ' "$file" > "$tmp_file"
+    mv "$tmp_file" "$file"
+  else
+    local tmp_file
+    tmp_file=$(mktemp)
+    {
+      echo "---"
+      echo "archived-with: $ARCHIVE_NAME"
+      if [ -n "$extra_fields" ]; then
+        echo "$extra_fields"
+      fi
+      echo "status: final"
+      echo "---"
+      cat "$file"
+    } > "$tmp_file"
+    mv "$tmp_file" "$file"
+  fi
+
+  step_ok "Annotated: $file"
+}
+
+if [ -n "$DESIGN_DOC" ] && [ "$DESIGN_DOC" != "null" ]; then
+  annotate_frontmatter "$DESIGN_DOC" "status: final"
+fi
+
+# --- Step 6: Annotate plan frontmatter ---
+
+if [ -n "$PLAN_PATH" ] && [ "$PLAN_PATH" != "null" ]; then
+  annotate_frontmatter "$PLAN_PATH" ""
+fi
+
+# --- Step 7: Move change to archive ---
+
+STEPS_TOTAL=$((STEPS_TOTAL + 1))
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  yellow "  [DRY-RUN] Would move: $CHANGE_DIR → $ARCHIVE_DIR"
+  STEPS_OK=$((STEPS_OK + 1))
+else
+  mkdir -p "openspec/changes/archive"
+  mv "$CHANGE_DIR" "$ARCHIVE_DIR"
+  step_ok "Moved to: $ARCHIVE_DIR"
+fi
+
+# --- Step 8: Update archived: true in .comet.yaml ---
+
+STEPS_TOTAL=$((STEPS_TOTAL + 1))
+
+ARCHIVE_YAML="$ARCHIVE_DIR/.comet.yaml"
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  yellow "  [DRY-RUN] Would set archived: true in $ARCHIVE_YAML"
+  STEPS_OK=$((STEPS_OK + 1))
+else
+  if [ -f "$ARCHIVE_YAML" ]; then
+    sed -i 's/^archived:.*/archived: true/' "$ARCHIVE_YAML"
+    step_ok "archived: true"
+  else
+    step_fail "archived: true (.comet.yaml not found after move)"
+  fi
+fi
+
+# --- Step 9: Print summary ---
+
+echo "" >&2
+if [ "$DRY_RUN" -eq 1 ]; then
+  yellow "Dry run complete. $STEPS_OK/$STEPS_TOTAL steps would succeed."
+else
+  green "Archive complete. $STEPS_OK/$STEPS_TOTAL steps succeeded."
+fi
+
+if [ "$STEPS_OK" -lt "$STEPS_TOTAL" ]; then
+  exit 1
+fi
+
+exit 0

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

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Comet Phase Guard — validates exit conditions before phase transitions
-# Usage: comet-guard.sh <change-name> <from-phase>
+# Usage: comet-guard.sh <change-name> <current-phase> [--apply]
 # Phases: open, design, build, verify, archive
 # Exit 0 = all checks pass, exit 1 = blocked (reasons printed to stderr)
 
@@ -35,6 +35,10 @@ validate_change_name "$1"
 
 CHANGE="$1"
 PHASE="$2"
+APPLY=0
+if [[ "${3:-}" == "--apply" ]]; then
+  APPLY=1
+fi
 CHANGE_DIR="openspec/changes/$CHANGE"
 
 BLOCK=0
@@ -177,6 +181,43 @@ guard_archive() {
   check "tasks.md all tasks checked" tasks_all_done
 }
 
+apply_state_update() {
+  local state_sh="$SCRIPT_DIR/comet-state.sh"
+  local p="$1"
+
+  if [ -f "$state_sh" ]; then
+    case "$p" in
+      open)   bash "$state_sh" set "$CHANGE" phase design ;;
+      design) bash "$state_sh" set "$CHANGE" phase build ;;
+      build)
+        bash "$state_sh" set "$CHANGE" phase verify
+        bash "$state_sh" set "$CHANGE" verify_result pending
+        ;;
+      verify)
+        bash "$state_sh" set "$CHANGE" phase archive
+        bash "$state_sh" set "$CHANGE" verify_result pass
+        bash "$state_sh" set "$CHANGE" verified_at "$(date +%Y-%m-%d)"
+        ;;
+    esac
+  else
+    local yaml="$CHANGE_DIR/.comet.yaml"
+    case "$p" in
+      open)   sed -i 's/^phase:.*/phase: design/' "$yaml" ;;
+      design) sed -i 's/^phase:.*/phase: build/' "$yaml" ;;
+      build)  sed -i 's/^phase:.*/phase: verify/' "$yaml"; sed -i 's/^verify_result:.*/verify_result: pending/' "$yaml" ;;
+      verify)
+        sed -i 's/^phase:.*/phase: archive/' "$yaml"
+        sed -i 's/^verify_result:.*/verify_result: pass/' "$yaml"
+        if ! grep -q '^verified_at:' "$yaml" 2>/dev/null; then
+          echo "verified_at: $(date +%Y-%m-%d)" >> "$yaml"
+        else
+          sed -i "s/^verified_at:.*/verified_at: $(date +%Y-%m-%d)/" "$yaml"
+        fi
+        ;;
+    esac
+  fi
+}
+
 # --- Main ---
 
 case "$PHASE" in
@@ -199,5 +240,14 @@ if [ "$BLOCK" -eq 1 ]; then
 else
   echo "" >&2
   green "ALL CHECKS PASSED — ready for next phase"
+  if [ "$APPLY" -eq 1 ]; then
+    apply_state_update "$PHASE"
+    case "$PHASE" in
+      open)   green "  [APPLY] .comet.yaml updated: phase=design" ;;
+      design) green "  [APPLY] .comet.yaml updated: phase=build" ;;
+      build)  green "  [APPLY] .comet.yaml updated: phase=verify, verify_result=pending" ;;
+      verify) green "  [APPLY] .comet.yaml updated: phase=archive, verify_result=pass" ;;
+    esac
+  fi
   exit 0
 fi