aether-colony 3.1.4 → 3.1.15

package/.claude/commands/ant/init.md

@@ -9,7 +9,23 @@ You are the **Queen Ant Colony**. Initialize the colony with the Queen's intenti
 
 The user's goal is: `$ARGUMENTS`
 
-### Step 0: Version Check (Non-blocking)
+Parse `$ARGUMENTS`:
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- Otherwise: set `visual_mode = true`
+
+### Step 0: Initialize Visual Mode (if enabled)
+
+If `visual_mode` is true:
+```bash
+# Generate session ID
+init_id="init-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$init_id"
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Colony initialization" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
+```
+
+### Step 0.5: Version Check (Non-blocking)
 
 Run using the Bash tool: `bash .aether/aether-utils.sh version-check 2>/dev/null || true`
 
@@ -58,20 +74,53 @@ Check if `.aether/aether-utils.sh` exists using the Read tool.
   ```
   Stop here. Do not proceed.
 
-### Step 2: Read Current State
+### Step 1.6: Initialize QUEEN.md Wisdom Document
+
+After bootstrap completes (or if system files already existed), run using the Bash tool:
+```
+bash .aether/aether-utils.sh queen-init
+```
+
+Parse the JSON result:
+- If `created` is true: Display `QUEEN.md initialized`
+- If `created` is false and `reason` is "already_exists": Display `QUEEN.md already exists`
+
+This step is non-blocking — proceed regardless of outcome.
+
+### Step 2: Read Current State with Freshness Check
+
+Capture session start time:
+```bash
+INIT_START=$(date +%s)
+```
 
 Use the Read tool to read `.aether/data/COLONY_STATE.json`.
 
-If the `goal` field is not null, output:
+Check freshness of existing state:
+```bash
+fresh_check=$(bash .aether/aether-utils.sh session-verify-fresh --command init "" "$INIT_START")
+is_stale=$(echo "$fresh_check" | jq -r '.stale | length')
+freshness_status=$([[ "$is_stale" -gt 0 ]] && echo "stale" || echo "fresh")
+```
+
+If the `goal` field is not null:
+- If state is stale (old session): Warn user but proceed
+- If state is fresh (active session): Strongly recommend continuation
 
 ```
 Colony already initialized with goal: "{existing_goal}"
 
+State freshness: {freshness_status}
+Session: {session_id}
+Initialized: {initialized_at}
+
 To reinitialize with a new goal, the current state will be reset.
 Proceeding with new goal: "{new_goal}"
 ```
 
-### Step 2.5: Load Prior Colony Knowledge (Optional)
+**Note:** Init never auto-clears COLONY_STATE.json. Reinitialization is an explicit user choice.
+
+### Step 2.6: Load Prior Colony Knowledge (Optional)
 
 Check if `.aether/data/completion-report.md` exists using the Read tool.
 
@@ -81,7 +130,7 @@ Check if `.aether/data/completion-report.md` exists using the Read tool.
 1. **Instincts** — look for the `## Colony Instincts` section. Each line has format: `N. [confidence] domain: description`. Keep only instincts with confidence >= 0.5.
 2. **Learnings** — look for the `## Colony Learnings (Validated)` section. Keep all numbered items.
 
-Store the extracted instincts and learnings for use in Step 3. Display a brief note:
+Store the extracted instincts and learnings for use in Step 3 (Write Colony State). Display a brief note:
 
 ```
 🧠 Prior colony knowledge found:
@@ -102,7 +151,7 @@ Generate a session ID in the format `session_{unix_timestamp}_{random}` and an I
 
 Use the Write tool to write `.aether/data/COLONY_STATE.json` with the v3.0 structure.
 
-**If Step 2.5 found instincts to inherit**, convert each into the instinct format and seed the `memory.instincts` array. Each inherited instinct should have:
+**If Step 2.6 found instincts to inherit**, convert each into the instinct format and seed the `memory.instincts` array. Each inherited instinct should have:
 - `id`: `instinct_inherited_{index}`
 - `trigger`: inferred from the instinct description
 - `action`: the instinct description
@@ -115,13 +164,13 @@ Use the Write tool to write `.aether/data/COLONY_STATE.json` with the v3.0 struc
 - `applications`: 0
 - `successes`: 0
 
-**If Step 2.5 found validated learnings**, seed `memory.phase_learnings` with each as:
+**If Step 2.6 found validated learnings**, seed `memory.phase_learnings` with each as:
 - `phase`: `"inherited"`
 - `learning`: the learning text
 - `status`: `"validated"`
 - `source`: `"inherited:completion-report"`
 
-**If Step 2.5 was skipped or found nothing**, use empty arrays as before.
+**If Step 2.6 was skipped or found nothing**, use empty arrays as before.
 
 ```json
 {
@@ -166,7 +215,16 @@ Write `.aether/data/constraints.json`:
 }
 ```
 
-### Step 5: Validate State File
+### Step 5: Initialize Context Document
+
+Run using Bash tool:
+```
+bash .aether/aether-utils.sh context-update init "$ARGUMENTS"
+```
+
+This creates `.aether/CONTEXT.md` — the colony's persistent memory. If context collapses, this file tells the next session what we were doing.
+
+### Step 6: Validate State File
 
 Use the Bash tool to run:
 ```
@@ -175,7 +233,7 @@ bash .aether/aether-utils.sh validate-state colony
 
 This validates COLONY_STATE.json structure. If validation fails, output a warning.
 
-### Step 5.5: Detect Nestmates
+### Step 6.5: Detect Nestmates
 
 Run using Bash tool: `node -e "const nl = require('./bin/lib/nestmate-loader'); console.log(JSON.stringify(nl.findNestmates(process.cwd())))"`
 
@@ -184,7 +242,7 @@ If nestmates are found:
 2. List each nestmate with name and truncated goal
 3. Check for shared TO-DOs or cross-project dependencies
 
-### Step 5.6: Register Repo (Silent)
+### Step 6.6: Register Repo (Silent)
 
 Attempt to register this repo in the global hub. Both steps are silent on failure — registry is not required for the colony to work.
 
@@ -200,7 +258,13 @@ cp ~/.aether/version.json .aether/version.json 2>/dev/null || true
 
 If either command fails, proceed silently. These are optional bookkeeping.
 
-### Step 6: Display Result
+### Step 7: Display Result
+
+**If visual_mode is true, render final swarm display:**
+```bash
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Colony initialized" "Colony" '{"read":5,"grep":2,"edit":3,"bash":2}' 100 "fungus_garden" 100
+bash .aether/aether-utils.sh swarm-display-render "$init_id"
+```
 
 Output this header:
 
@@ -220,7 +284,7 @@ Then output the result:
 🏠 Colony Status: READY
 📋 Session: <session_id>
 
-{If instincts or learnings were inherited from Step 2.5:}
+{If instincts or learnings were inherited from Step 2.6:}
 🧠 Inherited from prior colony:
    {N} instinct(s) | {N} learning(s)
 {End if}
@@ -238,4 +302,14 @@ Then output the result:
    /ant:watch     👁️  Set up live visibility
 
 💾 State persisted — safe to /clear, then run /ant:plan
+
+📋 Context document created at `.aether/CONTEXT.md` — read this if session resets
+```
+
+### Step 8: Initialize Session
+
+Initialize session tracking to enable `/ant:resume` after context clear:
+
+```bash
+bash .aether/aether-utils.sh session-init "$(jq -r '.session_id' .aether/data/COLONY_STATE.json)" "$ARGUMENTS"
 ```

package/.claude/commands/ant/lay-eggs.md

@@ -7,6 +7,22 @@ You are the **Queen**. Begin a new colony, preserving pheromones.
 
 ## Instructions
 
+Parse `$ARGUMENTS`:
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- Otherwise: set `visual_mode = true`
+
+### Step 0: Initialize Visual Mode (if enabled)
+
+If `visual_mode` is true:
+```bash
+# Generate session ID
+layeggs_id="layeggs-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$layeggs_id"
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Laying first eggs" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "nursery" 0
+```
+
 ### Step 1: Validate Input
 
 - If `$ARGUMENTS` is empty:
@@ -26,13 +42,31 @@ You are the **Queen**. Begin a new colony, preserving pheromones.
 - Read `.aether/data/COLONY_STATE.json`
 - If goal is not null AND phases exist with status != "completed":
   ```
-  Active colony exists: {goal}
-
-  To start a new colony, you must first:
-  1. Complete all phases, then /ant:entomb to archive
-  2. Or manually reset by deleting .aether/data/COLONY_STATE.json
+  🚫 Cannot lay eggs — active colony has unsaved pheromones
 
+  Active colony: {goal}
   Current: Phase {current_phase}, {phases_count} phases in plan
+
+  ┌─────────────────────────────────────────────────────────┐
+  │  COLONY LIFECYCLE                                       │
+  ├─────────────────────────────────────────────────────────┤
+  │                                                         │
+  │   🟢 ACTIVE COLONY  →  🏺 SEAL/ENTOMB  →  🥚 LAY EGGS   │
+  │       (working)         (preserve memory)   (new goal)  │
+  │                                                         │
+  └─────────────────────────────────────────────────────────┘
+
+  Why this matters:
+  Your active colony contains preserved learnings, decisions, and
+  instincts (pheromones) from prior work. These must be sealed
+  before starting a new project, or they will be lost forever.
+
+  To start a new colony:
+  1. Complete work → run `/ant:seal` or `/ant:entomb` to archive
+  2. Then run `/ant:lay-eggs "new goal"` to begin fresh
+
+  Emergency reset (loses all pheromones):
+     rm .aether/data/COLONY_STATE.json
   ```
   Stop here.
 
@@ -86,6 +120,12 @@ Write `.aether/data/constraints.json`:
 
 ### Step 6: Display Result
 
+**If visual_mode is true, render final swarm display:**
+```bash
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "First eggs laid" "Colony" '{"read":3,"grep":0,"edit":2,"bash":1}' 100 "nursery" 100
+bash .aether/aether-utils.sh swarm-display-render "$layeggs_id"
+```
+
 ```
 🥚 ═══════════════════════════════════════════════════
    F I R S T   E G G S   L A I D

package/.claude/commands/ant/oracle.md

@@ -1,6 +1,6 @@
 ---
 name: ant:oracle
-description: "🔮🐜🧠🐜🔮 Oracle Ant - deep research agent using RALF iterative loop pattern"
+description: "🔮🐜🧠🐜🔮🐜 Oracle Ant - deep research agent using RALF iterative loop pattern"
 ---
 
 You are the **Oracle Ant** command handler. You configure and launch a deep research loop that runs autonomously in a separate process.
@@ -17,9 +17,36 @@ Oracle NEVER touches COLONY_STATE.json, constraints.json, activity.log, or any c
 
 Parse `$ARGUMENTS` to determine the action:
 
-1. **If `$ARGUMENTS` is exactly `stop`** — go to **Step 0b: Stop Oracle**
-2. **If `$ARGUMENTS` is exactly `status`** — go to **Step 0c: Show Status**
-3. **Otherwise** — go to **Step 1: Research Wizard**
+1. Check for flags:
+   - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+   - If contains `--force` or `--force-research`: set `force_research = true`
+   - Otherwise: set `visual_mode = true`, `force_research = false`
+   - Remove flags from arguments before routing
+
+2. **If remaining arguments is exactly `stop`** — go to **Step 0b: Stop Oracle**
+3. **If remaining arguments is exactly `status`** — go to **Step 0c: Show Status**
+4. **Otherwise** — go to **Step 0.5: Initialize Visual Mode** then **Step 1: Research Wizard**
+
+### Step 0.5: Initialize Visual Mode (if enabled)
+
+If `visual_mode` is true:
+```bash
+# Generate session ID
+oracle_id="oracle-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$oracle_id"
+bash .aether/aether-utils.sh swarm-display-update "Oracle" "oracle" "researching" "Deep research in progress" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
+```
+
+Display visual header:
+```
+🔮🐜🧠🐜🔮 ═══════════════════════════════════════════════
+          O R A C L E  —  R e s e a r c h  M o d e
+═══════════════════════════════════════════════ 🔮🐜🧠🐜🔮
+
+Oracle peering into the depths...
+```
 
 ---
 
@@ -34,7 +61,7 @@ mkdir -p .aether/oracle && touch .aether/oracle/.stop
 Output:
 
 ```
-🔮 Oracle Stop Signal Sent
+🔮🐜 Oracle Stop Signal Sent
 
    Created .aether/oracle/.stop
    The research loop will halt at the end of the current iteration.
@@ -53,7 +80,7 @@ Check if `.aether/oracle/progress.md` exists using the Read tool.
 **If it does NOT exist**, output:
 
 ```
-🔮 Oracle Status: No Research In Progress
+🔮🐜 Oracle Status: No Research In Progress
 
    No progress.md found. Start a research session:
    /ant:oracle
@@ -68,7 +95,7 @@ Count the number of `## Iteration` headings in progress.md to determine iteratio
 Output:
 
 ```
-🔮 Oracle Status
+🔮🐜 Oracle Status
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Topic:       {topic from research.json, or "unknown"}
 Confidence:  {target_confidence}%
@@ -165,6 +192,40 @@ After collecting all answers, proceed to Step 2.
 
 ---
 
+### Step 1.5: Check for Stale Oracle Session
+
+Before starting new research, check for existing oracle session files.
+
+Capture session start time:
+```bash
+ORACLE_START=$(date +%s)
+```
+
+Check for stale files:
+```bash
+stale_check=$(bash .aether/aether-utils.sh session-verify-fresh --command oracle "" "$ORACLE_START")
+has_stale=$(echo "$stale_check" | jq -r '.stale | length')
+has_progress=$(echo "$stale_check" | jq -r '.fresh | length')
+
+if [[ "$has_stale" -gt 0 ]] || [[ "$has_progress" -gt 0 ]]; then
+  # Found existing oracle session
+  if [[ "$force_research" == "true" ]]; then
+    bash .aether/aether-utils.sh session-clear --command oracle
+    echo "Cleared stale oracle session for fresh research"
+  else
+    # Existing session found - prompt user
+    echo "Found existing oracle session. Options:"
+    echo "  /ant:oracle status     - View current session"
+    echo "  /ant:oracle --force    - Restart with fresh session"
+    echo "  /ant:oracle stop       - Stop current session"
+    # Don't proceed - let user decide
+    exit 0
+  fi
+fi
+```
+
+---
+
 ### Step 2: Configure Research
 
 Create the oracle directory structure:
@@ -229,6 +290,18 @@ Use the Write tool to write `.aether/oracle/progress.md`:
 
 ```
 
+#### Step 2.5: Verify Oracle Files Are Fresh
+
+Verify that progress.md and research.json were created successfully:
+```bash
+verify_result=$(bash .aether/aether-utils.sh session-verify-fresh --command oracle "" "$ORACLE_START")
+fresh_count=$(echo "$verify_result" | jq -r '.fresh | length')
+
+if [[ "$fresh_count" -lt 2 ]]; then
+  echo "Warning: Oracle files not properly initialized"
+fi
+```
+
 Proceed to Step 3.
 
 ---
@@ -259,13 +332,13 @@ Now launch the loop. Try tmux first, fall back to manual.
 **Try tmux:**
 
 ```bash
-tmux new-session -d -s oracle "cd $(pwd) && bash .aether/oracle/oracle.sh; echo ''; echo '🔮 Oracle loop finished. Press any key to close.'; read -n1" 2>/dev/null && echo "TMUX_OK" || echo "TMUX_FAIL"
+tmux new-session -d -s oracle "cd $(pwd) && bash .aether/oracle/oracle.sh; echo ''; echo '🔮🐜 Oracle loop finished. Press any key to close.'; read -n1" 2>/dev/null && echo "TMUX_OK" || echo "TMUX_FAIL"
 ```
 
 **If TMUX_OK:**
 
 ```
-🔮 Oracle Launched
+🔮🐜 Oracle Launched
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
    The Oracle is researching in a background tmux session.

package/.claude/commands/ant/organize.md

@@ -48,7 +48,8 @@ If no active signals after filtering:
 
 Read `.aether/workers.md` and extract the `## Architect` section.
 
-Spawn via **Task tool** with `subagent_type="general"`:
+Spawn via **Task tool** with `subagent_type="aether-architect"`:
+# FALLBACK: If "Agent type not found", use general-purpose and inject role: "You are an Architect Ant - synthesizes knowledge and coordinates documentation."
 
 ```
 --- WORKER SPEC ---
@@ -159,7 +160,6 @@ CONSTRAINTS:
 - Do NOT flag standard framework files (package.json, tsconfig.json, etc.) as orphaned.
 - Do NOT flag .aether/ internal data files as stale (they are managed by the colony).
 - Do NOT flag .claude/ command files as stale (they are the colony's brain).
-- Do NOT flag .planning/ files as stale (they are project management artifacts).
 - Aim for a useful report, not an exhaustive one. 5-15 findings is ideal.
 ```
 

package/.claude/commands/ant/pause-colony.md

@@ -7,6 +7,22 @@ You are the **Queen Ant Colony**. Save current state for session handoff.
 
 ## Instructions
 
+Parse `$ARGUMENTS`:
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- Otherwise: set `visual_mode = true`
+
+### Step 0: Initialize Visual Mode (if enabled)
+
+If `visual_mode` is true:
+```bash
+# Generate session ID
+pause_id="pause-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$pause_id"
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Pausing colony" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
+```
+
 ### Step 1: Read State
 
 Use the Read tool to read `.aether/data/COLONY_STATE.json`.
@@ -86,74 +102,101 @@ This flag indicates the colony is in a paused state and will be cleared on resum
 
 Before displaying the pause confirmation, check if the user has uncommitted work worth preserving.
 
-1. **Check for uncommitted changes:**
+**1. Check for uncommitted changes:**
 ```bash
 git status --porcelain 2>/dev/null
 ```
 If the output is empty (nothing to commit) or the command fails (not a git repo), skip this step silently and continue to Step 5.
 
-2. **Check for double-prompting:**
+**2. Check for double-prompting:**
 Read `last_commit_suggestion_phase` from COLONY_STATE.json (already loaded in Step 1).
 If `last_commit_suggestion_phase` equals the current phase, skip this step silently — the user was already prompted at POST-ADVANCE. Continue to Step 5.
 
-3. **Generate the commit message:**
-```bash
-bash .aether/aether-utils.sh generate-commit-message "pause" {current_phase} "{phase_name}"
-```
-Parse the returned JSON to extract `message` and `files_changed`.
+**3. Capture AI Description:**
 
-4. **Check files changed:**
+**As the AI, briefly describe what was in progress when pausing.**
+
+Examples:
+- "Mid-implementation of task-based routing, tests passing"
+- "Completed model selection logic, integration tests pending"
+- "Fixed file locking, ready for verification"
+
+Store this as `ai_description`. If no clear description emerges, leave empty (will use fallback).
+
+**4. Generate Enhanced Commit Message:**
 ```bash
-git diff --stat HEAD 2>/dev/null | tail -5
+bash .aether/aether-utils.sh generate-commit-message "contextual" {current_phase} "{phase_name}" "{ai_description}" {plan_number}
 ```
 
-5. **Display the suggestion:**
+Parse the returned JSON to extract `message`, `body`, `files_changed`, `subsystem`, and `scope`.
+
+**5. Display the enhanced suggestion:**
 ```
 ──────────────────────────────────────────────────
 Commit Suggestion
 ──────────────────────────────────────────────────
 
-  Message:  {generated_message}
-  Files:    {files_changed} files changed
-  Preview:  {first 5 lines of git diff --stat}
+  AI Description: {ai_description}
+
+  Formatted Message:
+  {message}
+
+  Metadata:
+  Scope: {scope}
+  Files: {files_changed} files changed
 
 ──────────────────────────────────────────────────
 ```
 
-6. **Use AskUserQuestion:**
+**6. Use AskUserQuestion:**
 ```
 Commit your work before pausing?
 
 1. Yes, commit with this message
-2. Yes, but let me write the message
+2. Yes, but let me edit the description
 3. No, I'll commit later
 ```
 
-7. **If option 1 ("Yes, commit with this message"):**
+**7. If option 1 ("Yes, commit with this message"):**
 ```bash
-git add -A && git commit -m "{generated_message}"
+git add -A && git commit -m "{message}" -m "{body}"
 ```
-Display: `Committed: {generated_message} ({files_changed} files)`
+Display: `Committed: {message} ({files_changed} files)`
 
-8. **If option 2 ("Yes, but let me write the message"):**
-Use AskUserQuestion to get the user's custom commit message, then:
-```bash
-git add -A && git commit -m "{custom_message}"
-```
-Display: `Committed: {custom_message} ({files_changed} files)`
+**8. If option 2 ("Yes, but let me edit"):**
+Prompt for custom description, then regenerate and commit.
 
-9. **If option 3 ("No, I'll commit later"):**
+**9. If option 3 ("No, I'll commit later"):**
 Display: `Skipped. Your changes are saved on disk but not committed.`
 
-10. **Record the suggestion to prevent double-prompting:**
-Set `last_commit_suggestion_phase` to `{current_phase}` in COLONY_STATE.json (add the field at the top level if it does not exist).
+**10. Record the suggestion:**
+Set `last_commit_suggestion_phase` to `{current_phase}` in COLONY_STATE.json.
 
-**Error handling:** If any git command fails (not a repo, merge conflict, pre-commit hook rejection), display the error output and continue to Step 5. The commit suggestion is advisory only — it never blocks the pause flow.
+**Error handling:** If any git command fails, display the error and continue to Step 5.
 
 Continue to Step 5.
 
+### Step 4.8: Update Context Document
+
+Log this pause activity to `.aether/CONTEXT.md`:
+
+```bash
+bash .aether/aether-utils.sh context-update activity "pause-colony" "Colony paused — handoff created" "—"
+```
+
+Update safe-to-clear status:
+```bash
+bash .aether/aether-utils.sh context-update safe-to-clear "YES" "Colony paused — safe to /clear, run /ant:resume-colony to continue"
+```
+
 ### Step 5: Display Confirmation
 
+**If visual_mode is true, render final swarm display:**
+```bash
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Colony paused" "Colony" '{"read":3,"grep":0,"edit":2,"bash":1}' 100 "fungus_garden" 100
+bash .aether/aether-utils.sh swarm-display-render "$pause_id"
+```
+
 Output header:
 
 ```
@@ -176,4 +219,19 @@ Then output:
 
 To resume in a new session:
   /ant:resume-colony
+
+💾 State persisted — safe to /clear
+
+📋 Context document updated at `.aether/CONTEXT.md`
+
+🐜 What would you like to do next?
+   1. /ant:resume-colony              — Resume work in this session
+   2. /ant:lay-eggs "<new goal>"      — Start a new colony
+   3. /clear                          — Clear context and continue
+
+Use AskUserQuestion with these three options.
+
+If option 1 selected: proceed to run /ant:resume-colony flow
+If option 2 selected: run /ant:lay-eggs flow
+If option 3 selected: display "Run /ant:resume-colony when ready to continue, or /ant:lay-eggs to start fresh"
 ```

package/.claude/commands/ant/phase.md

@@ -89,3 +89,29 @@ Legend: [✓] completed  [~] in progress  [ ] pending
 
 🐜 /ant:phase <id> for details
 ```
+
+### Step 4: Update Handoff (Optional)
+
+After displaying phase details, offer to update the handoff document with review notes:
+
+Use AskUserQuestion:
+```
+Update handoff with phase review notes?
+
+1. Yes — add notes about blockers or decisions
+2. No — continue without updating
+```
+
+If option 1 selected:
+Use AskUserQuestion to collect notes, then append to handoff:
+
+```bash
+cat >> .aether/HANDOFF.md << 'HANDOFF_EOF'
+
+## Phase {id} Review Notes
+- Reviewed: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+- Notes: {user_notes}
+HANDOFF_EOF
+```
+
+Display: `Handoff updated with review notes.`