aether-colony 5.3.2 → 5.3.3

package/.aether/utils/consolidation.sh

@@ -0,0 +1,127 @@
+#!/bin/bash
+# Consolidation utility — lightweight end-of-phase consolidation
+# Provides: _consolidation_phase_end
+#
+# These functions are sourced by aether-utils.sh at startup.
+# All shared infrastructure (json_ok, json_err, atomic_write,
+# COLONY_DATA_DIR, SCRIPT_DIR, error constants) is available.
+#
+# Subcommand: consolidation-phase-end [--dry-run]
+# Runs nurse + herald + janitor curation ants in sequence,
+# then publishes a consolidation.phase_end event to the event bus.
+# Each step is non-blocking: failures are logged and execution continues.
+
+# ============================================================================
+# _consolidation_phase_end
+# Run lightweight end-of-phase consolidation.
+#
+# Usage: consolidation-phase-end [--dry-run]
+#
+# Output: json_ok with:
+#   {type, steps:[{name, status, summary}], event_published, dry_run}
+# ============================================================================
+_consolidation_phase_end() {
+    local dry_run="false"
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --dry-run) dry_run="true"; shift ;;
+            *) shift ;;
+        esac
+    done
+
+    local dry_run_flag=""
+    [[ "$dry_run" == "true" ]] && dry_run_flag="--dry-run"
+
+    local steps_json="[]"
+
+    # ── Step 1: curation-nurse (trust recalculation) ──────────────────────────
+    local nurse_status="ok"
+    local nurse_summary=""
+    local nurse_result
+    # shellcheck disable=SC2086
+    nurse_result=$(bash "$0" curation-nurse $dry_run_flag 2>/dev/null) || nurse_status="failed"
+
+    if [[ "$nurse_status" == "ok" ]]; then
+        nurse_summary=$(echo "$nurse_result" | jq -r \
+            '"observations_updated=\(.result.observations_updated // 0) instincts_updated=\(.result.instincts_updated // 0)"' \
+            2>/dev/null || echo "completed")
+    else
+        nurse_summary="nurse step failed; continuing"
+    fi
+
+    steps_json=$(echo "$steps_json" | jq -c \
+        --arg name "nurse" \
+        --arg status "$nurse_status" \
+        --arg summary "$nurse_summary" \
+        '. + [{name:$name,status:$status,summary:$summary}]')
+
+    # ── Step 2: curation-herald (promote high-trust to QUEEN.md) ─────────────
+    local herald_status="ok"
+    local herald_summary=""
+    local herald_result
+    # shellcheck disable=SC2086
+    herald_result=$(bash "$0" curation-herald $dry_run_flag 2>/dev/null) || herald_status="failed"
+
+    if [[ "$herald_status" == "ok" ]]; then
+        herald_summary=$(echo "$herald_result" | jq -r \
+            '"eligible=\(.result.eligible // 0) promoted=\(.result.promoted // 0)"' \
+            2>/dev/null || echo "completed")
+    else
+        herald_summary="herald step failed; continuing"
+    fi
+
+    steps_json=$(echo "$steps_json" | jq -c \
+        --arg name "herald" \
+        --arg status "$herald_status" \
+        --arg summary "$herald_summary" \
+        '. + [{name:$name,status:$status,summary:$summary}]')
+
+    # ── Step 3: curation-janitor (clean expired) ─────────────────────────────
+    local janitor_status="ok"
+    local janitor_summary=""
+    local janitor_result
+    # shellcheck disable=SC2086
+    janitor_result=$(bash "$0" curation-janitor $dry_run_flag 2>/dev/null) || janitor_status="failed"
+
+    if [[ "$janitor_status" == "ok" ]]; then
+        janitor_summary=$(echo "$janitor_result" | jq -r \
+            '"events_removed=\(.result.events_removed // 0) instincts_pruned=\(.result.instincts_pruned // 0)"' \
+            2>/dev/null || echo "completed")
+    else
+        janitor_summary="janitor step failed; continuing"
+    fi
+
+    steps_json=$(echo "$steps_json" | jq -c \
+        --arg name "janitor" \
+        --arg status "$janitor_status" \
+        --arg summary "$janitor_summary" \
+        '. + [{name:$name,status:$status,summary:$summary}]')
+
+    # ── Step 4: publish event to event bus ───────────────────────────────────
+    local event_published="false"
+
+    local current_phase
+    current_phase=$(jq -r '.current_phase // 0' "$COLONY_DATA_DIR/COLONY_STATE.json" 2>/dev/null || echo "0")
+
+    local payload
+    payload=$(jq -nc \
+        --argjson phase "$current_phase" \
+        --argjson dry_run "$dry_run" \
+        --argjson steps "$steps_json" \
+        '{phase:$phase,dry_run:$dry_run,steps:$steps}')
+
+    if bash "$0" event-publish \
+            --topic "consolidation.phase_end" \
+            --payload "$payload" \
+            --source "consolidation" \
+            > /dev/null 2>&1; then
+        event_published="true"
+    fi
+
+    json_ok "$(jq -nc \
+        --argjson steps "$steps_json" \
+        --argjson event_published "$event_published" \
+        --argjson dry_run "$dry_run" \
+        '{type:"phase_end",steps:$steps,event_published:$event_published,dry_run:$dry_run}')"
+}

package/.aether/utils/curation-ants/archivist.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+# Curation Archivist — Low-Trust Instinct Archival
+# Archives instincts that have decayed below a trust threshold.
+#
+# Functions:
+#   _curation_archivist
+#
+# These functions are sourced by aether-utils.sh at startup.
+# All shared infrastructure (json_ok, json_err, atomic_write, COLONY_DATA_DIR,
+# DATA_DIR, error constants) is available when sourced.
+
+# ============================================================================
+# _curation_archivist
+# Archive active instincts with trust_score below threshold.
+# Usage: curation-archivist [--threshold <float>] [--dry-run]
+#
+# Default threshold: 0.25
+# Output: json_ok with {archived:N, below_threshold:N, dry_run:bool}
+# ============================================================================
+_curation_archivist() {
+    local ca_threshold="0.25"
+    local ca_dry_run="false"
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --threshold)
+                ca_threshold="${2:-0.25}"
+                shift 2
+                ;;
+            --dry-run)
+                ca_dry_run="true"
+                shift
+                ;;
+            *)
+                shift
+                ;;
+        esac
+    done
+
+    local ca_data_dir="${COLONY_DATA_DIR:-${DATA_DIR:-}}"
+    if [[ -z "$ca_data_dir" ]]; then
+        json_err "$E_VALIDATION_FAILED" "curation-archivist: COLONY_DATA_DIR is not set"
+    fi
+
+    local ca_instincts_file="$ca_data_dir/instincts.json"
+
+    # No instincts file — nothing to archive
+    if [[ ! -f "$ca_instincts_file" ]]; then
+        json_ok "$(jq -nc \
+            --argjson archived 0 \
+            --argjson below_threshold 0 \
+            --argjson dry_run "$ca_dry_run" \
+            '{archived:$archived, below_threshold:$below_threshold, dry_run:$dry_run}')"
+        return 0
+    fi
+
+    if ! jq empty "$ca_instincts_file" 2>/dev/null; then
+        json_err "$E_JSON_INVALID" "curation-archivist: instincts.json is not valid JSON"
+    fi
+
+    # Count active instincts below threshold
+    local ca_below_threshold
+    ca_below_threshold=$(jq --argjson thresh "$ca_threshold" \
+        '[.instincts[] | select(.archived != true and (.trust_score // .confidence // 0) < $thresh)] | length' \
+        "$ca_instincts_file" 2>/dev/null || echo 0)
+
+    local ca_archived=0
+
+    if [[ "$ca_dry_run" == "false" && "$ca_below_threshold" -gt 0 ]]; then
+        local ca_ts
+        ca_ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+        local ca_updated
+        ca_updated=$(jq \
+            --argjson thresh "$ca_threshold" \
+            --arg ts "$ca_ts" \
+            '.instincts |= [.[] | if (.archived != true and (.trust_score // .confidence // 0) < $thresh)
+                then . + {archived: true, updated_at: $ts}
+                else .
+                end]' \
+            "$ca_instincts_file" 2>/dev/null)
+
+        if [[ -n "$ca_updated" ]]; then
+            atomic_write "$ca_instincts_file" "$ca_updated" 2>/dev/null \
+                || json_err "$E_UNKNOWN" "curation-archivist: failed to write instincts.json"
+            ca_archived="$ca_below_threshold"
+        fi
+    elif [[ "$ca_dry_run" == "true" ]]; then
+        ca_archived="$ca_below_threshold"
+    fi
+
+    json_ok "$(jq -nc \
+        --argjson archived "$ca_archived" \
+        --argjson below_threshold "$ca_below_threshold" \
+        --argjson dry_run "$ca_dry_run" \
+        '{archived:$archived, below_threshold:$below_threshold, dry_run:$dry_run}')"
+}

package/.aether/utils/curation-ants/critic.sh

@@ -0,0 +1,214 @@
+#!/bin/bash
+# Critic curation ant — contradiction detection between instincts
+# Provides: _curation_critic
+#
+# These functions are sourced by aether-utils.sh at startup.
+# All shared infrastructure (json_ok, json_err, atomic_write,
+# COLONY_DATA_DIR, error constants) is available.
+#
+# Subcommand: curation-critic [--auto-resolve]
+# Finds contradicting instincts using text heuristics and graph edges.
+
+# ============================================================================
+# _curation_critic_opposing_words
+# Internal helper: check if two action strings oppose each other.
+# Detects "always"/"never" and "do"/"don't" opposites in the same domain.
+# Outputs "true" if opposing, "false" otherwise.
+# ============================================================================
+_curation_critic_opposing_words() {
+    local action_a="$1"
+    local action_b="$2"
+
+    local low_a low_b
+    low_a=$(echo "$action_a" | tr '[:upper:]' '[:lower:]')
+    low_b=$(echo "$action_b" | tr '[:upper:]' '[:lower:]')
+
+    # "always" in one and "never" in the other
+    if [[ "$low_a" == *"always"* && "$low_b" == *"never"* ]]; then
+        echo "true"; return
+    fi
+    if [[ "$low_a" == *"never"* && "$low_b" == *"always"* ]]; then
+        echo "true"; return
+    fi
+
+    # "don't" or "do not" in one and plain action (no negation) in the other
+    if [[ "$low_a" == *"don't"* || "$low_a" == *"do not"* ]]; then
+        # Strip negation from a: "don't add X" -> "add X" — check overlap with b
+        local stripped_a
+        stripped_a=$(echo "$low_a" | sed "s/don't //g; s/do not //g")
+        if [[ "$low_b" == *"$stripped_a"* || "$stripped_a" == *"$low_b"* ]]; then
+            # Only flag if they share substantial content (>= 4 chars of overlap)
+            local overlap_len=${#stripped_a}
+            [[ "$overlap_len" -ge 4 ]] && echo "true" && return
+        fi
+    fi
+    if [[ "$low_b" == *"don't"* || "$low_b" == *"do not"* ]]; then
+        local stripped_b
+        stripped_b=$(echo "$low_b" | sed "s/don't //g; s/do not //g")
+        if [[ "$low_a" == *"$stripped_b"* || "$stripped_b" == *"$low_a"* ]]; then
+            local overlap_len=${#stripped_b}
+            [[ "$overlap_len" -ge 4 ]] && echo "true" && return
+        fi
+    fi
+
+    echo "false"
+}
+
+# ============================================================================
+# _curation_critic
+# Find contradicting instincts and optionally auto-resolve them.
+#
+# Usage: curation-critic [--auto-resolve]
+#
+# Contradiction criteria:
+#   - Same domain
+#   - Opposing triggers (same trigger text) with opposing action keywords
+#   - OR existing "contradicts" edge in the graph
+#
+# Auto-resolve: archive the lower-trust instinct, create "contradicts" graph edge.
+#
+# Output: {contradictions: [{instinct_a, instinct_b, reason, resolved}], count: N}
+# ============================================================================
+_curation_critic() {
+    local auto_resolve="false"
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --auto-resolve) auto_resolve="true"; shift ;;
+            *) shift ;;
+        esac
+    done
+
+    local inst_file="$COLONY_DATA_DIR/instincts.json"
+
+    if [[ ! -f "$inst_file" ]]; then
+        json_ok '{"contradictions":[],"count":0}'
+        return
+    fi
+
+    # Load all active instincts into a bash-friendly form
+    local active_instincts
+    active_instincts=$(jq -c '[.instincts[] | select(.archived == false)]' "$inst_file" 2>/dev/null || echo "[]")
+
+    local total_active
+    total_active=$(echo "$active_instincts" | jq 'length')
+
+    local contradictions_json="[]"
+    local resolved_ids=()
+
+    if [[ "$total_active" -ge 2 ]]; then
+        # Compare all pairs using indexed access
+        local i=0
+        while [[ $i -lt $((total_active - 1)) ]]; do
+            local inst_a
+            inst_a=$(echo "$active_instincts" | jq -c ".[$i]")
+            local id_a domain_a trigger_a action_a score_a
+            id_a=$(echo "$inst_a" | jq -r '.id')
+            domain_a=$(echo "$inst_a" | jq -r '.domain // ""')
+            trigger_a=$(echo "$inst_a" | jq -r '.trigger // ""')
+            action_a=$(echo "$inst_a" | jq -r '.action // ""')
+            score_a=$(echo "$inst_a" | jq -r '.trust_score // 0')
+
+            local j=$((i + 1))
+            while [[ $j -lt $total_active ]]; do
+                local inst_b
+                inst_b=$(echo "$active_instincts" | jq -c ".[$j]")
+                local id_b domain_b trigger_b action_b score_b
+                id_b=$(echo "$inst_b" | jq -r '.id')
+                domain_b=$(echo "$inst_b" | jq -r '.domain // ""')
+                trigger_b=$(echo "$inst_b" | jq -r '.trigger // ""')
+                action_b=$(echo "$inst_b" | jq -r '.action // ""')
+                score_b=$(echo "$inst_b" | jq -r '.trust_score // 0')
+
+                local contradiction_reason=""
+
+                # Heuristic 1: Same domain + similar trigger + opposing actions
+                if [[ -n "$domain_a" && "$domain_a" == "$domain_b" ]]; then
+                    # Check if triggers are similar (first 40 chars match or substantial overlap)
+                    local trig_prefix_a trig_prefix_b
+                    trig_prefix_a=$(echo "$trigger_a" | cut -c1-40 | tr '[:upper:]' '[:lower:]')
+                    trig_prefix_b=$(echo "$trigger_b" | cut -c1-40 | tr '[:upper:]' '[:lower:]')
+
+                    if [[ "$trig_prefix_a" == "$trig_prefix_b" && -n "$trig_prefix_a" ]]; then
+                        local opposing
+                        opposing=$(_curation_critic_opposing_words "$action_a" "$action_b")
+                        if [[ "$opposing" == "true" ]]; then
+                            contradiction_reason="same domain and trigger with opposing actions"
+                        fi
+                    fi
+                fi
+
+                # Heuristic 2: Check existing "contradicts" graph edge
+                if [[ -z "$contradiction_reason" ]]; then
+                    local graph_file="$COLONY_DATA_DIR/instinct-graph.json"
+                    if [[ -f "$graph_file" ]]; then
+                        local has_edge
+                        has_edge=$(jq -r \
+                            --arg a "$id_a" --arg b "$id_b" \
+                            '[.edges[] | select(
+                                .relationship == "contradicts" and (
+                                    (.source == $a and .target == $b) or
+                                    (.source == $b and .target == $a)
+                                )
+                            )] | length' "$graph_file" 2>/dev/null || echo 0)
+                        if [[ "$has_edge" -gt 0 ]]; then
+                            contradiction_reason="existing contradicts graph edge"
+                        fi
+                    fi
+                fi
+
+                if [[ -n "$contradiction_reason" ]]; then
+                    local resolved="false"
+
+                    if [[ "$auto_resolve" == "true" ]]; then
+                        # Archive the lower-trust instinct
+                        local lower_id higher_id
+                        local cmp
+                        cmp=$(awk "BEGIN{print ($score_a >= $score_b)}" 2>/dev/null || echo "1")
+                        if [[ "$cmp" == "1" ]]; then
+                            lower_id="$id_b"
+                            higher_id="$id_a"
+                        else
+                            lower_id="$id_a"
+                            higher_id="$id_b"
+                        fi
+
+                        # Only archive if not already scheduled (avoid double-archive)
+                        local already_resolving="false"
+                        for rid in "${resolved_ids[@]:-}"; do
+                            [[ "$rid" == "$lower_id" ]] && already_resolving="true" && break
+                        done
+
+                        if [[ "$already_resolving" != "true" ]]; then
+                            _instinct_archive --id "$lower_id" >/dev/null 2>&1 || true
+                            resolved_ids+=("$lower_id")
+                            resolved="true"
+
+                            # Create "contradicts" graph edge (best effort)
+                            _graph_link --source "$higher_id" --target "$lower_id" \
+                                --relationship contradicts >/dev/null 2>&1 || true
+                        fi
+                    fi
+
+                    contradictions_json=$(echo "$contradictions_json" | jq \
+                        --arg a "$id_a" \
+                        --arg b "$id_b" \
+                        --arg reason "$contradiction_reason" \
+                        --argjson resolved "$([ "$resolved" == "true" ] && echo true || echo false)" \
+                        '. += [{instinct_a: $a, instinct_b: $b, reason: $reason, resolved: $resolved}]')
+                fi
+
+                j=$((j + 1))
+            done
+            i=$((i + 1))
+        done
+    fi
+
+    local count
+    count=$(echo "$contradictions_json" | jq 'length')
+
+    json_ok "$(jq -n \
+        --argjson contradictions "$contradictions_json" \
+        --argjson count "$count" \
+        '{contradictions: $contradictions, count: $count}')"
+}

package/.aether/utils/curation-ants/herald.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# Herald curation ant — QUEEN.md promotion of high-trust instincts
+# Provides: _curation_herald
+#
+# These functions are sourced by aether-utils.sh at startup.
+# All shared infrastructure (json_ok, json_err, atomic_write,
+# COLONY_DATA_DIR, AETHER_ROOT, SCRIPT_DIR, error constants) is available.
+#
+# Subcommand: curation-herald [--min-trust <float>] [--dry-run]
+# Promotes instincts with trust_score >= min-trust to QUEEN.md wisdom.
+
+# ============================================================================
+# _curation_herald
+# Promote high-trust instincts to QUEEN.md.
+#
+# Usage: curation-herald [--min-trust <float>] [--dry-run]
+# Default min-trust: 0.75
+#
+# Output: {eligible: N, promoted: N, already_in_queen: N, dry_run: bool}
+# ============================================================================
+_curation_herald() {
+    local min_trust="0.75"
+    local dry_run="false"
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --min-trust) min_trust="${2:-0.75}"; shift 2 ;;
+            --dry-run)   dry_run="true";         shift   ;;
+            *)           shift ;;
+        esac
+    done
+
+    local inst_file="$COLONY_DATA_DIR/instincts.json"
+
+    if [[ ! -f "$inst_file" ]]; then
+        json_ok "$(jq -n --argjson dry "$([ "$dry_run" == "true" ] && echo true || echo false)" \
+            '{eligible: 0, promoted: 0, already_in_queen: 0, dry_run: $dry}')"
+        return
+    fi
+
+    # Collect eligible instincts: active, trust_score >= min_trust
+    local eligible_instincts
+    eligible_instincts=$(jq -c \
+        --argjson min "$min_trust" \
+        '[.instincts[] | select(.archived == false and .trust_score >= $min)]' \
+        "$inst_file" 2>/dev/null || echo "[]")
+
+    local eligible_count
+    eligible_count=$(echo "$eligible_instincts" | jq 'length')
+
+    local promoted=0
+    local already_in_queen=0
+
+    if [[ "$eligible_count" -gt 0 && "$dry_run" != "true" ]]; then
+        while IFS= read -r inst_json; do
+            local trigger action confidence domain
+            trigger=$(echo "$inst_json" | jq -r '.trigger // ""')
+            action=$(echo "$inst_json" | jq -r '.action // ""')
+            confidence=$(echo "$inst_json" | jq -r '.confidence // 0.75')
+            domain=$(echo "$inst_json" | jq -r '.domain // "workflow"')
+
+            [[ -z "$trigger" || -z "$action" ]] && continue
+
+            local promote_result
+            promote_result=$(_queen_promote_instinct "$trigger" "$action" "$confidence" "$domain" 2>/dev/null) || true
+
+            if echo "$promote_result" | jq -e '.ok == true' >/dev/null 2>&1; then
+                local was_promoted
+                was_promoted=$(echo "$promote_result" | jq -r '.result.promoted // false')
+                local reason
+                reason=$(echo "$promote_result" | jq -r '.result.reason // ""')
+
+                if [[ "$was_promoted" == "true" ]]; then
+                    promoted=$((promoted + 1))
+                elif [[ "$reason" == "duplicate" ]]; then
+                    already_in_queen=$((already_in_queen + 1))
+                fi
+            fi
+        done < <(echo "$eligible_instincts" | jq -c '.[]')
+    elif [[ "$eligible_count" -gt 0 && "$dry_run" == "true" ]]; then
+        # Dry run: count what would be promoted vs already present
+        local queen_file="${AETHER_ROOT:-}/.aether/QUEEN.md"
+        while IFS= read -r inst_json; do
+            local action
+            action=$(echo "$inst_json" | jq -r '.action // ""')
+            [[ -z "$action" ]] && continue
+
+            if [[ -f "$queen_file" ]] && grep -Fq -- "$action" "$queen_file" 2>/dev/null; then
+                already_in_queen=$((already_in_queen + 1))
+            else
+                promoted=$((promoted + 1))
+            fi
+        done < <(echo "$eligible_instincts" | jq -c '.[]')
+    fi
+
+    json_ok "$(jq -n \
+        --argjson eligible "$eligible_count" \
+        --argjson promoted "$promoted" \
+        --argjson already "$already_in_queen" \
+        --argjson dry "$([ "$dry_run" == "true" ] && echo true || echo false)" \
+        '{eligible: $eligible, promoted: $promoted, already_in_queen: $already, dry_run: $dry}')"
+}

package/.aether/utils/curation-ants/janitor.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+# Curation Janitor — Expired Event/Archive Pruning
+# Cleans up expired events and old archived instincts.
+#
+# Functions:
+#   _curation_janitor
+#
+# These functions are sourced by aether-utils.sh at startup.
+# All shared infrastructure (json_ok, json_err, atomic_write, COLONY_DATA_DIR,
+# DATA_DIR, error constants) is available when sourced.
+
+# ============================================================================
+# _curation_janitor
+# Remove expired events and prune stale data.
+# Usage: curation-janitor [--dry-run] [--max-age-days <N>]
+#
+# Default max-age-days: 90
+# Output: json_ok with {events_removed:N, instincts_pruned:N,
+#                       observations_pruned:N, dry_run:bool}
+# ============================================================================
+_curation_janitor() {
+    local cj_dry_run="false"
+    local cj_max_age_days=90
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --dry-run)
+                cj_dry_run="true"
+                shift
+                ;;
+            --max-age-days)
+                cj_max_age_days="${2:-90}"
+                shift 2
+                ;;
+            *)
+                shift
+                ;;
+        esac
+    done
+
+    local cj_data_dir="${COLONY_DATA_DIR:-${DATA_DIR:-}}"
+    if [[ -z "$cj_data_dir" ]]; then
+        json_err "$E_VALIDATION_FAILED" "curation-janitor: COLONY_DATA_DIR is not set"
+    fi
+
+    # Step 1: Clean expired events via event-cleanup subcommand
+    local cj_events_removed=0
+    local cj_cleanup_dry_run_flag=""
+    [[ "$cj_dry_run" == "true" ]] && cj_cleanup_dry_run_flag="--dry-run"
+
+    local cj_cleanup_result
+    if [[ -n "$cj_cleanup_dry_run_flag" ]]; then
+        cj_cleanup_result=$(COLONY_DATA_DIR="$cj_data_dir" DATA_DIR="$cj_data_dir" \
+            bash "$0" event-cleanup "$cj_cleanup_dry_run_flag" 2>/dev/null) || true
+    else
+        cj_cleanup_result=$(COLONY_DATA_DIR="$cj_data_dir" DATA_DIR="$cj_data_dir" \
+            bash "$0" event-cleanup 2>/dev/null) || true
+    fi
+    if echo "$cj_cleanup_result" | jq -e '.ok == true' >/dev/null 2>&1; then
+        cj_events_removed=$(echo "$cj_cleanup_result" | jq '.result.removed // 0' 2>/dev/null || echo 0)
+    fi
+
+    # Step 2: Prune archived instincts older than max-age-days
+    local cj_instincts_pruned=0
+    local cj_instincts_file="$cj_data_dir/instincts.json"
+
+    if [[ -f "$cj_instincts_file" ]] && jq empty "$cj_instincts_file" 2>/dev/null; then
+        local cj_cutoff
+        cj_cutoff=$(date -u -v"-${cj_max_age_days}d" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+            || date -u -d "-${cj_max_age_days} days" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+            || echo "1970-01-01T00:00:00Z")
+
+        cj_instincts_pruned=$(jq --arg cutoff "$cj_cutoff" \
+            '[.instincts[] | select(.archived == true and (.updated_at // .created_at) < $cutoff)] | length' \
+            "$cj_instincts_file" 2>/dev/null || echo 0)
+
+        if [[ "$cj_dry_run" == "false" && "$cj_instincts_pruned" -gt 0 ]]; then
+            local cj_updated_instincts
+            cj_updated_instincts=$(jq --arg cutoff "$cj_cutoff" \
+                '.instincts |= [.[] | select(not (.archived == true and (.updated_at // .created_at) < $cutoff))]' \
+                "$cj_instincts_file" 2>/dev/null)
+            if [[ -n "$cj_updated_instincts" ]]; then
+                atomic_write "$cj_instincts_file" "$cj_updated_instincts" 2>/dev/null || true
+            fi
+        fi
+    fi
+
+    # Step 3: Prune stale learning-observations (observation_count=1, older than 90 days)
+    local cj_observations_pruned=0
+    local cj_obs_file="$cj_data_dir/learning-observations.json"
+    local cj_obs_cutoff_days=90
+
+    if [[ -f "$cj_obs_file" ]] && jq empty "$cj_obs_file" 2>/dev/null; then
+        local cj_obs_cutoff
+        cj_obs_cutoff=$(date -u -v"-${cj_obs_cutoff_days}d" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+            || date -u -d "-${cj_obs_cutoff_days} days" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+            || echo "1970-01-01T00:00:00Z")
+
+        cj_observations_pruned=$(jq --arg cutoff "$cj_obs_cutoff" \
+            '[.observations[] | select((.observation_count // 0) == 1 and (.last_observed // .observed_at // "") < $cutoff)] | length' \
+            "$cj_obs_file" 2>/dev/null || echo 0)
+
+        if [[ "$cj_dry_run" == "false" && "$cj_observations_pruned" -gt 0 ]]; then
+            local cj_updated_obs
+            cj_updated_obs=$(jq --arg cutoff "$cj_obs_cutoff" \
+                '.observations |= [.[] | select(not ((.observation_count // 0) == 1 and (.last_observed // .observed_at // "") < $cutoff))]' \
+                "$cj_obs_file" 2>/dev/null)
+            if [[ -n "$cj_updated_obs" ]]; then
+                atomic_write "$cj_obs_file" "$cj_updated_obs" 2>/dev/null || true
+            fi
+        fi
+    fi
+
+    json_ok "$(jq -nc \
+        --argjson events_removed "$cj_events_removed" \
+        --argjson instincts_pruned "$cj_instincts_pruned" \
+        --argjson observations_pruned "$cj_observations_pruned" \
+        --argjson dry_run "$cj_dry_run" \
+        '{events_removed:$events_removed, instincts_pruned:$instincts_pruned,
+          observations_pruned:$observations_pruned, dry_run:$dry_run}')"
+}