aether-colony 5.0.0 → 5.1.0

package/.aether/commands/watch.yaml

@@ -0,0 +1,454 @@
+name: "ant:watch"
+description: "👁️🔄🐜🏠🔄👁️ Set up tmux session to watch ants working in real-time"
+body_claude: |
+  You are the **Queen**. Set up live visibility into colony activity.
+
+  ## Instructions
+
+  ### Step 1: Check Prerequisites
+
+  Use Bash with description "Checking for tmux..." to check if tmux is available:
+  ```bash
+  command -v tmux >/dev/null 2>&1 && echo "tmux_available" || echo "tmux_missing"
+  ```
+
+  If tmux is missing:
+  ```
+  tmux is required for live colony viewing.
+
+  Install with:
+    macOS:  brew install tmux
+    Ubuntu: sudo apt install tmux
+    Fedora: sudo dnf install tmux
+  ```
+  Stop here.
+
+  ### Step 2: Initialize Activity Log
+
+  Ensure activity log exists by running using the Bash tool with description "Initializing watch files...":
+  ```bash
+  mkdir -p .aether/data
+  touch .aether/data/activity.log
+  ```
+
+  ### Step 2.5: Check for Stale Watch Session
+
+  Capture session start time:
+  ```bash
+  WATCH_START=$(date +%s)
+  ```
+
+  Check for stale watch files by running using the Bash tool with description "Checking for stale watch session...":
+  ```bash
+  stale_check=$(bash .aether/aether-utils.sh session-verify-fresh --command watch "" "$WATCH_START")
+  has_stale=$(echo "$stale_check" | jq -r '.stale | length' 2>/dev/null || echo "0")
+  ```
+
+  If stale files exist, they will be overwritten by the new watch session.
+  The tmux session check in Step 4 handles concurrent sessions.
+
+  ### Step 3: Create Status File
+
+  Write initial status to `.aether/data/watch-status.txt`:
+
+  ```
+         .-.
+        (o o)  AETHER COLONY
+        | O |  Live Status
+         `-`
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Session Started: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  State: IDLE
+  Phase: -/-
+
+  Active Workers:
+    (none)
+
+  Last Activity:
+    (waiting for colony activity)
+  ```
+
+  ### Step 4: Create or Attach to tmux Session
+
+  Check if session exists by running using the Bash tool with description "Checking tmux session...":
+  ```bash
+  tmux has-session -t aether-colony 2>/dev/null && echo "exists" || echo "new"
+  ```
+
+  **If session exists:** Attach to it by running using the Bash tool with description "Attaching to watch session...":
+  ```bash
+  tmux attach-session -t aether-colony
+  ```
+  Output: `Attached to existing aether-colony session.`
+  Stop here.
+
+  **If session is new:** Create the layout.
+
+  ### Step 5: Create tmux Layout (4-Pane)
+
+  Use Bash with description "Creating watch session layout..." to create the session with 4 panes in a 2x2 grid:
+
+  ```bash
+  # Create session with first pane
+  tmux new-session -d -s aether-colony -n colony
+
+  # Split into 4 panes (2x2 grid)
+  # First split horizontally (left|right)
+  tmux split-window -h -t aether-colony:colony
+
+  # Split left side vertically (top-left, bottom-left)
+  tmux split-window -v -t aether-colony:colony.0
+
+  # Split right side vertically (top-right, bottom-right)
+  tmux split-window -v -t aether-colony:colony.2
+
+  # Set pane contents:
+  # Pane 0 (top-left): Status display
+  tmux send-keys -t aether-colony:colony.0 'watch -n 1 cat .aether/data/watch-status.txt' C-m
+
+  # Pane 1 (bottom-left): Progress bar
+  tmux send-keys -t aether-colony:colony.1 'watch -n 1 cat .aether/data/watch-progress.txt' C-m
+
+  # Pane 2 (top-right): Spawn tree visualization
+  tmux send-keys -t aether-colony:colony.2 'bash .aether/utils/watch-spawn-tree.sh .aether/data' C-m
+
+  # Pane 3 (bottom-right): Colorized activity log stream
+  tmux send-keys -t aether-colony:colony.3 'bash .aether/utils/colorize-log.sh .aether/data/activity.log' C-m
+
+  # Set pane titles (if supported)
+  tmux select-pane -t aether-colony:colony.0 -T "Status"
+  tmux select-pane -t aether-colony:colony.1 -T "Progress"
+  tmux select-pane -t aether-colony:colony.2 -T "Spawn Tree"
+  tmux select-pane -t aether-colony:colony.3 -T "Activity Log"
+
+  # Balance panes for even 2x2 grid
+  tmux select-layout -t aether-colony:colony tiled
+
+  echo "Session created"
+  ```
+
+  ### Step 6: Create Progress File
+
+  Write initial progress to `.aether/data/watch-progress.txt`:
+
+  ```
+         .-.
+        (o o)  AETHER COLONY
+        | O |  Progress
+         `-`
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Phase: -/-
+
+  [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0%
+
+  ⏳ Waiting for build...
+
+  Target: 95% confidence
+  ```
+
+  ### Step 7: Attach and Display
+
+  Run using the Bash tool with description "Attaching to watch display...":
+  ```bash
+  tmux attach-session -t aether-colony
+  ```
+
+  Before attaching, output:
+
+  ```
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  👁️🔄🐜🏠🔄👁️  A E T H E R   C O L O N Y   W A T C H
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  tmux session 'aether-colony' created.
+
+  Layout (4-pane 2x2 grid):
+    +------------------+------------------+
+    | Status           | Spawn Tree       |
+    | Colony state     | Worker hierarchy |
+    +------------------+------------------+
+    | Progress         | Activity Log     |
+    | Phase progress   | Live stream      |
+    +------------------+------------------+
+
+  Commands:
+    Ctrl+B D          Detach from session
+    Ctrl+B [          Scroll mode (q to exit)
+    Ctrl+B Arrow      Navigate between panes
+    tmux kill-session -t aether-colony   Stop watching
+
+  The session will update in real-time as colony works.
+  Attaching now...
+  ```
+
+  Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
+
+  ---
+
+  ## Status Update Protocol
+
+  Workers and commands update watch files as they work:
+
+  ### Activity Log
+  Workers write via: `bash .aether/aether-utils.sh activity-log "ACTION" "caste" "description"`
+
+  For named ants (recommended):
+  ```bash
+  # Generate a name first
+  ant_name=$(bash .aether/aether-utils.sh generate-ant-name "builder" | jq -r '.result')
+  # Log with ant name
+  bash .aether/aether-utils.sh activity-log "CREATED" "$ant_name (Builder)" "Implemented auth module"
+  ```
+
+  ### Spawn Tracking
+  Log spawns for tree visualization:
+  ```bash
+  bash .aether/aether-utils.sh spawn-log "Prime" "builder" "Hammer-42" "implementing auth"
+  bash .aether/aether-utils.sh spawn-complete "Hammer-42" "completed" "auth module done"
+  ```
+
+  ### Status File
+  Commands update `.aether/data/watch-status.txt` with current state:
+  - State: PLANNING, EXECUTING, READY
+  - Phase: current/total
+  - Active Workers: list of named ants
+  - Last Activity: most recent log entry
+
+  ### Progress File
+  Update via: `bash .aether/aether-utils.sh update-progress <percent> "<message>" <phase> <total>`
+
+  Example:
+  ```bash
+  bash .aether/aether-utils.sh update-progress 45 "Building auth module..." 2 5
+  ```
+
+  ---
+
+  ## Cleanup
+
+  To stop watching:
+  ```bash
+  tmux kill-session -t aether-colony
+  ```
+
+  This stops the session but preserves all log files.
+
+body_opencode: |
+  You are the **Queen**. Set up live visibility into colony activity.
+
+  ## Instructions
+
+  ### Step 1: Check Prerequisites
+
+  Use Bash to check if tmux is available:
+  ```bash
+  command -v tmux >/dev/null 2>&1 && echo "tmux_available" || echo "tmux_missing"
+  ```
+
+  If tmux is missing:
+  ```
+  tmux is required for live colony viewing.
+
+  Install with:
+    macOS:  brew install tmux
+    Ubuntu: sudo apt install tmux
+    Fedora: sudo dnf install tmux
+  ```
+  Stop here.
+
+  ### Step 2: Initialize Activity Log
+
+  Ensure activity log exists:
+  ```bash
+  mkdir -p .aether/data
+  touch .aether/data/activity.log
+  ```
+
+  ### Step 3: Create Status File
+
+  Write initial status to `.aether/data/watch-status.txt`:
+
+  ```
+         .-.
+        (o o)  AETHER COLONY
+        | O |  Live Status
+         `-`
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  State: IDLE
+  Phase: -/-
+
+  Active Workers:
+    (none)
+
+  Last Activity:
+    (waiting for colony activity)
+  ```
+
+  ### Step 4: Create or Attach to tmux Session
+
+  Check if session exists:
+  ```bash
+  tmux has-session -t aether-colony 2>/dev/null && echo "exists" || echo "new"
+  ```
+
+  **If session exists:** Attach to it
+  ```bash
+  tmux attach-session -t aether-colony
+  ```
+  Output: `Attached to existing aether-colony session.`
+  Stop here.
+
+  **If session is new:** Create the layout.
+
+  ### Step 5: Create tmux Layout (4-Pane)
+
+  Use Bash to create the session with 4 panes in a 2x2 grid:
+
+  ```bash
+  # Create session with first pane
+  tmux new-session -d -s aether-colony -n colony
+
+  # Split into 4 panes (2x2 grid)
+  # First split horizontally (left|right)
+  tmux split-window -h -t aether-colony:colony
+
+  # Split left side vertically (top-left, bottom-left)
+  tmux split-window -v -t aether-colony:colony.0
+
+  # Split right side vertically (top-right, bottom-right)
+  tmux split-window -v -t aether-colony:colony.2
+
+  # Set pane contents:
+  # Pane 0 (top-left): Status display
+  tmux send-keys -t aether-colony:colony.0 'watch -n 1 cat .aether/data/watch-status.txt' C-m
+
+  # Pane 1 (bottom-left): Progress bar
+  tmux send-keys -t aether-colony:colony.1 'watch -n 1 cat .aether/data/watch-progress.txt' C-m
+
+  # Pane 2 (top-right): Spawn tree visualization
+  tmux send-keys -t aether-colony:colony.2 'bash .aether/utils/watch-spawn-tree.sh .aether/data' C-m
+
+  # Pane 3 (bottom-right): Colorized activity log stream
+  tmux send-keys -t aether-colony:colony.3 'bash .aether/utils/colorize-log.sh .aether/data/activity.log' C-m
+
+  # Set pane titles (if supported)
+  tmux select-pane -t aether-colony:colony.0 -T "Status"
+  tmux select-pane -t aether-colony:colony.1 -T "Progress"
+  tmux select-pane -t aether-colony:colony.2 -T "Spawn Tree"
+  tmux select-pane -t aether-colony:colony.3 -T "Activity Log"
+
+  # Balance panes for even 2x2 grid
+  tmux select-layout -t aether-colony:colony tiled
+
+  echo "Session created"
+  ```
+
+  ### Step 6: Create Progress File
+
+  Write initial progress to `.aether/data/watch-progress.txt`:
+
+  ```
+         .-.
+        (o o)  AETHER COLONY
+        | O |  Progress
+         `-`
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Phase: -/-
+
+  [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0%
+
+  ⏳ Waiting for build...
+
+  Target: 95% confidence
+  ```
+
+  ### Step 7: Attach and Display
+
+  ```bash
+  tmux attach-session -t aether-colony
+  ```
+
+  Before attaching, output:
+
+  ```
+         .-.
+        (o o)  AETHER COLONY :: WATCH
+        | O |
+         `-`
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  tmux session 'aether-colony' created.
+
+  Layout (4-pane 2x2 grid):
+    +------------------+------------------+
+    | Status           | Spawn Tree       |
+    | Colony state     | Worker hierarchy |
+    +------------------+------------------+
+    | Progress         | Activity Log     |
+    | Phase progress   | Live stream      |
+    +------------------+------------------+
+
+  Commands:
+    Ctrl+B D          Detach from session
+    Ctrl+B [          Scroll mode (q to exit)
+    Ctrl+B Arrow      Navigate between panes
+    tmux kill-session -t aether-colony   Stop watching
+
+  The session will update in real-time as colony works.
+  Attaching now...
+  ```
+
+  ---
+
+  ## Status Update Protocol
+
+  Workers and commands update watch files as they work:
+
+  ### Activity Log
+  Workers write via: `bash .aether/aether-utils.sh activity-log "ACTION" "caste" "description"`
+
+  For named ants (recommended):
+  ```bash
+  # Generate a name first
+  ant_name=$(bash .aether/aether-utils.sh generate-ant-name "builder" | jq -r '.result')
+  # Log with ant name
+  bash .aether/aether-utils.sh activity-log "CREATED" "$ant_name (Builder)" "Implemented auth module"
+  ```
+
+  ### Spawn Tracking
+  Log spawns for tree visualization:
+  ```bash
+  bash .aether/aether-utils.sh spawn-log "Prime" "builder" "Hammer-42" "implementing auth"
+  bash .aether/aether-utils.sh spawn-complete "Hammer-42" "completed" "auth module done"
+  ```
+
+  ### Status File
+  Commands update `.aether/data/watch-status.txt` with current state:
+  - State: PLANNING, EXECUTING, READY
+  - Phase: current/total
+  - Active Workers: list of named ants
+  - Last Activity: most recent log entry
+
+  ### Progress File
+  Update via: `bash .aether/aether-utils.sh update-progress <percent> "<message>" <phase> <total>`
+
+  Example:
+  ```bash
+  bash .aether/aether-utils.sh update-progress 45 "Building auth module..." 2 5
+  ```
+
+  ---
+
+  ## Cleanup
+
+  To stop watching:
+  ```bash
+  tmux kill-session -t aether-colony
+  ```
+
+  This stops the session but preserves all log files.
+

package/.aether/docs/INCIDENT_TEMPLATE.md

@@ -0,0 +1,32 @@
+# Incident Report: {INCIDENT_ID}
+
+## Trigger
+- Command run: `/ant:{command}`
+- Expected outcome:
+- Actual outcome:
+
+## Root Cause Analysis
+- What failed:
+- Why it failed:
+- Which component: [ ] Orchestration [ ] State [ ] Memory [ ] Verification [ ] Spawn
+
+## Fix Applied
+- Commit: {hash}
+- Files changed:
+- Fix description:
+
+## Regression Test Added
+- Test file:
+- Test description:
+- How to run: `bash .aether/tests/{test_name}.sh`
+
+## Rule Added
+- Rule type: [ ] QUEEN.md decree [ ] workers.md constraint [ ] command-playbooks gate
+- Rule text:
+- Location:
+
+## Metrics
+- Time to detect:
+- Time to fix:
+- Spawn efficiency before:
+- Spawn efficiency after:

package/.aether/docs/QUEEN-SYSTEM.md

@@ -9,7 +9,7 @@ The Queen represents the accumulation of validated knowledge from all colonies.
 ## File Location
 
 ```
-.aether/docs/QUEEN.md
+.aether/QUEEN.md
 ```
 
 ## Structure
@@ -18,7 +18,7 @@ The Queen represents the accumulation of validated knowledge from all colonies.
 
 Core beliefs validated through repeated successful application across multiple colonies.
 
-**Threshold:** 5 successful validations required for promotion
+**Threshold:** 1 successful validation required for promotion
 
 Example:
 ```markdown
@@ -29,7 +29,7 @@ Example:
 
 Validated approaches that consistently work. These represent discovered best practices.
 
-**Threshold:** 3 successful validations required for promotion
+**Threshold:** 1 successful validation required for promotion
 
 Example:
 ```markdown
@@ -40,7 +40,7 @@ Example:
 
 Anti-patterns to avoid. Approaches that have caused problems.
 
-**Threshold:** 2 failed validations required for promotion
+**Threshold:** 1 failed validation required for promotion
 
 Example:
 ```markdown
@@ -85,7 +85,7 @@ bash .aether/aether-utils.sh queen-init
 
 **Returns:**
 ```json
-{"created": true, "path": ".aether/docs/QUEEN.md", "source": "~/.aether/system/templates/QUEEN.md.template"}
+{"created": true, "path": ".aether/QUEEN.md", "source": "~/.aether/system/templates/QUEEN.md.template"}
 ```
 
 ### queen-read
@@ -162,9 +162,9 @@ Before creating the chamber, promotes validated learnings to QUEEN.md.
 
 | Type | Threshold | Rationale |
 |------|-----------|-----------|
-| Philosophy | 5 | Core beliefs need strongest validation |
-| Pattern | 3 | Best practices need multiple confirmations |
-| Redirect | 2 | Anti-patterns need fewer failures to document |
+| Philosophy | 1 | Promote validated guidance quickly |
+| Pattern | 1 | Promote reusable practices quickly |
+| Redirect | 1 | Promote anti-pattern protection immediately |
 | Stack | 1 | Tech insights are domain-specific |
 | Decree | 0 | User mandates are immediate |
 
@@ -179,9 +179,9 @@ The QUEEN.md file includes a METADATA block at the end:
   "last_evolved": "2026-02-15T13:08:40Z",
   "colonies_contributed": ["colony-a"],
   "promotion_thresholds": {
-    "philosophy": 5,
-    "pattern": 3,
-    "redirect": 2,
+    "philosophy": 1,
+    "pattern": 1,
+    "redirect": 1,
     "stack": 1,
     "decree": 0
   },

package/.aether/docs/README.md

@@ -1,6 +1,15 @@
 # Aether Documentation
 
-This directory contains actively maintained documentation for the Aether colony system. 8 files total plus `disciplines/` subdirectory.
+This directory contains actively maintained documentation for the Aether colony system.
+
+Runtime/behavior authority remains in:
+- `.aether/aether-utils.sh` (execution)
+- `.claude/commands/ant/*.md` (command flow)
+
+Docs in this directory are explanatory references and should not override runtime behavior.
+
+Distribution note:
+- `aether update` does not sync repo-local session files like `.aether/CONTEXT.md` and `.aether/HANDOFF.md`.
 
 ---
 
@@ -11,6 +20,8 @@ Distributed to target repos via `aether update` (update allowlist):
 | File | Purpose |
 |------|---------|
 | `pheromones.md` | Pheromone system guide (FOCUS/REDIRECT/FEEDBACK signals) |
+| `source-of-truth-map.md` | Authority map and docs/runtime drift tracking |
+| `context-continuity.md` | Context retention architecture (capsules, compact priming, rolling summary) |
 
 ---
 
@@ -23,7 +34,8 @@ Packaged in npm, available to all Aether installations:
 | `caste-system.md` | Worker caste definitions and emoji assignments |
 | `QUEEN-SYSTEM.md` | Queen wisdom promotion system |
 | `queen-commands.md` | Queen command documentation |
-| `QUEEN.md` | Generated Queen wisdom file (repo-specific, auto-updated) |
+| `xml-utilities.md` | XML utility/runtime integration reference |
+| `.aether/QUEEN.md` | Generated Queen wisdom file (repo-specific, auto-updated) |
 | `error-codes.md` | Error code reference (E_* constants) |
 
 ---
@@ -54,6 +66,24 @@ Training protocols that govern worker behavior (in `disciplines/` subdirectory):
 
 ---
 
+## Command Playbooks
+
+Split playbooks used by orchestrator commands:
+
+| File | Purpose |
+|------|---------|
+| `command-playbooks/build-prep.md` | Build preparation and validation |
+| `command-playbooks/build-context.md` | Context and survey loading |
+| `command-playbooks/build-wave.md` | Worker wave orchestration |
+| `command-playbooks/build-verify.md` | Watcher/measurer/chaos verification |
+| `command-playbooks/build-complete.md` | Build synthesis and session updates |
+| `command-playbooks/continue-verify.md` | Continue verification setup |
+| `command-playbooks/continue-gates.md` | Continue quality/security gates |
+| `command-playbooks/continue-advance.md` | State advancement and pheromone/learning steps |
+| `command-playbooks/continue-finalize.md` | Handoff/changelog/session finalization |
+
+---
+
 ## Archived Docs
 
 Historical documentation moved to `archive/` subdirectory:

package/.aether/docs/command-playbooks/README.md

@@ -0,0 +1,23 @@
+# Command Playbooks
+
+This directory contains split execution playbooks for high-complexity commands.
+
+## Build
+
+- `build-prep.md` - Version/state checks, argument validation, checkpoint setup
+- `build-context.md` - Colony context loading, survey, archaeology, suggestions
+- `build-wave.md` - Swarm initialization, wave execution, result processing
+- `build-verify.md` - Watcher/measurer/chaos verification and flag creation
+- `build-complete.md` - Synthesis, handoff/context update, display, session update
+
+## Continue
+
+- `continue-verify.md` - State loading and verification-loop setup
+- `continue-gates.md` - Enforcement, anti-pattern, security, quality, runtime, flags gates
+- `continue-advance.md` - State advancement, pheromone updates, learning proposal checks
+- `continue-finalize.md` - Handoff/changelog/commit, completion display, session update
+
+## Canonical Sources
+
+- `build-full.md` - Full original build command prior to split
+- `continue-full.md` - Full original continue command prior to split