aether-colony 3.1.17 → 5.0.0

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

@@ -9,9 +9,46 @@ The phase to build is: `$ARGUMENTS`
 
 ## Instructions
 
+<failure_modes>
+### Wave Failure Mid-Build
+If a worker fails during a build wave:
+- Do NOT continue to next wave (failed dependencies will cascade)
+- Report which worker failed, what task it was on, and what was attempted
+- Options: (1) Retry the failed task, (2) Skip and continue with remaining tasks, (3) Abort build
+
+### Partial File Writes
+If a builder crashes mid-write:
+- Check git status for uncommitted partial changes
+- If partial changes exist, offer: (1) Review and keep, (2) Revert with git checkout, (3) Stash for later
+
+### State Corruption
+If COLONY_STATE.json becomes invalid during build:
+- STOP all workers immediately
+- Do not attempt to fix state automatically
+- Report the issue and offer to restore from last known good state
+</failure_modes>
+
+<success_criteria>
+Command is complete when:
+- All waves executed in order with no skipped dependencies
+- Each worker's task output is verified (files exist, tests pass)
+- COLONY_STATE.json reflects completed phase progress
+- Build summary reports all workers' outcomes
+</success_criteria>
+
+<read_only>
+Do not touch during build:
+- .aether/dreams/ (user notes)
+- .aether/chambers/ (archived colonies)
+- .env* files
+- .claude/settings.json
+- .github/workflows/
+- Other agents' config files (only modify files assigned to the current build task)
+</read_only>
+
 ### Step 0: Version Check (Non-blocking)
 
-Run using the Bash tool: `bash .aether/aether-utils.sh version-check 2>/dev/null || true`
+Run using the Bash tool with description "Checking colony version...": `bash .aether/aether-utils.sh version-check-cached 2>/dev/null || true`
 
 If the command succeeds and the JSON result contains a non-empty string, display it as a one-line notice. Proceed regardless of outcome.
 
@@ -19,6 +56,7 @@ If the command succeeds and the JSON result contains a non-empty string, display
 
 Check that the LiteLLM proxy is running for model routing:
 
+Run using the Bash tool with description "Checking model proxy...":
 ```bash
 curl -s http://localhost:4000/health | grep -q "healthy" && echo "Proxy healthy" || echo "Proxy not running - workers will use default model"
 ```
@@ -27,7 +65,7 @@ If proxy is not healthy, log a warning but continue (workers will fall back to d
 
 ### Step 0.5: Load Colony State
 
-Run using Bash tool: `bash .aether/aether-utils.sh load-state`
+Run using the Bash tool with description "Loading colony state...": `bash .aether/aether-utils.sh load-state`
 
 If the command fails (non-zero exit or JSON has ok: false):
 1. Parse error JSON
@@ -45,7 +83,7 @@ If successful:
    ```
    (If HANDOFF.md exists, this provides orientation before the build proceeds)
 
-After displaying context, run: `bash .aether/aether-utils.sh unload-state` to release the lock.
+After displaying context, run using the Bash tool with description "Releasing colony lock...": `bash .aether/aether-utils.sh unload-state` to release the lock.
 
 ### Step 1: Validate + Read State
 
@@ -78,7 +116,7 @@ Stop here.
 
 **Validate CLI model override (if provided):**
 If `cli_model_override` is set:
-1. Validate the model: `bash .aether/aether-utils.sh model-profile validate "$cli_model_override"`
+1. Run using the Bash tool with description "Validating model override...": `bash .aether/aether-utils.sh model-profile validate "$cli_model_override"`
 2. Parse JSON result - if `.result.valid` is false:
    - Display: `Error: Invalid model "$cli_model_override"`
    - Display: `Valid models: {list from .result.models}`
@@ -107,6 +145,7 @@ Extract:
 
 Check for unresolved blocker flags on the requested phase:
 
+Run using the Bash tool with description "Checking for blockers...":
 ```bash
 bash .aether/aether-utils.sh flag-check-blockers {phase_number}
 ```
@@ -115,6 +154,7 @@ Parse the JSON result (`.result.blockers`):
 
 - **If blockers == 0:** Display nothing (or optionally a brief `No active blockers for Phase {id}.` line). Proceed to Step 2.
 - **If blockers > 0:** Retrieve blocker details:
+  Run using the Bash tool with description "Loading blocker details...":
   ```bash
   bash .aether/aether-utils.sh flag-list --type blocker --phase {phase_number}
   ```
@@ -143,21 +183,28 @@ If `events` exceeds 100 entries, keep only the last 100.
 
 Write COLONY_STATE.json.
 
+Validate the state file:
+Run using the Bash tool with description "Validating colony state...":
+```bash
+bash .aether/aether-utils.sh validate-state colony
+```
+
 ### Step 3: Git Checkpoint
 
 Create a git checkpoint for rollback capability.
 
+Run using the Bash tool with description "Checking git repository...":
 ```bash
 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 runtime bin`
-  2. **If changes exist**: `git stash push -m "aether-checkpoint: pre-phase-$PHASE_NUMBER" -- .aether .claude/commands/ant .claude/commands/st .opencode runtime bin`
+  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`
      - IMPORTANT: Never use `--include-untracked` — it stashes ALL files including user work!
-     - Verify: `git stash list | head -1 | grep "aether-checkpoint"` — warn if empty
+     - 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"}`
-  3. **If clean working tree**: Record `HEAD` hash via `git rev-parse HEAD`
+  3. **If clean working tree**: Run using the Bash tool with description "Recording HEAD position...": `git rev-parse HEAD`
      - Store checkpoint as `{type: "commit", ref: "$HEAD_HASH"}`
 - **If fails** (not a git repo): Set checkpoint to `{type: "none", ref: "(not a git repo)"}`.
 
@@ -166,13 +213,12 @@ Rollback procedure: `git stash pop` (if type is "stash") or `git reset --hard $r
 Output header:
 
 ```
-🔨🐜🏗️🐜🔨 ═══════════════════════════════════════════════════
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    B U I L D I N G   P H A S E   {id}
-═══════════════════════════════════════════════════ 🔨🐜🏗️🐜🔨
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 📍 Phase {id}: {name}
-💾 Git Checkpoint: {checkpoint_type} → {checkpoint_ref}
-🔄 Rollback: `git stash pop` (stash) or `git reset --hard {ref}` (commit)
+💾 Git checkpoint saved
 ```
 
 ### Step 4: Load Constraints
@@ -191,10 +237,31 @@ If file doesn't exist or is empty:
 CONSTRAINTS: (none)
 ```
 
+**Load pheromone context for worker injection:**
+
+Run using the Bash tool with description "Loading pheromone signals...":
+```bash
+prime_result=$(bash .aether/aether-utils.sh pheromone-prime 2>/dev/null)
+```
+
+Parse the JSON result from `.result`:
+- Extract `signal_count` (number of active signals)
+- Extract `instinct_count` (number of filtered instincts)
+- Extract `prompt_section` as `pheromone_section` variable — the formatted markdown to inject into worker prompts
+- Extract `log_line` for display
+
+Display after constraints:
+```
+{log_line from pheromone-prime}
+```
+
+If `pheromone-prime` fails, returns an error, or is unavailable: set `pheromone_section` to empty string and continue. **Builds MUST NEVER fail because pheromones are unavailable.**
+
 ### Step 4.0: Load Territory Survey
 
 Check if territory survey exists and load relevant documents:
 
+Run using the Bash tool with description "Loading territory survey...":
 ```bash
 bash .aether/aether-utils.sh survey-load "{phase_name}" 2>/dev/null
 ```
@@ -222,8 +289,7 @@ bash .aether/aether-utils.sh survey-load "{phase_name}" 2>/dev/null
 
 **Display summary:**
 ```
-🗺️ SURVEY LOADED
-================
+━━━ 🗺️🐜 S U R V E Y   L O A D E D ━━━
 {for each doc loaded}
   {emoji} {filename} — {brief description}
 {/for}
@@ -242,6 +308,7 @@ bash .aether/aether-utils.sh survey-load "{phase_name}" 2>/dev/null
 
 Call `queen-read` to extract eternal wisdom for worker priming:
 
+Run using the Bash tool with description "Loading queen wisdom...":
 ```bash
 bash .aether/aether-utils.sh queen-read 2>/dev/null
 ```
@@ -261,8 +328,7 @@ queen_decrees = .result.wisdom.decrees (if .result.priming.has_decrees)
 
 **Display summary (if any wisdom exists):**
 ```
-📜 QUEEN WISDOM LOADED
-=====================
+━━━ 📜🐜 Q U E E N   W I S D O M ━━━
 {if queen_philosophies:}  📜 Philosophies: yes{/if}
 {if queen_patterns:}  🧭 Patterns: yes{/if}
 {if queen_redirects:}  ⚠️ Redirects: yes{/if}
@@ -274,6 +340,29 @@ queen_decrees = .result.wisdom.decrees (if .result.priming.has_decrees)
 
 **Graceful handling:** If QUEEN.md doesn't exist or `queen-read` fails, continue without wisdom injection. Workers will receive standard prompts.
 
+### Step 4.1.6: Load Active Pheromones (Signal Consumption)
+
+**This injects current FOCUS and REDIRECT signals into worker context.**
+
+Call `pheromone-read` to get active signals:
+
+```bash
+bash .aether/aether-utils.sh pheromone-read 2>/dev/null
+```
+
+**Parse the JSON response:**
+- If `.ok` is false or command fails: Set `pheromone_section = null` and skip
+- If successful: Extract `.result.priorities` and `.result.avoid`
+
+**Display summary:**
+```
+━━━ 🎯🐜 A C T I V E   S I G N A L S ━━━
+Priorities (FOCUS): {N}
+Constraints (REDIRECT): {M}
+```
+
+**Store for worker injection:** The `pheromone_section` markdown will be included in builder prompts (see Step 5.1 Active Signals Section).
+
 ### Step 4.2: Archaeologist Pre-Build Scan
 
 **Conditional step — only fires when the phase modifies existing files.**
@@ -290,12 +379,9 @@ queen_decrees = .result.wisdom.decrees (if .result.priming.has_decrees)
 
 2. **If existing code modification detected — spawn Archaeologist Scout:**
 
-   Generate archaeologist name and log:
-   ```bash
-   bash .aether/aether-utils.sh generate-ant-name "archaeologist"
-   bash .aether/aether-utils.sh spawn-log "Queen" "scout" "{archaeologist_name}" "Pre-build archaeology scan"
-   bash .aether/aether-utils.sh swarm-display-update "{archaeologist_name}" "scout" "excavating" "Pre-build archaeology scan" "Queen" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 15
-   ```
+   Generate archaeologist name and dispatch:
+   Run using the Bash tool with description "Naming archaeologist...": `bash .aether/aether-utils.sh generate-ant-name "archaeologist"` (store as `{archaeologist_name}`)
+   Run using the Bash tool with description "Dispatching archaeologist...": `bash .aether/aether-utils.sh spawn-log "Queen" "scout" "{archaeologist_name}" "Pre-build archaeology scan" && bash .aether/aether-utils.sh swarm-display-update "{archaeologist_name}" "scout" "excavating" "Pre-build archaeology scan" "Queen" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 15`
 
    Display:
    ```
@@ -303,7 +389,7 @@ queen_decrees = .result.wisdom.decrees (if .result.priming.has_decrees)
        Scanning history of files to be modified...
    ```
 
-   Spawn a Scout (using Task tool with `subagent_type="aether-archaeologist"`) with this prompt:
+   Spawn a Scout (using Task tool with `subagent_type="aether-archaeologist"`, include `description: "🏺 Archaeologist {archaeologist_name}: Pre-build history scan"`) 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."
 
    ```
@@ -333,10 +419,7 @@ queen_decrees = .result.wisdom.decrees (if .result.priming.has_decrees)
    **Wait for results** (blocking — use TaskOutput with `block: true`).
 
    Log completion and update swarm display:
-   ```bash
-   bash .aether/aether-utils.sh spawn-complete "{archaeologist_name}" "completed" "Pre-build archaeology scan"
-   bash .aether/aether-utils.sh swarm-display-update "{archaeologist_name}" "scout" "completed" "Pre-build archaeology scan" "Queen" '{"read":8,"grep":5,"edit":0,"bash":2}' 100 "fungus_garden" 100
-   ```
+   Run using the Bash tool with description "Recording archaeologist findings...": `bash .aether/aether-utils.sh spawn-complete "{archaeologist_name}" "completed" "Pre-build archaeology scan" && bash .aether/aether-utils.sh swarm-display-update "{archaeologist_name}" "scout" "completed" "Pre-build archaeology scan" "Queen" '{"read":8,"grep":5,"edit":0,"bash":2}' 100 "fungus_garden" 100`
 
 3. **Store and display findings:**
 
@@ -344,8 +427,7 @@ queen_decrees = .result.wisdom.decrees (if .result.priming.has_decrees)
 
    Display summary:
    ```
-   🏺 ARCHAEOLOGY CONTEXT
-   =====================
+   ━━━ 🏺🐜 A R C H A E O L O G Y ━━━
    {summary of findings from archaeologist}
    ```
 
@@ -360,6 +442,7 @@ queen_decrees = .result.wisdom.decrees (if .result.priming.has_decrees)
 **YOU (the Queen) will spawn workers directly. Do NOT delegate to a single Prime Worker.**
 
 **Initialize visual swarm tracking:**
+Run using the Bash tool with description "Initializing build display...":
 ```bash
 # Generate unique build ID
 build_id="build-$(date +%s)"
@@ -376,14 +459,15 @@ bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "
 
 **Show real-time display header:**
 ```
-🔨  COLONY BUILD INITIATED
-═══════════════════════════════════════════════════
-Phase {id}: {name}
-Build ID: {build_id}
-
-Launching swarm display...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Phase {id}: {name} — {N} waves, {M} tasks
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+Where N = number of builder waves (excluding watcher/chaos) and M = total builder tasks.
+
+Record `build_started_at_epoch=$(date +%s)` — this epoch integer is used by the BUILD SUMMARY block in Step 7 to calculate elapsed time.
+
 Analyze the phase tasks:
 
 Analyze the phase tasks:
@@ -400,15 +484,14 @@ Analyze the phase tasks:
    - Resilience testing → 🎲🐜 Chaos (ALWAYS spawn one after Watcher)
 
 3. **Generate ant names for each worker:**
-```bash
-bash .aether/aether-utils.sh generate-ant-name "builder"
-bash .aether/aether-utils.sh generate-ant-name "watcher"
-bash .aether/aether-utils.sh generate-ant-name "chaos"
-```
+
+Run using the Bash tool with description "Naming builder ant...": `bash .aether/aether-utils.sh generate-ant-name "builder"`
+Run using the Bash tool with description "Naming watcher ant...": `bash .aether/aether-utils.sh generate-ant-name "watcher"`
+Run using the Bash tool with description "Naming chaos ant...": `bash .aether/aether-utils.sh generate-ant-name "chaos"`
 
 Display spawn plan with caste emojis:
 ```
-🐜  SPAWN PLAN
+━━━ 🐜 S P A W N   P L A N ━━━
 
 Wave 1  — Parallel
   🔨🐜 {Builder-Name}  Task {id}  {description}
@@ -434,24 +517,57 @@ Total: {N} Builders + 1 Watcher + 1 Chaos = {N+2} spawns
 
 **Every spawn must show its caste emoji.**
 
+### Step 5.0.5: Select and Announce Workflow Pattern
+
+Examine the phase name and task descriptions. Select the first matching pattern:
+
+| Phase contains | Pattern |
+|----------------|---------|
+| "bug", "fix", "error", "broken", "failing" | Investigate-Fix |
+| "research", "oracle", "explore", "investigate" | Deep Research |
+| "refactor", "restructure", "clean", "reorganize" | Refactor |
+| "security", "audit", "compliance", "accessibility", "license" | Compliance |
+| "docs", "documentation", "readme", "guide" | Documentation Sprint |
+| (default) | SPBV |
+
+Display the selected pattern:
+```
+━━ Pattern: {pattern_name} ━━
+{announce_line from Queen's Workflow Patterns definition}
+```
+
+Store `selected_pattern` for inclusion in the BUILD SUMMARY (Step 7).
+
 ### Step 5.1: Spawn Wave 1 Workers (Parallel)
 
 **CRITICAL: Spawn ALL Wave 1 workers in a SINGLE message using multiple Task tool calls.**
 
-**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}
+**Announce the wave before spawning:**
+
+Display the spawn announcement immediately before firing Task calls:
+
+For single-caste waves (typical — all builders):
+```
+──── 🔨🐜 Spawning {N} Builders in parallel ────
 ```
 
-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):
+For mixed-caste waves (uncommon):
+```
+──── 🐜 Spawning {N} workers ({X} 🔨 Builder, {Y} 🔍 Scout) ────
+```
 
-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}"
+For a single worker:
+```
+──── 🔨🐜 Spawning {ant_name} — {task_summary} ────
 ```
 
+**First, mark build start in context:**
+Run using the Bash tool with description "Marking build start...": `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"`, include `description: "🔨 Builder {Ant-Name}: {task_description}"` (DO NOT use run_in_background - multiple Task calls in a single message run in parallel and block until complete):
+
+**PER WORKER:** Run using the Bash tool with description "Preparing worker {name}...": `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 (CLEAN OUTPUT):**
 ```
 You are {Ant-Name}, a 🔨🐜 Builder Ant.
@@ -464,20 +580,39 @@ Goal: "{colony_goal}"
 
 { queen_wisdom_section if any wisdom exists }
 
+{ pheromone_section if pheromone_section is not empty }
+
+{ if pheromone_section is not empty: }
+IMPORTANT: REDIRECT signals above are HARD CONSTRAINTS. You MUST follow them. FOCUS and FEEDBACK are flexible guidance — use your judgment on relevance.
+{ end if }
+
+**IMPORTANT:** When using the Bash tool for activity calls, always include a description parameter:
+- activity-log calls → "Logging {action}..."
+- swarm-display-update calls → "Updating build display..."
+- pheromone-read calls → "Checking colony signals..."
+- spawn-can-spawn calls → "Checking spawn budget..."
+- generate-ant-name calls → "Naming sub-worker..."
+- spawn-log calls → "Dispatching sub-worker..."
+
+Use colony-flavored language, 4-8 words, trailing ellipsis.
+
 Work:
 1. Read .aether/workers.md for Builder discipline
 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
+3. Log activity using Bash tool with description
+4. Update display using Bash tool with description
+5. At natural breakpoints (between tasks, after errors): Check for new signals using Bash tool with description
 
 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"
+- Check spawn budget using Bash tool with description
+- Generate name using Bash tool with description
 - Announce: "🐜 Spawning {child_name} for {reason}"
-- Log: bash .aether/aether-utils.sh spawn-log "{Ant-Name}" "builder" "{child_name}" "{task}"
+- Log spawn using Bash tool with description
+
+Count your total tool calls (Read + Grep + Edit + Bash + Write) and report as tool_count.
 
 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": []}
+{"ant_name": "{Ant-Name}", "task_id": "{id}", "status": "completed|failed|blocked", "summary": "What you did", "tool_count": 0, "files_created": [], "files_modified": [], "tests_written": [], "blockers": []}
 ```
 
 **Queen Wisdom Section Template (injected only if wisdom exists):**
@@ -506,45 +641,130 @@ Return ONLY this JSON (no other text):
 --- END QUEEN WISDOM ---
 ```
 
+**Active Signals Section (injected if pheromones exist):**
+```
+--- ACTIVE SIGNALS (From User) ---
+
+🎯 PRIORITIES (FOCUS):
+{for each priority}
+- {priority}
+{endfor}
+
+⚠️ CONSTRAINTS (REDIRECT - AVOID):
+{for each constraint}
+- {constraint.content}
+{endfor}
+
+--- END ACTIVE SIGNALS ---
+```
+
 ### Step 5.2: Process Wave 1 Results
 
 **Task calls return results directly (no TaskOutput needed).**
 
-**As each worker result arrives, immediately display:**
+**As each worker result arrives, IMMEDIATELY display a single completion line — do not wait for other workers:**
+
+For successful workers:
 ```
-✅ 🔨🐜 {Builder-Name} completed Task {id}
-   📖{read_count} 🔍{grep_count} ✏️{edit_count} ⚡{bash_count}  {elapsed_time}
+🔨 {Ant-Name}: {task_description} ({tool_count} tools) ✓
 ```
 
-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"
+For failed workers:
+```
+🔨 {Ant-Name}: {task_description} ✗ ({failure_reason} after {tool_count} tools)
 ```
 
-**Parse each worker's JSON output to collect:** status, files_created, files_modified, blockers
+Where `tool_count` comes from the worker's returned JSON `tool_count` field, and `failure_reason` is extracted from the first item in the worker's `blockers` array or "unknown error" if empty.
 
-**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-inline "$build_id"
+**PER WORKER:** Run using the Bash tool with description "Recording {name} completion...": `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"`
+
+**Check for total wave failure:**
+
+After processing all worker results in this wave, check if EVERY worker returned `status: "failed"`. If ALL workers in the wave failed:
+
+Display a prominent halt alert:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ⚠ WAVE FAILURE — BUILD HALTED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+All {N} workers in Wave {X} failed. Something is fundamentally wrong.
+
+Failed workers:
+  {for each failed worker in this wave:}
+  {caste_emoji} {Ant-Name}: {task_description} ✗ ({failure_reason} after {tool_count} tools)
+  {end for}
+
+Next steps:
+  /ant:flags      Review blockers
+  /ant:swarm      Auto-repair mode
 ```
 
+Then STOP — do not proceed to subsequent waves, Watcher, or Chaos. Skip directly to Step 5.9 synthesis with `status: "failed"`.
+
+**Partial wave failure — escalation path:**
+
+If SOME (but not all) workers in the wave failed:
+1. For each failed worker, attempt Tier 3 escalation: Queen spawns a different caste for the same task
+2. If Tier 3 succeeds: continue to next wave
+3. If Tier 3 fails: display the Tier 4 ESCALATION banner (from Queen agent definition):
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ⚠ ESCALATION — QUEEN NEEDS YOU
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Task: {failed task description}
+Phase: {phase number} — {phase name}
+
+Tried:
+  • Worker retry (2 attempts) — {what failed}
+  • Parent tried alternate approach — {what failed}
+  • Queen reassigned to {other caste} — {what failed}
+
+Options:
+  A) {recommended option} — RECOMMENDED
+  B) {alternate option}
+  C) Skip and continue — this task will be marked blocked
+
+Awaiting your choice.
+```
+
+Log escalation as flag:
+Run using the Bash tool with description "Logging escalation...": `bash .aether/aether-utils.sh flag-add "blocker" "{task title}" "{failure summary}" "escalation" {phase_number}`
+
+If at least one worker succeeded, continue normally to the next wave.
+
+**Parse each worker's JSON output to collect:** status, files_created, files_modified, blockers
+
+**Visual Mode: Render live display (tmux only):**
+If `visual_mode` is true AND the build is running inside a tmux session (`$TMUX` environment variable is set), run using the Bash tool with description "Rendering build progress...": `bash .aether/aether-utils.sh swarm-display-text "$build_id"`
+
+If `$TMUX` is not set, skip this call entirely — do not attempt it. Chat users see the structured completion lines above instead.
+
 ### Step 5.3: Spawn Wave 2+ Workers (Sequential Waves)
 
+**Before each subsequent wave, display a wave separator:**
+```
+━━━ 🐜 Wave {X} of {N} ━━━
+```
+Then display the spawn announcement (same format as Step 5.1).
+
 Repeat Step 5.1-5.2 for each subsequent wave, waiting for previous wave to complete.
 
 ### Step 5.4: Spawn Watcher for Verification
 
 **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
+**Announce the verification wave:**
 ```
+━━━ 👁️🐜 V E R I F I C A T I O N ━━━
+──── 👁️🐜 Spawning {watcher_name} ────
+```
+
+Spawn the Watcher using Task tool with `subagent_type="aether-watcher"`, include `description: "👁️ Watcher {Watcher-Name}: Independent verification"` (DO NOT use run_in_background - task blocks until complete):
+
+Run using the Bash tool with description "Dispatching watcher...": `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 (CLEAN OUTPUT):**
 ```
@@ -556,6 +776,16 @@ Files to verify:
 - Created: {list from builder results}
 - Modified: {list from builder results}
 
+{ pheromone_section if pheromone_section is not empty }
+
+**IMPORTANT:** When using the Bash tool for activity calls, always include a description parameter:
+- activity-log calls → "Logging {action}..."
+- swarm-display-update calls → "Updating build display..."
+- pheromone-read calls → "Checking colony signals..."
+- spawn-log calls → "Dispatching sub-worker..."
+
+Use colony-flavored language, 4-8 words, trailing ellipsis.
+
 Verification:
 1. Check files exist (Read each)
 2. Run build/type-check
@@ -563,11 +793,13 @@ Verification:
 4. Check success criteria: {list}
 
 Spawn sub-workers if needed:
-- Log: bash .aether/aether-utils.sh spawn-log "{Watcher-Name}" "watcher" "{child}" "{task}"
+- Log spawn using Bash tool with description
 - Announce: "🐜 Spawning {child} to investigate {issue}"
 
+Count your total tool calls (Read + Grep + Edit + Bash + Write) and report as tool_count.
+
 Return ONLY this JSON:
-{"ant_name": "{Watcher-Name}", "verification_passed": true|false, "files_verified": [], "issues_found": [], "quality_score": N, "recommendation": "proceed|fix_required"}
+{"ant_name": "{Watcher-Name}", "verification_passed": true|false, "files_verified": [], "issues_found": [], "quality_score": N, "tool_count": 0, "recommendation": "proceed|fix_required"}
 ```
 
 ### Step 5.5: Process Watcher Results
@@ -576,31 +808,39 @@ Return ONLY this JSON:
 
 **Parse the Watcher's JSON response:** verification_passed, issues_found, quality_score, recommendation
 
+**Display Watcher completion line:**
+
+For successful verification:
+```
+👁️ {Watcher-Name}: Independent verification ({tool_count} tools) ✓
+```
+
+For failed verification:
+```
+👁️ {Watcher-Name}: Independent verification ✗ ({issues_found count} issues after {tool_count} tools)
+```
+
 **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
-```
+Run using the Bash tool with description "Recording watcher completion...": `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`
 
 ### 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.**
 
-Generate a chaos ant name and log the spawn:
-```bash
-bash .aether/aether-utils.sh generate-ant-name "chaos"
-bash .aether/aether-utils.sh spawn-log "Queen" "chaos" "{chaos_name}" "Resilience testing of Phase {id} work"
-bash .aether/aether-utils.sh swarm-display-update "{chaos_name}" "chaos" "probing" "Resilience testing" "Queen" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "refuse_pile" 75
-```
+Generate a chaos ant name and dispatch:
+Run using the Bash tool with description "Naming chaos ant...": `bash .aether/aether-utils.sh generate-ant-name "chaos"` (store as `{chaos_name}`)
+Run using the Bash tool with description "Loading existing flags...": `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".
+Run using the Bash tool with description "Dispatching chaos ant...": `bash .aether/aether-utils.sh spawn-log "Queen" "chaos" "{chaos_name}" "Resilience testing of Phase {id} work" && bash .aether/aether-utils.sh swarm-display-update "{chaos_name}" "chaos" "probing" "Resilience testing" "Queen" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "refuse_pile" 75`
 
-**Retrieve existing flags for this phase** (to avoid duplicate findings):
-```bash
-bash .aether/aether-utils.sh flag-list --phase {phase_number}
+**Announce the resilience testing wave:**
+```
+──── 🎲🐜 Spawning {chaos_name} — resilience testing ────
 ```
-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="aether-chaos"` (DO NOT use run_in_background - task blocks until complete):
+Spawn the Chaos Ant using Task tool with `subagent_type="aether-chaos"`, include `description: "🎲 Chaos {Chaos-Name}: Resilience testing"` (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 (CLEAN OUTPUT):**
@@ -614,13 +854,22 @@ Files to test:
 
 Skip these known issues: {existing_flag_titles}
 
+**IMPORTANT:** When using the Bash tool for activity calls, always include a description parameter:
+- activity-log calls → "Logging {action}..."
+- swarm-display-update calls → "Updating build display..."
+- pheromone-read calls → "Checking colony signals..."
+
+Use colony-flavored language, 4-8 words, trailing ellipsis.
+
 Rules:
 - Max 5 scenarios
 - Read-only (don't modify code)
 - Focus: edge cases, boundaries, error handling
 
+Count your total tool calls (Read + Grep + Edit + Bash + Write) and report as tool_count.
+
 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": "..."}
+{"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", "tool_count": 0, "summary": "..."}
 ```
 
 ### Step 5.7: Process Chaos Ant Results
@@ -629,41 +878,27 @@ Return ONLY this JSON:
 
 **Parse the Chaos Ant's JSON response:** findings, overall_resilience, summary
 
+**Display Chaos completion line:**
+```
+🎲 {Chaos-Name}: Resilience testing ({tool_count} tools) ✓
+```
+
 **Store results for synthesis in Step 5.9**
 
 **Flag critical/high findings:**
 
 If any findings have severity `"critical"` or `"high"`:
-```bash
-# Create a blocker flag for each critical/high chaos finding
-bash .aether/aether-utils.sh flag-add "blocker" "{finding.title}" "{finding.description}" "chaos-testing" {phase_number}
-```
-
-Log the flag:
-```bash
-bash .aether/aether-utils.sh activity-log "FLAG" "Chaos" "Created blocker: {finding.title}"
-```
+Run using the Bash tool with description "Flagging {finding.title}...": `bash .aether/aether-utils.sh flag-add "blocker" "{finding.title}" "{finding.description}" "chaos-testing" {phase_number} && bash .aether/aether-utils.sh activity-log "FLAG" "Chaos" "Created blocker: {finding.title}"`
 
 Log chaos ant completion and update swarm display:
-```bash
-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
-```
+Run using the Bash tool with description "Recording chaos completion...": `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`
 
 ### Step 5.8: Create Flags for Verification Failures
 
 If the Watcher reported `verification_passed: false` or `recommendation: "fix_required"`:
 
 For each issue in `issues_found`:
-```bash
-# Create a blocker flag for each verification failure
-bash .aether/aether-utils.sh flag-add "blocker" "{issue_title}" "{issue_description}" "verification" {phase_number}
-```
-
-Log the flag creation:
-```bash
-bash .aether/aether-utils.sh activity-log "FLAG" "Watcher" "Created blocker: {issue_title}"
-```
+Run using the Bash tool with description "Flagging {issue_title}...": `bash .aether/aether-utils.sh flag-add "blocker" "{issue_title}" "{issue_description}" "verification" {phase_number} && 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.7.
 
@@ -705,46 +940,26 @@ Collect all worker outputs and create phase summary:
 **Graveyard Recording:**
 For each worker that returned `status: "failed"`:
   For each file in that worker's `files_modified` or `files_created`:
-```bash
-bash .aether/aether-utils.sh grave-add "{file}" "{ant_name}" "{task_id}" {phase} "{first blocker or summary}"
-```
-  Log the grave marker:
-```bash
-bash .aether/aether-utils.sh activity-log "GRAVE" "Queen" "Grave marker placed at {file} — {ant_name} failed: {summary}"
-```
+Run using the Bash tool with description "Recording failure grave...": `bash .aether/aether-utils.sh grave-add "{file}" "{ant_name}" "{task_id}" {phase} "{first blocker or summary}" && 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}
+Resolve the build error handoff template path:
+  Check ~/.aether/system/templates/handoff-build-error.template.md first,
+  then .aether/templates/handoff-build-error.template.md.
 
-## Grave Markers Placed
-{for each grave:}
-- {file}: {caution_level} caution
-{end for}
+If no template found: output "Template missing: handoff-build-error.template.md. Run aether update to fix." and stop.
 
-## 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`
+Read the template file. Fill all {{PLACEHOLDER}} values:
+  - {{PHASE_NUMBER}} → current phase number
+  - {{PHASE_NAME}} → current phase name
+  - {{BUILD_TIMESTAMP}} → current ISO-8601 UTC timestamp
+  - {{FAILED_WORKERS}} → formatted list of failed workers (one "- {ant_name}: {failure_summary}" per line)
+  - {{GRAVE_MARKERS}} → formatted list of grave markers (one "- {file}: {caution_level} caution" per line)
 
-## Session Note
-Build completed but workers failed. Grave markers placed.
-Review failures before advancing.
-HANDOFF_EOF
-```
+Remove the HTML comment lines at the top of the template.
+Write the result to .aether/HANDOFF.md using the Write tool.
 
 Only fires when workers fail. Zero impact on successful builds.
 
@@ -822,8 +1037,7 @@ Return JSON:
 Parse synthesis result. If `ui_touched` is true:
 
 ```
-Visual Checkpoint
-=================
+━━━ 🖼️🐜 V I S U A L   C H E C K P O I N T ━━━
 
 UI changes detected. Verify appearance before continuing.
 
@@ -869,40 +1083,29 @@ jq -n \
     "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}
+Resolve the build success handoff template path:
+  Check ~/.aether/system/templates/handoff-build-success.template.md first,
+  then .aether/templates/handoff-build-success.template.md.
 
-## Files Changed
-- Created: {synthesis.files_created | length} files
-- Modified: {synthesis.files_modified | length} files
+If no template found: output "Template missing: handoff-build-success.template.md. Run aether update to fix." and stop.
 
-## 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`
+Read the template file. Fill all {{PLACEHOLDER}} values:
+  - {{GOAL}} → colony goal (from COLONY_STATE.json)
+  - {{PHASE_NUMBER}} → current phase number
+  - {{PHASE_NAME}} → current phase name
+  - {{BUILD_STATUS}} → synthesis.status
+  - {{BUILD_TIMESTAMP}} → current ISO-8601 UTC timestamp
+  - {{BUILD_SUMMARY}} → synthesis summary
+  - {{TASKS_COMPLETED}} → count of completed tasks
+  - {{TASKS_FAILED}} → count of failed tasks
+  - {{FILES_CREATED}} → count of created files
+  - {{FILES_MODIFIED}} → count of modified files
+  - {{SESSION_NOTE}} → "Build succeeded — ready to advance." if status is completed, else "Build completed with issues — review before continuing."
 
-## Session Note
-$(if synthesis.status == "completed" then "Build succeeded — ready to advance." else "Build completed with issues — review before continuing." end)
-HANDOFF_EOF
-```
+Remove the HTML comment lines at the top of the template.
+Write the result to .aether/HANDOFF.md using the Write tool.
 
 This ensures the handoff always reflects the latest build state, even if the session crashes before explicit pause.
 
@@ -910,14 +1113,7 @@ This ensures the handoff always reflects the latest build state, even if the ses
 
 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'}"
-```
+Run using the Bash tool with description "Updating build context...": `bash .aether/aether-utils.sh context-update activity "build {phase_id}" "{synthesis.status}" "{files_created_count + files_modified_count}" && 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"`
@@ -927,114 +1123,51 @@ Also update safe-to-clear status:
 
 **This step runs ONLY after synthesis is complete. All values come from actual worker results.**
 
-**First, render the final swarm display showing all completed workers:**
-```bash
-# Final swarm display update - mark Queen as completed
-bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Phase {id} complete" "Colony" '{"read":10,"grep":5,"edit":5,"bash":2}' 100 "fungus_garden" 100
+**Update swarm display state (always) and render (tmux only):**
+Run using the Bash tool with description "Recording build completion...": `bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Phase {id} complete" "Colony" '{"read":10,"grep":5,"edit":5,"bash":2}' 100 "fungus_garden" 100`
 
-# Render the final swarm display
-bash .aether/aether-utils.sh swarm-display-inline "$build_id"
-```
+If `$TMUX` is set, also run using the Bash tool with description "Rendering final swarm display...": `bash .aether/aether-utils.sh swarm-display-text "$build_id"`
 
-The swarm display will show:
-- 🐜 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
-- 🌈 Color-coded by caste
+**Display BUILD SUMMARY (always shown, replaces compact/verbose split):**
 
-**Then display build summary based on synthesis results AND `verbose_mode` from Step 1:**
+Calculate `total_tools` by summing `tool_count` from all worker return JSONs (builders + watcher + chaos).
+Calculate `elapsed` using `build_started_at_epoch` (epoch integer captured at Step 5 start by Plan 01): `$(( $(date +%s) - build_started_at_epoch ))` formatted as Xm Ys.
 
-**If verbose_mode = false (compact output, ~12 lines):**
-
-```
-🔨 PHASE {id} {status_icon}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📍 {name}
-📊 {status} | 📁 {files_created count} created, {files_modified count} modified
-🐜 {spawn_count} workers | 🧪 {tests_total} tests {if all_passing}passing{else}{passed}/{total}{end if}
-{if learning.patterns_observed.length > 0:}🧠 +{patterns_observed.length} patterns{end if}
-
-{if synthesis.status == "failed" OR verification.recommendation == "fix_required":}
-⚠️  BLOCKERS: {first 2 issues, comma-separated}
-{end if}
-
-➡️  Next: {primary_command}
-    --verbose for spawn tree, TDD details, patterns
 ```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   B U I L D   S U M M A R Y
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Phase {id}: {name}
+Pattern:  {selected_pattern}
 
-**Status icon logic:** completed+proceed = checkmark, blockers = warning, failed = X
-
-**Primary command logic:**
-- completed + proceed: `/ant:continue`
-- has blockers: `/ant:flags`
-- failed: `/ant:swarm`
-
-**If verbose_mode = true (full output):**
-
-```
-🔨🐜🏗️🐜🔨 ═══════════════════════════════════════════════════
-   P H A S E   {id}   C O M P L E T E
-═══════════════════════════════════════════════════ 🔨🐜🏗️🐜🔨
-
-📍 Phase {id}: {name}
-📊 Status: {status}
-💾 Git Checkpoint: {commit_hash}
-
-📝 Summary:
-   {summary from synthesis}
-
-🐜 Colony Work Tree:
-   👑Queen
-{for each spawn in spawn_tree:}
-   ├── {caste_emoji}{ant_name}: {task} [{status}]
-{end for}
-
-✅ Tasks Completed:
-{for each task in tasks_completed:}
-   🐜 {task_id}: done
-{end for}
-{for each task in tasks_failed:}
-   ❌ {task_id}: failed
-{end for}
-
-📁 Files: {files_created count} created, {files_modified count} modified
-
-{if tdd.tests_added > 0:}
-🧪 TDD: {tdd.cycles_completed} cycles | {tdd.tests_added} tests | {tdd.coverage_percent}% coverage
-{end if}
+Workers:  {pass_count} passed  {fail_count} failed  ({total} total)
+Tools:    {total_tools} calls across all workers
+Duration: {elapsed}
 
-{if learning.patterns_observed not empty:}
-🧠 Patterns Learned:
-{for each pattern in learning.patterns_observed:}
-   🐜 {pattern.trigger} → {pattern.action}
-{end for}
-{end if}
+{if fail_count > 0:}
+Failed:
+  {for each failed worker:}
+  {caste_emoji} {Ant-Name}: {task_description} ✗ ({failure_reason} after {tool_count} tools)
+  {end for}
 
-{if debugging.issues_encountered > 0:}
-🔧 Debugging: {debugging.issues_resolved}/{debugging.issues_encountered} resolved
+Retry: /ant:swarm to auto-repair failed tasks, or /ant:flags to review blockers
 {end if}
+```
 
-🤖 Model Routing:
-{for each spawn in spawn_tree where model_context exists:}
-   {caste_emoji}{ant_name}: {model_context.assigned} {if model_context.assigned matches caste expectation:}✓{else}⚠️{end if}
-{end for}
-   Proxy: {if proxy_healthy:}✓ Healthy @ http://localhost:4000{else}✗ Not running (using default model){end if}
-
-🐜 Next Steps:
-{if synthesis.status == "completed" AND verification.recommendation == "proceed":}
-   /ant:continue   ➡️  Advance to next phase
-   /ant:feedback   💬 Give feedback first
-{else if synthesis.status == "failed" OR verification.recommendation == "fix_required":}
-   ⚠️  BLOCKERS DETECTED - Cannot proceed until resolved
-   /ant:flags      🚩 View blockers
-   /ant:swarm      🔥 Auto-fix issues
-{end if}
+**If verbose_mode is true**, additionally show the spawn tree and TDD details after the BUILD SUMMARY block (keep the existing verbose-only sections: Colony Work Tree, Tasks Completed, TDD, Patterns Learned, Debugging, Model Routing). Prepend with:
+```
+━━ Details (--verbose) ━━
+```
 
-💾 State persisted — safe to /clear, then run /ant:continue
+After displaying the BUILD SUMMARY (and optional verbose details), call the Next Up helper by running using the Bash tool with description "Displaying next steps...":
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json 2>/dev/null || echo "IDLE")
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json 2>/dev/null || echo "0")
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json 2>/dev/null || echo "0")
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
 ```
 
-**Conditional Next Steps:** The suggestions above are based on actual worker results. If verification failed or blockers exist, `/ant:continue` is NOT suggested.
+**Routing Note:** The state-based Next Up block above routes based on colony state. If verification failed or blockers exist, review `/ant:flags` before continuing.
 
 **IMPORTANT:** Build does NOT update task statuses or advance state. Run `/ant:continue` to:
 - Mark tasks as completed
@@ -1045,6 +1178,4 @@ The swarm display will show:
 
 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}"
-```
+Run using the Bash tool with description "Saving build session...": `bash .aether/aether-utils.sh session-update "/ant:build {phase_id}" "/ant:continue" "Phase {phase_id} build completed: {synthesis.status}"`