aether-colony 5.3.2 → 5.4.0

package/.aether/commands/watch.yaml

@@ -40,7 +40,7 @@ body_claude: |
 
   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")
+  stale_check=$(aether session-verify-fresh --command watch "" "$WATCH_START")
   has_stale=$(echo "$stale_check" | jq -r '.stale | length' 2>/dev/null || echo "0")
   ```
 
@@ -192,21 +192,21 @@ body_claude: |
   Workers and commands update watch files as they work:
 
   ### Activity Log
-  Workers write via: `bash .aether/aether-utils.sh activity-log "ACTION" "caste" "description"`
+  Workers write via: `aether 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')
+  ant_name=$(aether generate-ant-name --caste "builder" | jq -r '.result')
   # Log with ant name
-  bash .aether/aether-utils.sh activity-log "CREATED" "$ant_name (Builder)" "Implemented auth module"
+  aether 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"
+  aether spawn-log --name "Prime" --caste "builder" --id "Hammer-42" --description "implementing auth"
+  aether spawn-complete --id "Hammer-42" --status "completed" --summary "auth module done"
   ```
 
   ### Status File
@@ -217,11 +217,11 @@ body_claude: |
   - Last Activity: most recent log entry
 
   ### Progress File
-  Update via: `bash .aether/aether-utils.sh update-progress <percent> "<message>" <phase> <total>`
+  Update via: `aether update-progress <percent> "<message>" <phase> <total>`
 
   Example:
   ```bash
-  bash .aether/aether-utils.sh update-progress 45 "Building auth module..." 2 5
+  aether update-progress 45 "Building auth module..." 2 5
   ```
 
   ---
@@ -409,21 +409,21 @@ body_opencode: |
   Workers and commands update watch files as they work:
 
   ### Activity Log
-  Workers write via: `bash .aether/aether-utils.sh activity-log "ACTION" "caste" "description"`
+  Workers write via: `aether 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')
+  ant_name=$(aether generate-ant-name --caste "builder" | jq -r '.result')
   # Log with ant name
-  bash .aether/aether-utils.sh activity-log "CREATED" "$ant_name (Builder)" "Implemented auth module"
+  aether 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"
+  aether spawn-log --name "Prime" --caste "builder" --id "Hammer-42" --description "implementing auth"
+  aether spawn-complete --id "Hammer-42" --status "completed" --summary "auth module done"
   ```
 
   ### Status File
@@ -434,11 +434,11 @@ body_opencode: |
   - Last Activity: most recent log entry
 
   ### Progress File
-  Update via: `bash .aether/aether-utils.sh update-progress <percent> "<message>" <phase> <total>`
+  Update via: `aether update-progress <percent> "<message>" <phase> <total>`
 
   Example:
   ```bash
-  bash .aether/aether-utils.sh update-progress 45 "Building auth module..." 2 5
+  aether update-progress 45 "Building auth module..." 2 5
   ```
 
   ---

package/.aether/docs/command-playbooks/build-complete.md

@@ -1,3 +1,36 @@
+### Stage Audit Gate (Pre-Synthesis Check)
+
+**This gate runs before Step 5.9. All 4 prior playbook stages must have completed with "ok" status.**
+
+Check the cross-stage state record for each of the following stages:
+
+| Stage | Playbook | Required Status |
+|-------|----------|----------------|
+| 1 | build-prep | ok |
+| 2 | build-context | ok |
+| 3 | build-wave | ok |
+| 4 | build-verify | ok |
+
+To verify, read the cross-stage state (typically `.aether/data/build-stage-state.json` or the in-memory record accumulated during the build run) and confirm each stage entry has `"status": "ok"`.
+
+**If any stage is missing or did not complete with "ok" status:**
+- HALT — do not proceed to Step 5.9
+- Display:
+  ```
+  Stage Audit FAILED — cannot synthesize results.
+
+  Missing or failed stages:
+    {list each stage name with its recorded status, or "not recorded" if absent}
+
+  Recovery options:
+    1. Re-run the missing stage(s) manually, then retry /ant:build
+    2. Run /ant:flags to review blockers
+    3. Run /ant:swarm to auto-repair failed tasks
+  ```
+- Return `{"status": "failed", "summary": "Stage audit failed — stages {names} did not complete successfully"}` and stop.
+
+**If all 4 stages passed:** proceed to Step 5.9.
+
 ### Step 5.9: Synthesize Results
 
 **This step runs after all worker tasks have completed (Builders, Watcher, Chaos).**
@@ -41,7 +74,7 @@ Collect all worker outputs and create phase summary:
 **Graveyard Recording:**
 For each worker that returned `status: "failed"`:
   For each file in that worker's `files_modified` or `files_created`:
-Run using the Bash tool with description "Recording failure grave...": `bash .aether/aether-utils.sh grave-add "{file}" "{ant_name}" "{task_id}" {phase} "{first blocker or summary}" && bash .aether/aether-utils.sh activity-log "GRAVE" "Queen" "Grave marker placed at {file} — {ant_name} failed: {summary}"`
+Run using the Bash tool with description "Recording failure grave...": `aether grave-add "{file}" "{ant_name}" "{task_id}" {phase} "{first blocker or summary}" && aether activity-log "GRAVE" "Queen" "Grave marker placed at {file} — {ant_name} failed: {summary}"`
   Then display a user-visible confirmation line:
   `⚰️ Grave recorded: {file} — {ant_name} failed ({summary})`
 
@@ -55,7 +88,7 @@ For each pattern in `learning.patterns_observed`:
 - If `success_capture_count >= 2`, stop (cap reached)
 - Run using the Bash tool with description "Capturing synthesis pattern success...":
 ```bash
-bash .aether/aether-utils.sh memory-capture \
+aether memory-capture \
   "success" \
   "${pattern.trigger}: ${pattern.action} (evidence: ${pattern.evidence})" \
   "pattern" \
@@ -253,30 +286,30 @@ Write the result to .aether/HANDOFF.md using the Write tool.
 
 This ensures the handoff always reflects the latest build state, even if the session crashes before explicit pause.
 
-### Step 6.5: Update Context Document
+### Step 6.6: Update Context Document
 
 Log this build activity to `.aether/CONTEXT.md`:
 
-Run using the Bash tool with description "Updating build context...": `bash .aether/aether-utils.sh context-update activity "build {phase_id}" "{synthesis.status}" "{files_created_count + files_modified_count}" && bash .aether/aether-utils.sh context-update build-complete "{synthesis.status}" "{synthesis.status == 'completed' ? 'success' : 'failed'}"`
+Run using the Bash tool with description "Updating build context...": `aether context-update activity "build {phase_id}" "{synthesis.status}" "{files_created_count + files_modified_count}" && aether context-update build-complete "{synthesis.status}" "{synthesis.status == 'completed' ? 'success' : 'failed'}"`
 
 Also update safe-to-clear status:
 - If build completed successfully: `context-update safe-to-clear "YES" "Build complete, ready to continue"`
 - If build failed: `context-update safe-to-clear "NO" "Build failed — run /ant:swarm or /ant:flags"`
 
-### Step 5.10: Check for Promotion Proposals
+### Step 6.7: Check for Promotion Proposals
 
 After build completion (success or failure), check if any observations have met promotion thresholds.
 
 Run using the Bash tool with description "Checking for wisdom promotions...":
 ```bash
-proposals=$(bash .aether/aether-utils.sh learning-check-promotion 2>/dev/null || echo '{"proposals":[]}')
+proposals=$(aether learning-check-promotion 2>/dev/null || echo '{"proposals":[]}')
 proposal_count=$(echo "$proposals" | jq '.proposals | length')
 echo "{\"proposal_count\": $proposal_count}"
 ```
 
 Parse the result. If proposal_count > 0:
 - Display: "📚 $proposal_count wisdom proposal(s) ready for review"
-- Run: `bash .aether/aether-utils.sh learning-approve-proposals`
+- Run: `aether learning-approve-proposals`
 - This presents the one-at-a-time UI for user review
 
 If proposal_count == 0:
@@ -295,14 +328,14 @@ Calculate `elapsed` using `build_started_at_epoch` (epoch integer captured at St
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   B U I L D   S U M M A R Y
+🔨 B U I L D   S U M M A R Y
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Phase {id}: {name}
-Pattern:  {selected_pattern}
+📍 Phase {id}: {name}
+🎲 Pattern:  {selected_pattern}
 
-Workers:  {pass_count} passed  {fail_count} failed  ({total} total)
-Tools:    {total_tools} calls across all workers
-Duration: {elapsed}
+🐜 Workers:  {pass_count} passed  {fail_count} failed  ({total} total)
+🛠️ Tools:    {total_tools} calls across all workers
+⏱️ Duration: {elapsed}
 
 {if measurer_ran:}
 📊 Measurer: {baseline_count} baselines established, {bottleneck_count} bottlenecks identified
@@ -332,7 +365,7 @@ After displaying the BUILD SUMMARY (and optional verbose details), call the Next
 state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json 2>/dev/null || echo "IDLE")
 current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json 2>/dev/null || echo "0")
 total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json 2>/dev/null || echo "0")
-bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
+aether print-next-up "$state" "$current_phase" "$total_phases"
 ```
 
 **Routing Note:** The state-based Next Up block above routes based on colony state. If verification failed or blockers exist, review `/ant:flags` before continuing.
@@ -346,4 +379,4 @@ bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_pha
 
 Update the session tracking file to enable `/ant:resume` after context clear:
 
-Run using the Bash tool with description "Saving build session...": `bash .aether/aether-utils.sh session-update "/ant:build {phase_id}" "/ant:continue" "Phase {phase_id} build completed: {synthesis.status}"`
+Run using the Bash tool with description "Saving build session...": `aether session-update "/ant:build {phase_id}" "/ant:continue" "Phase {phase_id} build completed: {synthesis.status}"`

package/.aether/docs/command-playbooks/build-context.md

@@ -4,7 +4,7 @@ Call `colony-prime --compact` to get unified worker context (wisdom + context ca
 
 Run using the Bash tool with description "Loading colony context...":
 ```bash
-prime_result=$(bash .aether/aether-utils.sh colony-prime --compact 2>/dev/null)
+prime_result=$(aether colony-prime --compact 2>/dev/null)
 ```
 
 **Parse the JSON response:**
@@ -22,7 +22,7 @@ Display after constraints:
 
 Then display the active pheromones table by running:
 ```bash
-bash .aether/aether-utils.sh pheromone-display
+aether pheromone-display
 ```
 
 This shows the user exactly what signals are guiding the colony:
@@ -38,7 +38,7 @@ Check if territory survey exists and load relevant documents:
 
 Run using the Bash tool with description "Loading territory survey...":
 ```bash
-bash .aether/aether-utils.sh survey-load "{phase_name}" 2>/dev/null
+aether survey-load "{phase_name}" 2>/dev/null
 ```
 
 **Parse the JSON response:**
@@ -152,14 +152,14 @@ Analyze codebase and suggest pheromone signals based on detected patterns.
 
 Run using the Bash tool with description "Analyzing codebase for suggestions...":
 ```bash
-bash .aether/aether-utils.sh suggest-approve --dry-run 2>/dev/null
+aether suggest-approve --dry-run 2>/dev/null
 ```
 
 Parse the JSON result to get `suggestion_count`.
 
 If `suggestion_count` > 0:
 - Display: "💡 {count} pheromone suggestion(s) detected from code analysis"
-- Run: `bash .aether/aether-utils.sh suggest-approve`
+- Run: `aether suggest-approve`
 - Parse result for approved/rejected/skipped counts
 - If approved > 0: Display "✓ {approved} FOCUS signal(s) added"
 
@@ -184,7 +184,7 @@ Build the skills index and detect which domain skills match the current codebase
 
 Run using the Bash tool with description "Building skills index...":
 ```bash
-skill_index_result=$(bash .aether/aether-utils.sh skill-index 2>/dev/null)
+skill_index_result=$(aether skill-index 2>/dev/null)
 ```
 
 **Parse the JSON response:**
@@ -195,7 +195,7 @@ skill_index_result=$(bash .aether/aether-utils.sh skill-index 2>/dev/null)
 
 Run using the Bash tool with description "Detecting codebase skills...":
 ```bash
-skill_detect_result=$(bash .aether/aether-utils.sh skill-detect "$(pwd)" 2>/dev/null)
+skill_detect_result=$(aether skill-detect "$(pwd)" 2>/dev/null)
 ```
 
 **Parse the JSON response:**
@@ -222,8 +222,8 @@ Display to user:
 2. **If existing code modification detected — spawn Archaeologist Scout:**
 
    Generate archaeologist name and dispatch:
-   Run using the Bash tool with description "Naming archaeologist...": `bash .aether/aether-utils.sh generate-ant-name "archaeologist"` (store as `{archaeologist_name}`)
-   Run using the Bash tool with description "Dispatching archaeologist...": `bash .aether/aether-utils.sh spawn-log "Queen" "scout" "{archaeologist_name}" "Pre-build archaeology scan"`
+   Run using the Bash tool with description "Naming archaeologist...": `aether generate-ant-name "archaeologist"` (store as `{archaeologist_name}`)
+   Run using the Bash tool with description "Dispatching archaeologist...": `aether spawn-log "Queen" "scout" "{archaeologist_name}" "Pre-build archaeology scan"`
 
    Display:
    ```
@@ -250,7 +250,7 @@ Display to user:
    4. Run: git blame "{file_path}" | head -40 for authorship
    5. Note TODO/FIXME/HACK markers
 
-   Log activity: bash .aether/aether-utils.sh activity-log "READ" "{Ant-Name}" "description"
+   Log activity: aether activity-log "READ" "{Ant-Name}" "description"
 
    Report (plain text):
    - WHY key code sections exist (from commits)
@@ -263,7 +263,7 @@ Display to user:
    **Wait for results** (blocking — use TaskOutput with `block: true`).
 
    Log completion:
-   Run using the Bash tool with description "Recording archaeologist findings...": `bash .aether/aether-utils.sh spawn-complete "{archaeologist_name}" "completed" "Pre-build archaeology scan"`
+   Run using the Bash tool with description "Recording archaeologist findings...": `aether spawn-complete "{archaeologist_name}" "completed" "Pre-build archaeology scan"`
 
 3. **Store and display findings:**