aether-colony 3.1.17 → 5.0.0

package/.claude/commands/ant/chaos.md

@@ -66,7 +66,7 @@ Parse `$ARGUMENTS`:
 
 ### Step 0: Initialize Visual Mode (if enabled)
 
-If `visual_mode` is true:
+If `visual_mode` is true, run using the Bash tool with description "Initializing chaos display...":
 ```bash
 # Generate session ID
 chaos_id="chaos-$(date +%s)"
@@ -100,9 +100,9 @@ Stop here.
 
 Display awakening:
 ```
-🎲🐜🔍🐜🎲 ═══════════════════════════════════════════════
-        R E S I L I E N C E   T E S T E R   A C T I V E
-═══════════════════════════════════════════════ 🎲🐜🔍🐜🎲
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎲🐜🔍🐜🎲  R E S I L I E N C E   T E S T E R   A C T I V E
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Target: {target description}
 Files:  {list of files being investigated}
@@ -222,7 +222,7 @@ For each scenario, produce a finding in this format. Display each to the termina
 
 ### Step 5: Produce the Chaos Report
 
-**If visual_mode is true, render final swarm display:**
+**If visual_mode is true, render final swarm display** by running using the Bash tool with description "Updating chaos display...":
 ```bash
 bash .aether/aether-utils.sh swarm-display-update "Chaos Ant" "chaos" "completed" "Resilience test complete" "Colony" '{"read":8,"grep":4,"edit":0,"bash":3}' 100 "fungus_garden" 100
 bash .aether/aether-utils.sh swarm-display-inline "$chaos_id"
@@ -231,9 +231,9 @@ bash .aether/aether-utils.sh swarm-display-inline "$chaos_id"
 After all 5 scenarios, compile the structured report:
 
 ```
-🎲🐜🔍🐜🎲 ═══════════════════════════════════════════════
-             C H A O S   R E P O R T
-═══════════════════════════════════════════════ 🎲🐜🔍🐜🎲
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎲🐜🔍🐜🎲  C H A O S   R E P O R T
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Target: {target description}
 Files investigated: {count}
@@ -304,14 +304,14 @@ After the display report, output the machine-readable JSON summary:
 
 ### Step 6.5: Persist Blocker Flags for Critical/High Findings
 
-After outputting the JSON report, iterate through the chaos report scenarios. For each finding with severity `"CRITICAL"` or `"HIGH"`, persist a blocker flag so the colony tracks it:
+After outputting the JSON report, iterate through the chaos report scenarios. For each finding with severity `"CRITICAL"` or `"HIGH"`, persist a blocker flag so the colony tracks it by running using the Bash tool with description "Raising colony flag...":
 
 ```bash
 # For each scenario where status == "finding" AND severity is "CRITICAL" or "HIGH":
 bash .aether/aether-utils.sh flag-add "blocker" "{scenario.title}" "{scenario.description}" "chaos-standalone" {current_phase_number}
 ```
 
-Log each flag creation:
+Log each flag creation by running using the Bash tool with description "Logging chaos flag...":
 ```bash
 bash .aether/aether-utils.sh activity-log "FLAG" "Chaos Ant" "Created blocker: {scenario.title}"
 ```
@@ -322,10 +322,19 @@ The `{current_phase_number}` comes from the colony state loaded in Step 1 (`.aet
 
 ### Step 7: Log Activity
 
+Run using the Bash tool with description "Logging chaos activity...":
 ```bash
 bash .aether/aether-utils.sh activity-log "CHAOS" "Chaos Ant" "Resilience test on {target}: {findings_count} finding(s) ({critical} critical, {high} high, {medium} medium, {low} low), {resilient_count} resilient"
 ```
 
+Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json)
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
+```
+
 ## Investigation Guidelines
 
 Throughout your investigation, remember:

package/.claude/commands/ant/colonize.md

@@ -12,6 +12,37 @@ The arguments are: `$ARGUMENTS`
 - If contains `--force` or `--force-resurvey`: set `force_resurvey = true`
 - Otherwise: set `visual_mode = true`, `force_resurvey = false`
 
+<failure_modes>
+### Existing Survey Overwrite
+If .aether/data/survey/ already contains survey documents:
+- Warn before overwriting: "Existing survey found from [date]. Re-surveying will replace it."
+- Options: (1) Continue and overwrite, (2) Keep existing survey, (3) Merge (re-survey only outdated sections)
+
+### Surveyor Spawn Failure
+If a surveyor agent fails during codebase exploration:
+- Report which survey document was not produced
+- Partial surveys are acceptable -- note which documents are complete vs. missing
+- Recovery: user can re-run /ant:colonize to regenerate missing surveys
+</failure_modes>
+
+<success_criteria>
+Command is complete when:
+- All surveyor agents have completed their exploration
+- Survey documents exist in .aether/data/survey/
+- COLONY_STATE.json reflects colonized status
+- User sees summary of survey findings
+</success_criteria>
+
+<read_only>
+Do not touch during colonize:
+- .aether/dreams/ (user notes)
+- .aether/chambers/ (archived colonies)
+- Source code files (survey is read-only exploration)
+- .env* files
+- .claude/settings.json
+- COLONY_STATE.json structure beyond colonize-specific fields
+</read_only>
+
 ## Instructions
 
 ### Step 0: Initialize Visual Mode (if enabled)
@@ -21,16 +52,15 @@ If `visual_mode` is true:
 # Generate session ID
 colonize_id="colonize-$(date +%s)"
 
-# Initialize swarm display
-bash .aether/aether-utils.sh swarm-display-init "$colonize_id"
-bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "dispatching" "Surveying territory" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
+# Initialize swarm display (consolidated)
+bash .aether/aether-utils.sh swarm-display-init "$colonize_id" && bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "dispatching" "Surveying territory" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
 ```
 
 Display header:
 ```
-📊🐜🗺️🐜📊 ═══════════════════════════════════════════════
-         C O L O N I Z E  —  T e r r i t o r y  S u r v e y
-═══════════════════════════════════════════════ 📊🐜🗺️🐜📊
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊🐜🗺️🐜📊  C O L O N I Z E  —  T e r r i t o r y  S u r v e y
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Queen dispatching Surveyor Ants...
 ```
@@ -101,20 +131,17 @@ if [[ "$has_stale" -gt 0 ]] || [[ "$has_fresh" -gt 0 ]]; then
 fi
 ```
 
-Generate unique names for the 4 Surveyor Ants and log their dispatch:
+Generate unique names for the 4 Surveyor Ants (each name must be captured separately):
 ```bash
-bash .aether/aether-utils.sh generate-ant-name "surveyor"
+ bash .aether/aether-utils.sh generate-ant-name "surveyor"
 bash .aether/aether-utils.sh generate-ant-name "surveyor"
 bash .aether/aether-utils.sh generate-ant-name "surveyor"
 bash .aether/aether-utils.sh generate-ant-name "surveyor"
 ```
 
-Log the dispatch:
+Log the dispatches (consolidated - fire-and-forget logging):
 ```bash
-bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{provisions_name}" "Mapping provisions and trails"
-bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{nest_name}" "Mapping nest structure"
-bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{disciplines_name}" "Mapping disciplines and sentinels"
-bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{pathogens_name}" "Identifying pathogens"
+bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{provisions_name}" "Mapping provisions and trails" && bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{nest_name}" "Mapping nest structure" && bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{disciplines_name}" "Mapping disciplines and sentinels" && bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{pathogens_name}" "Identifying pathogens"
 ```
 
 **Spawn 4 Surveyor Ants in parallel using the Task tool:**
@@ -147,15 +174,9 @@ Collect confirmations from all 4 surveyors. Each should return:
 
 ### Step 4: Verify Survey Completeness
 
-Check that all 7 documents were created:
+Check that all 7 documents were created (consolidated):
 ```bash
-ls .aether/data/survey/PROVISIONS.md 2>/dev/null && echo "PROVISIONS: OK" || echo "PROVISIONS: MISSING"
-ls .aether/data/survey/TRAILS.md 2>/dev/null && echo "TRAILS: OK" || echo "TRAILS: MISSING"
-ls .aether/data/survey/BLUEPRINT.md 2>/dev/null && echo "BLUEPRINT: OK" || echo "BLUEPRINT: MISSING"
-ls .aether/data/survey/CHAMBERS.md 2>/dev/null && echo "CHAMBERS: OK" || echo "CHAMBERS: MISSING"
-ls .aether/data/survey/DISCIPLINES.md 2>/dev/null && echo "DISCIPLINES: OK" || echo "DISCIPLINES: MISSING"
-ls .aether/data/survey/SENTINEL-PROTOCOLS.md 2>/dev/null && echo "SENTINEL: OK" || echo "SENTINEL: MISSING"
-ls .aether/data/survey/PATHOGENS.md 2>/dev/null && echo "PATHOGENS: OK" || echo "PATHOGENS: MISSING"
+ls .aether/data/survey/PROVISIONS.md .aether/data/survey/TRAILS.md .aether/data/survey/BLUEPRINT.md .aether/data/survey/CHAMBERS.md .aether/data/survey/DISCIPLINES.md .aether/data/survey/SENTINEL-PROTOCOLS.md .aether/data/survey/PATHOGENS.md 2>&1 | grep -q "No such file" && echo "Some documents missing" || echo "All survey documents present"
 ```
 
 If any documents are missing, note which ones in the output.
@@ -175,6 +196,11 @@ if [[ "$fresh_count" -lt 7 ]]; then
 fi
 ```
 
+Display colony activity summary:
+```bash
+bash .aether/aether-utils.sh swarm-display-text "$colonize_id"
+```
+
 ### Step 5: Update State
 
 Read `.aether/data/COLONY_STATE.json`. Update:
@@ -193,9 +219,9 @@ Write the updated COLONY_STATE.json.
 Output header:
 
 ```
-📊🐜🗺️🐜📊 ═══════════════════════════════════════════════════
-   T E R R I T O R Y   S U R V E Y   C O M P L E T E
-═══════════════════════════════════════════════════ 📊🐜🗺️🐜📊
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊🐜🗺️🐜📊  T E R R I T O R Y   S U R V E Y   C O M P L E T E
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
 Then output:
@@ -234,3 +260,11 @@ Next:
   /ant:focus "<area>"    Inject focus before planning
   /ant:redirect "<pat>"  Inject constraint before planning
 ```
+
+Generate the state-based Next Up block:
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json)
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
+```