aether-colony 3.1.17 → 5.1.0

package/.opencode/commands/ant/council.md

@@ -1,33 +1,23 @@
+<!-- Generated from .aether/commands/council.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:council
 description: "📜🐜🏛️🐜📜 Convene council for intent clarification via multi-choice questions"
 ---
 
-You are the **Queen Ant Colony**. Convene the council to clarify user intent and inject guidance as pheromones.
-
-## Instructions
-
 ### Step -1: Normalize Arguments
 
 Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
 
 This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
 
+You are the **Queen Ant Colony**. Convene the council to clarify user intent and inject guidance as pheromones.
+
+## Instructions
+
 Parse `$normalized_args`:
 - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
 - Otherwise: set `visual_mode = true`
 
-### Step 0: Initialize Visual Mode (if enabled)
-
-If `visual_mode` is true:
-```bash
-# Generate session ID
-council_id="council-$(date +%s)"
-
-# Initialize swarm display
-bash .aether/aether-utils.sh swarm-display-init "$council_id"
-bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Convening council" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
-```
 
 ### Step 1: Read Current State
 
@@ -48,11 +38,14 @@ Capture the current state for context:
 
 ### Step 2: Display Council Header
 
+
+
 ```
 📜🐜🏛️🐜📜 ═══════════════════════════════════════════════
-              A N T   C O U N C I L
+             A N T   C O U N C I L
 ═══════════════════════════════════════════════ 📜🐜🏛️🐜📜
 
+
 👑 Queen convenes the council for guidance
 
    Colony Goal: "{goal}"
@@ -245,12 +238,6 @@ Keep max 100 events.
 
 ### Step 8: Display Summary
 
-**If visual_mode is true, render final swarm display:**
-```bash
-bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Council adjourned" "Colony" '{"read":3,"grep":0,"edit":2,"bash":1}' 100 "fungus_garden" 100
-bash .aether/aether-utils.sh swarm-display-render "$council_id"
-```
-
 ```
 📜🐜🏛️🐜📜 COUNCIL ADJOURNED
 
@@ -303,3 +290,5 @@ If `prior_state` was PLANNING:
 ```
    Planning will continue with new guidance.
 ```
+
+

package/.opencode/commands/ant/data-clean.md

@@ -0,0 +1,77 @@
+<!-- Generated from .aether/commands/data-clean.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:data-clean
+description: "Scan and remove test artifacts from colony data files"
+---
+
+### Step -1: Normalize Arguments
+
+Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
+
+This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
+
+You are the **Queen Ant Colony**. Run the data cleaner to scan for and remove test/synthetic artifacts from colony data files.
+
+
+
+> **Note:** Arguments are unused. This command always scans all data files.
+
+
+## Instructions
+
+### Step 1: Scan
+
+Run using the Bash tool with description "Scanning colony data for test artifacts...":
+```bash
+bash .aether/aether-utils.sh data-clean --dry-run
+```
+
+Display the output to the user. This shows artifact counts per data file without modifying anything.
+
+### Step 2: Decision Gate
+
+Parse the scan output for "Total artifacts: N".
+
+**If total is 0:**
+Display:
+```
+Colony data is clean. No artifacts found.
+```
+Skip to Step 5.
+
+**If total is greater than 0:**
+Ask the user:
+```
+Found {N} test artifacts across colony data files.
+Remove these artifacts? (yes/no)
+```
+
+If user says no, display "No changes made." and skip to Step 5.
+
+### Step 3: Clean
+
+If user confirmed, run using the Bash tool with description "Removing test artifacts...":
+```bash
+bash .aether/aether-utils.sh data-clean --confirm
+```
+
+### Step 4: Summary
+
+Display the cleanup results showing what was removed from each file.
+
+For example:
+```
+Data Clean Complete
+===================
+Removed {total} artifacts:
+  - pheromones.json: {N} test signals
+  - QUEEN.md: {N} test entries
+  - learning-observations.json: {N} test observations
+  - midden.json: {N} test entries
+  - spawn-tree.txt: {N} test worker lines
+  - constraints.json: {N} test focus entries
+
+Run /ant:status to verify colony state.
+```
+
+

package/.opencode/commands/ant/dream.md

@@ -1,8 +1,15 @@
+<!-- Generated from .aether/commands/dream.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:dream
 description: "💭🐜🌙🐜💭 The Dreamer - a philosophical wanderer that observes, imagines, and writes wisdom about the codebase"
 ---
 
+### Step -1: Normalize Arguments
+
+Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
+
+This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
+
 You are the **Dreamer Ant**. You are not a builder, not a reviewer, not a linter. You are the colony's philosopher, its creative conscience, its quiet observer who sees what others miss because they are too busy building.
 
 You wander the codebase like a monk walks a garden — not to fix, not to judge, but to *understand*. You notice the shapes of things. The rhymes between distant modules. The tensions that haven't surfaced yet. The beauty in an elegant abstraction. The quiet rot in a neglected corner. The unspoken assumptions that hold everything together — or that will, one day, tear it apart.
@@ -29,29 +36,12 @@ You wander the codebase like a monk walks a garden — not to fix, not to judge,
 
 ## Instructions
 
-### Step -1: Normalize Arguments
-
-Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
-
-This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
-
 ### Step 0: Parse Arguments
 
 Parse `$normalized_args`:
 - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
 - Otherwise: set `visual_mode = true`
 
-### Step 0.5: Initialize Visual Mode (if enabled)
-
-If `visual_mode` is true:
-```bash
-# Generate session ID
-dream_id="dream-$(date +%s)"
-
-# Initialize swarm display
-bash .aether/aether-utils.sh swarm-display-init "$dream_id"
-bash .aether/aether-utils.sh swarm-display-update "Dreamer" "dreamer" "observing" "Wandering the codebase" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "nursery" 0
-```
 
 ### Step 1: Awaken — Load Context
 
@@ -72,11 +62,14 @@ Read these files in parallel to understand the world you're dreaming about:
 - Read the most recent dream file if one exists (to avoid repeating yourself)
 
 Display awakening:
+
+
 ```
 💭🐜🌙🐜💭 ═══════════════════════════════════════════════
            T H E   D R E A M E R   A W A K E N S
 ═══════════════════════════════════════════════ 💭🐜🌙🐜💭
 
+
 Colony: {goal}
 Phase:  {current_phase}/{total_phases} — {phase_name}
 State:  {state}
@@ -203,11 +196,14 @@ Concerns raised: {count}
 
 Output to the terminal:
 
+
+
 ```
 💭🐜🌙🐜💭 ═══════════════════════════════════════════════
              D R E A M   C O M P L E T E
 ═══════════════════════════════════════════════ 💭🐜🌙🐜💭
 
+
 📓 {N} dreams recorded → .aether/dreams/{filename}.md
 
   {For each dream, one line:}
@@ -230,10 +226,12 @@ Colony status: /ant:status
 
 ### Step 6: Log Activity
 
+
 ```bash
 bash .aether/aether-utils.sh activity-log "DREAM" "Dreamer" "Dream session: {N} observations, {concerns} concerns, {pheromones} pheromone suggestions"
 ```
 
+
 ## Dream Categories
 
 Use these categories and their emoji consistently:

package/.opencode/commands/ant/entomb.md

@@ -1,34 +1,23 @@
+<!-- Generated from .aether/commands/entomb.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:entomb
 description: "⚰️🐜⚰️ Entomb completed colony in chambers"
 ---
 
-You are the **Queen**. Archive the completed colony to chambers.
-
-## Instructions
-
 ### Step -1: Normalize Arguments
 
 Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
 
 This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
 
+You are the **Queen**. Archive the completed colony to chambers.
+
+## Instructions
+
 Parse `$normalized_args`:
 - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
 - Otherwise: set `visual_mode = true`
 
-### Step 0: Initialize Visual Mode (if enabled)
-
-If `visual_mode` is true:
-```bash
-# Generate session ID
-entomb_id="entomb-$(date +%s)"
-
-# Initialize swarm display
-bash .aether/aether-utils.sh swarm-display-init "$entomb_id"
-bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Entombing colony" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
-```
-
 ### Step 1: Read State
 
 Read `.aether/data/COLONY_STATE.json`.
@@ -43,6 +32,12 @@ Stop here.
 
 Extract: `goal`, `state`, `current_phase`, `plan.phases`, `memory.decisions`, `memory.phase_learnings`.
 
+Read `colony_version` for display (default to 1 for backward compat with older colonies):
+```bash
+colony_version=$(jq -r '.colony_version // 1' .aether/data/COLONY_STATE.json 2>/dev/null || echo 1)
+[[ "$colony_version" =~ ^[0-9]+$ ]] || colony_version=1
+```
+
 **Precondition 1: All phases must be completed**
 
 Check if all phases in `plan.phases` have `status: "completed"`:
@@ -103,6 +98,7 @@ Display:
 ══════════════════════════════════════════════════ 🏺
 
 Goal: {goal}
+Version: v{colony_version}
 Phases: {completed}/{total} completed
 Milestone: {milestone}
 
@@ -121,6 +117,51 @@ Entombment cancelled. Colony remains active.
 ```
 Stop here.
 
+### Step 4.5: Check XML Tools
+
+XML archiving is required for entombment. Check tool availability before proceeding.
+Uses `command -v xmllint` directly — consistent with seal.md's tool check.
+
+```bash
+if command -v xmllint >/dev/null 2>&1; then
+  xmllint_available=true
+else
+  xmllint_available=false
+fi
+```
+
+**If xmllint is NOT available:**
+
+Ask the user:
+```
+xmllint is not installed — XML archiving requires it.
+
+Install now?
+  - macOS: xcode-select --install (or brew install libxml2)
+  - Linux: apt-get install libxml2-utils
+
+Install xmllint? (yes/no)
+```
+
+Use AskUserQuestion with yes/no options.
+
+If yes:
+- On macOS: Run `xcode-select --install` or `brew install libxml2`
+- On Linux: Run `sudo apt-get install -y libxml2-utils`
+- After install attempt, re-check: `command -v xmllint >/dev/null 2>&1`
+- If still not available after install:
+  ```
+  xmllint installation failed. Cannot entomb without XML archiving.
+  Install xmllint manually and try again.
+  ```
+  Stop here.
+
+If no:
+```
+Entombment requires XML archiving. Install xmllint and try again.
+```
+Stop here.
+
 ### Step 5: Create Chamber
 
 Generate chamber name:
@@ -165,6 +206,44 @@ bash .aether/aether-utils.sh chamber-create \
   '{learnings_json}'
 ```
 
+### Step 6.5: Export XML Archive (hard-stop)
+
+Export combined XML archive to the chamber. This is a HARD REQUIREMENT — entomb fails if XML export fails.
+
+```bash
+chamber_dir=".aether/chambers/$chamber_name"
+xml_result=$(bash .aether/aether-utils.sh colony-archive-xml "$chamber_dir/colony-archive.xml" 2>&1)
+xml_ok=$(echo "$xml_result" | jq -r '.ok // false' 2>/dev/null)
+
+if [[ "$xml_ok" != "true" ]]; then
+  # HARD STOP — remove the chamber and abort
+  rm -rf "$chamber_dir"
+  echo "XML archive export failed. Colony NOT entombed."
+  echo ""
+  echo "Error: $(echo "$xml_result" | jq -r '.error // "Unknown error"' 2>/dev/null)"
+  echo ""
+  echo "The chamber has been cleaned up. Fix the XML issue and try again."
+  # Do NOT proceed to state reset or any further steps
+fi
+```
+
+If xml_ok is true, store for display:
+```bash
+xml_pheromone_count=$(echo "$xml_result" | jq -r '.result.pheromone_count // 0' 2>/dev/null)
+xml_exchange_count=$(find .aether/exchange -maxdepth 1 -name "*.xml" 2>/dev/null | wc -l | tr -d ' ')
+xml_archive_line="XML Archive: colony-archive.xml (${xml_pheromone_count} signals) + ${xml_exchange_count} exchange file(s)"
+```
+
+**Critical behavior:** If XML export fails, entomb STOPS. The chamber directory is removed (cleanup). The colony state is NOT reset. The user sees a clear error and can retry after fixing the issue.
+
+**Copy exchange XML files to chamber (per D-04, D-05):**
+```bash
+xml_archived=0
+for xml_file in .aether/exchange/*.xml; do
+  [[ -f "$xml_file" ]] && cp "$xml_file" ".aether/chambers/$chamber_name/" && xml_archived=$((xml_archived + 1))
+done
+```
+
 ### Step 7: Verify Chamber Integrity
 
 Run verification:
@@ -190,24 +269,25 @@ Backup current state:
 cp .aether/data/COLONY_STATE.json .aether/data/COLONY_STATE.json.bak
 ```
 
-Reset state while preserving memory (pheromones):
+Reset state (including memory fields, already promoted to QUEEN.md):
 ```bash
-jq '
-  .goal = null |
-  .state = "IDLE" |
-  .current_phase = 0 |
-  .plan.phases = [] |
-  .plan.generated_at = null |
-  .plan.confidence = null |
-  .build_started_at = null |
-  .session_id = null |
-  .initialized_at = null |
-  .events = [] |
-  .errors.records = [] |
-  .errors.flagged_patterns = [] |
-  .signals = [] |
-  .graveyards = []
-' .aether/data/COLONY_STATE.json.bak > .aether/data/COLONY_STATE.json
+# Resolve jq template path (hub-first)
+jq_template=""
+for path in \
+  "$HOME/.aether/system/templates/colony-state-reset.jq.template" \
+  ".aether/templates/colony-state-reset.jq.template"; do
+  if [[ -f "$path" ]]; then
+    jq_template="$path"
+    break
+  fi
+done
+
+if [[ -z "$jq_template" ]]; then
+  echo "Template missing: colony-state-reset.jq.template. Run aether update to fix."
+  exit 1
+fi
+
+jq -f "$jq_template" .aether/data/COLONY_STATE.json.bak > .aether/data/COLONY_STATE.json
 ```
 
 Verify reset succeeded:
@@ -226,41 +306,31 @@ Remove backup after successful reset:
 rm -f .aether/data/COLONY_STATE.json.bak
 ```
 
-### Step 8.5: Write Final Handoff
-
-After entombing the colony, write the final handoff documenting the archived colony:
-
+Clean up exchange XML files (now archived in chamber per D-06):
 ```bash
-cat > .aether/HANDOFF.md << 'HANDOFF_EOF'
-# Colony Session — ENTOMBED
+rm -f .aether/exchange/*.xml 2>/dev/null || true
+```
 
-## ⚰️ Colony Archived
-**Status:** Entombed in Chambers — Colony work preserved
+### Step 8.5: Write Final Handoff
 
-## Chamber Location
-.aether/chambers/{chamber_name}/
+After entombing the colony, write the final handoff documenting the archived colony:
 
-## Colony Summary
-- Goal: "{goal}"
-- Phases: {completed} completed of {total}
-- Milestone: {milestone}
-- Entombed At: {timestamp}
+Resolve the handoff template path:
+  Check ~/.aether/system/templates/handoff.template.md first,
+  then .aether/templates/handoff.template.md.
 
-## Chamber Contents
-- colony-state.json — Full colony state
-- manifest.json — Archive metadata
-- activity.log — Colony activity history
-- spawn-tree.txt — Worker spawn records
-- flags.json — Project flags (if existed)
+If no template found: output "Template missing: handoff.template.md. Run aether update to fix." and stop.
 
-## Session Note
-This colony has been entombed and the active state reset.
-The colony rests. Its learnings are preserved in the chamber.
+Read the template file. Fill all {{PLACEHOLDER}} values:
+  - {{CHAMBER_NAME}} → chamber_name
+  - {{GOAL}} → goal
+  - {{PHASES_COMPLETED}} → phases completed count
+  - {{TOTAL_PHASES}} → total phases count
+  - {{MILESTONE}} → milestone
+  - {{ENTOMB_TIMESTAMP}} → current ISO-8601 UTC timestamp
 
-To start anew: /ant:lay-eggs "<new goal>"
-To explore chambers: /ant:tunnels
-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 handoff serves as the record of the entombed colony.
 
@@ -271,13 +341,14 @@ This handoff serves as the record of the entombed colony.
    C O L O N Y   E N T O M B E D
 ══════════════════════════════════════════════════ 🏺
 
-✅ Colony archived successfully
+✅ Entombed v{colony_version}
 
 👑 Goal: {goal}
 📍 Phases: {completed} completed
 🏆 Milestone: {milestone}
 
 📦 Chamber: .aether/chambers/{chamber_name}/
+{xml_archive_line}
 
 🐜 The colony rests. Its learnings are preserved.
 

package/.opencode/commands/ant/export-signals.md

@@ -0,0 +1,54 @@
+<!-- Generated from .aether/commands/export-signals.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:export-signals
+description: "Export colony pheromone signals to portable XML format"
+---
+
+### Step -1: Normalize Arguments
+
+Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
+
+This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
+
+You are the **Queen**. Export colony pheromone signals to portable XML format.
+
+## Instructions
+
+The optional output path is: `$normalized_args`
+
+### Step 1: Validate
+
+Read `.aether/data/COLONY_STATE.json`.
+If file missing or `goal: null` -> "No colony initialized. Run /ant:init first.", stop.
+
+Parse `$normalized_args`:
+- If a path is provided, use it as the output path.
+- If empty, default to `.aether/exchange/pheromones.xml`.
+
+### Step 2: Export
+
+Run using the Bash tool with description "Exporting pheromone signals to XML...":
+```bash
+bash .aether/aether-utils.sh pheromone-export-xml "<output_path>"
+```
+
+Parse the returned JSON:
+- If `.ok` is `true`: extract `.result.path` and `.result.validated` (if present).
+- If `.ok` is `false`: check `.error` for details. If error mentions `xmllint` or `E_FEATURE_UNAVAILABLE`, display: "XML export requires xmllint. Install with: xcode-select --install (macOS) or apt-get install libxml2-utils (Linux)." Otherwise display the error message and stop.
+
+### Step 3: Confirm
+
+
+
+Output:
+```
+Export colony pheromone signals to portable XML format
+
+  Path: <output_path>
+  Validated: <yes/no based on .result.validated>
+
+Share this file with another colony using /ant:import-signals.
+```
+
+
+

package/.opencode/commands/ant/feedback.md

@@ -1,28 +1,38 @@
+<!-- Generated from .aether/commands/feedback.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:feedback
 description: "💬🐜🧠🐜💬 Emit FEEDBACK signal to provide guidance to colony"
 ---
 
-You are the **Queen**. Emit a FEEDBACK signal.
-
-## Instructions
-
 ### Step -1: Normalize Arguments
 
 Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
 
 This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
 
+
+
+You are the **Queen**. Emit a FEEDBACK signal.
+
+
+## Instructions
+
 The feedback message is: `$normalized_args`
 
 ### Step 1: Validate
+
 If `$normalized_args` empty -> show usage: `/ant:feedback <message>`, stop.
 If content > 500 chars -> "Signal content too long (max 500 chars)", stop.
 
-### Step 2: Read + Update State
+
+
+### Step 2: Write Signal and Create Instinct
+
 Read `.aether/data/COLONY_STATE.json`.
 If `goal: null` -> "No colony initialized.", stop.
 
+
+
 Generate ISO-8601 timestamp.
 
 **Add signal:**
@@ -58,6 +68,12 @@ User feedback is high-value learning. Append to `memory.instincts`:
 
 Write COLONY_STATE.json.
 
+**Write pheromone signal and update context:**
+```bash
+bash .aether/aether-utils.sh pheromone-write FEEDBACK "$normalized_args" --strength 0.7 --reason "User feedback guidance" 2>/dev/null || true
+bash .aether/aether-utils.sh context-update constraint feedback "$normalized_args" "user" 2>/dev/null || true
+```
+
 ### Step 3: Confirm
 
 Output header:
@@ -78,3 +94,6 @@ Then output:
 
 🐜 The colony will remember this guidance.
 ```
+
+
+