aether-colony 3.1.17 → 5.1.0

package/.opencode/commands/ant/status.md

@@ -1,15 +1,22 @@
+<!-- Generated from .aether/commands/status.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:status
 description: "📈🐜🏘️🐜📈 Show colony status at a glance"
 ---
 
+### 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**. Show colony status.
 
 ## Instructions
 
 ### Step 0: Version Check (Non-blocking)
 
-Run using the Bash tool: `bash .aether/aether-utils.sh version-check 2>/dev/null || true`
+Run: `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.
 
@@ -51,7 +58,7 @@ If `version` field is missing, "1.0", or "2.0":
 
 ### Step 1.5: Load State and Show Resumption Context
 
-Run using Bash tool: `bash .aether/aether-utils.sh load-state`
+Run: `bash .aether/aether-utils.sh load-state`
 
 If successful and goal is not null:
 1. Extract current_phase from state
@@ -75,22 +82,44 @@ Run: `bash .aether/aether-utils.sh unload-state` to release lock.
 
 From state, extract:
 
+### Step 2.4: Survey Freshness (Advisory)
+
+Run:
+```bash
+survey_docs=$(ls -1 .aether/data/survey/*.md 2>/dev/null | wc -l | tr -d ' ')
+survey_latest=$(ls -t .aether/data/survey/*.md 2>/dev/null | head -1)
+if [[ -n "$survey_latest" ]]; then
+  now_epoch=$(date +%s)
+  modified_epoch=$(stat -f %m "$survey_latest" 2>/dev/null || stat -c %Y "$survey_latest" 2>/dev/null || echo 0)
+  survey_age_days=$(( (now_epoch - modified_epoch) / 86400 ))
+else
+  survey_age_days=-1
+fi
+echo "survey_docs=$survey_docs"
+echo "survey_age_days=$survey_age_days"
+```
+
+Interpretation:
+- If `survey_docs == 0`: `survey_status = "missing"`
+- If `survey_age_days > 14`: `survey_status = "stale"`
+- Otherwise: `survey_status = "fresh"`
+
 ### Step 2.5: Gather Dream Information
 
-Run using Bash tool: `ls -1 .aether/dreams/*.md 2>/dev/null | wc -l`
+Run: `ls -1 .aether/dreams/*.md 2>/dev/null | wc -l`
 
 Capture:
 - Dream count: number of .md files in .aether/dreams/
 - Latest dream: most recent file by name (files are timestamped: YYYY-MM-DD-HHMM.md)
 
-To get latest dream timestamp:
+To get latest dream timestamp, Run:
 ```bash
 ls -1 .aether/dreams/*.md 2>/dev/null | sort | tail -1 | sed 's/.*\/\([0-9]\{4\}-[0-9]\{2\}-[0-9]\{2\}\)-\([0-9]\{4\}\).*/\1 \2/'
 ```
 
 Format the timestamp as: YYYY-MM-DD HH:MM
 
-From state, extract:
+
 
 **Phase info:**
 - Current phase number: `current_phase`
@@ -114,6 +143,15 @@ Extract:
 - Issues count (high, warnings)
 - Notes count (low, informational)
 
+**Escalation state:**
+Count escalated flags by checking for blocker flags with source "escalation":
+
+Run:
+```bash
+escalated_count=$(bash .aether/aether-utils.sh flag-list --type blocker 2>/dev/null | jq '[.result.flags[] | select(.source == "escalation")] | length' 2>/dev/null || echo "0")
+echo "escalated_count=$escalated_count"
+```
+
 **Instincts:**
 From `memory.instincts`:
 - Total count: `instincts.length`
@@ -129,7 +167,7 @@ From `memory.instincts`:
 
 ### Step 2.6: Detect Milestone
 
-Run using Bash tool: `bash .aether/aether-utils.sh milestone-detect`
+Run: `bash .aether/aether-utils.sh milestone-detect`
 
 Extract from JSON result:
 - `milestone`: Current milestone name
@@ -137,6 +175,54 @@ Extract from JSON result:
 - `phases_completed`: Number of completed phases
 - `total_phases`: Total phases in plan
 
+### Step 2.8: Load Memory Health Metrics
+
+Run:
+```bash
+bash .aether/aether-utils.sh memory-metrics
+```
+
+Extract from JSON result:
+- wisdom.total
+- pending.total
+- recent_failures.count
+- last_activity.queen_md_updated
+- last_activity.learning_captured
+
+Format timestamps for display (YYYY-MM-DD HH:MM).
+
+### Step 2.7: Generate Progress Bars
+
+Calculate progress metrics and generate visual bars.
+
+Run:
+```bash
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
+
+# Calculate task progress in current phase
+if [[ "$current_phase" -gt 0 && "$current_phase" -le "$total_phases" ]]; then
+  phase_idx=$((current_phase - 1))
+  tasks_completed=$(jq -r ".plan.phases[$phase_idx].tasks // [] | map(select(.status == \"completed\")) | length" .aether/data/COLONY_STATE.json)
+  tasks_total=$(jq -r ".plan.phases[$phase_idx].tasks // [] | length" .aether/data/COLONY_STATE.json)
+  phase_name=$(jq -r ".plan.phases[$phase_idx].name // \"Unnamed\"" .aether/data/COLONY_STATE.json)
+else
+  tasks_completed=0
+  tasks_total=0
+  phase_name="No plan created"
+fi
+
+# Generate progress bars
+phase_bar=$(bash .aether/aether-utils.sh generate-progress-bar "$current_phase" "$total_phases" 20)
+task_bar=$(bash .aether/aether-utils.sh generate-progress-bar "$tasks_completed" "$tasks_total" 20)
+
+echo "phase_bar=$phase_bar"
+echo "task_bar=$task_bar"
+echo "phase_name=$phase_name"
+```
+
+Store `phase_bar`, `task_bar`, and `phase_name` values for display in Step 3.
+
 ### Step 3: Display
 
 Output format:
@@ -146,30 +232,38 @@ Output format:
       (o o)  AETHER COLONY
       | O |  Status Report
        `-`
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 👑 Goal: <goal (truncated to 60 chars)>
 
-📍 Phase <N>/<M>: <phase name>
-   Tasks: <completed>/<total> complete
+📍 Progress
+   Phase: [████████░░░░░░░░░░░░] <N>/<M> phases
+   Tasks: [████████████████░░░░] <completed>/<total> tasks in Phase <N>
 
 🎯 Focus: <focus_count> areas | 🚫 Avoid: <constraints_count> patterns
 🧠 Instincts: <total> learned (<high_confidence> strong)
 🚩 Flags: <blockers> blockers | <issues> issues | <notes> notes
+{if escalated_count > 0:}
+⚠️  Escalated: {escalated_count} task(s) awaiting your decision
+{end if}
 🏆 Milestone: <milestone> (<version>)
+
 💭 Dreams: <dream_count> recorded (latest: <latest_dream>)
+🗺️ Survey: <survey_docs> docs (<survey_age_days>d old, <fresh|stale|missing>)
+
+📚 Memory Health
+┌─────────────────┬────────┬─────────────────────────────┐
+│ Metric          │ Count  │ Last Updated                │
+├─────────────────┼────────┼─────────────────────────────┤
+│ Wisdom Entries  │ {wisdom_total:>6} │ {queen_updated}             │
+│ Pending Promos  │ {pending_total:>6} │ {learning_updated}          │
+│ Recent Failures │ {failures_count:>6} │ {last_failure}              │
+└─────────────────┴────────┴─────────────────────────────┘
 
 State: <state>
-Next:  <suggested_command>   <phase_context>
 ```
 
-**Phase context for Next line:** Include the phase name inline with the suggestion:
-- READY → `Next:  /ant:build 3   Phase 3: Add Authentication`
-- EXECUTING → `Next:  /ant:continue   Phase 3: Add Authentication`
-- PLANNING → `Next:  /ant:plan`
-- IDLE → `Next:  /ant:init`
-
-Look up the phase name from `plan.phases[current_phase].name` and append it.
+Use the `phase_bar` and `task_bar` values computed in Step 2.7 for the actual bar characters and counts.
 
 **If instincts exist, also show top 3:**
 ```
@@ -179,23 +273,33 @@ Look up the phase name from `plan.phases[current_phase].name` and append it.
    [0.7] 🐜 debugging: Trace to root cause first
 ```
 
-**Suggested command logic (use actual values, not templates):**
-
-Calculate `next_phase = current_phase + 1` from state.
-
-Generate the suggested command based on colony state:
-- IDLE -> `/ant:init`
-- READY -> `/ant:build {next_phase}` (e.g., if current_phase is 2, output `/ant:build 3`)
-- EXECUTING -> `/ant:continue`
-- PLANNING -> `/ant:plan`
-
-The output must be a copy-pasteable command with real numbers, not placeholders.
-
 **Dream display:**
 - If no dreams exist: `💭 Dreams: None recorded`
 - If dreams exist: `💭 Dreams: <count> recorded (latest: YYYY-MM-DD HH:MM)`
 
+**Memory Health display:**
+- If memory-metrics returns empty/null values, show:
+```
+📚 Memory Health
+   No memory data available. Colony wisdom will accumulate as you complete phases.
+```
+
+
+
 **Edge cases:**
-- No phases yet: "Phase 0/0: No plan created"
-- No tasks in phase: "Tasks: 0/0 complete"
+- No phases yet: show `[░░░░░░░░░░░░░░░░░░░░] 0/0 phases`
+- No tasks in phase: show `[░░░░░░░░░░░░░░░░░░░░] 0/0 tasks in Phase 0`
 - No constraints file: "Constraints: 0 focus, 0 avoid"
+
+**At the end of the output, generate the Next Up block:**
+
+Run:
+```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"
+```
+
+This auto-generates state-based recommendations (IDLE → init, READY → build, EXECUTING → continue, PLANNING → plan).

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