aether-colony 3.1.17 → 5.1.0

package/.opencode/commands/ant/tunnels.md

@@ -1,24 +1,18 @@
+<!-- Generated from .aether/commands/tunnels.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:tunnels
 description: "🕳️🐜🕳️ Explore tunnels (browse archived colonies, compare chambers)"
 ---
 
-You are the **Queen**. Browse the colony history.
-
-## 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.
 
-### Argument Handling
+You are the **Queen**. Browse the colony history.
 
-- No arguments: Show chamber list (Step 4)
-- One argument: Show single chamber detail (Step 3)
-- Two arguments: Compare two chambers (Step 5)
-- More than two: "Too many arguments. Use: /ant:tunnels [chamber1] [chamber2]"
+## Instructions
 
 ### Step 1: Check for Chambers Directory
 
@@ -106,6 +100,37 @@ To get the counts and hash status:
 - If not verified: hash_status = "⚠️ hash mismatch"
 - If error: hash_status = "⚠️ error"
 
+Check if `colony-archive.xml` exists in the chamber:
+
+```bash
+chamber_has_xml=false
+[[ -f ".aether/chambers/{chamber_name}/colony-archive.xml" ]] && chamber_has_xml=true
+```
+
+**If `colony-archive.xml` exists**, add import option to the detail view footer:
+```
+📁 Files:
+   - COLONY_STATE.json (verified: {hash_status})
+   - manifest.json
+   - colony-archive.xml (XML Archive)
+
+Actions:
+  1. Import signals from this colony into current colony
+  2. Return to chamber list
+
+Select an action (1/2)
+```
+
+Use AskUserQuestion with two options.
+
+If option 1 selected: proceed to Step 6 (Import Signals from Chamber).
+If option 2 selected: return to chamber list (run /ant:tunnels).
+
+**If `colony-archive.xml` does NOT exist**, show existing footer unchanged:
+```
+Run /ant:tunnels to return to chamber list.
+```
+
 Stop here.
 
 ### Step 5: Chamber Comparison Mode (Two Arguments)
@@ -231,6 +256,124 @@ Run /ant:tunnels <chamber_name> to view details
 - Missing COLONY_STATE.json: show "⚠️  Incomplete chamber" for that chamber
 - Very long chamber list: display all (no pagination for now)
 
+### Step 6: Import Signals from Chamber
+
+When user selects "Import signals" from Step 3:
+
+**Step 6.1: Check XML tools**
+```bash
+if command -v xmllint >/dev/null 2>&1; then
+  xmllint_available=true
+else
+  xmllint_available=false
+fi
+```
+
+If xmllint not available:
+```
+Import requires xmllint. Install it first:
+  macOS: xcode-select --install
+  Linux: apt-get install libxml2-utils
+```
+Stop here (return to chamber list).
+
+**Step 6.2: Extract source colony name**
+```bash
+chamber_xml=".aether/chambers/{chamber_name}/colony-archive.xml"
+# Extract colony_id from the archive root element
+source_colony=$(xmllint --xpath "string(/*/@colony_id)" "$chamber_xml" 2>/dev/null)
+[[ -z "$source_colony" ]] && source_colony="{chamber_name}"
+```
+
+**Step 6.3: Extract pheromone section and show import preview**
+
+The combined `colony-archive.xml` contains pheromones, wisdom, and registry sections. Extract the pheromone section to a temp file before counting or importing. This prevents over-counting signals from wisdom/registry sections and ensures `pheromone-import-xml` receives the format it expects (`<pheromones>` as root element).
+
+```bash
+# Extract the <pheromones> section from the combined archive into a standalone temp file
+import_tmp_dir=$(mktemp -d)
+import_tmp_pheromones="$import_tmp_dir/pheromones-extracted.xml"
+
+# Use xmllint to extract the pheromones element (with its namespace)
+xmllint --xpath "//*[local-name()='pheromones']" "$chamber_xml" > "$import_tmp_pheromones" 2>/dev/null
+
+# Add XML declaration to make it a standalone well-formed document
+if [[ -s "$import_tmp_pheromones" ]]; then
+  # Portable approach: prepend declaration via temp file (avoids macOS/Linux sed -i differences)
+  { echo '<?xml version="1.0" encoding="UTF-8"?>'; cat "$import_tmp_pheromones"; } > "$import_tmp_dir/tmp_decl.xml"
+  mv "$import_tmp_dir/tmp_decl.xml" "$import_tmp_pheromones"
+fi
+
+# Count pheromone signals in extracted pheromone-only XML
+# Scoped to pheromone section only — no over-counting from wisdom/registry sections
+pheromone_count=$(xmllint --xpath "count(//*[local-name()='signal'])" "$import_tmp_pheromones" 2>/dev/null || echo "unknown")
+```
+
+Display:
+```
+IMPORT FROM COLONY: {source_colony}
+
+Source: .aether/chambers/{chamber_name}/colony-archive.xml
+Signals available: ~{pheromone_count} pheromone signals
+
+Import behavior:
+  - Signals tagged with prefix "{source_colony}:" to identify origin
+  - Additive merge — your current signals are never overwritten
+  - On conflict, your current colony wins
+
+Import these signals? (yes/no)
+```
+
+Use AskUserQuestion with yes/no options.
+
+If no: "Import cancelled." Clean up: `rm -rf "$import_tmp_dir"`. Return to chamber list.
+
+**Step 6.4: Perform import**
+
+Pass the extracted pheromone-only temp file (NOT the combined `colony-archive.xml`) to `pheromone-import-xml`, along with `$source_colony` as the second argument. This ensures:
+1. `pheromone-import-xml` receives XML with `<pheromones>` as root element (the format it expects)
+2. The prefix-tagging logic prepends `${source_colony}:` to each imported signal's ID before the merge
+
+```bash
+# Import the EXTRACTED pheromone-only XML (NOT the combined colony-archive.xml)
+# $import_tmp_pheromones has <pheromones> as root — the format pheromone-import-xml expects
+# Second argument triggers prefix-tagging — imported signal IDs become "{source_colony}:original_id"
+import_result=$(bash .aether/aether-utils.sh pheromone-import-xml "$import_tmp_pheromones" "$source_colony" 2>&1)
+import_ok=$(echo "$import_result" | jq -r '.ok // false' 2>/dev/null)
+
+if [[ "$import_ok" == "true" ]]; then
+  imported_count=$(echo "$import_result" | jq -r '.result.signal_count // 0' 2>/dev/null)
+else
+  imported_count=0
+  import_error=$(echo "$import_result" | jq -r '.error // "Unknown error"' 2>/dev/null)
+fi
+
+# Clean up temp files
+rm -rf "$import_tmp_dir"
+```
+
+**Step 6.5: Display result**
+
+If import succeeded:
+```
+SIGNALS IMPORTED
+
+Source: {source_colony}
+Imported: {imported_count} pheromone signals
+Tagged with: "{source_colony}:" prefix
+
+Your colony now carries wisdom from {source_colony}.
+Run /ant:status to see current colony state.
+```
+
+If import failed:
+```
+Import failed: {import_error}
+
+The archive may be malformed. Check:
+  .aether/chambers/{chamber_name}/colony-archive.xml
+```
+
 ## Implementation Notes
 
 The `chamber-list` utility returns JSON in this format:

package/.opencode/commands/ant/update.md

@@ -1,148 +1,127 @@
+<!-- Generated from .aether/commands/update.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:update
-description: "🔄🐜📦🐜🔄 Update system files from the global Aether hub"
+description: "🔄🐜📦🐜🔄 Update Aether safely from the global hub (transactional)"
 ---
 
+### 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**. Update this repo's Aether system files from the global distribution hub.
 
+## Safety Rules
+
+1. Use the CLI transactional updater (`aether update`) instead of manual `cp` chains.
+2. Never overwrite colony runtime data (`.aether/data/`) or user wisdom (`.aether/QUEEN.md`).
+3. Do **not** assume version numbers are monotonic. Labels may reset; avoid "downgrade" wording.
+4. If update reports dirty managed files, stop and show recovery options unless user requested force.
+
 ## Instructions
 
 ### Step 1: Check Hub Availability
 
-Use the Read tool to read `~/.aether/version.json` (expand `~` to the user's home directory).
+Run:
+
+```bash
+test -f ~/.aether/version.json && cat ~/.aether/version.json || echo "__NO_HUB__"
+```
 
-If the file does not exist, output:
+If output is `__NO_HUB__`, display:
 
 ```
 No Aether distribution hub found at ~/.aether/
 
 To set up the hub, run:
   npx aether-colony install
-  — or —
+  - or -
   aether install
-
-The hub provides system file updates across all your Aether repos.
 ```
 
-Stop here. Do not proceed.
+Stop here.
 
-Read the `version` field — this is the **available version**.
+Parse `version` from the JSON as `available_version`.
 
-### Step 2: Check Current Version
+### Step 1.5: Verify CLI Availability
 
-Use the Read tool to read `.aether/version.json`.
+Run:
 
-If the file does not exist, set current version to "unknown".
-Otherwise, read the `version` field — this is the **current version**.
+```bash
+command -v aether >/dev/null 2>&1 && echo "__CLI_OK__" || echo "__CLI_MISSING__"
+```
 
-If current version equals available version, output:
+If output is `__CLI_MISSING__`, display:
 
 ```
-Already up-to-date (v{version}).
+The transactional updater is not available because the `aether` CLI is missing.
 
-System files and commands match the global hub.
-Colony data (.aether/data/) is always untouched by updates.
+Install/update it, then retry:
+  npx aether-colony install
+  - or -
+  npm i -g aether-colony
 ```
 
-Stop here. Do not proceed.
+Stop here.
 
-### Step 3: Bootstrap System Files
+### Step 2: Parse Force Flag
 
-If `.aether/aether-utils.sh` does not exist yet (new repo that predates the hub), copy it from the hub first:
-```
-cp ~/.aether/system/aether-utils.sh .aether/aether-utils.sh && chmod +x .aether/aether-utils.sh
-```
+Treat either of these as force:
+- `--force`
+- `--force-update`
 
-Then run using the Bash tool:
-```
-bash .aether/aether-utils.sh bootstrap-system
-```
+Set:
+- `update_flags="--force"` when force requested
+- `update_flags=""` otherwise
 
-This copies system files (docs, utils, aether-utils.sh) from `~/.aether/system/` into `.aether/` using an explicit allowlist. Colony data is never touched.
+### Step 3: Dry-Run Preview
 
-Parse the JSON output to get the count of copied files.
+Run:
 
-### Step 4: Sync Commands (with orphan cleanup)
+```bash
+aether update --dry-run $update_flags
+```
 
-Sync command files from the hub to this repo **and remove stale files** that no longer exist in the hub. This prevents renamed or deleted commands from accumulating as orphans.
+If this fails, show the error output and stop.
 
-For each directory pair, run using the Bash tool:
+### Step 4: Execute Transactional Update
+
+Run:
 
 ```bash
-# Sync Claude commands
-mkdir -p .claude/commands/ant
-cp -R ~/.aether/commands/claude/* .claude/commands/ant/ 2>/dev/null
-# Remove orphans: files in dest that aren't in hub
-comm -23 \
-  <(cd .claude/commands/ant && find . -type f ! -name '.*' | sort) \
-  <(cd ~/.aether/commands/claude && find . -type f ! -name '.*' | sort) \
-  | while read f; do rm ".claude/commands/ant/$f" && echo "  removed stale: .claude/commands/ant/$f"; done
-echo "claude: done"
-
-# Sync OpenCode commands
-mkdir -p .opencode/commands/ant
-cp -R ~/.aether/commands/opencode/* .opencode/commands/ant/ 2>/dev/null
-comm -23 \
-  <(cd .opencode/commands/ant && find . -type f ! -name '.*' | sort) \
-  <(cd ~/.aether/commands/opencode && find . -type f ! -name '.*' | sort) \
-  | while read f; do rm ".opencode/commands/ant/$f" && echo "  removed stale: .opencode/commands/ant/$f"; done
-echo "opencode: done"
-
-# Sync agents
-mkdir -p .opencode/agents
-cp -R ~/.aether/agents/* .opencode/agents/ 2>/dev/null
-comm -23 \
-  <(cd .opencode/agents && find . -type f ! -name '.*' | sort) \
-  <(cd ~/.aether/agents && find . -type f ! -name '.*' | sort) \
-  | while read f; do rm ".opencode/agents/$f" && echo "  removed stale: .opencode/agents/$f"; done
-echo "agents: done"
+aether update $update_flags
 ```
 
-Report any removed stale files in the summary.
+This command handles:
+- checkpoint creation
+- safe sync
+- integrity verification
+- automatic rollback on failure
 
-### Step 5: Register and Version Stamp
+### Step 5: Clear Version Cache
 
-Run using the Bash tool:
-```
-bash .aether/aether-utils.sh registry-add "$(pwd)" "{available_version}"
-```
 
-Substitute `{available_version}` with the version from Step 1.
 
-Then use the Write tool to write `.aether/version.json`:
-```json
-{
-  "version": "{available_version}",
-  "updated_at": "{ISO-8601 timestamp}"
-}
+Run:
+
+
+```bash
+rm -f .aether/data/.version-check-cache
 ```
 
 ### Step 6: Display Summary
 
-Output:
+Display a concise summary:
 
 ```
-🔄🐜📦🐜🔄 ═══════════════════════════════════════════════════
-   A E T H E R   U P D A T E
-═══════════════════════════════════════════════════ 🔄🐜📦🐜🔄
-
-Updated: v{current_version} -> v{available_version}
-
-  System files: {N} updated
-  Commands: synced from hub
-  Agents: synced from hub
-{if stale files were removed:}
-  Stale files removed: {count}
-    {list each removed file}
-{end if}
+🔄🐜📦🐜🔄 AETHER UPDATE COMPLETE
 
+Hub version label: {available_version}
+Update mode: {normal|force}
 Colony data (.aether/data/) untouched.
-Repo registered in ~/.aether/registry.json.
-```
 
-### CLI Equivalents
+Note: version labels are treated as identifiers, not strict upgrade/downgrade ordering.
+```
 
-The CLI version (`aether update`) performs the same sync-with-cleanup and also supports:
 
-- `--dry-run` — Preview what would change without modifying any files
-- `--force` — Stash uncommitted changes in managed files and proceed with the update

package/.opencode/commands/ant/verify-castes.md

@@ -1,85 +1,139 @@
+<!-- Generated from .aether/commands/verify-castes.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:verify-castes
 description: "Verify colony caste assignments and system status"
 ---
 
+### 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**. Display the caste assignments and system status.
 
 ## Step 1: Show Caste Assignments
 
-Display the colony caste structure:
+Display the colony caste structure as a compact table:
+
+
 
 ```
 Aether Colony Caste System
-═══════════════════════════════════════════
+═════════════════════════════════════════
+
 
 CASTE ASSIGNMENTS
-─────────────────
-👑 Prime           - Colony coordination and strategic planning
-🏺 Archaeologist   - Git history analysis and pattern excavation
-🏛️ Architect      - System design and documentation
-🔮 Oracle          - Deep research and foresight
-🗺️ Route Setter    - Task decomposition and planning
-🔨 Builder         - Implementation and coding
-👁️ Watcher         - Verification and testing
-🔍 Scout           - Research and exploration
-🎲 Chaos           - Edge case testing and resilience probing
-🧭 Colonizer       - Environment setup and exploration
-
-───────────────────────────────────────────
+────────────────────────────────────
+Caste                Slot     Active
+────────────────────────────────────
+[reasoning]
+  Archaeologist      opus     yes
+  Architect          opus     yes
+  Auditor            opus     yes
+  Gatekeeper         opus     yes
+  Measurer           opus     yes
+  Oracle             opus     yes
+  Queen              opus     yes
+  Route-setter       opus     yes
+  Sage               opus     yes
+  Tracker            opus     yes
+────────────────────────────────────
+[execution]
+  Ambassador         sonnet   yes
+  Builder            sonnet   yes
+  Chaos              sonnet   yes
+  Disciplines        sonnet   yes
+  Nest               sonnet   yes
+  Pathogens          sonnet   yes
+  Probe              sonnet   yes
+  Provisions         sonnet   yes
+  Scout              sonnet   yes
+  Weaver             sonnet   yes
+  Watcher            sonnet   yes
+────────────────────────────────────
+[inherit]
+  Chronicler         inherit  yes
+  Includer           inherit  yes
+  Keeper             inherit  yes
+
+
+═════════════════════════════════════════
+
 ```
 
+Source of truth: Agent frontmatter `model:` fields in `.claude/agents/ant/*.md`.
+Caste slots come from agent frontmatter (`model:` field).
+
 ## Step 2: Check System Status
 
+
+
 Run using Bash tool: `bash .aether/aether-utils.sh version-check 2>/dev/null || echo "Utils available"`
 
+
 Check LiteLLM proxy status:
 ```bash
 curl -s http://localhost:4000/health 2>/dev/null | grep -q "healthy" && echo "✓ Proxy healthy" || echo "⚠ Proxy not running"
 ```
 
-## Step 3: Show Current Session Info
+## Step 3: Show Current Model Configuration
+
+Display the active model configuration:
+
+
 
 ```
-SESSION INFORMATION
-───────────────────
-All workers in this session use the same model configuration.
-To change models, restart Claude Code with different settings:
-
-export ANTHROPIC_BASE_URL=http://localhost:4000
-export ANTHROPIC_AUTH_TOKEN=sk-litellm-local
-export ANTHROPIC_MODEL=<model-name>
-claude
-
-Available models (via LiteLLM proxy):
-  • glm-5        - Complex reasoning, architecture, planning
-  • kimi-k2.5    - Fast coding, implementation
-  • minimax-2.5  - Validation, research, exploration
+MODEL CONFIGURATION
+════════════════════════════════
+
+Default: Claude API mode (opus -> claude-opus-4, sonnet -> claude-sonnet-4)
+
+To switch to GLM Proxy mode:
+  cp ~/.claude/settings.json.glm ~/.claude/settings.json
+  (opus -> glm-5, sonnet -> glm-5-turbo, haiku -> glm-4.5-air)
+
+To switch back to Claude API:
+  cp ~/.claude/settings.json.claude ~/.claude/settings.json
+
+
+════════════════════════════════
+
+
+Current model mapping from agent frontmatter:
+```bash
+grep "^model:" .claude/agents/ant/*.md
 ```
 
 ## Step 4: Summary
 
+
+
 ```
-═══════════════════════════════════════════
+═══════════════════════════════════════════════════════
 System Status
-═══════════════════════════════════════════
+═══════════════════════════════════════════════════════
+
 Utils: ✓ Operational
 Proxy: {status from Step 2}
-Castes: 10 defined
-
-Note: Model-per-caste routing was attempted but is not
-possible with Claude Code's Task tool (no env var support).
-See archived config: .aether/archive/model-routing/
-Tag: model-routing-v1-archived
+Castes: 24 defined (10 opus, 11 sonnet, 3 inherit)
+Routing: Per-caste via agent frontmatter model: field
 ```
 
+
+
 ## Historical Note
 
-A model-per-caste system was designed and implemented but cannot
-function due to Claude Code Task tool limitations. The complete
-configuration is archived in `.aether/archive/model-routing/`.
+Per-caste model routing was initially attempted using environment variable
+injection at spawn time (archived in `.aether/archive/model-routing/`).
+That approach failed due to Claude Code Task tool limitations.
+
+The current approach uses agent frontmatter `model:` fields, which Claude Code
+handles natively. No Aether code intervention is required -- Claude Code reads
+the frontmatter and resolves the slot name through `ANTHROPIC_DEFAULT_*_MODEL`
+environment variables.
 
-To view the archived configuration:
+To view the archived v1 configuration:
 ```bash
 git show model-routing-v1-archived
 ```

package/.opencode/commands/ant/watch.md

@@ -1,8 +1,15 @@
+<!-- Generated from .aether/commands/watch.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:watch
 description: "👁️🔄🐜🏠🔄👁️ Set up tmux session to watch ants working in real-time"
 ---
 
+### 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**. Set up live visibility into colony activity.
 
 ## Instructions