aether-colony 3.1.4 → 3.1.15

package/.claude/commands/ant/build.md

@@ -53,22 +53,24 @@ After displaying context, run: `bash .aether/aether-utils.sh unload-state` to re
 1. Extract the phase number (first argument)
 2. Check remaining arguments for flags:
    - If contains `--verbose` or `-v`: set `verbose_mode = true`
+   - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
    - If contains `--model <name>` or `-m <name>`: set `cli_model_override = <name>`
-   - Otherwise: set defaults
+   - Otherwise: set `visual_mode = true` (visual is default)
 
 If the phase number is empty or not a number:
 
 ```
-Usage: /ant:build <phase_number> [--verbose|-v] [--model <model>|-m <model>]
+Usage: /ant:build <phase_number> [--verbose|-v] [--no-visual] [--model <model>|-m <model>]
 
 Options:
   --verbose, -v       Show full completion details (spawn tree, TDD, patterns)
+  --no-visual         Disable real-time visual display (visual is on by default)
   --model, -m <name>  Override model for this build (one-time)
 
 Examples:
-  /ant:build 1              Build Phase 1 (compact output)
-  /ant:build 1 --verbose    Build Phase 1 (full details)
-  /ant:build 3 -v           Build Phase 3 (full details)
+  /ant:build 1              Build Phase 1 (with visual display)
+  /ant:build 1 --verbose    Build Phase 1 (full details + visual)
+  /ant:build 1 --no-visual  Build Phase 1 without visual display
   /ant:build 1 --model glm-5    Build Phase 1 with glm-5 for all workers
 ```
 
@@ -189,7 +191,90 @@ If file doesn't exist or is empty:
 CONSTRAINTS: (none)
 ```
 
-### Step 4.5: Archaeologist Pre-Build Scan
+### Step 4.0: Load Territory Survey
+
+Check if territory survey exists and load relevant documents:
+
+```bash
+bash .aether/aether-utils.sh survey-load "{phase_name}" 2>/dev/null
+```
+
+**Parse the JSON response:**
+- If `.ok` is false: Set `survey_docs = null` and skip survey loading
+- If successful: Extract `.docs` (comma-separated list) and `.dir`
+
+**Determine phase type from phase name:**
+| Phase Contains | Documents to Load |
+|----------------|-------------------|
+| UI, frontend, component, button, page | DISCIPLINES.md, CHAMBERS.md |
+| API, endpoint, backend, route | BLUEPRINT.md, DISCIPLINES.md |
+| database, schema, model, migration | BLUEPRINT.md, PROVISIONS.md |
+| test, spec, coverage | SENTINEL-PROTOCOLS.md, DISCIPLINES.md |
+| integration, external, client | TRAILS.md, PROVISIONS.md |
+| refactor, cleanup, debt | PATHOGENS.md, BLUEPRINT.md |
+| setup, config, initialize | PROVISIONS.md, CHAMBERS.md |
+| *default* | PROVISIONS.md, BLUEPRINT.md |
+
+**Read the relevant survey documents** from `.aether/data/survey/`:
+- Extract key patterns to follow
+- Note file locations for new code
+- Identify known concerns to avoid
+
+**Display summary:**
+```
+🗺️ SURVEY LOADED
+================
+{for each doc loaded}
+  {emoji} {filename} — {brief description}
+{/for}
+
+{if no survey}
+  (No territory survey — run /ant:colonize for deeper context)
+{/if}
+```
+
+**Store for builder injection:**
+- `survey_patterns` — patterns to follow
+- `survey_locations` — where to place files
+- `survey_concerns` — concerns to avoid
+
+### Step 4.1: Load QUEEN.md Wisdom
+
+Call `queen-read` to extract eternal wisdom for worker priming:
+
+```bash
+bash .aether/aether-utils.sh queen-read 2>/dev/null
+```
+
+**Parse the JSON response:**
+- If `.ok` is false or command fails: Set `queen_wisdom = null` and skip wisdom injection
+- If successful: Extract wisdom sections from `.result.wisdom`
+
+**Store wisdom variables:**
+```
+queen_philosophies = .result.wisdom.philosophies (if .result.priming.has_philosophies)
+queen_patterns = .result.wisdom.patterns (if .result.priming.has_patterns)
+queen_redirects = .result.wisdom.redirects (if .result.priming.has_redirects)
+queen_stack_wisdom = .result.wisdom.stack_wisdom (if .result.priming.has_stack_wisdom)
+queen_decrees = .result.wisdom.decrees (if .result.priming.has_decrees)
+```
+
+**Display summary (if any wisdom exists):**
+```
+📜 QUEEN WISDOM LOADED
+=====================
+{if queen_philosophies:}  📜 Philosophies: yes{/if}
+{if queen_patterns:}  🧭 Patterns: yes{/if}
+{if queen_redirects:}  ⚠️ Redirects: yes{/if}
+{if queen_stack_wisdom:}  🔧 Stack Wisdom: yes{/if}
+{if queen_decrees:}  🏛️ Decrees: yes{/if}
+
+{if none exist:}  (no eternal wisdom recorded yet){/if}
+```
+
+**Graceful handling:** If QUEEN.md doesn't exist or `queen-read` fails, continue without wisdom injection. Workers will receive standard prompts.
+
+### Step 4.2: Archaeologist Pre-Build Scan
 
 **Conditional step — only fires when the phase modifies existing files.**
 
@@ -214,46 +299,35 @@ CONSTRAINTS: (none)
 
    Display:
    ```
-   🏺 Spawning Archaeologist: {archaeologist_name}
-      Scanning history of files to be modified...
+   🏺🐜 Archaeologist {archaeologist_name} spawning
+       Scanning history of files to be modified...
    ```
 
-   Spawn a Scout (using Task tool with `subagent_type="general"`) with this prompt:
+   Spawn a Scout (using Task tool with `subagent_type="aether-archaeologist"`) with this prompt:
+   # FALLBACK: If "Agent type not found", use general-purpose and inject role: "You are an Archaeologist Ant - git historian that excavates why code exists."
 
    ```
-   You are {Archaeologist-Name}, a 🏺 Archaeologist Ant (Scout) in the Aether Colony.
-
-   --- YOUR MISSION ---
-   Perform a pre-build archaeology scan on files that are about to be modified.
-
-   --- FILES TO INVESTIGATE ---
-   {list of existing files that will be modified by this phase's tasks}
-
-   --- INSTRUCTIONS ---
-   For each file:
-   1. Read the file to understand its current state
-   2. Run: git log --oneline -15 -- "{file_path}" to see recent history
-   3. Run: git log --all --grep="fix\|bug\|workaround\|hack\|revert" --oneline -- "{file_path}" to find incident history
-   4. Run: git blame "{file_path}" | head -40 to see authorship of key sections
-   5. Note any TODO/FIXME/HACK markers in the current code
-
-   --- MODEL CONTEXT ---
-   Assigned model: {model} (from caste: archaeologist)
-   This ant is running as: {Ant-Name} (archaeologist caste)
-
-   --- OUTPUT ---
-   For each file, report:
-   - WHY key code sections exist (from commit messages)
-   - Known workarounds or hacks that must not be broken
-   - Key architectural decisions visible in history
-   - Areas of caution (high churn, reverted changes, emergency fixes)
-   - Sections that are stable bedrock vs volatile sand
-
-   Include in your header:
-   Model: {model} | Caste: archaeologist | Ant: {Ant-Name}
-
-   Keep the report concise and actionable — builders need quick context, not a thesis.
-   Format as plain text with file headers. No JSON output needed.
+   You are {Archaeologist-Name}, a 🏺🐜 Archaeologist Ant.
+
+   Mission: Pre-build archaeology scan
+
+   Files: {list of existing files that will be modified}
+
+   Work:
+   1. Read each file to understand current state
+   2. Run: git log --oneline -15 -- "{file_path}" for history
+   3. Run: git log --all --grep="fix\|bug\|workaround\|hack\|revert" --oneline -- "{file_path}" for incident history
+   4. Run: git blame "{file_path}" | head -40 for authorship
+   5. Note TODO/FIXME/HACK markers
+
+   Log activity: bash .aether/aether-utils.sh activity-log "READ" "{Ant-Name}" "description"
+
+   Report (plain text):
+   - WHY key code sections exist (from commits)
+   - Known workarounds/hacks to preserve
+   - Key architectural decisions
+   - Areas of caution (high churn, reverts, emergencies)
+   - Stable bedrock vs volatile sand sections
    ```
 
    **Wait for results** (blocking — use TaskOutput with `block: true`).
@@ -279,6 +353,8 @@ CONSTRAINTS: (none)
    The `archaeology_context` will be injected into builder prompts in Step 5.1 (see below).
    If this step was skipped (no existing files modified), the archaeology section is omitted from builder prompts.
 
+---
+
 ### Step 5: Initialize Swarm Display and Analyze Tasks
 
 **YOU (the Queen) will spawn workers directly. Do NOT delegate to a single Prime Worker.**
@@ -300,12 +376,12 @@ bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "
 
 **Show real-time display header:**
 ```
-🔨🐜 COLONY BUILD INITIATED 🐜🔨
+🔨  COLONY BUILD INITIATED
 ═══════════════════════════════════════════════════
 Phase {id}: {name}
 Build ID: {build_id}
 
-Launching swarm display... (visual tracking enabled)
+Launching swarm display...
 ```
 
 Analyze the phase tasks:
@@ -318,10 +394,10 @@ Analyze the phase tasks:
    - **Wave 3+:** Continue until all tasks assigned
 
 2. **Assign castes:**
-   - Implementation tasks → 🔨 Builder
-   - Research/docs tasks → 🔍 Scout
-   - Testing/validation → 👁️ Watcher (ALWAYS spawn at least one)
-   - Resilience testing → 🎲 Chaos (ALWAYS spawn one after Watcher)
+   - Implementation tasks → 🔨🐜 Builder
+   - Research/docs tasks → 🔍🐜 Scout
+   - Testing/validation → 👁️🐜 Watcher (ALWAYS spawn at least one)
+   - Resilience testing → 🎲🐜 Chaos (ALWAYS spawn one after Watcher)
 
 3. **Generate ant names for each worker:**
 ```bash
@@ -330,154 +406,130 @@ bash .aether/aether-utils.sh generate-ant-name "watcher"
 bash .aether/aether-utils.sh generate-ant-name "chaos"
 ```
 
-Display spawn plan:
+Display spawn plan with caste emojis:
 ```
-🐜 SPAWN PLAN
-=============
-Wave 1 (parallel):
-  🔨{Builder-Name}: Task {id} - {description}
-  🔨{Builder-Name}: Task {id} - {description}
+🐜  SPAWN PLAN
 
-Wave 2 (after Wave 1):
-  🔨{Builder-Name}: Task {id} - {description}
+Wave 1  — Parallel
+  🔨🐜 {Builder-Name}  Task {id}  {description}
+  🔨🐜 {Builder-Name}  Task {id}  {description}
 
-Verification:
-  👁️{Watcher-Name}: Verify all work independently
-  🎲{Chaos-Name}: Resilience testing (after Watcher)
+Wave 2  — After Wave 1
+  🔨🐜 {Builder-Name}  Task {id}  {description}
+
+Verification
+  👁️🐜 {Watcher-Name}  Verify all work independently
+  🎲🐜 {Chaos-Name}   Resilience testing (after Watcher)
 
 Total: {N} Builders + 1 Watcher + 1 Chaos = {N+2} spawns
 ```
 
+**Caste Emoji Legend:**
+- 🔨🐜 Builder  (cyan if color enabled)
+- 👁️🐜 Watcher  (green if color enabled)
+- 🎲🐜 Chaos    (red if color enabled)
+- 🔍🐜 Scout    (yellow if color enabled)
+- 🏺🐜 Archaeologist (magenta if color enabled)
+- 🥚 Queen/Prime
+
+**Every spawn must show its caste emoji.**
+
 ### Step 5.1: Spawn Wave 1 Workers (Parallel)
 
 **CRITICAL: Spawn ALL Wave 1 workers in a SINGLE message using multiple Task tool calls.**
 
-For each Wave 1 task, use Task tool with `subagent_type="general"` and `run_in_background: true`:
+**First, mark build start in context:**
+```bash
+bash .aether/aether-utils.sh context-update build-start {phase_id} {wave_1_worker_count} {wave_1_task_count}
+```
+
+For each Wave 1 task, use Task tool with `subagent_type="aether-builder"` (DO NOT use run_in_background - multiple Task calls in a single message run in parallel and block until complete):
 
 Log each spawn and update swarm display:
 ```bash
 bash .aether/aether-utils.sh spawn-log "Queen" "builder" "{ant_name}" "{task_description}"
 bash .aether/aether-utils.sh swarm-display-update "{ant_name}" "builder" "excavating" "{task_description}" "Queen" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 10
+bash .aether/aether-utils.sh context-update worker-spawn "{ant_name}" "builder" "{task_description}"
 ```
 
-**Builder Worker Prompt Template:**
+**Builder Worker Prompt (CLEAN OUTPUT):**
 ```
-You are {Ant-Name}, a 🔨 Builder Ant in the Aether Colony at depth {depth}.
+You are {Ant-Name}, a 🔨🐜 Builder Ant.
 
---- YOUR TASK ---
 Task {id}: {description}
 
---- CONTEXT ---
 Goal: "{colony_goal}"
-Phase: {phase_name}
-
---- CONSTRAINTS ---
-{constraints from Step 4}
-
---- COLONY KNOWLEDGE ---
-{Include this section ONLY if memory.instincts or memory.phase_learnings exist in COLONY_STATE.json.}
-
-Top Instincts (proven patterns — follow these):
-{For each instinct in memory.instincts where confidence >= 0.5, sorted by confidence descending, max 5:}
-  [{confidence}] {trigger} → {action}
-{If none qualify: omit this sub-section}
 
-Recent Learnings:
-{For each learning in memory.phase_learnings (last 3 phases only) where status == "validated":}
-  - {claim}
-{If none qualify: omit this sub-section}
+{ archaeology_context if exists }
 
-Error Patterns to Avoid:
-{For each pattern in errors.flagged_patterns:}
-  ⚠️ {description}
-{If none: omit this sub-section}
+{ queen_wisdom_section if any wisdom exists }
 
-{If archaeology_context exists (Step 4.5 produced findings):}
---- ARCHAEOLOGY CONTEXT ---
-The following historical insights were discovered about files you will modify:
-{archaeology_context findings}
-{End if — omit this entire section if Step 4.5 was skipped}
-
---- INSTRUCTIONS ---
+Work:
 1. Read .aether/workers.md for Builder discipline
-2. Implement the task completely
-3. Write actual test files (not just claims)
-4. Log your work: bash .aether/aether-utils.sh activity-log "CREATED" "{ant_name} (Builder)" "{file_path}"
-5. Before modifying any file, check for grave markers:
-   bash .aether/aether-utils.sh grave-check "{file_path}"
-   If caution_level is "high": read the failure_summary, add extra test coverage for that area, mention the graveyard in your summary
-   If caution_level is "low": note it and proceed carefully
-   If caution_level is "none": proceed normally
-
---- SPAWN CAPABILITY ---
-You are at depth {depth}. You MAY spawn sub-workers if you encounter genuine surprise (3x expected complexity).
-
-Spawn limits by depth:
-- Depth 1: max 4 spawns
-- Depth 2: max 2 spawns
-- Depth 3: NO spawns (complete inline)
-
-When to spawn:
-- Task is 3x larger than expected
-- Discovered sub-domain requiring different expertise
-- Found blocking dependency needing parallel investigation
-
-DO NOT spawn for work you can complete in < 10 tool calls.
-
-Before spawning:
-  1. Check: bash .aether/aether-utils.sh spawn-can-spawn {depth}
-  2. Generate name: bash .aether/aether-utils.sh generate-ant-name "{caste}"
-  3. Log spawn: bash .aether/aether-utils.sh spawn-log "{your_name}" "{caste}" "{child_name}" "{task}"
-  4. Update swarm display: bash .aether/aether-utils.sh swarm-display-update "{child_name}" "{caste}" "excavating" "{task}" "{your_name}" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 10
-  5. Use Task tool with subagent_type="general"
-  6. After completion:
-     - Log completion: bash .aether/aether-utils.sh spawn-complete "{child_name}" "{status}" "{summary}"
-     - Update swarm display: bash .aether/aether-utils.sh swarm-display-update "{child_name}" "{caste}" "completed" "{task}" "{your_name}" '{"read":5,"grep":3,"edit":2,"bash":1}' 100 "fungus_garden" 100
-
-Full spawn format: .aether/workers.md section "Spawning Sub-Workers"
-
---- OUTPUT ---
-Return JSON:
-{
-  "ant_name": "{your name}",
-  "task_id": "{task_id}",
-  "status": "completed" | "failed" | "blocked",
-  "summary": "What you accomplished",
-  "files_created": [],
-  "files_modified": [],
-  "tests_written": [],
-  "blockers": [],
-  "spawns": [],
-  "model_context": {
-    "assigned": "{model}",
-    "caste": "builder",
-    "source": "caste-default",
-    "reported_at": "ISO-8601 timestamp"
-  }
-}
+2. Implement task, write tests
+3. Log activity: bash .aether/aether-utils.sh activity-log "ACTION" "{Ant-Name}" "description"
+4. Update display: bash .aether/aether-utils.sh swarm-display-update "{Ant-Name}" "builder" "excavating" "current task" "Queen" '{"read":0,"grep":0,"edit":0,"bash":0}' {progress} "fungus_garden" 50
+
+Spawn sub-workers ONLY if 3x complexity:
+- Check: bash .aether/aether-utils.sh spawn-can-spawn {depth}
+- Generate name: bash .aether/aether-utils.sh generate-ant-name "builder"
+- Announce: "🐜 Spawning {child_name} for {reason}"
+- Log: bash .aether/aether-utils.sh spawn-log "{Ant-Name}" "builder" "{child_name}" "{task}"
+
+Return ONLY this JSON (no other text):
+{"ant_name": "{Ant-Name}", "task_id": "{id}", "status": "completed|failed|blocked", "summary": "What you did", "files_created": [], "files_modified": [], "tests_written": [], "blockers": []}
 ```
 
-### Step 5.2: Collect Wave 1 Results (BLOCKING)
+**Queen Wisdom Section Template (injected only if wisdom exists):**
+```
+--- QUEEN WISDOM (Eternal Guidance) ---
+{ if queen_philosophies: }
+📜 Philosophies:
+{queen_philosophies}
+{ endif }
+{ if queen_patterns: }
+🧭 Patterns:
+{queen_patterns}
+{ endif }
+{ if queen_redirects: }
+⚠️ Redirects (AVOID these):
+{queen_redirects}
+{ endif }
+{ if queen_stack_wisdom: }
+🔧 Stack Wisdom:
+{queen_stack_wisdom}
+{ endif }
+{ if queen_decrees: }
+🏛️ Decrees:
+{queen_decrees}
+{ endif }
+--- END QUEEN WISDOM ---
+```
 
-**CRITICAL: You MUST wait for ALL Wave 1 workers to complete before proceeding.**
+### Step 5.2: Process Wave 1 Results
 
-For each spawned worker, call TaskOutput with `block: true` to wait for completion:
-- Use the task_id from each Task tool response
-- Do NOT proceed to Step 5.3 until ALL workers have returned results
-- Parse each worker's JSON output to collect: status, files_created, files_modified, blockers
+**Task calls return results directly (no TaskOutput needed).**
 
-Store all results for synthesis in Step 5.6.
+**As each worker result arrives, immediately display:**
+```
+✅ 🔨🐜 {Builder-Name} completed Task {id}
+   📖{read_count} 🔍{grep_count} ✏️{edit_count} ⚡{bash_count}  {elapsed_time}
+```
 
-For each completed worker, log and update swarm display:
+Log and update swarm display:
 ```bash
 bash .aether/aether-utils.sh spawn-complete "{ant_name}" "completed" "{summary}"
 bash .aether/aether-utils.sh swarm-display-update "{ant_name}" "builder" "completed" "{task_description}" "Queen" '{"read":5,"grep":3,"edit":2,"bash":1}' 100 "fungus_garden" 100
+bash .aether/aether-utils.sh context-update worker-complete "{ant_name}" "completed"
 ```
 
-**Update swarm display with accumulated tool usage:**
-As workers complete, accumulate their actual tool usage (Read, Grep, Edit, Bash counts from their activity logs) and update the swarm display to show live progress.
+**Parse each worker's JSON output to collect:** status, files_created, files_modified, blockers
 
-**Only proceed to Step 5.3 after ALL Wave 1 TaskOutput calls have returned.**
+**Visual Mode: Render live display (if enabled):**
+If `visual_mode` is true, render the swarm display after all workers complete:
+```bash
+bash .aether/aether-utils.sh swarm-display-render "$build_id"
+```
 
 ### Step 5.3: Spawn Wave 2+ Workers (Sequential Waves)
 
@@ -487,129 +539,51 @@ Repeat Step 5.1-5.2 for each subsequent wave, waiting for previous wave to compl
 
 **MANDATORY: Always spawn a Watcher — testing must be independent.**
 
+Spawn the Watcher using Task tool with `subagent_type="aether-watcher"` (DO NOT use run_in_background - task blocks until complete):
+
 ```bash
 bash .aether/aether-utils.sh spawn-log "Queen" "watcher" "{watcher_name}" "Independent verification"
 bash .aether/aether-utils.sh swarm-display-update "{watcher_name}" "watcher" "observing" "Verification in progress" "Queen" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "nursery" 50
 ```
 
-**Watcher Worker Prompt:**
+**Watcher Worker Prompt (CLEAN OUTPUT):**
 ```
-You are {Watcher-Name}, a 👁️ Watcher Ant in the Aether Colony at depth {depth}.
-
---- YOUR MISSION ---
-Independently verify all work done by Builders in Phase {id}.
-
---- MODEL CONTEXT ---
-Optimal model for verification: {model} (from caste: watcher)
-Model characteristics: Efficient validation and testing model
-Verification focus: Quick, thorough checks with fast turnaround
-
---- WHAT TO VERIFY ---
-Files created: {list from builder results}
-Files modified: {list from builder results}
+You are {Watcher-Name}, a 👁️🐜 Watcher Ant.
 
---- COMMAND RESOLUTION ---
-Resolve build, test, type-check, and lint commands using this priority chain (stop at first match per command):
-1. **CLAUDE.md** — Check project CLAUDE.md (in your system context) for explicit commands
-2. **CODEBASE.md** — Read `.planning/CODEBASE.md` `## Commands` section
-3. **Fallback** — Use language-specific examples below (Execution Verification section)
+Verify all work done by Builders in Phase {id}.
 
-Use resolved commands for all verification steps below.
+Files to verify:
+- Created: {list from builder results}
+- Modified: {list from builder results}
 
---- VERIFICATION CHECKLIST ---
-1. Do the files exist? (Read each one)
-2. Does the code compile/parse? (Run build command)
-3. Do tests exist AND pass? (Run test command)
-4. Are success criteria met? {list success_criteria}
-
---- EXECUTION VERIFICATION (MANDATORY) ---
-Before assigning a quality score, you MUST attempt to execute the code:
-
-1. Syntax check: Run the language's syntax checker
-   - Python: `python3 -m py_compile {file}`
-   - Swift: `swiftc -parse {file}`
-   - TypeScript: `npx tsc --noEmit`
-
-2. Import check: Verify main entry point can be imported
-   - Python: `python3 -c "import {module}"`
-   - Node: `node -e "require('{entry}')"`
-
-3. Launch test: Attempt to start the application briefly
-   - Run main entry point with timeout
-   - If GUI, try headless mode if possible
-   - If launches successfully = pass
-   - If crashes = CRITICAL severity
-
-4. Test suite: If tests exist, run them
-   - Record pass/fail counts
-
-CRITICAL: If ANY execution check fails, quality_score CANNOT exceed 6/10.
-
---- SPAWN CAPABILITY ---
-You are at depth {depth}. You MAY spawn sub-workers for:
-- Deep investigation of suspicious code patterns
-- Parallel verification of independent components
-- Debugging assistance for complex failures
-
-Spawn limits: Depth 1→4, Depth 2→2, Depth 3→0
-
-Before spawning:
-  1. Log spawn: bash .aether/aether-utils.sh spawn-log "{your_name}" "{caste}" "{child_name}" "{task}"
-  2. Update swarm display: bash .aether/aether-utils.sh swarm-display-update "{child_name}" "{caste}" "observing" "{task}" "{your_name}" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "nursery" 50
-  3. After completion: bash .aether/aether-utils.sh swarm-display-update "{child_name}" "{caste}" "completed" "{task}" "{your_name}" '{"read":3,"grep":2,"edit":0,"bash":0}' 100 "nursery" 100
+Verification:
+1. Check files exist (Read each)
+2. Run build/type-check
+3. Run tests if they exist
+4. Check success criteria: {list}
 
---- CRITICAL ---
-- You did NOT build this code — verify it objectively
-- "Build passing" is NOT enough — check runtime execution
-- Be skeptical — Builders may have cut corners
+Spawn sub-workers if needed:
+- Log: bash .aether/aether-utils.sh spawn-log "{Watcher-Name}" "watcher" "{child}" "{task}"
+- Announce: "🐜 Spawning {child} to investigate {issue}"
 
---- OUTPUT ---
-Return JSON:
-{
-  "ant_name": "{your name}",
-  "verification_passed": true | false,
-  "files_verified": [],
-  "execution_verification": {
-    "syntax_check": {"command": "...", "passed": true|false},
-    "import_check": {"command": "...", "passed": true|false},
-    "launch_test": {"command": "...", "passed": true|false, "error": null},
-    "test_suite": {"command": "...", "passed": N, "failed": N}
-  },
-  "build_result": {"command": "...", "passed": true|false},
-  "test_result": {"command": "...", "passed": N, "failed": N},
-  "success_criteria_results": [
-    {"criterion": "...", "passed": true|false, "evidence": "..."}
-  ],
-  "issues_found": [],
-  "quality_score": N,
-  "recommendation": "proceed" | "fix_required",
-  "spawns": [],
-  "model_context": {
-    "assigned": "{model}",
-    "caste": "watcher",
-    "source": "caste-default",
-    "reported_at": "ISO-8601 timestamp"
-  }
-}
+Return ONLY this JSON:
+{"ant_name": "{Watcher-Name}", "verification_passed": true|false, "files_verified": [], "issues_found": [], "quality_score": N, "recommendation": "proceed|fix_required"}
 ```
 
-### Step 5.4.1: Collect Watcher Results (BLOCKING)
+### Step 5.5: Process Watcher Results
 
-**CRITICAL: You MUST wait for the Watcher to complete before proceeding.**
+**Task call returns results directly (no TaskOutput needed).**
 
-Call TaskOutput with `block: true` using the Watcher's task_id:
-- Wait for the Watcher's JSON response
-- Parse: verification_passed, issues_found, quality_score, recommendation
-- Store results for synthesis in Step 5.6
+**Parse the Watcher's JSON response:** verification_passed, issues_found, quality_score, recommendation
+
+**Store results for synthesis in Step 5.7**
 
 **Update swarm display when Watcher completes:**
 ```bash
 bash .aether/aether-utils.sh swarm-display-update "{watcher_name}" "watcher" "completed" "Verification complete" "Queen" '{"read":3,"grep":2,"edit":0,"bash":1}' 100 "nursery" 100
 ```
 
-**Only proceed to Step 5.4.2 after Watcher TaskOutput has returned.**
-
-### Step 5.4.2: Spawn Chaos Ant for Resilience Testing
+### Step 5.6: Spawn Chaos Ant for Resilience Testing
 
 **After the Watcher completes, spawn a Chaos Ant to probe the phase work for edge cases and boundary conditions.**
 
@@ -626,69 +600,36 @@ bash .aether/aether-utils.sh flag-list --phase {phase_number}
 ```
 Parse the result and extract unresolved flag titles into a list: `{existing_flag_titles}` (comma-separated titles from `.result.flags[].title`). If no flags exist, set `{existing_flag_titles}` to "None".
 
-Spawn the Chaos Ant using Task tool with `subagent_type="general"`:
+Spawn the Chaos Ant using Task tool with `subagent_type="aether-chaos"` (DO NOT use run_in_background - task blocks until complete):
+# FALLBACK: If "Agent type not found", use general-purpose and inject role: "You are a Chaos Ant - resilience tester that probes edge cases and boundary conditions."
 
-**Chaos Ant Prompt:**
+**Chaos Ant Prompt (CLEAN OUTPUT):**
 ```
-You are {Chaos-Name}, a 🎲 Chaos Ant (Resilience Tester) in the Aether Colony at depth {depth}.
+You are {Chaos-Name}, a 🎲🐜 Chaos Ant.
 
---- YOUR MISSION ---
-Probe the work done by Builders in Phase {id} for edge cases, boundary conditions, and unexpected inputs.
+Test Phase {id} work for edge cases and boundary conditions.
 
---- MODEL CONTEXT ---
-Optimal model for chaos testing: {model} (from caste: chaos)
-Model characteristics: Efficient edge case exploration
-Testing focus: Rapid probing of boundaries and edge cases
+Files to test:
+- {list from builder results}
 
---- SCOPE ---
-Files created: {list from builder results}
-Files modified: {list from builder results}
+Skip these known issues: {existing_flag_titles}
 
---- EXISTING FLAGS (already known — do NOT re-report) ---
-{existing_flag_titles}
-These issues have already been flagged. Do NOT report findings that duplicate or overlap with the above titles. Focus your 5 scenarios on NEW, undiscovered issues only.
+Rules:
+- Max 5 scenarios
+- Read-only (don't modify code)
+- Focus: edge cases, boundaries, error handling
 
---- RULES ---
-1. Limit to 5 edge case scenarios maximum
-2. You are a TESTER, not an attacker — use investigating/probing language
-3. Do NOT modify any code — read-only analysis
-4. Focus on: edge cases, boundary conditions, error handling gaps, state corruption risks, unexpected inputs
-5. Do NOT re-report issues listed in EXISTING FLAGS above — skip any finding that substantially overlaps with a known flag
-
---- OUTPUT ---
-Return JSON:
-{
-  "ant_name": "{your name}",
-  "scenarios_tested": 5,
-  "findings": [
-    {
-      "id": 1,
-      "category": "edge_case|boundary|error_handling|state|unexpected_input",
-      "severity": "critical|high|medium|low|info",
-      "title": "...",
-      "description": "...",
-      "reproduction_steps": ["..."],
-      "affected_files": ["..."],
-      "recommendation": "..."
-    }
-  ],
-  "overall_resilience": "strong|moderate|weak",
-  "summary": "...",
-  "model_context": {
-    "assigned": "{model}",
-    "caste": "chaos",
-    "source": "caste-default",
-    "reported_at": "ISO-8601 timestamp"
-  }
-}
+Return ONLY this JSON:
+{"ant_name": "{Chaos-Name}", "scenarios_tested": 5, "findings": [{"id": 1, "category": "edge_case|boundary|error_handling", "severity": "critical|high|medium|low", "title": "...", "description": "..."}], "overall_resilience": "strong|moderate|weak", "summary": "..."}
 ```
 
-**Collect Chaos Ant results (BLOCKING):**
+### Step 5.7: Process Chaos Ant Results
 
-Call TaskOutput with `block: true` using the Chaos Ant's task_id:
-- Wait for the Chaos Ant's JSON response
-- Parse: findings, overall_resilience, summary
-- Store results for synthesis in Step 5.6
+**Task call returns results directly (no TaskOutput needed).**
+
+**Parse the Chaos Ant's JSON response:** findings, overall_resilience, summary
+
+**Store results for synthesis in Step 5.9**
 
 **Flag critical/high findings:**
 
@@ -709,9 +650,7 @@ bash .aether/aether-utils.sh spawn-complete "{chaos_name}" "completed" "{summary
 bash .aether/aether-utils.sh swarm-display-update "{chaos_name}" "chaos" "completed" "Resilience testing done" "Queen" '{"read":2,"grep":1,"edit":0,"bash":0}' 100 "refuse_pile" 100
 ```
 
-**Only proceed to Step 5.5 after Chaos Ant TaskOutput has returned.**
-
-### Step 5.5: Create Flags for Verification Failures
+### Step 5.8: Create Flags for Verification Failures
 
 If the Watcher reported `verification_passed: false` or `recommendation: "fix_required"`:
 
@@ -726,11 +665,11 @@ Log the flag creation:
 bash .aether/aether-utils.sh activity-log "FLAG" "Watcher" "Created blocker: {issue_title}"
 ```
 
-This ensures verification failures are persisted as blockers that survive context resets. Chaos Ant findings are flagged in Step 5.4.2.
+This ensures verification failures are persisted as blockers that survive context resets. Chaos Ant findings are flagged in Step 5.7.
 
-### Step 5.6: Synthesize Results
+### Step 5.9: Synthesize Results
 
-**This step runs ONLY after ALL TaskOutput calls have returned (Steps 5.2, 5.3, 5.4.1, 5.4.2).**
+**This step runs after all worker tasks have completed (Builders, Watcher, Chaos).**
 
 Collect all worker outputs and create phase summary:
 
@@ -774,6 +713,39 @@ bash .aether/aether-utils.sh grave-add "{file}" "{ant_name}" "{task_id}" {phase}
 bash .aether/aether-utils.sh activity-log "GRAVE" "Queen" "Grave marker placed at {file} — {ant_name} failed: {summary}"
 ```
 
+**Error Handoff Update:**
+If workers failed, update handoff with error context for recovery:
+```bash
+cat > .aether/HANDOFF.md << 'HANDOFF_EOF'
+# Colony Session — Build Errors
+
+## ⚠️ Build Status: ISSUES DETECTED
+**Phase:** {phase_number} — {phase_name}
+**Status:** Build completed with failures
+**Updated:** $(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+## Failed Workers
+{for each failed worker:}
+- {ant_name}: {failure_summary}
+{end for}
+
+## Grave Markers Placed
+{for each grave:}
+- {file}: {caution_level} caution
+{end for}
+
+## Recovery Options
+1. Review failures: Check `.aether/data/activity.log`
+2. Fix and retry: `/ant:build {phase_number}`
+3. Swarm fix: `/ant:swarm` for auto-repair
+4. Manual fix: Address issues, then `/ant:continue`
+
+## Session Note
+Build completed but workers failed. Grave markers placed.
+Review failures before advancing.
+HANDOFF_EOF
+```
+
 Only fires when workers fail. Zero impact on successful builds.
 
 --- SPAWN TRACKING ---
@@ -868,6 +840,89 @@ Use AskUserQuestion to get approval. Record in events:
 - If approved: `"<timestamp>|visual_approved|build|Phase {id} UI approved"`
 - If rejected: `"<timestamp>|visual_rejected|build|Phase {id} UI rejected: {reason}"`
 
+### Step 6.5: Update Handoff Document
+
+After synthesis is complete, update the handoff document with current state for session recovery:
+
+```bash
+# Update handoff with build results
+jq -n \
+  --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  --arg goal "$(jq -r '.goal' .aether/data/COLONY_STATE.json)" \
+  --arg phase "$(jq -r '.current_phase' .aether/data/COLONY_STATE.json)" \
+  --arg phase_name "{phase_name}" \
+  --arg status "{synthesis.status}" \
+  --arg summary "{synthesis.summary}" \
+  --argjson tasks_completed '{synthesis.tasks_completed | length}' \
+  --argjson tasks_failed '{synthesis.tasks_failed | length}' \
+  --arg next_action "{if synthesis.status == "completed" then "/ant:continue" else "/ant:flags" end}" \
+  '{
+    "last_updated": $timestamp,
+    "goal": $goal,
+    "current_phase": $phase,
+    "phase_name": $phase_name,
+    "build_status": $status,
+    "summary": $summary,
+    "tasks_completed": $tasks_completed,
+    "tasks_failed": $tasks_failed,
+    "next_recommended_action": $next_action,
+    "can_resume": true,
+    "note": "Phase build completed. Run /ant:continue to advance if verification passed."
+  }' > .aether/data/last-build-result.json
+
+# Write handoff markdown
+cat > .aether/HANDOFF.md << 'HANDOFF_EOF'
+# Colony Session — Build Complete
+
+## Quick Resume
+Run `/ant:continue` to advance phase, or `/ant:resume-colony` to restore full context.
+
+## State at Build Completion
+- Goal: "$(jq -r '.goal' .aether/data/COLONY_STATE.json)"
+- Phase: {phase_number} — {phase_name}
+- Build Status: {synthesis.status}
+- Updated: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+## Build Summary
+{summary}
+
+## Tasks
+- Completed: {synthesis.tasks_completed | length}
+- Failed: {synthesis.tasks_failed | length}
+
+## Files Changed
+- Created: {synthesis.files_created | length} files
+- Modified: {synthesis.files_modified | length} files
+
+## Next Steps
+- If verification passed: `/ant:continue` to advance to next phase
+- If issues found: `/ant:flags` to review blockers
+- To pause: `/ant:pause-colony`
+
+## Session Note
+$(if synthesis.status == "completed" then "Build succeeded — ready to advance." else "Build completed with issues — review before continuing." end)
+HANDOFF_EOF
+```
+
+This ensures the handoff always reflects the latest build state, even if the session crashes before explicit pause.
+
+### Step 6.5: Update Context Document
+
+Log this build activity to `.aether/CONTEXT.md`:
+
+```bash
+bash .aether/aether-utils.sh context-update activity "build {phase_id}" "{synthesis.status}" "{files_created_count + files_modified_count}"
+```
+
+Mark build as complete in context:
+```bash
+bash .aether/aether-utils.sh context-update build-complete "{synthesis.status}" "{synthesis.status == 'completed' ? 'success' : 'failed'}"
+```
+
+Also update safe-to-clear status:
+- If build completed successfully: `context-update safe-to-clear "YES" "Build complete, ready to continue"`
+- If build failed: `context-update safe-to-clear "NO" "Build failed — run /ant:swarm or /ant:flags"`
+
 ### Step 7: Display Results
 
 **This step runs ONLY after synthesis is complete. All values come from actual worker results.**
@@ -882,7 +937,7 @@ bash .aether/aether-utils.sh swarm-display-render "$build_id"
 ```
 
 The swarm display will show:
-- 🐜 All workers with their caste emojis (🔨 Builder, 👁️ Watcher, 🎲 Chaos)
+- 🐜 All workers with their caste emojis (🔨🐜 Builder, 👁️🐜 Watcher, 🎲🐜 Chaos)
 - 📖 Tool usage stats (Read, Grep, Edit, Bash counts)
 - 🏠 Chamber activity map (Fungus Garden, Nursery, Refuse Pile)
 - ✅ Progress bars at 100% for completed work
@@ -985,3 +1040,11 @@ The swarm display will show:
 - Mark tasks as completed
 - Extract learnings
 - Advance to next phase
+
+### Step 8: Update Session
+
+Update the session tracking file to enable `/ant:resume` after context clear:
+
+```bash
+bash .aether/aether-utils.sh session-update "/ant:build {phase_id}" "/ant:continue" "Phase {phase_id} build completed: {synthesis.status}"
+```