aether-colony 3.1.4 → 3.1.15

package/.claude/commands/ant/continue.md

@@ -7,7 +7,23 @@ You are the **Queen Ant Colony**. Reconcile completed work and advance to the ne
 
 ## Instructions
 
-### Step 0: Version Check (Non-blocking)
+Parse `$ARGUMENTS`:
+- 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
+continue_id="continue-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$continue_id"
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Phase continuation" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
+```
+
+### Step 0.5: Version Check (Non-blocking)
 
 Run using the Bash tool: `bash .aether/aether-utils.sh version-check 2>/dev/null || true`
 
@@ -82,8 +98,8 @@ Resolve each command (build, test, types, lint) using this priority chain. Stop
 **Priority 1 — CLAUDE.md (System Context):**
 Check the CLAUDE.md instructions already loaded in your system context for explicit build, test, type-check, or lint commands. These are authoritative and override all other sources.
 
-**Priority 2 — .planning/CODEBASE.md `## Commands`:**
-Read `.planning/CODEBASE.md` and look for the `## Commands` section. Use any commands listed there for slots not yet filled by Priority 1.
+**Priority 2 — codebase.md `## Commands`:**
+Read `.aether/data/codebase.md` and look for the `## Commands` section. Use any commands listed there for slots not yet filled by Priority 1.
 
 **Priority 3 — Fallback Heuristic Table:**
 For any commands still unresolved, check for these files in order, use first match:
@@ -649,6 +665,105 @@ Update COLONY_STATE.json:
 
 Write COLONY_STATE.json.
 
+### Step 2.2: Promote Validated Learnings to QUEEN.md
+
+After extracting learnings in Step 2, promote high-confidence validated learnings to QUEEN.md wisdom.
+
+**Promotion Criteria:**
+- Only learnings with `status: "validated"` are eligible
+- Must have been tested and confirmed working
+- Should represent actionable patterns, not one-off observations
+
+**Process:**
+
+1. **Get colony name from state:**
+   ```bash
+   colony_name=$(jq -r '.session_id | split("_")[1] // "unknown"' .aether/data/COLONY_STATE.json)
+   ```
+
+2. **Extract validated learnings from current phase:**
+   Read `memory.phase_learnings` and filter for entries where:
+   - `phase` matches the completed phase number
+   - Any learning in `learnings[]` has `status: "validated"`
+
+3. **Promote to QUEEN.md using queen-promote:**
+
+   For each validated learning, determine the wisdom type and call queen-promote:
+
+   **Type Mapping:**
+   - Learning about success patterns → `pattern`
+   - Learning about what to avoid/corrections → `redirect`
+   - Learning about fundamental principles → `philosophy`
+   - Learning about technology/stack → `stack`
+
+   ```bash
+   # Example promotions
+   bash .aether/aether-utils.sh queen-promote "pattern" "<learning claim>" "$colony_name"
+   bash .aether/aether-utils.sh queen-promote "redirect" "<what to avoid>" "$colony_name"
+   ```
+
+4. **Log promotion results:**
+   ```bash
+   bash .aether/aether-utils.sh activity-log "PROMOTED" "Queen" "Promoted N validated learnings to QUEEN.md wisdom"
+   ```
+
+**Display promotion summary:**
+```
+🧠 Wisdom Promotion
+==================
+{count} validated learning(s) promoted to QUEEN.md:
+  - [{type}] {brief claim preview}
+```
+
+Skip this step if:
+- No validated learnings exist for this phase
+- QUEEN.md does not exist (run queen-init first if needed)
+- All learnings are still hypotheses or disproven
+
+### Step 2.3: Update Handoff Document
+
+After advancing the phase, update the handoff document with the new current state:
+
+```bash
+# Determine if there's a next phase
+next_phase_id=$((current_phase + 1))
+has_next_phase=$(jq --arg next "$next_phase_id" '.plan.phases | map(select(.id == ($next | tonumber))) | length' .aether/data/COLONY_STATE.json)
+
+# Write updated handoff
+cat > .aether/HANDOFF.md << 'HANDOFF_EOF'
+# Colony Session — Phase Advanced
+
+## Quick Resume
+Run `/ant:build {next_phase_id}` to start working on the current phase.
+
+## State at Advancement
+- Goal: "$(jq -r '.goal' .aether/data/COLONY_STATE.json)"
+- Completed Phase: {completed_phase_id} — {completed_phase_name}
+- Current Phase: {next_phase_id} — {next_phase_name}
+- State: READY
+- Updated: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+## What Was Completed
+- Phase {completed_phase_id} marked as completed
+- Learnings extracted: {learning_count}
+- Instincts updated: {instinct_count}
+- Wisdom promoted to QUEEN.md: {promoted_count}
+
+## Current Phase Tasks
+$(jq -r '.plan.phases[] | select(.id == next_phase_id) | .tasks[] | "- [ ] \(.id): \(.description)"' .aether/data/COLONY_STATE.json)
+
+## Next Steps
+- Build current phase: `/ant:build {next_phase_id}`
+- Review phase details: `/ant:phase {next_phase_id}`
+- Pause colony: `/ant:pause-colony`
+
+## Session Note
+Phase advanced successfully. Colony is READY to build Phase {next_phase_id}.
+HANDOFF_EOF
+```
+
+This handoff reflects the post-advancement state, allowing seamless resumption even if the session is lost.
+
 ### Step 2.4: Update Changelog
 
 **Append a changelog entry for the completed phase.**
@@ -681,57 +796,88 @@ If `CHANGELOG.md` exists in the project root:
 
 After the phase is advanced and changelog updated, suggest a commit to preserve the milestone.
 
-1. **Generate the commit message:**
+#### Step 2.6.1: Capture AI Description
+
+**As the AI, briefly describe what was accomplished in this phase.**
+
+Look at:
+1. The phase PLAN.md `<objective>` section (what we set out to do)
+2. Tasks that were marked complete
+3. Files that were modified (from git diff --stat)
+4. Any patterns or decisions recorded
+
+**Provide a brief, memorable description** (10-15 words, imperative mood):
+- Good: "Implement task-based model routing with keyword detection and precedence chain"
+- Good: "Fix build timing by removing background execution from worker spawns"
+- Bad: "Phase complete" (too vague)
+- Bad: "Modified files in bin/lib" (too mechanical)
+
+Store this as `ai_description` for the commit message.
+
+#### Step 2.6.2: Generate Enhanced Commit Message
+
 ```bash
-bash .aether/aether-utils.sh generate-commit-message "milestone" {phase_id} "{phase_name}" "{one_line_summary}"
+bash .aether/aether-utils.sh generate-commit-message "contextual" {phase_id} "{phase_name}" "{ai_description}" {plan_number}
 ```
-Parse the returned JSON to extract `message` and `files_changed`.
 
-2. **Check files changed:**
+Parse the returned JSON to extract:
+- `message` - the commit subject line
+- `body` - structured metadata (Scope, Files)
+- `files_changed` - file count
+- `subsystem` - derived subsystem name
+- `scope` - phase.plan format
+
+**Check files changed:**
 ```bash
 git diff --stat HEAD 2>/dev/null | tail -5
 ```
 If not in a git repo or no changes detected, skip this step silently.
 
-3. **Display the suggestion:**
+**Display the enhanced suggestion:**
 ```
 ──────────────────────────────────────────────────
 Commit Suggestion
 ──────────────────────────────────────────────────
 
-  Message:  {generated_message}
-  Files:    {files_changed} files changed
-  Preview:  {first 5 lines of git diff --stat}
+  AI Description: {ai_description}
+
+  Formatted Message:
+  {message}
+
+  Metadata:
+  Scope: {scope}
+  Files: {files_changed} files changed
+  Preview: {first 5 lines of git diff --stat}
 
 ──────────────────────────────────────────────────
 ```
 
-4. **Use AskUserQuestion:**
+**Use AskUserQuestion:**
 ```
 Commit this milestone?
 
 1. Yes, commit with this message
-2. Yes, but let me write the message
+2. Yes, but let me edit the description
 3. No, I'll commit later
 ```
 
-5. **If option 1 ("Yes, commit with this message"):**
+**If option 1 ("Yes, commit with this message"):**
 ```bash
-git add -A && git commit -m "{generated_message}"
+git add -A && git commit -m "{message}" -m "{body}"
 ```
-Display: `Committed: {generated_message} ({files_changed} files)`
+Display: `Committed: {message} ({files_changed} files)`
 
-6. **If option 2 ("Yes, but let me write the message"):**
-Use AskUserQuestion to get the user's custom commit message, then:
-```bash
-git add -A && git commit -m "{custom_message}"
+**If option 2 ("Yes, but let me edit"):**
+Use AskUserQuestion to get the user's custom description:
+```
+Enter your description (or press Enter to keep: '{ai_description}'):
 ```
-Display: `Committed: {custom_message} ({files_changed} files)`
+Then regenerate the commit message with the new description and commit.
 
-7. **If option 3 ("No, I'll commit later"):**
+**If option 3 ("No, I'll commit later"):**
 Display: `Skipped. Your changes are saved on disk but not committed.`
 
-8. **Record the suggestion to prevent double-prompting:**
+**Record the suggestion to prevent double-prompting:**
 Set `last_commit_suggestion_phase` to `{phase_id}` in COLONY_STATE.json (add the field at the top level if it does not exist).
 
 **Error handling:** If any git command fails (not a repo, merge conflict, pre-commit hook rejection), display the error output and continue to the next step. The commit suggestion is advisory only -- it never blocks the flow.
@@ -780,6 +926,26 @@ Clear context now?
 
 Continue to Step 2.5 (Project Completion) or Step 3 (Display Result).
 
+### Step 2.8: Update Context Document
+
+After phase advancement is complete, update `.aether/CONTEXT.md`:
+
+**Log the activity:**
+```bash
+bash .aether/aether-utils.sh context-update activity "continue" "Phase {prev_id} completed, advanced to {next_id}" "—"
+```
+
+**Update the phase:**
+```bash
+bash .aether/aether-utils.sh context-update update-phase {next_id} "{next_phase_name}" "YES" "Phase advanced, ready to build"
+```
+
+**Log any decisions from this session:**
+If any architectural decisions were made during verification, also run:
+```bash
+bash .aether/aether-utils.sh context-update decision "{decision_description}" "{rationale}" "Queen"
+```
+
 ### Step 2.5: Project Completion
 
 Runs ONLY when all phases complete.
@@ -803,6 +969,9 @@ Runs ONLY when all phases complete.
 🧠 Colony Learnings:
 {condensed learnings from memory.phase_learnings}
 
+👑 Wisdom Added to QUEEN.md:
+{count} patterns/redirects/philosophies promoted across all phases
+
 🐜 The colony rests. Well done!
 ```
 
@@ -811,6 +980,12 @@ Runs ONLY when all phases complete.
 
 ### Step 3: Display Result
 
+**If visual_mode is true, render final swarm display:**
+```bash
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Phase advanced" "Colony" '{"read":5,"grep":2,"edit":3,"bash":2}' 100 "fungus_garden" 100
+bash .aether/aether-utils.sh swarm-display-render "$continue_id"
+```
+
 Output:
 
 ```
@@ -823,6 +998,11 @@ Output:
 🧠 Learnings Extracted:
 {list learnings added}
 
+👑 Wisdom Promoted to QUEEN.md:
+{for each promoted learning:}
+   [{type}] {brief claim}
+{end for}
+
 🐜 Instincts Updated:
 {for each instinct created or updated:}
    [{confidence}] {domain}: {action}
@@ -841,6 +1021,16 @@ Output:
    /ant:focus "<area>"    🎯 Guide colony attention
 
 💾 State persisted — context clear suggested above
+
+📋 Context document updated at `.aether/CONTEXT.md`
 ```
 
 **IMPORTANT:** In the "Next Steps" section above, substitute the actual phase number for `{next_id}` (calculated in Step 2 as `current_phase + 1`). For example, if advancing to phase 4, output `/ant:build 4` not `/ant:build {next_id}`.
+
+### Step 4: Update Session
+
+Update the session tracking file to enable `/ant:resume` after context clear:
+
+```bash
+bash .aether/aether-utils.sh session-update "/ant:continue" "/ant:build {next_id}" "Phase {prev_id} completed, advanced to Phase {next_id}"
+```

package/.claude/commands/ant/council.md

@@ -7,6 +7,22 @@ You are the **Queen Ant Colony**. Convene the council to clarify user intent and
 
 ## Instructions
 
+Parse `$ARGUMENTS`:
+- 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
 
 Read `.aether/data/COLONY_STATE.json`.
@@ -223,6 +239,12 @@ 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
 

package/.claude/commands/ant/dream.md

@@ -29,6 +29,24 @@ You wander the codebase like a monk walks a garden — not to fix, not to judge,
 
 ## Instructions
 
+### Step 0: Parse Arguments
+
+Parse `$ARGUMENTS`:
+- 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
 
 Read these files in parallel to understand the world you're dreaming about:

package/.claude/commands/ant/entomb.md

@@ -7,6 +7,22 @@ You are the **Queen**. Archive the completed colony to chambers.
 
 ## Instructions
 
+Parse `$ARGUMENTS`:
+- 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`.
@@ -17,6 +33,28 @@ No colony to entomb. Run /ant:init first.
 ```
 Stop here.
 
+#### Step 1.5: Check for Concurrent Entomb Operations
+
+Capture session start time:
+```bash
+ENTOMB_START=$(date +%s)
+```
+
+Check for incomplete chamber operations:
+```bash
+# Check for incomplete chambers (no colony-state.json)
+incomplete_chambers=$(find .aether/chambers -type d -mindepth 1 -maxdepth 1 2>/dev/null | while read dir; do
+  if [[ ! -f "$dir/colony-state.json" ]]; then
+    echo "$dir"
+  fi
+done)
+
+if [[ -n "$incomplete_chambers" ]]; then
+  echo "Warning: Incomplete chamber operations detected:"
+  echo "$incomplete_chambers"
+fi
+```
+
 ### Step 2: Validate Colony Can Be Entombed
 
 Extract: `goal`, `state`, `current_phase`, `plan.phases`, `memory.decisions`, `memory.phase_learnings`.
@@ -99,7 +137,91 @@ Entombment cancelled. Colony remains active.
 ```
 Stop here.
 
-### Step 5: Create Chamber
+### Step 5: Promote Wisdom to QUEEN.md
+
+Before creating the chamber, promote validated learnings to QUEEN.md for future colonies.
+
+**Step 5.1: Ensure QUEEN.md exists**
+
+```bash
+queen_file=".aether/docs/QUEEN.md"
+if [[ ! -f "$queen_file" ]]; then
+  init_result=$(bash .aether/aether-utils.sh queen-init 2>/dev/null || echo '{"ok":false}')
+  init_ok=$(echo "$init_result" | jq -r '.ok // false')
+  if [[ "$init_ok" == "true" ]]; then
+    created=$(echo "$init_result" | jq -r '.result.created // false')
+    if [[ "$created" == "true" ]]; then
+      bash .aether/aether-utils.sh activity-log "CREATED" "Queen" "Initialized QUEEN.md for wisdom promotion"
+    fi
+  fi
+fi
+```
+
+**Step 5.2: Extract and promote validated learnings**
+
+```bash
+# Extract colony name from goal (sanitized)
+colony_name=$(jq -r '.goal' .aether/data/COLONY_STATE.json | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]' '-' | sed 's/^-//;s/-$//' | cut -c1-30)
+
+# Extract validated learnings from phase_learnings
+learnings=$(jq -c '.memory.phase_learnings // []' .aether/data/COLONY_STATE.json)
+
+# Extract decisions
+decisions=$(jq -c '.memory.decisions // []' .aether/data/COLONY_STATE.json)
+
+promotion_count=0
+
+# Promote patterns from validated learnings
+if [[ -f "$queen_file" ]]; then
+  # Process each phase's learnings
+  echo "$learnings" | jq -c '.[]' 2>/dev/null | while read -r learning_group; do
+    phase=$(echo "$learning_group" | jq -r '.phase // "unknown"')
+    # Extract individual learnings and promote as patterns
+    echo "$learning_group" | jq -r '.learnings[]? | select(.status == "validated") | .claim' 2>/dev/null | while read -r claim; do
+      if [[ -n "$claim" && "$claim" != "null" ]]; then
+        # Truncate if too long
+        content=$(echo "$claim" | cut -c1-200)
+        result=$(bash .aether/aether-utils.sh queen-promote "pattern" "$content" "$colony_name" 2>/dev/null || echo '{"ok":false}')
+        if [[ $(echo "$result" | jq -r '.ok // false') == "true" ]]; then
+          promotion_count=$((promotion_count + 1))
+        fi
+      fi
+    done
+  done
+
+  # Promote high-confidence instincts as patterns
+  instincts=$(jq -c '.memory.instincts // []' .aether/data/COLONY_STATE.json)
+  echo "$instincts" | jq -c '.[]' 2>/dev/null | while read -r instinct; do
+    confidence=$(echo "$instinct" | jq -r '.confidence // 0')
+    status=$(echo "$instinct" | jq -r '.status // ""')
+    action=$(echo "$instinct" | jq -r '.action // ""')
+    # Promote validated instincts with high confidence (>= 0.7)
+    if [[ "$status" == "validated" && $(echo "$confidence >= 0.7" | bc -l 2>/dev/null || echo 0) -eq 1 && -n "$action" ]]; then
+      content=$(echo "$action" | cut -c1-200)
+      result=$(bash .aether/aether-utils.sh queen-promote "pattern" "$content" "$colony_name" 2>/dev/null || echo '{"ok":false}')
+      if [[ $(echo "$result" | jq -r '.ok // false') == "true" ]]; then
+        promotion_count=$((promotion_count + 1))
+      fi
+    fi
+  done
+
+  # Log promotion results
+  bash .aether/aether-utils.sh activity-log "MODIFIED" "Queen" "Promoted $promotion_count validated learnings to QUEEN.md from entombed colony"
+fi
+```
+
+**Step 5.3: Display promotion summary**
+
+```
+---
+Wisdom Promotion Summary
+---
+Colony: {colony_name}
+Promoted: {promotion_count} validated patterns to QUEEN.md
+---
+```
+
+### Step 6: Create Chamber
 
 Generate chamber name:
 ```bash
@@ -118,7 +240,7 @@ while [[ -d ".aether/chambers/$chamber_name" ]]; do
 done
 ```
 
-### Step 6: Create Chamber Using Utilities
+### Step 7: Create Chamber Using Utilities
 
 Extract decisions and learnings as JSON arrays:
 ```bash
@@ -143,7 +265,7 @@ bash .aether/aether-utils.sh chamber-create \
   '{learnings_json}'
 ```
 
-### Step 7: Verify Chamber Integrity
+### Step 8: Verify Chamber Integrity
 
 Run verification:
 ```bash
@@ -161,7 +283,7 @@ The colony has NOT been reset. Please check the chamber directory:
 ```
 Stop here.
 
-### Step 8: Reset Colony State
+### Step 9: Reset Colony State
 
 Backup current state:
 ```bash
@@ -204,7 +326,45 @@ Remove backup after successful reset:
 rm -f .aether/data/COLONY_STATE.json.bak
 ```
 
-### Step 9: Display Result
+### Step 9.5: Write Final Handoff
+
+After entombing the colony, write the final handoff documenting the archived colony:
+
+```bash
+cat > .aether/HANDOFF.md << 'HANDOFF_EOF'
+# Colony Session — ENTOMBED
+
+## ⚰️ Colony Archived
+**Status:** Entombed in Chambers — Colony work preserved
+
+## Chamber Location
+.aether/chambers/{chamber_name}/
+
+## Colony Summary
+- Goal: "{goal}"
+- Phases: {completed} completed of {total}
+- Milestone: {milestone}
+- Entombed At: {timestamp}
+
+## 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)
+
+## Session Note
+This colony has been entombed and the active state reset.
+The colony rests. Its learnings are preserved in the chamber.
+
+To start anew: /ant:lay-eggs "<new goal>"
+To explore chambers: /ant:tunnels
+HANDOFF_EOF
+```
+
+This handoff serves as the record of the entombed colony.
+
+### Step 10: Display Result
 
 ```
 🏺 ═══════════════════════════════════════════════════
@@ -220,7 +380,19 @@ rm -f .aether/data/COLONY_STATE.json.bak
 📦 Chamber: .aether/chambers/{chamber_name}/
 
 🐜 The colony rests. Its learnings are preserved.
-   Run /ant:lay-eggs to begin anew.
+
+💾 State persisted — safe to /clear
+
+🐜 What would you like to do next?
+   1. /ant:lay-eggs "<new goal>"  — Start a new colony
+   2. /ant:tunnels                — Browse archived colonies
+   3. /clear                      — Clear context and continue
+
+Use AskUserQuestion with these three options.
+
+If option 1 selected: proceed to run /ant:lay-eggs flow
+If option 2 selected: run /ant:tunnels
+If option 3 selected: display "Run /ant:lay-eggs to begin anew after clearing"
 ```
 
 ### Edge Cases