aether-colony 5.3.2 → 5.4.0

package/.aether/aether-utils.sh

@@ -48,6 +48,21 @@ CURRENT_LOCK=${CURRENT_LOCK:-""}
 [[ -f "$SCRIPT_DIR/utils/council.sh" ]] && source "$SCRIPT_DIR/utils/council.sh"
 [[ -f "$SCRIPT_DIR/utils/clash-detect.sh" ]] && source "$SCRIPT_DIR/utils/clash-detect.sh"
 [[ -f "$SCRIPT_DIR/utils/worktree.sh" ]] && source "$SCRIPT_DIR/utils/worktree.sh"
+[[ -f "$SCRIPT_DIR/utils/event-bus.sh" ]] && source "$SCRIPT_DIR/utils/event-bus.sh"
+[[ -f "$SCRIPT_DIR/utils/trust-scoring.sh" ]] && source "$SCRIPT_DIR/utils/trust-scoring.sh"
+[[ -f "$SCRIPT_DIR/utils/instinct-store.sh" ]] && source "$SCRIPT_DIR/utils/instinct-store.sh"
+[[ -f "$SCRIPT_DIR/utils/graph.sh" ]] && source "$SCRIPT_DIR/utils/graph.sh"
+[[ -f "$SCRIPT_DIR/utils/curation-ants/sentinel.sh" ]] && source "$SCRIPT_DIR/utils/curation-ants/sentinel.sh"
+[[ -f "$SCRIPT_DIR/utils/curation-ants/janitor.sh" ]] && source "$SCRIPT_DIR/utils/curation-ants/janitor.sh"
+[[ -f "$SCRIPT_DIR/utils/curation-ants/archivist.sh" ]] && source "$SCRIPT_DIR/utils/curation-ants/archivist.sh"
+[[ -f "$SCRIPT_DIR/utils/curation-ants/scribe.sh" ]] && source "$SCRIPT_DIR/utils/curation-ants/scribe.sh"
+[[ -f "$SCRIPT_DIR/utils/curation-ants/nurse.sh" ]] && source "$SCRIPT_DIR/utils/curation-ants/nurse.sh"
+[[ -f "$SCRIPT_DIR/utils/curation-ants/herald.sh" ]] && source "$SCRIPT_DIR/utils/curation-ants/herald.sh"
+[[ -f "$SCRIPT_DIR/utils/curation-ants/librarian.sh" ]] && source "$SCRIPT_DIR/utils/curation-ants/librarian.sh"
+[[ -f "$SCRIPT_DIR/utils/curation-ants/critic.sh" ]] && source "$SCRIPT_DIR/utils/curation-ants/critic.sh"
+[[ -f "$SCRIPT_DIR/utils/curation-ants/orchestrator.sh" ]] && source "$SCRIPT_DIR/utils/curation-ants/orchestrator.sh"
+[[ -f "$SCRIPT_DIR/utils/consolidation-seal.sh" ]] && source "$SCRIPT_DIR/utils/consolidation-seal.sh"
+[[ -f "$SCRIPT_DIR/utils/consolidation.sh" ]] && source "$SCRIPT_DIR/utils/consolidation.sh"
 
 # Fallback error constants if error-handler.sh wasn't sourced
 # This prevents "unbound variable" errors in older installations
@@ -1260,13 +1275,16 @@ case "$cmd" in
       {"name": "pheromone-export", "description": "Export pheromone data to JSON"},
       {"name": "pheromone-export-xml", "description": "Export pheromone data to XML"},
       {"name": "pheromone-import-xml", "description": "Import pheromone data from XML"},
-      {"name": "pheromone-validate-xml", "description": "Validate pheromone XML against schema"}
+      {"name": "pheromone-validate-xml", "description": "Validate pheromone XML against schema"},
+      {"name": "pheromone-snapshot-inject", "description": "Copy active pheromone signals into a new worktree branch"},
+      {"name": "pheromone-export-branch", "description": "Export branch-specific pheromone signals for merge"},
+      {"name": "pheromone-merge-back", "description": "Merge eligible branch pheromone signals back to main"}
     ],
     "Utilities": [
       {"name": "generate-ant-name", "description": "Generate a unique ant name with caste prefix"},
       {"name": "activity-log", "description": "Append an entry to the activity log"},
       {"name": "activity-log-init", "description": "Initialize the activity log file"},
-      {"name": "activity-log-read", "description": "Read recent activity log entries"},
+      {"name": "activity-log-read", "description": "Read recent activity log entries; --no-errors excludes ERROR/WARN lines"},
       {"name": "generate-commit-message", "description": "Generate a commit message (types: milestone, pause, fix, contextual, seal)"},
       {"name": "version-check", "description": "Check if Aether version meets requirement"},
       {"name": "registry-add", "description": "Register a repo with Aether (supports --tags, --goal, --active)"},
@@ -1295,7 +1313,9 @@ case "$cmd" in
       {"name": "suggest-quick-dismiss", "description": "Dismiss all suggestions without approving"}
     ],
     "Maintenance": [
-      {"name": "data-clean", "description": "Scan and remove test/synthetic artifacts from colony data files"}
+      {"name": "data-clean", "description": "Scan and remove test/synthetic artifacts from colony data files"},
+      {"name": "backup-prune-global", "description": "Prune .aether/data/backups/ to 50-file global cap (newest kept)"},
+      {"name": "temp-clean", "description": "Remove files from .aether/temp/ older than 7 days"}
     ],
     "Autopilot": [
       {"name": "autopilot-init", "description": "Initialize autopilot run state (run-state.json)"},
@@ -1793,6 +1813,12 @@ HELP_EOF
     json_ok "{\"archived\":$archived_flag}"
     ;;
   activity-log-read)
+    # Parse optional --no-errors flag before positional caste_filter
+    _alr_no_errors=false
+    if [[ "${1:-}" == "--no-errors" ]]; then
+      _alr_no_errors=true
+      shift
+    fi
     caste_filter="${1:-}"
 
     # Graceful degradation: check if activity logging is enabled
@@ -1808,6 +1834,12 @@ HELP_EOF
     else
       content=$(cat "$log_file")
     fi
+
+    # Filter out ERROR/WARN lines if --no-errors flag was set
+    if [[ "$_alr_no_errors" == "true" ]]; then
+      content=$(echo "$content" | grep -vE 'ERROR|WARN' || true)
+    fi
+
     json_ok "$(echo "$content" | jq -Rs '.')"
     ;;
   learning-promote) _learning_promote "$@" ;;
@@ -3567,12 +3599,14 @@ Files: ${files_changed} files changed"
 
   memory-capture)
     # Capture learning/failure events with deterministic memory actions.
-    # Usage: memory-capture <event_type> <content> [wisdom_type] [source]
+    # Usage: memory-capture <event_type> <content> [wisdom_type] [source] [source_type] [evidence_type]
     # event_type: learning|failure|redirect|feedback|success|resolution
     mc_event="${1:-}"
     mc_content="${2:-}"
     mc_wisdom_type="${3:-}"
     mc_source="${4:-system:memory-capture}"
+    mc_source_type="${5:-observation}"
+    mc_evidence_type="${6:-anecdotal}"
 
     [[ -z "$mc_event" ]] && json_err "$E_VALIDATION_FAILED" "Usage: memory-capture <event_type> <content> [wisdom_type] [source]" '{"missing":"event_type"}'
     [[ -z "$mc_content" ]] && json_err "$E_VALIDATION_FAILED" "Usage: memory-capture <event_type> <content> [wisdom_type] [source]" '{"missing":"content"}'
@@ -3595,7 +3629,7 @@ Files: ${files_changed} files changed"
     [[ -z "$colony_name" ]] && colony_name="unknown"
 
     # SUPPRESS:OK -- read-default: returns fallback on failure
-    observe_result=$(bash "$0" learning-observe "$mc_content" "$mc_wisdom_type" "$colony_name" 2>/dev/null || echo '{}')
+    observe_result=$(bash "$0" learning-observe "$mc_content" "$mc_wisdom_type" "$colony_name" "$mc_source_type" "$mc_evidence_type" 2>/dev/null || echo '{}')
     if ! echo "$observe_result" | jq -e '.ok == true' >/dev/null 2>&1; then  # SUPPRESS:OK -- validation: testing JSON field
       # SUPPRESS:OK -- read-default: query may return empty
       obs_msg=$(echo "$observe_result" | jq -r '.error.message // "learning_observe_failed"' 2>/dev/null || echo "learning_observe_failed")
@@ -3907,6 +3941,9 @@ Files: ${files_changed} files changed"
   pheromone-count) _pheromone_count "$@" ;;
   pheromone-display) _pheromone_display "$@" ;;
   pheromone-read) _pheromone_read "$@" ;;
+  pheromone-snapshot-inject) _pheromone_snapshot_inject "$@" ;;
+  pheromone-export-branch) _pheromone_export_branch "$@" ;;
+  pheromone-merge-back) _pheromone_merge_back "$@" ;;
 
   instinct-read) _instinct_read "$@" ;;
   instinct-create) _instinct_create "$@" ;;
@@ -5174,6 +5211,50 @@ DRYRUN_EOF
       '{ok:true, removed:{pheromones:$phero, queen:$queen, observations:$obs, midden:$midden, spawn_tree:$spawn, constraints:$constraints}, total:$total}')"
     ;;
 
+  # --- Housekeeping Subcommands ---
+
+  backup-prune-global)
+    # Prune .aether/data/backups/ to a global cap of 50 files (newest kept).
+    # Per-filename rotation (MAX_BACKUPS=3) already runs in atomic-write.sh.
+    # This is the global sweep for unique-filename growth.
+    _bpg_cap=50
+    _bpg_dir="${BACKUP_DIR:-$DATA_DIR/backups}"
+
+    if [[ ! -d "$_bpg_dir" ]]; then
+      json_ok '{"pruned":0,"kept":0,"dir_exists":false}'; exit 0
+    fi
+
+    _bpg_total=$(find "$_bpg_dir" -maxdepth 1 -type f 2>/dev/null | wc -l | tr -d ' ')
+
+    if [[ "$_bpg_total" -le "$_bpg_cap" ]]; then
+      json_ok "$(jq -n --argjson pruned 0 --argjson kept "$_bpg_total" '{pruned:$pruned,kept:$kept}')"; exit 0
+    fi
+
+    _bpg_pruned=0
+    while IFS= read -r _bpg_file; do
+      rm -f "$_bpg_file" 2>/dev/null && _bpg_pruned=$((_bpg_pruned + 1))
+    done < <(find "$_bpg_dir" -maxdepth 1 -type f -print0 2>/dev/null | xargs -0 ls -t 2>/dev/null | tail -n +$((_bpg_cap + 1)))
+
+    _bpg_kept=$((_bpg_total - _bpg_pruned))
+    json_ok "$(jq -n --argjson pruned "$_bpg_pruned" --argjson kept "$_bpg_kept" '{pruned:$pruned,kept:$kept}')"
+    ;;
+
+  temp-clean)
+    # Remove files from .aether/temp/ older than 7 days.
+    _tc_dir="$AETHER_ROOT/.aether/temp"
+    _tc_cleaned=0
+
+    if [[ ! -d "$_tc_dir" ]]; then
+      json_ok '{"cleaned":0,"dir_exists":false}'; exit 0
+    fi
+
+    while IFS= read -r _tc_file; do
+      rm -f "$_tc_file" 2>/dev/null && _tc_cleaned=$((_tc_cleaned + 1))
+    done < <(find "$_tc_dir" -maxdepth 1 -type f -mtime +7 2>/dev/null)
+
+    json_ok "$(jq -n --argjson cleaned "$_tc_cleaned" '{cleaned:$cleaned}')"
+    ;;
+
   # --- Autopilot State Tracking ---
   # Tracks /ant:run autopilot sessions in run-state.json (separate from COLONY_STATE.json)
   # Optional — colonies without /ant:run are unaffected
@@ -5462,6 +5543,101 @@ DRYRUN_EOF
   worktree-cleanup)
     _worktree_cleanup "$@"
     ;;
+  worktree-merge)
+    _worktree_merge "$@"
+    ;;
+
+  # ── Event Bus ───────────────────────────────────────────────────────────────
+  event-publish)
+    _event_publish "$@"
+    ;;
+  event-subscribe)
+    _event_subscribe "$@"
+    ;;
+  event-cleanup)
+    _event_cleanup "$@"
+    ;;
+  event-replay)
+    _event_replay "$@"
+    ;;
+
+  # ── Trust Scoring ──────────────────────────────────────────────────────────
+  trust-calculate)
+    _trust_calculate "$@"
+    ;;
+  trust-decay)
+    _trust_decay "$@"
+    ;;
+  trust-tier)
+    _trust_tier "$@"
+    ;;
+
+  # ── Instinct Store ─────────────────────────────────────────────────────────
+  instinct-store)
+    _instinct_store "$@"
+    ;;
+  instinct-read-trusted)
+    _instinct_read_trusted "$@"
+    ;;
+  instinct-decay-all)
+    _instinct_decay_all "$@"
+    ;;
+  instinct-archive)
+    _instinct_archive "$@"
+    ;;
+
+  # ── Graph Traversal ────────────────────────────────────────────────────────
+  graph-link)
+    _graph_link "$@"
+    ;;
+  graph-neighbors)
+    _graph_neighbors "$@"
+    ;;
+  graph-reach)
+    _graph_reach "$@"
+    ;;
+  graph-cluster)
+    _graph_cluster "$@"
+    ;;
+
+  # ── Curation Ants ──────────────────────────────────────────────────────────
+  curation-sentinel)
+    _curation_sentinel "$@"
+    ;;
+  curation-janitor)
+    _curation_janitor "$@"
+    ;;
+  curation-archivist)
+    _curation_archivist "$@"
+    ;;
+  curation-scribe)
+    _curation_scribe "$@"
+    ;;
+  curation-nurse)
+    _curation_nurse "$@"
+    ;;
+  curation-herald)
+    _curation_herald "$@"
+    ;;
+  curation-librarian)
+    _curation_librarian "$@"
+    ;;
+  curation-critic)
+    _curation_critic "$@"
+    ;;
+  curation-run)
+    _curation_run "$@"
+    ;;
+
+  # ── Consolidation Seal ─────────────────────────────────────────────────────
+  consolidation-seal)
+    _consolidation_seal "$@"
+    ;;
+
+  # ── Consolidation Phase End ───────────────────────────────────────────────
+  consolidation-phase-end)
+    _consolidation_phase_end "$@"
+    ;;
 
   *)
     json_err "$E_VALIDATION_FAILED" "Unknown command: $cmd"

package/.aether/commands/archaeology.yaml

@@ -306,7 +306,7 @@ body_claude: |
 
   Run using the Bash tool with description "Logging excavation activity...":
   ```bash
-  bash .aether/aether-utils.sh activity-log "ARCHAEOLOGY" "Archaeologist" "Excavated {target}: {total_commits} commits, {author_count} authors, {findings_count} findings, {tech_debt_count} debt markers"
+  aether activity-log "ARCHAEOLOGY" "Archaeologist" "Excavated {target}: {total_commits} commits, {author_count} authors, {findings_count} findings, {tech_debt_count} debt markers"
   ```
 
   Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
@@ -314,7 +314,7 @@ body_claude: |
   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"
+  aether print-next-up
   ```
 
   ## Investigation Guidelines
@@ -635,7 +635,7 @@ body_opencode: |
   ### Step 8: Log Activity
 
   ```bash
-  bash .aether/aether-utils.sh activity-log "ARCHAEOLOGY" "Archaeologist" "Excavated {target}: {total_commits} commits, {author_count} authors, {findings_count} findings, {tech_debt_count} debt markers"
+  aether activity-log "ARCHAEOLOGY" "Archaeologist" "Excavated {target}: {total_commits} commits, {author_count} authors, {findings_count} findings, {tech_debt_count} debt markers"
   ```
 
   ## Investigation Guidelines

package/.aether/commands/build.yaml

@@ -70,7 +70,7 @@ body_opencode: |
 
   ### Step 0.5: Load Colony State
 
-  Run using Bash tool: `bash .aether/aether-utils.sh load-state`
+  Run using Bash tool: `aether load-state`
 
   If the command fails (non-zero exit or JSON has ok: false):
   1. Parse error JSON
@@ -88,7 +88,7 @@ body_opencode: |
      ```
      (If HANDOFF.md exists, this provides orientation before the build proceeds)
 
-  After displaying context, run: `bash .aether/aether-utils.sh unload-state` to release the lock.
+  After displaying context, run: `aether unload-state` to release the lock.
 
   ### Step 1: Validate + Read State
 
@@ -121,7 +121,7 @@ body_opencode: |
 
   **Set colony depth (if --depth flag provided):**
   If `cli_depth_override` is set:
-  1. Run using Bash tool: `bash .aether/aether-utils.sh colony-depth set "$cli_depth_override"`
+  1. Run using Bash tool: `aether colony-depth set "$cli_depth_override"`
   2. Parse JSON result - if `.ok` is false:
      - Display: `Error: Invalid depth "$cli_depth_override". Use: light, standard, deep, full`
      - Stop here
@@ -150,7 +150,7 @@ body_opencode: |
   Check for unresolved blocker flags on the requested phase:
 
   ```bash
-  bash .aether/aether-utils.sh flag-check-blockers {phase_number}
+  aether flag-check-blockers {phase_number}
   ```
 
   Parse the JSON result (`.result.blockers`):
@@ -158,7 +158,7 @@ body_opencode: |
   - **If blockers == 0:** Display nothing (or optionally a brief `No active blockers for Phase {id}.` line). Proceed to Step 2.
   - **If blockers > 0:** Retrieve blocker details:
     ```bash
-    bash .aether/aether-utils.sh flag-list --type blocker --phase {phase_number}
+    aether flag-list --type blocker --json --phase {phase_number}
     ```
     Parse `.result.flags` and display an advisory warning:
     ```
@@ -219,7 +219,7 @@ body_opencode: |
 
   Run using the Bash tool with description "Showing phase progress...":
   ```bash
-  progress_bar=$(bash .aether/aether-utils.sh generate-progress-bar "$current_phase" "$total_phases" 20 2>/dev/null || echo "")
+  progress_bar=$(aether generate-progress-bar "$current_phase" "$total_phases" 20 2>/dev/null || echo "")
   if [[ -n "$progress_bar" ]]; then
     echo "[Phase ${current_phase}/${total_phases}] ${progress_bar}"
   fi
@@ -246,7 +246,7 @@ body_opencode: |
   Check if territory survey exists and load relevant documents:
 
   ```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:**
@@ -292,7 +292,7 @@ body_opencode: |
   Call `queen-read` to extract eternal wisdom for worker priming:
 
   ```bash
-  bash .aether/aether-utils.sh queen-read 2>/dev/null
+  aether queen-read 2>/dev/null
   ```
 
   **Parse the JSON response:**
@@ -327,7 +327,7 @@ body_opencode: |
   Call `pheromone-read` to extract active colony signals for worker priming:
 
   ```bash
-  bash .aether/aether-utils.sh pheromone-read 2>/dev/null
+  aether pheromone-read 2>/dev/null
   ```
 
   **Parse the JSON response:**
@@ -381,8 +381,8 @@ body_opencode: |
 
      Generate archaeologist name and log:
      ```bash
-     bash .aether/aether-utils.sh generate-ant-name "archaeologist"
-     bash .aether/aether-utils.sh spawn-log "Queen" "scout" "{archaeologist_name}" "Pre-build archaeology scan"
+     aether generate-ant-name --caste "archaeologist"
+     aether spawn-log --name "Queen" --caste "scout" --id "{archaeologist_name}" --description "Pre-build archaeology scan"
      ```
 
      Display:
@@ -407,7 +407,7 @@ body_opencode: |
      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)
@@ -421,7 +421,7 @@ body_opencode: |
 
      Log completion:
      ```bash
-     bash .aether/aether-utils.sh spawn-complete "{archaeologist_name}" "completed" "Pre-build archaeology scan"
+     aether spawn-complete --id "{archaeologist_name}" --status "completed" --summary "Pre-build archaeology scan"
      ```
 
   3. **Store and display findings:**
@@ -472,9 +472,9 @@ body_opencode: |
 
   3. **Generate ant names for each worker:**
   ```bash
-  bash .aether/aether-utils.sh generate-ant-name "builder"
-  bash .aether/aether-utils.sh generate-ant-name "watcher"
-  bash .aether/aether-utils.sh generate-ant-name "chaos"
+  aether generate-ant-name --caste "builder"
+  aether generate-ant-name --caste "watcher"
+  aether generate-ant-name --caste "chaos"
   ```
 
   Display spawn plan with caste emojis:
@@ -553,12 +553,12 @@ body_opencode: |
 
   **First, mark build start in context:**
   ```bash
-  bash .aether/aether-utils.sh context-update build-start {phase_id} {wave_1_worker_count} {wave_1_task_count}
+  aether context-update build-start {phase_id} {wave_1_worker_count} {wave_1_task_count}
   ```
 
   Before dispatching each worker, refresh colony context so new pheromones/memory are visible:
   ```bash
-  prime_result=$(bash .aether/aether-utils.sh colony-prime --compact 2>/dev/null)
+  prime_result=$(aether colony-prime --compact 2>/dev/null)
   ```
   Update `prompt_section` from `prime_result.result.prompt_section`.
 
@@ -566,8 +566,8 @@ body_opencode: |
 
   Log each spawn and update swarm display:
   ```bash
-  bash .aether/aether-utils.sh spawn-log "Queen" "builder" "{ant_name}" "{task_description}"
-  bash .aether/aether-utils.sh context-update worker-spawn "{ant_name}" "builder" "{task_description}"
+  aether spawn-log --name "Queen" --caste "builder" --id "{ant_name}" --description "{task_description}"
+  aether context-update worker-spawn "{ant_name}" "builder" "{task_description}"
   ```
 
   **Builder Worker Prompt (CLEAN OUTPUT):**
@@ -587,13 +587,13 @@ body_opencode: |
   Work:
   1. Read .aether/workers.md for Builder discipline
   2. Implement task, write tests
-  3. Log activity: bash .aether/aether-utils.sh activity-log "ACTION" "{Ant-Name}" "description"
+  3. Log activity: aether activity-log "ACTION" "{Ant-Name}" "description"
 
   Spawn sub-workers ONLY if 3x complexity:
-  - Check: bash .aether/aether-utils.sh spawn-can-spawn {depth} --enforce
-  - Generate name: bash .aether/aether-utils.sh generate-ant-name "builder"
+  - Check: aether spawn-can-spawn {depth} --enforce
+  - Generate name: aether generate-ant-name --caste "builder"
   - Announce: "🐜 Spawning {child_name} for {reason}"
-  - Log: bash .aether/aether-utils.sh spawn-log "{Ant-Name}" "builder" "{child_name}" "{task}"
+  - Log: aether spawn-log --name "{Ant-Name}" --caste "builder" --id "{child_name}" --description "{task}"
 
   Count your total tool calls (Read + Grep + Edit + Bash + Write) and report as tool_count.
 
@@ -676,7 +676,7 @@ body_opencode: |
 
   Before using any worker payload, validate schema:
   ```bash
-  bash .aether/aether-utils.sh validate-worker-response builder '{worker_json}'
+  aether validate-worker-response builder '{worker_json}'
   ```
   If validation fails, treat the worker as failed with blocker `invalid_worker_response`.
 
@@ -696,8 +696,8 @@ body_opencode: |
 
   Log and update swarm display:
   ```bash
-  bash .aether/aether-utils.sh spawn-complete "{ant_name}" "completed" "{summary}"
-  bash .aether/aether-utils.sh context-update worker-complete "{ant_name}" "completed"
+  aether spawn-complete --id "{ant_name}" --status "completed" --summary "{summary}"
+  aether context-update worker-complete "{ant_name}" "completed"
   ```
 
   **Check for total wave failure:**
@@ -754,7 +754,7 @@ body_opencode: |
 
   Log escalation as flag:
   ```bash
-  bash .aether/aether-utils.sh flag-add "blocker" "{task title}" "{failure summary}" "escalation" {phase_number}
+  aether flag-add --severity "blocker" --title "{task title}" --description "{failure summary}" --source "escalation" --phase {phase_number}
   ```
 
   If at least one worker succeeded, continue normally to the next wave.
@@ -784,7 +784,7 @@ body_opencode: |
   Spawn the Watcher using Task tool with `subagent_type="aether-watcher"`, include `description: "👁️ Watcher {Watcher-Name}: Independent verification"` (DO NOT use run_in_background - task blocks until complete):
 
   ```bash
-  bash .aether/aether-utils.sh spawn-log "Queen" "watcher" "{watcher_name}" "Independent verification"
+  aether spawn-log --name "Queen" --caste "watcher" --id "{watcher_name}" --description "Independent verification"
   ```
 
   **Watcher Worker Prompt (CLEAN OUTPUT):**
@@ -804,7 +804,7 @@ body_opencode: |
   4. Check success criteria: {list}
 
   Spawn sub-workers if needed:
-  - Log: bash .aether/aether-utils.sh spawn-log "{Watcher-Name}" "watcher" "{child}" "{task}"
+  - Log: aether spawn-log --name "{Watcher-Name}" --caste "watcher" --id "{child}" --description "{task}"
   - Announce: "🐜 Spawning {child} to investigate {issue}"
 
   Count your total tool calls (Read + Grep + Edit + Bash + Write) and report as tool_count.
@@ -819,7 +819,7 @@ body_opencode: |
 
   Validate watcher payload first:
   ```bash
-  bash .aether/aether-utils.sh validate-worker-response watcher '{watcher_json}'
+  aether validate-worker-response watcher '{watcher_json}'
   ```
 
   **Parse the Watcher's validated JSON response:** verification_passed, issues_found, quality_score, recommendation
@@ -844,13 +844,13 @@ body_opencode: |
 
   Generate a chaos ant name and log the spawn:
   ```bash
-  bash .aether/aether-utils.sh generate-ant-name "chaos"
-  bash .aether/aether-utils.sh spawn-log "Queen" "chaos" "{chaos_name}" "Resilience testing of Phase {id} work"
+  aether generate-ant-name --caste "chaos"
+  aether spawn-log --name "Queen" --caste "chaos" --id "{chaos_name}" --description "Resilience testing of Phase {id} work"
   ```
 
   **Retrieve existing flags for this phase** (to avoid duplicate findings):
   ```bash
-  bash .aether/aether-utils.sh flag-list --phase {phase_number}
+  aether flag-list --phase {phase_number}
   ```
   Parse the result and extract unresolved flag titles into a list: `{existing_flag_titles}` (comma-separated titles from `.result.flags[].title`). If no flags exist, set `{existing_flag_titles}` to "None".
 
@@ -901,17 +901,17 @@ body_opencode: |
   If any findings have severity `"critical"` or `"high"`:
   ```bash
   # Create a blocker flag for each critical/high chaos finding
-  bash .aether/aether-utils.sh flag-add "blocker" "{finding.title}" "{finding.description}" "chaos-testing" {phase_number}
+  aether flag-add --severity "blocker" --title "{finding.title}" --description "{finding.description}" --source "chaos-testing" --phase {phase_number}
   ```
 
   Log the flag:
   ```bash
-  bash .aether/aether-utils.sh activity-log "FLAG" "Chaos" "Created blocker: {finding.title}"
+  aether activity-log "FLAG" "Chaos" "Created blocker: {finding.title}"
   ```
 
   Log chaos ant completion and update swarm display:
   ```bash
-  bash .aether/aether-utils.sh spawn-complete "{chaos_name}" "completed" "{summary}"
+  aether spawn-complete --id "{chaos_name}" --status "completed" --summary "{summary}"
   ```
 
   ### Step 5.8: Create Flags for Verification Failures
@@ -921,16 +921,51 @@ body_opencode: |
   For each issue in `issues_found`:
   ```bash
   # Create a blocker flag for each verification failure
-  bash .aether/aether-utils.sh flag-add "blocker" "{issue_title}" "{issue_description}" "verification" {phase_number}
+  aether flag-add --severity "blocker" --title "{issue_title}" --description "{issue_description}" --source "verification" --phase {phase_number}
   ```
 
   Log the flag creation:
   ```bash
-  bash .aether/aether-utils.sh activity-log "FLAG" "Watcher" "Created blocker: {issue_title}"
+  aether activity-log "FLAG" "Watcher" "Created blocker: {issue_title}"
   ```
 
   This ensures verification failures are persisted as blockers that survive context resets. Chaos Ant findings are flagged in Step 5.7.
 
+  ### Stage Audit Gate (Pre-Synthesis Check)
+
+  **This gate runs before Step 5.9. All build stages must have completed before synthesizing results.**
+
+  Verify that each of the following stages has a recorded completion status:
+
+  | Stage | Steps | Required |
+  |-------|-------|----------|
+  | Builder waves | Steps 5.1–5.3 | At least 1 worker completed (status "completed") |
+  | Watcher | Steps 5.4–5.5 | Watcher returned a result (any status) |
+  | Chaos | Steps 5.6–5.7 | Chaos ant returned a result (any status) |
+
+  Check by reviewing the in-memory worker results accumulated during Steps 5.1–5.7:
+  - `builder_results` — results from all builder wave tasks
+  - `watcher_result` — result from Step 5.5
+  - `chaos_result` — result from Step 5.7
+
+  **If any stage result is absent (stage did not run or returned no result):**
+  - HALT — do not proceed to Step 5.9
+  - Display:
+    ```
+    Stage Audit FAILED — cannot synthesize results.
+
+    Missing or incomplete stages:
+      {list each missing stage: "Builders — no results recorded" / "Watcher — did not complete" / "Chaos — did not complete"}
+
+    Recovery options:
+      1. Re-run /ant:build to restart this phase
+      2. Run /ant:flags to review blockers
+      3. Run /ant:swarm to auto-repair failed tasks
+    ```
+  - Return `{"status": "failed", "summary": "Stage audit failed — stages did not complete"}` and stop.
+
+  **If all stages have results (even if some workers failed):** proceed to Step 5.9.
+
   ### Step 5.9: Synthesize Results
 
   **This step runs after all worker tasks have completed (Builders, Watcher, Chaos).**
@@ -970,11 +1005,11 @@ body_opencode: |
   For each worker that returned `status: "failed"`:
     For each file in that worker's `files_modified` or `files_created`:
   ```bash
-  bash .aether/aether-utils.sh grave-add "{file}" "{ant_name}" "{task_id}" {phase} "{first blocker or summary}"
+  aether grave-add "{file}" "{ant_name}" "{task_id}" {phase} "{first blocker or summary}"
   ```
     Log the grave marker:
   ```bash
-  bash .aether/aether-utils.sh activity-log "GRAVE" "Queen" "Grave marker placed at {file} — {ant_name} failed: {summary}"
+  aether activity-log "GRAVE" "Queen" "Grave marker placed at {file} — {ant_name} failed: {summary}"
   ```
 
   **Error Handoff Update:**
@@ -1149,12 +1184,12 @@ body_opencode: |
   Log this build activity to `.aether/CONTEXT.md`:
 
   ```bash
-  bash .aether/aether-utils.sh context-update activity "build {phase_id}" "{synthesis.status}" "{files_created_count + files_modified_count}"
+  aether context-update activity "build {phase_id}" "{synthesis.status}" "{files_created_count + files_modified_count}"
   ```
 
   Mark build as complete in context:
   ```bash
-  bash .aether/aether-utils.sh context-update build-complete "{synthesis.status}" "{synthesis.status == 'completed' ? 'success' : 'failed'}"
+  aether context-update build-complete "{synthesis.status}" "{synthesis.status == 'completed' ? 'success' : 'failed'}"
   ```
 
   Also update safe-to-clear status:
@@ -1201,7 +1236,7 @@ body_opencode: |
   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
   ```
 
   **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.
@@ -1216,6 +1251,6 @@ body_opencode: |
   Update the session tracking file to enable `/ant:resume` after context clear:
 
   ```bash
-  bash .aether/aether-utils.sh session-update "/ant:build {phase_id}" "/ant:continue" "Phase {phase_id} build completed: {synthesis.status}"
+  aether session-update --command "/ant:build {phase_id}" --worker "/ant:continue" --summary "Phase {phase_id} build completed: {synthesis.status}"
   ```