aether-colony 5.1.0 → 5.3.0

package/.aether/commands/opencode/watch.md

@@ -0,0 +1,227 @@
+<!-- Generated from .aether/commands/watch.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:watch
+description: "👁️🔄🐜🏠🔄👁️ Set up tmux session to watch ants working in real-time"
+---
+
+### Step -1: Normalize Arguments
+
+Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
+
+This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
+
+You are the **Queen**. Set up live visibility into colony activity.
+
+## Instructions
+
+### Step 1: Check Prerequisites
+
+Use Bash to check if tmux is available:
+```bash
+command -v tmux >/dev/null 2>&1 && echo "tmux_available" || echo "tmux_missing"
+```
+
+If tmux is missing:
+```
+tmux is required for live colony viewing.
+
+Install with:
+  macOS:  brew install tmux
+  Ubuntu: sudo apt install tmux
+  Fedora: sudo dnf install tmux
+```
+Stop here.
+
+### Step 2: Initialize Activity Log
+
+Ensure activity log exists:
+```bash
+mkdir -p .aether/data
+touch .aether/data/activity.log
+```
+
+### Step 3: Create Status File
+
+Write initial status to `.aether/data/watch-status.txt`:
+
+```
+       .-.
+      (o o)  AETHER COLONY
+      | O |  Live Status
+       `-`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+State: IDLE
+Phase: -/-
+
+Active Workers:
+  (none)
+
+Last Activity:
+  (waiting for colony activity)
+```
+
+### Step 4: Create or Attach to tmux Session
+
+Check if session exists:
+```bash
+tmux has-session -t aether-colony 2>/dev/null && echo "exists" || echo "new"
+```
+
+**If session exists:** Attach to it
+```bash
+tmux attach-session -t aether-colony
+```
+Output: `Attached to existing aether-colony session.`
+Stop here.
+
+**If session is new:** Create the layout.
+
+### Step 5: Create tmux Layout (4-Pane)
+
+Use Bash to create the session with 4 panes in a 2x2 grid:
+
+```bash
+# Create session with first pane
+tmux new-session -d -s aether-colony -n colony
+
+# Split into 4 panes (2x2 grid)
+# First split horizontally (left|right)
+tmux split-window -h -t aether-colony:colony
+
+# Split left side vertically (top-left, bottom-left)
+tmux split-window -v -t aether-colony:colony.0
+
+# Split right side vertically (top-right, bottom-right)
+tmux split-window -v -t aether-colony:colony.2
+
+# Set pane contents:
+# Pane 0 (top-left): Status display
+tmux send-keys -t aether-colony:colony.0 'watch -n 1 cat .aether/data/watch-status.txt' C-m
+
+# Pane 1 (bottom-left): Progress bar
+tmux send-keys -t aether-colony:colony.1 'watch -n 1 cat .aether/data/watch-progress.txt' C-m
+
+# Pane 2 (top-right): Spawn tree visualization
+tmux send-keys -t aether-colony:colony.2 'bash .aether/utils/watch-spawn-tree.sh .aether/data' C-m
+
+# Pane 3 (bottom-right): Colorized activity log stream
+tmux send-keys -t aether-colony:colony.3 'bash .aether/utils/colorize-log.sh .aether/data/activity.log' C-m
+
+# Set pane titles (if supported)
+tmux select-pane -t aether-colony:colony.0 -T "Status"
+tmux select-pane -t aether-colony:colony.1 -T "Progress"
+tmux select-pane -t aether-colony:colony.2 -T "Spawn Tree"
+tmux select-pane -t aether-colony:colony.3 -T "Activity Log"
+
+# Balance panes for even 2x2 grid
+tmux select-layout -t aether-colony:colony tiled
+
+echo "Session created"
+```
+
+### Step 6: Create Progress File
+
+Write initial progress to `.aether/data/watch-progress.txt`:
+
+```
+       .-.
+      (o o)  AETHER COLONY
+      | O |  Progress
+       `-`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Phase: -/-
+
+[░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0%
+
+⏳ Waiting for build...
+
+Target: 95% confidence
+```
+
+### Step 7: Attach and Display
+
+```bash
+tmux attach-session -t aether-colony
+```
+
+Before attaching, output:
+
+```
+       .-.
+      (o o)  AETHER COLONY :: WATCH
+      | O |
+       `-`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+tmux session 'aether-colony' created.
+
+Layout (4-pane 2x2 grid):
+  +------------------+------------------+
+  | Status           | Spawn Tree       |
+  | Colony state     | Worker hierarchy |
+  +------------------+------------------+
+  | Progress         | Activity Log     |
+  | Phase progress   | Live stream      |
+  +------------------+------------------+
+
+Commands:
+  Ctrl+B D          Detach from session
+  Ctrl+B [          Scroll mode (q to exit)
+  Ctrl+B Arrow      Navigate between panes
+  tmux kill-session -t aether-colony   Stop watching
+
+The session will update in real-time as colony works.
+Attaching now...
+```
+
+---
+
+## Status Update Protocol
+
+Workers and commands update watch files as they work:
+
+### Activity Log
+Workers write via: `bash .aether/aether-utils.sh activity-log "ACTION" "caste" "description"`
+
+For named ants (recommended):
+```bash
+# Generate a name first
+ant_name=$(bash .aether/aether-utils.sh generate-ant-name "builder" | jq -r '.result')
+# Log with ant name
+bash .aether/aether-utils.sh activity-log "CREATED" "$ant_name (Builder)" "Implemented auth module"
+```
+
+### Spawn Tracking
+Log spawns for tree visualization:
+```bash
+bash .aether/aether-utils.sh spawn-log "Prime" "builder" "Hammer-42" "implementing auth"
+bash .aether/aether-utils.sh spawn-complete "Hammer-42" "completed" "auth module done"
+```
+
+### Status File
+Commands update `.aether/data/watch-status.txt` with current state:
+- State: PLANNING, EXECUTING, READY
+- Phase: current/total
+- Active Workers: list of named ants
+- Last Activity: most recent log entry
+
+### Progress File
+Update via: `bash .aether/aether-utils.sh update-progress <percent> "<message>" <phase> <total>`
+
+Example:
+```bash
+bash .aether/aether-utils.sh update-progress 45 "Building auth module..." 2 5
+```
+
+---
+
+## Cleanup
+
+To stop watching:
+```bash
+tmux kill-session -t aether-colony
+```
+
+This stops the session but preserves all log files.

package/.aether/commands/plan.yaml

@@ -20,7 +20,7 @@ body_claude: |
   3. Output: `State auto-upgraded to v3.0`
   4. Continue with command.
 
-  Extract: `goal`, `plan.phases`
+  Extract: `goal`, `milestone`, `plan.phases`
 
   **Validate:** If `goal: null`:
   ```
@@ -28,6 +28,12 @@ body_claude: |
   ```
   Stop here.
 
+  If `milestone` == `"Crowned Anthill"`:
+  ```
+  This colony has been sealed. Start a new colony with /ant:init "new goal".
+  ```
+  Stop here.
+
   ### Step 1.5: Load State and Show Resumption Context
 
   Run using Bash tool: `bash .aether/aether-utils.sh load-state`
@@ -556,6 +562,26 @@ body_claude: |
 
   Write COLONY_STATE.json.
 
+  **Verify the write** — read back and confirm the plan persisted:
+  ```bash
+  verify_phases=$(jq '.plan.phases | length' .aether/data/COLONY_STATE.json)
+  verify_timestamp=$(jq -r '.plan.generated_at' .aether/data/COLONY_STATE.json)
+  verify_state=$(jq -r '.state' .aether/data/COLONY_STATE.json)
+  if [[ "$verify_phases" -lt 1 || "$verify_timestamp" == "null" || "$verify_state" != "READY" ]]; then
+    echo "ERROR: Plan write verification failed (phases=$verify_phases, generated_at=$verify_timestamp, state=$verify_state)"
+    echo "Attempting retry write..."
+    # Retry: re-read, update, write via state API
+    bash .aether/aether-utils.sh state-write "$(jq --argjson phases "$(echo '$PLAN_JSON' | jq '.plan.phases')" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '.plan.phases = $phases | .plan.generated_at = $ts | .state = "READY"' .aether/data/COLONY_STATE.json)"
+    verify_phases=$(jq '.plan.phases | length' .aether/data/COLONY_STATE.json)
+    if [[ "$verify_phases" -lt 1 ]]; then
+      echo "FATAL: Retry write also failed. Plan was not persisted."
+      echo "Re-run /ant:plan to regenerate."
+      stop
+    fi
+  fi
+  echo "Plan verified: $verify_phases phases, generated_at=$verify_timestamp, state=$verify_state"
+  ```
+
   Log: `bash .aether/aether-utils.sh activity-log "PLAN_COMPLETE" "queen" "Plan finalized with {confidence}% confidence"`
 
   Update watch-status.txt:
@@ -683,7 +709,7 @@ body_opencode: |
   3. Output: `State auto-upgraded to v3.0`
   4. Continue with command.
 
-  Extract: `goal`, `plan.phases`
+  Extract: `goal`, `milestone`, `plan.phases`
 
   **Validate:** If `goal: null`:
   ```
@@ -691,6 +717,12 @@ body_opencode: |
   ```
   Stop here.
 
+  If `milestone` == `"Crowned Anthill"`:
+  ```
+  This colony has been sealed. Start a new colony with /ant:init "new goal".
+  ```
+  Stop here.
+
   ### Step 1.5: Load State and Show Resumption Context
 
   Run using Bash tool: `bash .aether/aether-utils.sh load-state`
@@ -1220,6 +1252,25 @@ body_opencode: |
 
   Write COLONY_STATE.json.
 
+  **Verify the write** — read back and confirm the plan persisted:
+  ```bash
+  verify_phases=$(jq '.plan.phases | length' .aether/data/COLONY_STATE.json)
+  verify_timestamp=$(jq -r '.plan.generated_at' .aether/data/COLONY_STATE.json)
+  verify_state=$(jq -r '.state' .aether/data/COLONY_STATE.json)
+  if [[ "$verify_phases" -lt 1 || "$verify_timestamp" == "null" || "$verify_state" != "READY" ]]; then
+    echo "ERROR: Plan write verification failed (phases=$verify_phases, generated_at=$verify_timestamp, state=$verify_state)"
+    echo "Attempting retry write..."
+    bash .aether/aether-utils.sh state-write "$(jq --argjson phases "$(echo '$PLAN_JSON' | jq '.plan.phases')" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '.plan.phases = $phases | .plan.generated_at = $ts | .state = "READY"' .aether/data/COLONY_STATE.json)"
+    verify_phases=$(jq '.plan.phases | length' .aether/data/COLONY_STATE.json)
+    if [[ "$verify_phases" -lt 1 ]]; then
+      echo "FATAL: Retry write also failed. Plan was not persisted."
+      echo "Re-run /ant:plan to regenerate."
+      stop
+    fi
+  fi
+  echo "Plan verified: $verify_phases phases, generated_at=$verify_timestamp, state=$verify_state"
+  ```
+
   Log plan completion: `bash .aether/aether-utils.sh activity-log "PLAN_COMPLETE" "queen" "Plan finalized with {confidence}% confidence"`
 
   Update watch-status.txt:

package/.aether/commands/quick.yaml

@@ -0,0 +1,104 @@
+name: "ant:quick"
+description: "Quick scout query — fast answers without build ceremony"
+description_opencode: "🔍🐜⚡🐜🔍 Quick scout query — fast answers without build ceremony"
+body: |
+  You are the **Queen**. Execute `/ant:quick` — a lightweight scout mission.
+
+  The query is: `{{ARGUMENTS}}`
+
+  ## Purpose
+
+  Quick, focused answers to questions about the codebase, patterns, or implementation
+  details. No build ceremony, no state changes, no verification waves.
+
+  ## Instructions
+
+  ### Step 1: Validate Arguments
+
+  If `{{ARGUMENTS}}` is empty:
+  ```
+  Usage: /ant:quick "<question>"
+
+  Examples:
+    /ant:quick "how does the pheromone system work?"
+    /ant:quick "find all uses of acquire_lock"
+    /ant:quick "what tests cover midden-write?"
+    /ant:quick "show me the colony-prime token budget logic"
+  ```
+  Stop here.
+
+  ### Step 2: Generate Scout Name
+
+  {{TOOL_PREFIX "Naming scout..."}}
+  ```bash
+  bash .aether/aether-utils.sh generate-ant-name "scout"
+  ```
+
+  Capture the output as `scout_name`.
+
+  ### Step 3: Spawn Scout
+
+  Display:
+  ```
+  ━━━ Quick Scout ━━━
+  Spawning {scout_name} — {query truncated to 50 chars}
+  ```
+
+  {{TOOL_PREFIX "Dispatching scout..."}}
+  ```bash
+  bash .aether/aether-utils.sh spawn-log "Queen" "scout" "{scout_name}" "Quick query: {query}"
+  ```
+
+  {{#claude}}
+  Spawn a Scout agent (using Task tool with subagent_type="aether-scout") with this prompt:
+
+  ```
+  You are {scout_name}, a Scout Ant on a quick mission.
+
+  Query: {query from ARGUMENTS}
+
+  Work:
+  1. Search the codebase to answer the query
+  2. Use Grep, Glob, and Read tools to find relevant code
+  3. Provide a clear, focused answer
+  4. Include file paths and line numbers for key findings
+
+  Keep your answer concise and actionable. This is a quick mission —
+  don't explore exhaustively, focus on the most relevant answer.
+
+  Return your findings as a clear text answer (not JSON).
+  ```
+  {{/claude}}
+  {{#opencode}}
+  Investigate the query directly using available tools (Grep, Glob, Read).
+  Search the codebase and provide a clear, focused answer with file paths and line numbers for key findings.
+  Keep your answer concise and actionable.
+  {{/opencode}}
+
+  ### Step 4: Display Results
+
+  {{#claude}}
+  Display the Scout's answer directly to the user.
+  {{/claude}}
+  {{#opencode}}
+  Display your findings directly to the user.
+  {{/opencode}}
+
+  {{TOOL_PREFIX "Recording scout completion..."}}
+  ```bash
+  bash .aether/aether-utils.sh spawn-complete "{scout_name}" "completed" "Quick query answered"
+  ```
+
+  ### Step 5: Update Session (lightweight)
+
+  {{TOOL_PREFIX "Updating session..."}}
+  ```bash
+  bash .aether/aether-utils.sh session-update "/ant:quick" "" "Quick query: {query truncated to 60 chars}" 2>/dev/null || true
+  ```
+
+  **NOTE:** This command does NOT:
+  - Modify COLONY_STATE.json
+  - Advance phases
+  - Create checkpoints
+  - Spawn watchers or chaos ants
+  - Run verification

package/.aether/commands/resume-colony.yaml

@@ -25,8 +25,9 @@ body_claude: |
   If successful:
   1. Parse state from result
   2. If goal is null: Show "No colony state found..." message and stop
-  3. Check if paused flag is true - if not, note "Colony was not paused, but resuming anyway"
-  4. Extract all state fields for display
+  3. If `milestone` == `"Crowned Anthill"`: Show "This colony has been sealed. Start a new colony with `/ant:init \"new goal\"`." and stop
+  4. Check if paused flag is true - if not, note "Colony was not paused, but resuming anyway"
+  5. Extract all state fields for display
 
   Keep state loaded (don't unload yet) - we'll need it for the full display.
 
@@ -214,8 +215,9 @@ body_opencode: |
   If successful:
   1. Parse state from result
   2. If goal is null: Show "No colony state found..." message and stop
-  3. Check if paused flag is true - if not, note "Colony was not paused, but resuming anyway"
-  4. Extract all state fields for display
+  3. If `milestone` == `"Crowned Anthill"`: Show "This colony has been sealed. Start a new colony with `/ant:init \"new goal\"`." and stop
+  4. Check if paused flag is true - if not, note "Colony was not paused, but resuming anyway"
+  5. Extract all state fields for display
 
   Keep state loaded (don't unload yet) - we'll need it for the full display.
 

package/.aether/commands/resume.yaml

@@ -60,6 +60,7 @@ body: |
 
   COLONY_STATE.json is the authoritative source for goal and state (session.json may be stale). Extract:
   - `goal` (use this as authoritative, overriding session.json colony_goal)
+  - `milestone` (check for sealed colony)
   - `state` (READY, PLANNING, EXECUTING, PAUSED)
   - `current_phase`
   - `plan.phases` (array with id, name, status for each phase)
@@ -67,6 +68,14 @@ body: |
   - `memory.decisions` (flat list — do NOT distinguish user vs Claude origin)
   - `events` (last 5 for recent activity context)
 
+  **If `milestone` == `"Crowned Anthill"`:** This colony has been sealed. Display:
+  ```
+  This colony has been sealed (Crowned Anthill).
+
+  Start a new colony with /ant:init "new goal"
+  ```
+  Stop here — do NOT display stale phase data from the sealed colony.
+
   If the file is missing or the JSON cannot be parsed, **stop immediately** and display:
 
   ```

package/.aether/commands/run.yaml

@@ -28,6 +28,7 @@ body: |
   - `--replan-interval N` — Pause for replan suggestion every N phases (default: 2)
   - `--continue` — Resume after a replan pause without replanning
   - `--dry-run` — Preview plan without executing
+  - `--headless` — Run without interactive prompts; queue decisions for later review
   - `--verbose` / `-v`, `--no-visual`, `--no-suggest` — Pass through to playbooks
 
   ```
@@ -36,6 +37,7 @@ body: |
   /ant:run --replan-interval 3   Suggest replan every 3 phases instead of 2
   /ant:run --continue            Resume after replan pause without replanning
   /ant:run --dry-run             Preview the autopilot plan
+  /ant:run --headless            Run all phases without interactive prompts
   /ant:run --max-phases 3 -v     Run 3 phases with verbose output
   ```
 
@@ -61,10 +63,14 @@ body: |
   ### Step 0: Initialize
 
   1. Read `.aether/data/COLONY_STATE.json`; validate goal + plan.phases exist
+     - If `milestone` == `"Crowned Anthill"`: output "This colony has been sealed. Start a new colony with `/ant:init \"new goal\"`." and stop
   2. Determine remaining incomplete phases; apply `--max-phases` cap
   3. Set `phases_completed = 0`, `autopilot_start = $(date +%s)`
   4. Record pre-build blocker count: `bash .aether/aether-utils.sh flag-check-blockers {phase}`
-  5. Display: `AUTOPILOT ENGAGED | Goal: {goal} | Phase {N} | Max: {max or "all"}`
+  5. If `--headless` flag is present:
+     - Run: `bash .aether/aether-utils.sh autopilot-set-headless true`
+     - Display: `Headless mode: ON — interactive prompts will be queued as pending decisions`
+  6. Display: `AUTOPILOT ENGAGED | Goal: {goal} | Phase {N} | Max: {max or "all"}`
 
   ### Step 1: Build Phase
 
@@ -95,6 +101,19 @@ body: |
   specific issues, and instruction: "Fix issues, then run /ant:run to resume."
   Log: `"<timestamp>|autopilot_paused|run|Paused at Phase {id}: {reason}"`
 
+  **Headless override for visual checkpoints:** If headless mode is active and a
+  visual checkpoint prompt would normally be shown to the user, instead queue it as
+  a pending decision:
+  ```bash
+  bash .aether/aether-utils.sh pending-decision-add \
+    --title "Visual checkpoint: Phase {id}" \
+    --type "checkpoint" \
+    --description "{checkpoint_description}" \
+    --phase "{id}" \
+    --source "build-pause-check"
+  ```
+  Then continue without pausing.
+
   **If no pause:** proceed to Step 3.
 
   ### Step 3: Continue (Verify + Advance)
@@ -112,6 +131,18 @@ body: |
   Skip the AskUserQuestion prompt. Instead, auto-PAUSE with reason
   "Runtime verification required" so the user can test manually before resuming.
 
+  **Headless override for runtime verification:** If headless mode is active and
+  runtime verification would normally pause, queue as a pending decision instead:
+  ```bash
+  bash .aether/aether-utils.sh pending-decision-add \
+    --title "Runtime verification needed: Phase {id}" \
+    --type "runtime-verification" \
+    --description "Manual testing required before advancing past Phase {id}" \
+    --phase "{id}" \
+    --source "continue-gates"
+  ```
+  Then continue without pausing.
+
   ### Step 4: Continue Pause Check
 
   **PAUSE if ANY of these are true:**
@@ -181,6 +212,11 @@ body: |
   {paused}        -> Fix {reason}, then /ant:run to resume
   ```
 
+  If headless mode was active and pending decisions were queued, display:
+  ```
+  Pending decisions: {N} — run `pending-decision-list` to review
+  ```
+
   Update session:
   `bash .aether/aether-utils.sh session-update "/ant:run" "/ant:run" "Autopilot: {N} phases, now Phase {current}"`
 

package/.aether/commands/seal.yaml

@@ -341,6 +341,15 @@ body_claude: |
   bash .aether/aether-utils.sh activity-log "MODIFIED" "Queen" "Colony sealed - wisdom review completed"
   ```
 
+  ### Step 4.4: Checkpoint State
+
+  Before modifying colony state, create a rolling backup:
+
+  Run using the Bash tool with description "Checkpointing colony state before seal...":
+  ```bash
+  bash .aether/aether-utils.sh state-checkpoint "pre-seal" 2>/dev/null || echo "Warning: State checkpoint failed -- continuing without backup" >&2
+  ```
+
   ### Step 4.5: Increment Colony Version
 
   Before writing the Crowned Anthill milestone, increment `colony_version` in COLONY_STATE.json.

package/.aether/commands/status.yaml

@@ -300,9 +300,53 @@ body: |
   ```
 
   {{#claude}}
-  **Data Safety:**
+  **Colony Vital Signs:**
   After the Memory Health table, run:
   ```bash
+  bash .aether/aether-utils.sh colony-vital-signs
+  ```
+
+  Extract from JSON result:
+  - build_velocity.phases_per_day and build_velocity.trend
+  - error_rate.errors_per_day and error_rate.status
+  - signal_health.active_count and signal_health.status
+  - memory_pressure.instinct_count and memory_pressure.status
+  - colony_age_hours
+  - overall_health (0-100 score)
+
+  Map overall_health score to a label:
+  - 80-100: "Thriving"
+  - 60-79: "Healthy"
+  - 40-59: "Stable"
+  - 20-39: "Struggling"
+  - 0-19: "Critical"
+
+  Display:
+  ```
+  💓 Colony Vital Signs
+  ┌─────────────────┬────────────┬─────────────────────────────┐
+  │ Vital Sign      │ Value      │ Status                      │
+  ├─────────────────┼────────────┼─────────────────────────────┤
+  │ Build Velocity  │ {phases_per_day}/d  │ {trend}            │
+  │ Error Rate      │ {errors_per_day}/d  │ {error_status}     │
+  │ Signal Health   │ {active_count}      │ {signal_status}    │
+  │ Memory Pressure │ {instinct_count}    │ {memory_status}    │
+  │ Colony Age      │ {colony_age_hours}h │                    │
+  ├─────────────────┼────────────┼─────────────────────────────┤
+  │ Overall Health  │ {overall_health}%   │ {health_label}     │
+  └─────────────────┴────────────┴─────────────────────────────┘
+  ```
+
+  If the command fails or returns no data, display:
+  ```
+  💓 Colony Vital Signs: No data available
+  ```
+  {{/claude}}
+
+  {{#claude}}
+  **Data Safety:**
+  After the Colony Vital Signs panel, run:
+  ```bash
   bash .aether/aether-utils.sh data-safety-stats
   ```
 

package/.aether/docs/command-playbooks/build-full.md

@@ -98,7 +98,8 @@ If the command fails (non-zero exit or JSON has ok: false):
 If successful:
 1. Parse the state JSON from result field
 2. Check if goal is null - if so: "No colony initialized. Run /ant:init first." and stop
-3. Extract current_phase and phase name from plan.phases[current_phase - 1].name
+3. Check if `milestone` == `"Crowned Anthill"` - if so: "This colony has been sealed. Start a new colony with `/ant:init \"new goal\"`." and stop
+4. Extract current_phase and phase name from plan.phases[current_phase - 1].name
 4. Display brief resumption context:
    ```
    🔄 Resuming: Phase X - Name
@@ -253,7 +254,7 @@ git rev-parse --git-dir 2>/dev/null
 
 - **If succeeds** (is a git repo):
   1. Check for changes in Aether-managed directories only: `.aether .claude/commands/ant .claude/commands/st .opencode bin`
-  2. **If changes exist**: Run using the Bash tool with description "Creating git checkpoint...": `git stash push -m "aether-checkpoint: pre-phase-$PHASE_NUMBER" -- .aether .claude/commands/ant .claude/commands/st .opencode bin`
+  2. **If changes exist**: Run using the Bash tool with description "Creating git checkpoint...": `git stash push -m "aether-checkpoint: pre-phase-$PHASE_NUMBER" -- .aether .claude/commands/ant .claude/commands/st .opencode bin ":(exclude).aether/data/"`
      - IMPORTANT: Never use `--include-untracked` — it stashes ALL files including user work!
      - Run using the Bash tool with description "Verifying checkpoint...": `git stash list | head -1 | grep "aether-checkpoint"` — warn if empty
      - Store checkpoint as `{type: "stash", ref: "aether-checkpoint: pre-phase-$PHASE_NUMBER"}`