aether-colony 5.1.0 → 5.3.0

package/.aether/commands/claude/watch.md

@@ -0,0 +1,239 @@
+<!-- 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"
+---
+
+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.

package/.aether/commands/colonize.yaml

@@ -66,6 +66,8 @@ body_claude: |
 
   **If the file exists:** continue.
 
+  **If `milestone` == `"Crowned Anthill"`:** output "This colony has been sealed. Start a new colony with `/ant:init \"new goal\"`.", stop.
+
   **If `plan.phases` is not empty:** output "Colony already has phases. Use /ant:continue.", stop.
 
   ### Step 2: Quick Surface Scan (for session context)
@@ -287,6 +289,8 @@ body_opencode: |
 
   **If the file exists:** continue.
 
+  **If `milestone` == `"Crowned Anthill"`:** output "This colony has been sealed. Start a new colony with `/ant:init \"new goal\"`.", stop.
+
   **If `plan.phases` is not empty:** output "Colony already has phases. Use /ant:continue.", stop.
 
   ### Step 2: Quick Surface Scan (for session context)

package/.aether/commands/council.yaml

@@ -6,9 +6,208 @@ body: |
   ## Instructions
 
   Parse `{{ARGUMENTS}}`:
+  - If starts with `--deliberate`: set `deliberate_mode = true`, extract proposal text after `--deliberate`
   - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
   - Otherwise: set `visual_mode = true`
 
+  **If `deliberate_mode` is true:** Skip to [Deliberation Mode](#deliberation-mode) and stop after it.
+
+  ---
+
+  ## Deliberation Mode
+
+  When `--deliberate "<proposal>"` is passed, run a structured Advocate/Challenger/Sage deliberation.
+
+  ### Step D1: Check Budget
+
+  Run using the Bash tool with description "Checking deliberation budget...":
+  ```bash
+  bash .aether/aether-utils.sh council-budget-check
+  ```
+
+  Parse result. If `allowed` is `false`:
+  ```
+  📜🐜🏛️🐜📜 COUNCIL — BUDGET EXHAUSTED
+
+  Spawn budget is fully allocated. Complete or close existing deliberations before starting new ones.
+  Run /ant:council to review existing deliberations.
+  ```
+  Stop here.
+
+  ### Step D2: Open Deliberation
+
+  Run using the Bash tool with description "Opening deliberation...":
+  ```bash
+  bash .aether/aether-utils.sh council-deliberate --proposal "<proposal>"
+  ```
+
+  Capture `deliberation_id` from `result.id`.
+
+  Display:
+  ```
+  📜🐜🏛️🐜📜 COUNCIL DELIBERATION OPENED
+
+  Proposal: "<proposal>"
+  ID: {deliberation_id}
+  Budget: {budget} spawns available
+
+  Convening Advocate, Challenger, and Sage...
+  ```
+
+  ### Step D3: Spawn Advocate Scout
+
+  Spawn an Advocate scout to argue **in favor** of the proposal.
+
+  {{#claude}}
+  Use the Task tool to spawn a scout with the following system prompt:
+  ```
+  You are the Advocate on the Ant Colony council.
+  Your role is to argue STRONGLY IN FAVOR of the proposal.
+  Present the strongest possible case for why this proposal should be adopted.
+  Be specific. Focus on concrete benefits and outcomes.
+  Keep your argument under 200 words.
+  Reply with ONLY your argument text — no preamble or meta-commentary.
+  ```
+
+  And user message:
+  ```
+  Proposal: "<proposal>"
+
+  Present your strongest argument in favor of this proposal.
+  ```
+
+  Capture the advocate's argument as `advocate_argument`.
+  {{/claude}}
+
+  Record the argument:
+  ```bash
+  bash .aether/aether-utils.sh council-advocate \
+    --deliberation-id "<deliberation_id>" \
+    --argument "<advocate_argument>"
+  ```
+
+  Display:
+  ```
+  ⚖️  ADVOCATE:
+  {advocate_argument}
+  ```
+
+  ### Step D4: Spawn Challenger Scout
+
+  Spawn a Challenger scout to argue **against** the proposal.
+
+  {{#claude}}
+  Use the Task tool to spawn a scout with the following system prompt:
+  ```
+  You are the Challenger on the Ant Colony council.
+  Your role is to argue STRONGLY AGAINST the proposal.
+  Present the strongest possible case for why this proposal should be rejected or deferred.
+  Be specific. Focus on concrete risks, costs, and downsides.
+  Keep your argument under 200 words.
+  Reply with ONLY your argument text — no preamble or meta-commentary.
+  ```
+
+  And user message:
+  ```
+  Proposal: "<proposal>"
+
+  Present your strongest argument against this proposal.
+  ```
+
+  Capture the challenger's argument as `challenger_argument`.
+  {{/claude}}
+
+  Record the argument:
+  ```bash
+  bash .aether/aether-utils.sh council-challenger \
+    --deliberation-id "<deliberation_id>" \
+    --argument "<challenger_argument>"
+  ```
+
+  Display:
+  ```
+  ⚔️  CHALLENGER:
+  {challenger_argument}
+  ```
+
+  ### Step D5: Spawn Sage Scout
+
+  Spawn a Sage scout to synthesize both positions and provide a recommendation.
+
+  {{#claude}}
+  Use the Task tool to spawn a scout with the following system prompt:
+  ```
+  You are the Sage on the Ant Colony council.
+  You have heard both the Advocate and Challenger arguments.
+  Your role is to synthesize both positions into balanced wisdom and provide a clear recommendation.
+  Your recommendation must be one of: adopt, reject, defer, or adopt-with-conditions.
+  Keep your synthesis under 150 words.
+  Reply with JSON only:
+  {"synthesis": "<your balanced synthesis>", "recommendation": "adopt|reject|defer|adopt-with-conditions"}
+  ```
+
+  And user message:
+  ```
+  Proposal: "<proposal>"
+
+  Advocate argued: "<advocate_argument>"
+
+  Challenger argued: "<challenger_argument>"
+
+  Synthesize both positions and provide your recommendation.
+  ```
+
+  Parse the JSON response. Capture `synthesis` and `recommendation`.
+  {{/claude}}
+
+  Record the sage synthesis:
+  ```bash
+  bash .aether/aether-utils.sh council-sage \
+    --deliberation-id "<deliberation_id>" \
+    --synthesis "<synthesis>" \
+    --recommendation "<recommendation>"
+  ```
+
+  ### Step D6: Display Result
+
+  ```
+  📜🐜🏛️🐜📜 COUNCIL DELIBERATION COMPLETE
+
+  Proposal: "<proposal>"
+
+  ⚖️  Advocate:
+  {advocate_argument}
+
+  ⚔️  Challenger:
+  {challenger_argument}
+
+  🧙 Sage Synthesis:
+  {synthesis}
+
+  Recommendation: {recommendation}
+  ```
+
+  If recommendation is `adopt` or `adopt-with-conditions`:
+  ```
+  ✅ Council recommends proceeding.
+     Run /ant:focus "<proposal summary>" to inject guidance for the colony.
+  ```
+
+  If recommendation is `reject`:
+  ```
+  ❌ Council recommends against this proposal.
+     Run /ant:redirect "<proposal summary>" if you want to make this a hard constraint.
+  ```
+
+  If recommendation is `defer`:
+  ```
+  ⏸️  Council recommends deferring this decision.
+     Return when more context is available.
+  ```
+
+  ---
+
+
   {{#claude}}
   ### Step 0: Initialize Visual Mode (if enabled)
 
@@ -26,6 +225,12 @@ body: |
   ```
   Stop here.
 
+  If `milestone` == `"Crowned Anthill"`:
+  ```
+  This colony has been sealed. Start a new colony with /ant:init "new goal".
+  ```
+  Stop here.
+
   Capture the current state for context:
   - `prior_state` = state field value (READY, EXECUTING, PLANNING, etc.)
   - `current_phase` = current_phase field value

package/.aether/commands/init.yaml

@@ -135,8 +135,14 @@ body: |
 
   Use Read tool to check `.aether/data/COLONY_STATE.json`.
 
-  - If file exists AND has a non-null `goal` field: set `reinit_mode = true`, store `existing_goal`
-  - Otherwise: set `reinit_mode = false`
+  - If file exists AND has a non-null `goal` field:
+    - Check the `milestone` field. If `milestone == "Crowned Anthill"`:
+      - This is a **sealed colony**. Treat as **fresh init**, NOT re-init.
+      - Set `reinit_mode = false`
+      - Display: `Previous colony was sealed. Starting fresh colony.`
+      - The old COLONY_STATE.json will be overwritten in Step 7 (fresh init path).
+    - Otherwise (colony exists but is NOT sealed): set `reinit_mode = true`, store `existing_goal`
+  - If file does not exist or `goal` is null: set `reinit_mode = false`
 
   If re-init mode, read existing charter entries from `.aether/QUEEN.md`:
   ```bash
@@ -276,14 +282,29 @@ body: |
 
   2. Auto-apply approved pheromone suggestions (see pheromone auto-apply below).
 
-  3. Optionally update the goal field in COLONY_STATE.json in-place:
+  3. Update the goal field in COLONY_STATE.json in-place using the state API:
   ```bash
-  jq --arg new_goal "{approved_intent}" '.goal = $new_goal' .aether/data/COLONY_STATE.json > .aether/data/COLONY_STATE.json.tmp && mv .aether/data/COLONY_STATE.json.tmp .aether/data/COLONY_STATE.json
+  bash .aether/aether-utils.sh state-write "$(jq --arg new_goal "{approved_intent}" '.goal = $new_goal' .aether/data/COLONY_STATE.json)"
   ```
 
-  4. Run `bash .aether/aether-utils.sh session-init "$(jq -r '.session_id' .aether/data/COLONY_STATE.json)" "{approved_intent}"`
+  4. **Verify the write** — read back and confirm goal is set:
+  ```bash
+  verify_goal=$(jq -r '.goal' .aether/data/COLONY_STATE.json)
+  if [[ "$verify_goal" == "null" || -z "$verify_goal" ]]; then
+    echo "ERROR: Colony state write failed — goal is still null after write. Re-run /ant:init."
+    # Attempt recovery: write goal directly
+    jq --arg g "{approved_intent}" '.goal = $g' .aether/data/COLONY_STATE.json > .aether/data/COLONY_STATE.json.tmp && mv .aether/data/COLONY_STATE.json.tmp .aether/data/COLONY_STATE.json
+    verify_goal=$(jq -r '.goal' .aether/data/COLONY_STATE.json)
+    if [[ "$verify_goal" == "null" || -z "$verify_goal" ]]; then
+      echo "FATAL: Recovery write also failed. Colony state may be corrupted."
+      stop
+    fi
+  fi
+  ```
+
+  5. Run `bash .aether/aether-utils.sh session-init "$(jq -r '.session_id' .aether/data/COLONY_STATE.json)" "{approved_intent}"`
 
-  5. Skip to Step 8 (display result). Do NOT write COLONY_STATE.json from template, do NOT write constraints.json, do NOT write pheromones.json.
+  6. Skip to Step 8 (display result). Do NOT write COLONY_STATE.json from template, do NOT write constraints.json, do NOT write pheromones.json.
 
   **If fresh init:**
 
@@ -299,12 +320,24 @@ body: |
      - Remove ALL keys starting with underscore
      - Write the resulting JSON to `.aether/data/COLONY_STATE.json` using the Write tool
 
-  5. Write constraints.json from template:
+  5. **Verify the write** — read back and confirm COLONY_STATE.json is valid and goal is set:
+  ```bash
+  verify_goal=$(jq -r '.goal' .aether/data/COLONY_STATE.json 2>/dev/null)
+  verify_valid=$(jq -e . .aether/data/COLONY_STATE.json >/dev/null 2>&1 && echo "valid" || echo "invalid")
+  if [[ "$verify_valid" != "valid" || "$verify_goal" == "null" || -z "$verify_goal" ]]; then
+    echo "ERROR: Colony state write verification failed (valid=$verify_valid, goal=$verify_goal)"
+    echo "The colony file may be corrupted. Remove .aether/data/COLONY_STATE.json and re-run /ant:init."
+    stop
+  fi
+  echo "Colony state verified: goal=\"$verify_goal\""
+  ```
+
+  6. Write constraints.json from template:
      - Resolve template: check `~/.aether/system/templates/constraints.template.json` first, then `.aether/templates/constraints.template.json`
      - If no template found: output "Template missing: constraints.template.json. Run aether update to fix." and stop
      - Read template, follow `_instructions`, remove `_` prefixed keys, write to `.aether/data/constraints.json`
 
-  6. Initialize runtime files from templates (non-blocking):
+  7. Initialize runtime files from templates (non-blocking):
   ```bash
   for template in pheromones midden learning-observations; do
     if [[ "$template" == "midden" ]]; then
@@ -327,15 +360,15 @@ body: |
   done
   ```
 
-  7. Run `bash .aether/aether-utils.sh context-update init "{approved_intent}"`
-  8. Run `bash .aether/aether-utils.sh validate-state colony`
-  9. Register repo (silent on failure):
+  8. Run `bash .aether/aether-utils.sh context-update init "{approved_intent}"`
+  9. Run `bash .aether/aether-utils.sh validate-state colony`
+  10. Register repo (silent on failure):
   ```bash
   domain_tags=$(bash .aether/aether-utils.sh domain-detect 2>/dev/null | jq -r '.result.tags // ""' || echo "")
   bash .aether/aether-utils.sh registry-add "$(pwd)" "$(jq -r '.version // "unknown"' ~/.aether/version.json 2>/dev/null || echo 'unknown')" --goal "{approved_intent}" --active true --tags "$domain_tags" 2>/dev/null || true
   cp ~/.aether/version.json .aether/version.json 2>/dev/null || true
   ```
-  10. Seed QUEEN.md from hive (non-blocking):
+  11. Seed QUEEN.md from hive (non-blocking):
   ```bash
   domain_tags=$(jq -r --arg repo "$(pwd)" \
     '[.repos[] | select(.path == $repo) | .domain_tags // []] | .[0] // [] | join(",")' \
@@ -345,7 +378,7 @@ body: |
   seed_result=$(bash .aether/aether-utils.sh $seed_args 2>/dev/null || echo '{}')
   seeded_count=$(echo "$seed_result" | jq -r '.result.seeded // 0' 2>/dev/null || echo "0")
   ```
-  11. Run `bash .aether/aether-utils.sh session-init "{session_id}" "{approved_intent}"`
+  12. Run `bash .aether/aether-utils.sh session-init "{session_id}" "{approved_intent}"`
 
   **Pheromone auto-apply (referenced by both re-init and fresh init paths above):**
 

package/.aether/commands/insert-phase.yaml

@@ -13,6 +13,10 @@ body: |
   `No colony initialized. Run /ant:init first.`
   Stop.
 
+  If `milestone` == `"Crowned Anthill"`:
+  `This colony has been sealed. Start a new colony with /ant:init "new goal".`
+  Stop.
+
   If `plan.phases` is empty:
   `No project plan. Run /ant:plan first.`
   Stop.