aether-colony 5.3.2 → 5.4.0

package/.aether/utils/session.sh

@@ -275,6 +275,13 @@ _session_init() {
         summary: "Session initialized"
       }' > "$session_file.tmp"
     mv "$session_file.tmp" "$session_file"
+
+    # Mirror to legacy path so session recovery (which checks .aether/data/session.json) works
+    local legacy_session="$DATA_DIR/session.json"
+    if [[ "$session_file" != "$legacy_session" ]]; then
+      cp "$session_file" "$legacy_session" 2>/dev/null || true
+    fi
+
     json_ok "$(jq -n --arg sid "$session_id" --arg goal "$goal" --arg file "$session_file" \
       '{session_id: $sid, goal: $goal, file: $file}')"
 }
@@ -361,6 +368,12 @@ _session_update() {
       json_err "$E_UNKNOWN" "Failed to rename temporary session file"
     }
 
+    # Mirror to legacy path so session recovery (which checks .aether/data/session.json) works
+    local legacy_session="$DATA_DIR/session.json"
+    if [[ "$session_file" != "$legacy_session" ]]; then
+      cp "$session_file" "$legacy_session" 2>/dev/null || true
+    fi
+
     json_ok "$(jq -n --arg cmd "$cmd_run" '{updated: true, command: $cmd}')"
 }
 

package/.aether/utils/state-api.sh

@@ -229,7 +229,7 @@ _state_migrate() {
 # Gracefully degrades: missing files produce zero/default values
 # ============================================================================
 _colony_vital_signs() {
-    local cvs_state_file="$COLONY_DATA_DIR/COLONY_STATE.json"
+    local cvs_state_file="$DATA_DIR/COLONY_STATE.json"
     local cvs_midden_file="$COLONY_DATA_DIR/midden/midden.json"
     local cvs_phero_file="$COLONY_DATA_DIR/pheromones.json"
     local cvs_session_file="$COLONY_DATA_DIR/session.json"

package/.aether/utils/trust-scoring.sh

@@ -0,0 +1,347 @@
+#!/bin/bash
+# Trust Scoring utility functions — Aether Structural Learning Stack
+# Provides: _trust_calculate, _trust_decay, _trust_tier
+#
+# These functions are sourced by aether-utils.sh at startup.
+# All shared infrastructure (json_ok, json_err, json_warn, atomic_write,
+# DATA_DIR, COLONY_DATA_DIR, SCRIPT_DIR, error constants) is available.
+#
+# This is a pure calculation module — no state is read or written.
+# All functions accept --flag <value> arguments and return JSON via json_ok.
+
+# ============================================================================
+# _trust_calculate
+# Calculate a weighted trust score from source, evidence, and activity inputs.
+#
+# Weights: source 40%, evidence 35%, activity 25%
+# Activity uses a 60-day half-life decay from days_since_last_use.
+# Floor: score is never below 0.2.
+#
+# Usage: trust-calculate --source <type> --evidence <type> --days-since <N>
+#
+# Source types and weights:
+#   user_feedback   1.0
+#   error_resolution 0.9
+#   success_pattern 0.8
+#   observation     0.6
+#   heuristic       0.4
+#
+# Evidence types and weights:
+#   test_verified   1.0
+#   multi_phase     0.9
+#   single_phase    0.7
+#   anecdotal       0.4
+#
+# Output: {score, source_score, evidence_score, activity_score, tier}
+# ============================================================================
+_trust_calculate() {
+    local source_type=""
+    local evidence_type=""
+    local days_since=""
+
+    # Parse --flag value arguments
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --source)
+                source_type="${2:-}"
+                shift 2
+                ;;
+            --evidence)
+                evidence_type="${2:-}"
+                shift 2
+                ;;
+            --days-since)
+                days_since="${2:-}"
+                shift 2
+                ;;
+            *)
+                json_err "$E_VALIDATION_FAILED" "Usage: trust-calculate --source <type> --evidence <type> --days-since <N>"
+                return
+                ;;
+        esac
+    done
+
+    [[ -z "$source_type" || -z "$evidence_type" || -z "$days_since" ]] && \
+        json_err "$E_VALIDATION_FAILED" "Usage: trust-calculate --source <type> --evidence <type> --days-since <N>"
+
+    # Map source type to score
+    local source_score
+    case "$source_type" in
+        user_feedback)    source_score="1.0" ;;
+        error_resolution) source_score="0.9" ;;
+        success_pattern)  source_score="0.8" ;;
+        observation)      source_score="0.6" ;;
+        heuristic)        source_score="0.4" ;;
+        *)
+            json_err "$E_VALIDATION_FAILED" "Unknown source type: $source_type. Valid: user_feedback, error_resolution, success_pattern, observation, heuristic"
+            return
+            ;;
+    esac
+
+    # Map evidence type to score
+    local evidence_score
+    case "$evidence_type" in
+        test_verified) evidence_score="1.0" ;;
+        multi_phase)   evidence_score="0.9" ;;
+        single_phase)  evidence_score="0.7" ;;
+        anecdotal)     evidence_score="0.4" ;;
+        *)
+            json_err "$E_VALIDATION_FAILED" "Unknown evidence type: $evidence_type. Valid: test_verified, multi_phase, single_phase, anecdotal"
+            return
+            ;;
+    esac
+
+    # Validate days_since is a non-negative integer
+    if ! [[ "$days_since" =~ ^[0-9]+$ ]]; then
+        json_err "$E_VALIDATION_FAILED" "--days-since must be a non-negative integer, got: $days_since"
+        return
+    fi
+
+    # Calculate activity score using 60-day half-life decay
+    # activity = 0.5 ^ (days / 60)
+    local activity_score
+    activity_score=$(_trust_halflife_decay "1.0" "$days_since" "60")
+
+    # Weighted formula: 0.4 * source + 0.35 * evidence + 0.25 * activity
+    local raw_score
+    if command -v bc &>/dev/null; then
+        raw_score=$(echo "scale=6; 0.4 * $source_score + 0.35 * $evidence_score + 0.25 * $activity_score" | bc)
+    else
+        raw_score=$(awk "BEGIN{printf \"%.6f\", 0.4 * $source_score + 0.35 * $evidence_score + 0.25 * $activity_score}")
+    fi
+
+    # Apply floor of 0.2
+    local score
+    score=$(_trust_apply_floor "$raw_score" "0.2")
+
+    # Derive tier from final score
+    local tier
+    tier=$(_trust_score_to_tier "$score")
+
+    json_ok "$(jq -n \
+        --argjson score "$score" \
+        --argjson source_score "$source_score" \
+        --argjson evidence_score "$evidence_score" \
+        --argjson activity_score "$activity_score" \
+        --arg tier "$tier" \
+        '{
+            score: $score,
+            source_score: $source_score,
+            evidence_score: $evidence_score,
+            activity_score: $activity_score,
+            tier: $tier
+        }')"
+}
+
+# ============================================================================
+# _trust_decay
+# Apply time-based half-life decay to an existing trust score.
+# The score never drops below the floor of 0.2.
+#
+# Formula: decayed = max(0.2, score * (0.5 ^ (days / 60)))
+#
+# Usage: trust-decay --score <float> --days <N>
+# Output: {original, decayed, days, half_life: 60}
+# ============================================================================
+_trust_decay() {
+    local score=""
+    local days=""
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --score)
+                score="${2:-}"
+                shift 2
+                ;;
+            --days)
+                days="${2:-}"
+                shift 2
+                ;;
+            *)
+                json_err "$E_VALIDATION_FAILED" "Usage: trust-decay --score <float> --days <N>"
+                return
+                ;;
+        esac
+    done
+
+    [[ -z "$score" || -z "$days" ]] && \
+        json_err "$E_VALIDATION_FAILED" "Usage: trust-decay --score <float> --days <N>"
+
+    # Validate score is a positive number
+    if ! [[ "$score" =~ ^[0-9]+(\.[0-9]+)?$ ]]; then
+        json_err "$E_VALIDATION_FAILED" "--score must be a non-negative number, got: $score"
+        return
+    fi
+
+    # Validate days is a non-negative integer
+    if ! [[ "$days" =~ ^[0-9]+$ ]]; then
+        json_err "$E_VALIDATION_FAILED" "--days must be a non-negative integer, got: $days"
+        return
+    fi
+
+    local decayed
+    decayed=$(_trust_halflife_decay "$score" "$days" "60")
+    local final
+    final=$(_trust_apply_floor "$decayed" "0.2")
+
+    json_ok "$(jq -n \
+        --argjson original "$score" \
+        --argjson decayed "$final" \
+        --argjson days "$days" \
+        --argjson half_life 60 \
+        '{
+            original: $original,
+            decayed: $decayed,
+            days: $days,
+            half_life: $half_life
+        }')"
+}
+
+# ============================================================================
+# _trust_tier
+# Map a trust score to a named tier.
+#
+# Tier table:
+#   0.90–1.00  canonical   (index 0) — proven across multiple contexts
+#   0.80–0.89  trusted     (index 1) — reliable with strong evidence
+#   0.70–0.79  established (index 2) — consistent but limited evidence
+#   0.60–0.69  emerging    (index 3) — promising, needs more validation
+#   0.45–0.59  provisional (index 4) — early stage, minimal evidence
+#   0.30–0.44  suspect     (index 5) — weak evidence or conflicting signals
+#   0.20–0.29  dormant     (index 6) — inactive, near floor
+#
+# Usage: trust-tier --score <float>
+# Output: {score, tier, tier_index}
+# ============================================================================
+_trust_tier() {
+    local score=""
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --score)
+                score="${2:-}"
+                shift 2
+                ;;
+            *)
+                json_err "$E_VALIDATION_FAILED" "Usage: trust-tier --score <float>"
+                return
+                ;;
+        esac
+    done
+
+    [[ -z "$score" ]] && \
+        json_err "$E_VALIDATION_FAILED" "Usage: trust-tier --score <float>"
+
+    # Validate score is a non-negative number
+    if ! [[ "$score" =~ ^[0-9]+(\.[0-9]+)?$ ]]; then
+        json_err "$E_VALIDATION_FAILED" "--score must be a non-negative number, got: $score"
+        return
+    fi
+
+    local tier
+    local tier_index
+    tier=$(_trust_score_to_tier "$score")
+    tier_index=$(_trust_tier_to_index "$tier")
+
+    json_ok "$(jq -n \
+        --argjson score "$score" \
+        --arg tier "$tier" \
+        --argjson tier_index "$tier_index" \
+        '{
+            score: $score,
+            tier: $tier,
+            tier_index: $tier_index
+        }')"
+}
+
+# ============================================================================
+# Internal helpers — not exposed as subcommands
+# ============================================================================
+
+# _trust_halflife_decay: compute score * (0.5 ^ (days / half_life))
+# Usage: _trust_halflife_decay <score> <days> <half_life>
+# Outputs the decayed value as a float string
+_trust_halflife_decay() {
+    local score="$1"
+    local days="$2"
+    local half_life="$3"
+
+    if command -v bc &>/dev/null; then
+        echo "scale=6; $score * e(l(0.5) * ($days / $half_life))" | bc -l
+    else
+        awk "BEGIN{printf \"%.6f\", $score * (0.5 ^ ($days / $half_life))}"
+    fi
+}
+
+# _trust_apply_floor: return max(floor, value)
+# Usage: _trust_apply_floor <value> <floor>
+# Outputs the floored value as a float string
+_trust_apply_floor() {
+    local value="$1"
+    local floor="$2"
+
+    if command -v bc &>/dev/null; then
+        local cmp
+        cmp=$(echo "$value < $floor" | bc -l)
+        if [[ "$cmp" == "1" ]]; then
+            echo "$floor"
+        else
+            echo "$value"
+        fi
+    else
+        awk "BEGIN{v=$value; f=$floor; printf \"%.6f\", (v < f ? f : v)}"
+    fi
+}
+
+# _trust_score_to_tier: map a numeric score to a tier name
+# Usage: _trust_score_to_tier <score>
+# Outputs the tier name string
+_trust_score_to_tier() {
+    local score="$1"
+
+    if command -v bc &>/dev/null; then
+        if [[ $(echo "$score >= 0.90" | bc -l) == "1" ]]; then
+            echo "canonical"
+        elif [[ $(echo "$score >= 0.80" | bc -l) == "1" ]]; then
+            echo "trusted"
+        elif [[ $(echo "$score >= 0.70" | bc -l) == "1" ]]; then
+            echo "established"
+        elif [[ $(echo "$score >= 0.60" | bc -l) == "1" ]]; then
+            echo "emerging"
+        elif [[ $(echo "$score >= 0.45" | bc -l) == "1" ]]; then
+            echo "provisional"
+        elif [[ $(echo "$score >= 0.30" | bc -l) == "1" ]]; then
+            echo "suspect"
+        else
+            echo "dormant"
+        fi
+    else
+        awk "BEGIN{
+            s = $score
+            if (s >= 0.90)      print \"canonical\"
+            else if (s >= 0.80) print \"trusted\"
+            else if (s >= 0.70) print \"established\"
+            else if (s >= 0.60) print \"emerging\"
+            else if (s >= 0.45) print \"provisional\"
+            else if (s >= 0.30) print \"suspect\"
+            else                print \"dormant\"
+        }"
+    fi
+}
+
+# _trust_tier_to_index: map tier name to integer index
+# Usage: _trust_tier_to_index <tier_name>
+# Outputs the index as an integer string
+_trust_tier_to_index() {
+    local tier="$1"
+    case "$tier" in
+        canonical)    echo "0" ;;
+        trusted)      echo "1" ;;
+        established)  echo "2" ;;
+        emerging)     echo "3" ;;
+        provisional)  echo "4" ;;
+        suspect)      echo "5" ;;
+        dormant)      echo "6" ;;
+        *)            echo "-1" ;;
+    esac
+}

package/.aether/utils/worktree.sh

@@ -187,3 +187,100 @@ _worktree_cleanup() {
 
     json_ok "$result"
 }
+
+# _worktree_merge
+# Merges a worktree branch back to the target branch with safety checks.
+#
+# Usage: _worktree_merge --branch <branch-name> [--target <target-branch>] [--force]
+# Returns JSON: {ok:true, result:{merged, branch, target, sha, commits_merged}}
+_worktree_merge() {
+    local branch=""
+    local target=""
+    local force=false
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --branch) branch="${2:-}"; shift 2 ;;
+            --target) target="${2:-}"; shift 2 ;;
+            --force)  force=true; shift ;;
+            *) shift ;;
+        esac
+    done
+
+    if [[ -z "$branch" ]]; then
+        json_err "$E_VALIDATION_FAILED" "Usage: worktree-merge --branch <branch-name> [--target <target-branch>]"
+    fi
+
+    # Sanitize branch name
+    if [[ "$branch" == *..* ]] || [[ "$branch" == */* ]] || [[ "$branch" == *\\* ]]; then
+        json_err "$E_VALIDATION_FAILED" "Branch name must not contain '..', '/', or backslashes"
+    fi
+
+    local worktree_dir="$WORKTREE_BASE_DIR/$branch"
+
+    # Default target to current branch
+    if [[ -z "$target" ]]; then
+        target=$(git -C "$AETHER_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
+    fi
+
+    # Safety check 1: worktree must exist
+    if [[ ! -d "$worktree_dir" ]]; then
+        json_err "$E_RESOURCE_NOT_FOUND" "No worktree found for branch '$branch'"
+    fi
+
+    # Safety check 2: worktree must have committed changes (unless --force)
+    if [[ "$force" == "false" ]]; then
+        local dirty_count
+        dirty_count=$(git -C "$worktree_dir" status --porcelain 2>/dev/null \
+            | grep -v '\.aether/' \
+            | wc -l | tr -d ' ') || dirty_count=0
+        if [[ "$dirty_count" -gt 0 ]]; then
+            json_err "$E_VALIDATION_FAILED" "Worktree '$branch' has $dirty_count uncommitted changes. Commit or stash before merging."
+        fi
+    fi
+
+    # Safety check 3: worktree must have commits ahead of target
+    local ahead_count
+    ahead_count=$(git -C "$AETHER_ROOT" rev-list --count "${target}..${branch}" 2>/dev/null || echo "0")
+    if [[ "$ahead_count" -eq 0 ]]; then
+        # Nothing to merge — just clean up
+        _worktree_cleanup --branch "$branch" --force
+        return $?
+    fi
+
+    # Safety check 4: check for merge conflicts (dry run)
+    local conflict_check
+    conflict_check=$(git -C "$AETHER_ROOT" merge-tree $(git -C "$AETHER_ROOT" merge-base "$target" "$branch") "$target" "$branch" 2>/dev/null | grep -c "changed in both" || echo "0")
+    if [[ "$conflict_check" -gt 0 ]] && [[ "$force" == "false" ]]; then
+        json_err "$E_VALIDATION_FAILED" "Merge would produce $conflict_check conflict(s). Resolve manually or use --force."
+    fi
+
+    # Perform the merge
+    local merge_sha
+    if ! git -C "$AETHER_ROOT" merge "$branch" --no-edit --no-ff -m "merge: worktree branch $branch into $target" >/dev/null 2>&1; then
+        # Merge failed — abort
+        git -C "$AETHER_ROOT" merge --abort 2>/dev/null || true
+        json_err "$E_GIT_ERROR" "Merge of '$branch' into '$target' failed. Aborted."
+    fi
+
+    merge_sha=$(git -C "$AETHER_ROOT" rev-parse HEAD 2>/dev/null || echo "unknown")
+
+    # Export pheromones from the worktree branch before cleanup
+    if [[ -f "$worktree_dir/.aether/data/pheromones.json" ]]; then
+        mkdir -p "$AETHER_ROOT/.aether/exchange"
+        cp "$worktree_dir/.aether/data/pheromones.json" \
+           "$AETHER_ROOT/.aether/exchange/pheromone-branch-export.json" 2>/dev/null || true
+    fi
+
+    # Cleanup the worktree
+    _worktree_cleanup --branch "$branch" --force 2>/dev/null || true
+
+    local result
+    result=$(jq -n \
+        --arg branch "$branch" \
+        --arg target "$target" \
+        --arg sha "$merge_sha" \
+        --argjson ahead "$ahead_count" \
+        '{merged: true, branch: $branch, target: $target, sha: $sha, commits_merged: $ahead}')
+    json_ok "$result"
+}

package/.claude/commands/ant/archaeology.md

@@ -309,7 +309,7 @@ Excavation date: {YYYY-MM-DD}
 
 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...":
@@ -317,7 +317,7 @@ Generate the state-based Next Up block by running using the Bash tool with descr
 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

package/.claude/commands/ant/chaos.md

@@ -295,12 +295,12 @@ After outputting the JSON report, iterate through the chaos report scenarios. Fo
 
 ```bash
 # For each scenario where status == "finding" AND severity is "CRITICAL" or "HIGH":
-bash .aether/aether-utils.sh flag-add "blocker" "{scenario.title}" "{scenario.description}" "chaos-standalone" {current_phase_number}
+aether flag-add --severity "blocker" --title "{scenario.title}" --description "{scenario.description}" --source "chaos-standalone" --phase {current_phase_number}
 ```
 
 Log each flag creation by running using the Bash tool with description "Logging chaos flag...":
 ```bash
-bash .aether/aether-utils.sh activity-log "FLAG" "Chaos Ant" "Created blocker: {scenario.title}"
+aether activity-log "FLAG" "Chaos Ant" "Created blocker: {scenario.title}"
 ```
 
 The `{current_phase_number}` comes from the colony state loaded in Step 1 (`.aether/data/COLONY_STATE.json` field `current_phase`).
@@ -311,7 +311,7 @@ The `{current_phase_number}` comes from the colony state loaded in Step 1 (`.aet
 
 Run using the Bash tool with description "Logging chaos activity...":
 ```bash
-bash .aether/aether-utils.sh activity-log "CHAOS" "Chaos Ant" "Resilience test on {target}: {findings_count} finding(s) ({critical} critical, {high} high, {medium} medium, {low} low), {resilient_count} resilient"
+aether activity-log "CHAOS" "Chaos Ant" "Resilience test on {target}: {findings_count} finding(s) ({critical} critical, {high} high, {medium} medium, {low} low), {resilient_count} resilient"
 ```
 
 Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
@@ -319,7 +319,7 @@ Generate the state-based Next Up block by running using the Bash tool with descr
 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

package/.claude/commands/ant/colonize.md

@@ -109,14 +109,14 @@ Before dispatching surveyors, check for existing survey files and capture sessio
 SURVEY_START=$(date +%s)
 
 # Check for stale survey files
-stale_check=$(bash .aether/aether-utils.sh session-verify-fresh --command survey "" "$SURVEY_START")
+stale_check=$(aether session-verify-fresh --command survey "" "$SURVEY_START")
 has_stale=$(echo "$stale_check" | jq -r '.stale | length')
 has_fresh=$(echo "$stale_check" | jq -r '.fresh | length')
 
 if [[ "$has_stale" -gt 0 ]] || [[ "$has_fresh" -gt 0 ]]; then
   # Found existing survey files
   if [[ "$force_resurvey" == "true" ]]; then
-    bash .aether/aether-utils.sh session-clear --command survey
+    aether session-clear --command survey
     echo "Cleared existing survey files for fresh territory mapping"
   else
     echo "Found existing territory survey. Use --force-resurvey to remap."
@@ -127,15 +127,15 @@ fi
 
 Generate unique names for the 4 Surveyor Ants (each name must be captured separately):
 ```bash
- bash .aether/aether-utils.sh generate-ant-name "surveyor"
-bash .aether/aether-utils.sh generate-ant-name "surveyor"
-bash .aether/aether-utils.sh generate-ant-name "surveyor"
-bash .aether/aether-utils.sh generate-ant-name "surveyor"
+ aether generate-ant-name --caste "surveyor"
+aether generate-ant-name --caste "surveyor"
+aether generate-ant-name --caste "surveyor"
+aether generate-ant-name --caste "surveyor"
 ```
 
 Log the dispatches (consolidated - fire-and-forget logging):
 ```bash
-bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{provisions_name}" "Mapping provisions and trails" && bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{nest_name}" "Mapping nest structure" && bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{disciplines_name}" "Mapping disciplines and sentinels" && bash .aether/aether-utils.sh spawn-log "Queen" "surveyor" "{pathogens_name}" "Identifying pathogens"
+aether spawn-log --name "Queen" --caste "surveyor" --id "{provisions_name}" --description "Mapping provisions and trails" && aether spawn-log --name "Queen" --caste "surveyor" --id "{nest_name}" --description "Mapping nest structure" && aether spawn-log --name "Queen" --caste "surveyor" --id "{disciplines_name}" --description "Mapping disciplines and sentinels" && aether spawn-log --name "Queen" --caste "surveyor" --id "{pathogens_name}" --description "Identifying pathogens"
 ```
 
 **Spawn 4 Surveyor Ants in parallel using the Task tool:**
@@ -179,7 +179,7 @@ If any documents are missing, note which ones in the output.
 
 Verify that all survey files were created after the session start:
 ```bash
-verify_result=$(bash .aether/aether-utils.sh session-verify-fresh --command survey "" "$SURVEY_START")
+verify_result=$(aether session-verify-fresh --command survey "" "$SURVEY_START")
 fresh_count=$(echo "$verify_result" | jq -r '.fresh | length')
 
 if [[ "$fresh_count" -lt 7 ]]; then
@@ -255,5 +255,5 @@ Generate the state-based Next Up block:
 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
 ```

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

@@ -25,7 +25,7 @@ When `--deliberate "<proposal>"` is passed, run a structured Advocate/Challenger
 
 Run using the Bash tool with description "Checking deliberation budget...":
 ```bash
-bash .aether/aether-utils.sh council-budget-check
+aether council-budget-check
 ```
 
 Parse result. If `allowed` is `false`:
@@ -41,7 +41,7 @@ Stop here.
 
 Run using the Bash tool with description "Opening deliberation...":
 ```bash
-bash .aether/aether-utils.sh council-deliberate --proposal "<proposal>"
+aether council-deliberate --proposal "<proposal>"
 ```
 
 Capture `deliberation_id` from `result.id`.
@@ -84,7 +84,7 @@ Capture the advocate's argument as `advocate_argument`.
 
 Record the argument:
 ```bash
-bash .aether/aether-utils.sh council-advocate \
+aether council-advocate \
   --deliberation-id "<deliberation_id>" \
   --argument "<advocate_argument>"
 ```
@@ -122,7 +122,7 @@ Capture the challenger's argument as `challenger_argument`.
 
 Record the argument:
 ```bash
-bash .aether/aether-utils.sh council-challenger \
+aether council-challenger \
   --deliberation-id "<deliberation_id>" \
   --argument "<challenger_argument>"
 ```
@@ -165,7 +165,7 @@ Parse the JSON response. Capture `synthesis` and `recommendation`.
 
 Record the sage synthesis:
 ```bash
-bash .aether/aether-utils.sh council-sage \
+aether council-sage \
   --deliberation-id "<deliberation_id>" \
   --synthesis "<synthesis>" \
   --recommendation "<recommendation>"
@@ -502,6 +502,6 @@ Generate the state-based Next Up block by running using the Bash tool with descr
 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
 ```
 

package/.claude/commands/ant/data-clean.md

@@ -17,7 +17,7 @@ You are the **Queen Ant Colony**. Run the data cleaner to scan for and remove te
 
 Run using the Bash tool with description "Scanning colony data for test artifacts...":
 ```bash
-bash .aether/aether-utils.sh data-clean --dry-run
+aether data-clean --dry-run
 ```
 
 Display the output to the user. This shows artifact counts per data file without modifying anything.
@@ -46,7 +46,7 @@ If user says no, display "No changes made." and skip to Step 5.
 
 If user confirmed, run using the Bash tool with description "Removing test artifacts...":
 ```bash
-bash .aether/aether-utils.sh data-clean --confirm
+aether data-clean --confirm
 ```
 
 ### Step 4: Summary
@@ -76,6 +76,6 @@ Generate the state-based Next Up block by running using the Bash tool with descr
 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
 ```