aether-colony 5.0.0 → 5.2.1

package/.opencode/commands/ant/swarm.md

@@ -1,357 +1,15 @@
+<!-- Generated from .aether/commands/swarm.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:swarm
 description: "🔥🐜🗡️🐜🔥 Real-time colony swarm display + stubborn bug destroyer"
 ---
 
-You are the **Queen Ant Colony**. Deploy the swarm to destroy a stubborn bug or view real-time colony activity.
-
-## 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.
 
-### Quick View Mode (No Arguments)
-
-If `$normalized_args` is empty or equals "--watch":
-
-Run the real-time swarm display:
-```bash
-bash .aether/utils/swarm-display.sh
-```
-
-This shows:
-- Active ants with caste colors and emojis (🔨 Builder in blue, etc.)
-- Tool usage stats per ant (📖5 🔍3 ✏️2 ⚡1)
-- Trophallaxis metrics (🍯 token consumption)
-- Timing information (elapsed time per ant)
-- Chamber activity map (which nest zones have active ants)
-- Animated status phrases ("excavating...", "foraging...")
-
-Display updates automatically as ants start/complete work.
-Press Ctrl+C to exit.
-
-### Bug Destruction Mode (With Arguments)
-
-The problem to investigate is: `$normalized_args`
-
-#### Step 1: Validate Input
-
-If `$normalized_args` is empty:
-```
-🔥🐜🗡️🐜🔥 SWARM
-
-Deploy parallel scouts to investigate and fix stubborn bugs.
-
-Usage: /ant:swarm "<describe the problem>"
-
-Examples:
-  /ant:swarm "Tests keep failing in auth module"
-  /ant:swarm "TypeError: Cannot read property 'id' of undefined"
-  /ant:swarm "API returns 500 but I can't find the cause"
-
-This is the nuclear option - use when repeated fix attempts fail.
-```
-Stop here.
-
-#### Step 2: Read State & Initialize
-
-Read `.aether/data/COLONY_STATE.json`.
-If `goal` is null → "No colony initialized. Run /ant:init first.", stop.
-
-Generate swarm ID: `swarm-<unix_timestamp>`
-
-Initialize swarm findings:
-```bash
-bash .aether/aether-utils.sh swarm-findings-init "<swarm_id>"
-```
-
-Initialize swarm display for real-time tracking:
-```bash
-bash .aether/aether-utils.sh swarm-display-init "<swarm_id>"
-```
-
-Display header:
-```
-🔥🐜🗡️🐜🔥 ═══════════════════════════════════════════════
-                S W A R M   D E P L O Y E D
-═══════════════════════════════════════════════ 🔥🐜🗡️🐜🔥
-
-🎯 Target: "{problem description}"
-📍 Swarm ID: {swarm_id}
-
-⚡ Deploying 4 parallel scouts...
-```
-
-#### Step 3: Create Git Checkpoint
-
-Before any investigation that might lead to fixes:
-```bash
-bash .aether/aether-utils.sh autofix-checkpoint "pre-swarm-$SWARM_ID"
-```
-
-Store the result for potential rollback:
-- `checkpoint_type` = result.type ("stash", "commit", or "none")
-- `checkpoint_ref` = result.ref
-
-```
-💾 Checkpoint: {checkpoint_type} → {checkpoint_ref}
-```
-
-#### Step 4: Read Context
-
-Read existing blockers for context:
-```bash
-bash .aether/aether-utils.sh flag-list --type blocker
-```
-
-Read recent activity:
-```bash
-tail -50 .aether/data/activity.log 2>/dev/null || echo "(no activity log)"
-```
-
-Scan recent git commits for context:
-```bash
-git log --oneline -20 2>/dev/null || echo "(no git history)"
-```
-
-#### Step 5: Deploy 4 Parallel Scouts
-
-Use the **Task** tool to spawn 4 scouts **in a single message** (parallel execution):
-
-Log each scout to swarm display before spawning:
-```bash
-bash .aether/aether-utils.sh swarm-display-update "{swarm_id}-Archaeologist" "scout" "excavating" "Git history investigation" "Queen" '{"read":0,"grep":0,"edit":0,"bash":3}' 0
-bash .aether/aether-utils.sh swarm-display-update "{swarm_id}-PatternHunter" "scout" "excavating" "Pattern search for similar code" "Queen" '{"read":5,"grep":10,"edit":0,"bash":0}' 0
-bash .aether/aether-utils.sh swarm-display-update "{swarm_id}-ErrorAnalyst" "scout" "excavating" "Error chain analysis" "Queen" '{"read":3,"grep":5,"edit":0,"bash":2}' 0
-bash .aether/aether-utils.sh swarm-display-update "{swarm_id}-WebResearcher" "scout" "excavating" "External source research" "Queen" '{"read":0,"grep":0,"edit":0,"bash":0}' 0
-```
-
-**Scout 1: 🏛️ Git Archaeologist**
-```
-You are {swarm_id}-Archaeologist, a 🏛️ Scout Ant.
-
-Investigate git history for: {problem description}
-
-Steps:
-1. Run `git log --oneline -30`
-2. Run `git log -p --since="1 week ago" -- {relevant files}`
-3. Run `git blame {suspected file}` if mentioned
-4. Find commits that introduced the bug
-
-Return ONLY this JSON:
-{"scout": "git-archaeologist", "confidence": 0.0-1.0, "finding": {"likely_cause": "...", "relevant_commits": [], "when_it_broke": "...", "evidence": []}, "suggested_fix": "..."}
-```
-
-**Scout 2: 🔍 Pattern Hunter**
-```
-You are {swarm_id}-PatternHunter, a 🔍 Scout Ant.
-
-Find working patterns for: {problem description}
-
-Steps:
-1. Grep/glob for related working code
-2. Find how other parts handle this
-3. Look for test files showing correct usage
-4. Identify applicable patterns
-
-Return ONLY this JSON:
-{"scout": "pattern-hunter", "confidence": 0.0-1.0, "finding": {"working_examples": [], "applicable_patterns": [], "differences": "..."}, "suggested_fix": "..."}
-```
-
-**Scout 3: 💥 Error Analyst**
-```
-You are {swarm_id}-ErrorAnalyst, a 🔍 Scout Ant.
-
-Analyze error: {problem description}
-
-Steps:
-1. Trace through stack trace frames
-2. Identify actual failing line vs surface error
-3. Check for null refs, async issues, type mismatches
-4. Look for error handling masking the issue
-
-Return ONLY this JSON:
-{"scout": "error-analyst", "confidence": 0.0-1.0, "finding": {"root_cause": "...", "error_chain": [], "masked_by": "...", "category": "null-ref|async|type|logic|config|dependency"}, "suggested_fix": "..."}
-```
-
-**Scout 4: 🌐 Web Researcher**
-```
-You are {swarm_id}-WebResearcher, a 🔍 Scout Ant.
-
-Research external solutions for: {problem description}
-
-Steps:
-1. Search for exact error message
-2. Find library/framework docs
-3. Check GitHub issues
-4. Find Stack Overflow answers
-
-Return ONLY this JSON:
-{"scout": "web-researcher", "confidence": 0.0-1.0, "finding": {"known_issue": true/false, "documentation_link": "...", "similar_issues": [], "community_solutions": []}, "suggested_fix": "..."}
-```
-
-Wait for all 4 scouts to complete.
-
-#### Step 6: Collect and Cross-Compare Findings
-
-As each scout returns, add their findings:
-```bash
-bash .aether/aether-utils.sh swarm-findings-add "{swarm_id}" "{scout_type}" "{confidence}" '{finding_json}'
-```
-
-Update scout status in swarm display to "completed":
-```bash
-bash .aether/aether-utils.sh swarm-display-update "{swarm_id}-Archaeologist" "scout" "completed" "Git history investigation" "Queen" '{"read":3,"grep":0,"edit":0,"bash":5}' 150
-```
-
-Display each scout's report as they complete:
-```
-🏛️ Archaeologist [{confidence}]
-   {summary of finding}
-
-🔍 PatternHunter [{confidence}]
-   {summary of finding}
-
-💥 ErrorAnalyst [{confidence}]
-   {summary of finding}
-
-🌐 WebResearcher [{confidence}]
-   {summary of finding}
-```
-
-#### Step 7: Synthesize Solution
-
-Cross-compare all findings:
-1. Identify where scouts agree (high confidence)
-2. Note where scouts disagree (investigate further)
-3. Weight by confidence scores
-4. Prefer findings with concrete evidence
-
-Rank fix options:
-```
-═══════════════════════════════════════════════
-              S O L U T I O N   R A N K I N G
-═══════════════════════════════════════════════
-
-#1 [0.85 confidence] {best solution}
-   Evidence: {supporting scouts}
-
-#2 [0.72 confidence] {alternative}
-   Evidence: {supporting scouts}
-
-#3 [0.45 confidence] {fallback}
-   Evidence: {limited support}
-```
-
-#### Step 8: Apply Best Fix
-
-Select the highest-confidence solution and apply it:
-
-**Command Resolution:** Before running verification, resolve `{build_command}` and `{test_command}` using this priority chain (stop at first match per command):
-1. **CLAUDE.md** — Check project CLAUDE.md (in your system context) for explicit build/test commands
-2. **CODEBASE.md** — Read `.aether/data/codebase.md` `## Commands` section
-3. **Fallback** — Use project manifest heuristics (e.g., `npm run build`/`npm test` for package.json)
-
-```
-🔧 Applying Fix #1...
-```
-
-Make the actual code changes using Edit/Write tools.
-
-After applying:
-```bash
-# Run verification
-{build_command} 2>&1 | tail -30
-{test_command} 2>&1 | tail -50
-```
-
-#### Step 9: Verify and Report
-
-**If verification passes:**
-```
-✅ FIX VERIFIED
-
-Build: PASS
-Tests: PASS
-
-🔥🐜🗡️🐜🔥 Swarm successful!
-
-The fix will be confirmed when you run:
-  /ant:continue
-```
-
-Inject learnings:
-- Add FOCUS for the pattern that worked (to constraints.json)
-- Add REDIRECT for the anti-pattern that caused the bug (to constraints.json)
-
-Set solution in swarm findings:
-```bash
-bash .aether/aether-utils.sh swarm-solution-set "{swarm_id}" '{solution_json}'
-```
-
-Log success:
-```bash
-bash .aether/aether-utils.sh activity-log "SWARM_SUCCESS" "Queen" "Swarm {swarm_id} fixed: {brief description}"
-```
-
-**If verification fails:**
-```
-❌ FIX VERIFICATION FAILED
-
-Build: {status}
-Tests: {status}
-
-Attempting rollback...
-```
-
-Rollback:
-```bash
-bash .aether/aether-utils.sh autofix-rollback "{checkpoint_type}" "{checkpoint_ref}"
-```
-
-Log failure:
-```bash
-bash .aether/aether-utils.sh activity-log "SWARM_FAILED" "Queen" "Swarm {swarm_id} fix failed verification"
-```
-
-Track attempt count. If this is the 3rd failure on the same issue:
-```
-⚠️ ARCHITECTURAL CONCERN
-
-This problem has resisted 3 swarm attempts.
-
-This suggests:
-  - Root cause may be architectural, not implementational
-  - Pattern may be fundamentally unsound
-  - Different approach needed
-
-Recommended:
-  - Review the codebase architecture
-  - Consider refactoring vs. patching
-  - Create a new phase for structural fix
-
-Swarm will not attempt further fixes on this issue.
-```
-
-#### Step 10: Cleanup
-
-Clear swarm display:
-```bash
-bash .aether/aether-utils.sh swarm-display-init "complete-{swarm_id}"
-```
-
-Archive swarm findings:
-```bash
-bash .aether/aether-utils.sh swarm-cleanup "{swarm_id}" --archive
-```
+You are the **Queen Ant Colony**. Deploy the swarm to destroy a stubborn bug or view real-time colony activity.
 
-Display next steps:
-```
-🐜 Next steps:
-   /ant:continue   ⏭️  Verify and advance phase
-   /ant:status     📊 View colony status
-   /ant:flags      🚩 Check remaining blockers
-```
+## Instructions

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
 

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

@@ -1,191 +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 Pending State and Current Version
+### Step 1.5: Verify CLI Availability
 
-First, check for a pending sentinel using the Bash tool:
+Run:
 
 ```bash
-test -f .aether/.update-pending && echo "PENDING" || echo "CLEAN"
+command -v aether >/dev/null 2>&1 && echo "__CLI_OK__" || echo "__CLI_MISSING__"
 ```
 
-If output is "PENDING":
-- Output: `Detected incomplete update, re-syncing...`
-- Run using the Bash tool: `rm -f .aether/.update-pending`
-- Skip the version comparison entirely — proceed directly to Step 3.
-
-If output is "CLEAN":
-
-Use the Read tool to read `.aether/version.json`.
-
-If the file does not exist, set current version to "unknown".
-Otherwise, read the `version` field — this is the **current version**.
-
-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: Sync System Files from Hub
+### Step 2: Parse Force Flag
 
-The hub stores all system files at `~/.aether/system/`.
+Treat either of these as force:
+- `--force`
+- `--force-update`
 
-Run ONE bash command that syncs everything:
+Set:
+- `update_flags="--force"` when force requested
+- `update_flags=""` otherwise
 
-```bash
-mkdir -p .aether/docs .aether/utils .aether/templates .aether/schemas .aether/exchange && \
-cp -f ~/.aether/system/aether-utils.sh .aether/ && \
-cp -f ~/.aether/system/workers.md .aether/ 2>/dev/null || true && \
-cp -f ~/.aether/system/CONTEXT.md .aether/ 2>/dev/null || true && \
-cp -f ~/.aether/system/model-profiles.yaml .aether/ 2>/dev/null || true && \
-cp -Rf ~/.aether/system/docs/* .aether/docs/ 2>/dev/null || true && \
-cp -Rf ~/.aether/system/utils/* .aether/utils/ 2>/dev/null || true && \
-cp -Rf ~/.aether/system/templates/* .aether/templates/ 2>/dev/null || true && \
-cp -Rf ~/.aether/system/schemas/* .aether/schemas/ 2>/dev/null || true && \
-cp -Rf ~/.aether/system/exchange/* .aether/exchange/ 2>/dev/null || true && \
-chmod +x .aether/aether-utils.sh && \
-echo "System files synced"
-```
-
-Colony data (`.aether/data/`) is never touched.
+### Step 3: Dry-Run Preview
 
-If any sync step fails, output:
-```
-Update couldn't finish — some files didn't copy. Run /ant:update again to retry.
-```
-
-### Step 3.5: Sync Rules to .claude/rules/
-
-Rules files teach Claude Code about the colony system. Sync them from the hub:
+Run:
 
 ```bash
-# Sync rules if hub has them
-if [ -d ~/.aether/system/rules ]; then
-  mkdir -p .claude/rules
-  cp -Rf ~/.aether/system/rules/* .claude/rules/ 2>/dev/null || true
-  echo "Rules synced"
-fi
+aether update --dry-run $update_flags
 ```
 
-### Step 4: Sync Commands (with orphan cleanup)
+If this fails, show the error output and stop.
 
-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.
+### Step 4: Execute Transactional Update
 
-For each directory pair, run using the Bash tool:
+Run:
 
 ```bash
-# Sync Claude commands
-mkdir -p .claude/commands/ant
-cp -R ~/.aether/system/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/system/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/system/commands/opencode/* .opencode/commands/ant/ 2>/dev/null
-comm -23 \
-  <(cd .opencode/commands/ant && find . -type f ! -name '.*' | sort) \
-  <(cd ~/.aether/system/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/system/agents/* .opencode/agents/ 2>/dev/null
-comm -23 \
-  <(cd .opencode/agents && find . -type f ! -name '.*' | sort) \
-  <(cd ~/.aether/system/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:
+
 
-Then delete any leftover pending sentinel (update is now complete) using the Bash tool:
 ```bash
-rm -f .aether/.update-pending
+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