aether-colony 3.1.5 → 3.1.16

package/runtime/lib/queen-utils.sh

@@ -0,0 +1,729 @@
+#!/bin/bash
+# Queen Utilities — QUEEN.md management for Aether colonies
+#
+# Usage: source this file or run functions directly
+# All functions output JSON for composability
+
+set -euo pipefail
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AETHER_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd 2>/dev/null || echo "$SCRIPT_DIR")"
+RUNTIME_DIR="$AETHER_ROOT/runtime"
+GLOBAL_QUEEN="${HOME}/.aether/QUEEN.md"
+
+# Ensure directories exist
+mkdir -p "${HOME}/.aether" 2>/dev/null || true
+
+# --- JSON helpers ---
+json_ok() { printf '{"ok":true,"result":%s}\n' "$1"; }
+json_err() { printf '{"ok":false,"error":"%s"}\n' "$1" >&2; return 1; }
+json_warn() { printf '{"ok":true,"warning":"%s"}\n' "$1"; }
+
+# --- Template path ---
+get_template_path() {
+  echo "$RUNTIME_DIR/templates/QUEEN.md.template"
+}
+
+# --- queen_init_global ---
+# Initialize global QUEEN.md at ~/.aether/QUEEN.md
+# Usage: queen_init_global
+# Returns: JSON with path and status
+queen_init_global() {
+  local template_path
+  template_path=$(get_template_path)
+
+  if [[ ! -f "$template_path" ]]; then
+    json_err "Template not found: $template_path"
+    return 1
+  fi
+
+  # If already exists, don't overwrite
+  if [[ -f "$GLOBAL_QUEEN" ]]; then
+    local version
+    version=$(queen_get_version "$GLOBAL_QUEEN" 2>/dev/null || echo "unknown")
+    json_ok "{\"initialized\":false,\"path\":\"$GLOBAL_QUEEN\",\"version\":\"$version\",\"reason\":\"already_exists\"}"
+    return 0
+  fi
+
+  # Create from template with current timestamp
+  local timestamp
+  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Replace {TIMESTAMP} placeholders
+  sed -e "s/{TIMESTAMP}/$timestamp/g" "$template_path" > "$GLOBAL_QUEEN"
+
+  json_ok "{\"initialized\":true,\"path\":\"$GLOBAL_QUEEN\",\"version\":\"1.0.0\"}"
+}
+
+# --- queen_init_local ---
+# Initialize local QUEEN.md at repo/.aether/QUEEN.md
+# Usage: queen_init_local [repo_path]
+# Returns: JSON with path and status
+queen_init_local() {
+  local repo_path="${1:-$(pwd)}"
+  local local_queen="$repo_path/.aether/QUEEN.md"
+  local template_path
+  template_path=$(get_template_path)
+
+  if [[ ! -f "$template_path" ]]; then
+    json_err "Template not found: $template_path"
+    return 1
+  fi
+
+  # Create .aether directory if needed
+  mkdir -p "$repo_path/.aether" 2>/dev/null || true
+
+  # If already exists, don't overwrite
+  if [[ -f "$local_queen" ]]; then
+    local version
+    version=$(queen_get_version "$local_queen" 2>/dev/null || echo "unknown")
+    json_ok "{\"initialized\":false,\"path\":\"$local_queen\",\"version\":\"$version\",\"reason\":\"already_exists\"}"
+    return 0
+  fi
+
+  # Create from template with current timestamp
+  local timestamp
+  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Replace {TIMESTAMP} placeholders
+  sed -e "s/{TIMESTAMP}/$timestamp/g" "$template_path" > "$local_queen"
+
+  json_ok "{\"initialized\":true,\"path\":\"$local_queen\",\"version\":\"1.0.0\"}"
+}
+
+# --- queen_parse_metadata ---
+# Extract JSON metadata block from QUEEN.md
+# Usage: queen_parse_metadata [queen_md_path]
+# Returns: JSON metadata object
+queen_parse_metadata() {
+  local queen_path="${1:-$GLOBAL_QUEEN}"
+
+  if [[ ! -f "$queen_path" ]]; then
+    json_err "QUEEN.md not found: $queen_path"
+    return 1
+  fi
+
+  # Extract content between <!-- METADATA and -->
+  local metadata
+  metadata=$(sed -n '/<!-- METADATA/,/-->/p' "$queen_path" | grep -v '<!--' | grep -v '-->')
+
+  if [[ -z "$metadata" ]]; then
+    json_err "No metadata block found in $queen_path"
+    return 1
+  fi
+
+  # Validate JSON
+  if ! echo "$metadata" | jq '.' >/dev/null 2>&1; then
+    json_err "Invalid JSON in metadata block"
+    return 1
+  fi
+
+  echo "$metadata"
+}
+
+# --- queen_get_version ---
+# Get the semantic version from QUEEN.md metadata
+# Usage: queen_get_version [queen_md_path]
+# Returns: version string
+queen_get_version() {
+  local queen_path="${1:-$GLOBAL_QUEEN}"
+
+  if [[ ! -f "$queen_path" ]]; then
+    json_err "QUEEN.md not found: $queen_path"
+    return 1
+  fi
+
+  local metadata
+  metadata=$(queen_parse_metadata "$queen_path" 2>/dev/null) || {
+    echo "0.0.0"
+    return 0
+  }
+
+  echo "$metadata" | jq -r '.version // "0.0.0"'
+}
+
+# --- queen_increment_version ---
+# Increment the patch version in QUEEN.md
+# Usage: queen_increment_version [queen_md_path] [component: patch|minor|major]
+# Returns: JSON with old and new version
+queen_increment_version() {
+  local queen_path="${1:-$GLOBAL_QUEEN}"
+  local component="${2:-patch}"
+
+  if [[ ! -f "$queen_path" ]]; then
+    json_err "QUEEN.md not found: $queen_path"
+    return 1
+  fi
+
+  local old_version
+  old_version=$(queen_get_version "$queen_path")
+
+  # Parse version components
+  local major minor patch
+  major=$(echo "$old_version" | cut -d. -f1)
+  minor=$(echo "$old_version" | cut -d. -f2)
+  patch=$(echo "$old_version" | cut -d. -f3)
+
+  # Increment appropriate component
+  case "$component" in
+    major)
+      major=$((major + 1))
+      minor=0
+      patch=0
+      ;;
+    minor)
+      minor=$((minor + 1))
+      patch=0
+      ;;
+    patch|*)
+      patch=$((patch + 1))
+      ;;
+  esac
+
+  local new_version="${major}.${minor}.${patch}"
+
+  # Update version in metadata block
+  local temp_file
+  temp_file=$(mktemp)
+
+  # Use jq to update the JSON inside the markdown
+  local metadata new_metadata
+  metadata=$(queen_parse_metadata "$queen_path")
+  new_metadata=$(echo "$metadata" | jq --arg v "$new_version" --arg ts "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" '
+    .version = $v | .last_evolved = $ts
+  ')
+
+  # Replace metadata block in file
+  awk -v new_metadata="$new_metadata" '
+    /<!-- METADATA/ { print; print new_metadata; in_metadata=1; next }
+    /-->/ && in_metadata { print; in_metadata=0; next }
+    in_metadata { next }
+    { print }
+  ' "$queen_path" > "$temp_file"
+
+  mv "$temp_file" "$queen_path"
+
+  # Update header line too
+  sed -i.bak "s/^> Wisdom version: .*/> Wisdom version: $new_version/" "$queen_path" && rm -f "$queen_path.bak"
+
+  json_ok "{\"old_version\":\"$old_version\",\"new_version\":\"$new_version\",\"component\":\"$component\"}"
+}
+
+# --- queen_merge_global_local ---
+# Merge global and local QUEEN.md content
+# Usage: queen_merge_global_local [repo_path]
+# Returns: JSON with merged content summary
+queen_merge_global_local() {
+  local repo_path="${1:-$(pwd)}"
+  local local_queen="$repo_path/.aether/QUEEN.md"
+
+  # Ensure global exists
+  if [[ ! -f "$GLOBAL_QUEEN" ]]; then
+    queen_init_global >/dev/null 2>&1 || true
+  fi
+
+  # If no local, just use global
+  if [[ ! -f "$local_queen" ]]; then
+    json_ok "{\"source\":\"global_only\",\"global_path\":\"$GLOBAL_QUEEN\",\"has_local\":false}"
+    return 0
+  fi
+
+  # Both exist - count entries
+  local global_stats local_stats
+  global_stats=$(queen_parse_metadata "$GLOBAL_QUEEN" | jq '{
+    philosophies: .stats.total_philosophies,
+    patterns: .stats.total_patterns,
+    redirects: .stats.total_redirects
+  }' 2>/dev/null || echo '{}')
+
+  local_stats=$(queen_parse_metadata "$local_queen" | jq '{
+    philosophies: .stats.total_philosophies,
+    patterns: .stats.total_patterns,
+    redirects: .stats.total_redirects
+  }' 2>/dev/null || echo '{}')
+
+  json_ok "{
+    \"source\":\"merged\",
+    \"global_path\":\"$GLOBAL_QUEEN\",
+    \"local_path\":\"$local_queen\",
+    \"has_local\":true,
+    \"global_stats\":$global_stats,
+    \"local_stats\":$local_stats
+  }"
+}
+
+# --- queen_ensure_both ---
+# Ensure both global and local QUEEN.md exist
+# Usage: queen_ensure_both [repo_path]
+# Returns: JSON with paths
+queen_ensure_both() {
+  local repo_path="${1:-$(pwd)}"
+
+  local global_result local_result
+  global_result=$(queen_init_global)
+  local_result=$(queen_init_local "$repo_path")
+
+  json_ok "{
+    \"global\":$global_result,
+    \"local\":$local_result
+  }"
+}
+
+# --- queen_get_stats ---
+# Get statistics from QUEEN.md
+# Usage: queen_get_stats [queen_md_path]
+# Returns: JSON with counts
+queen_get_stats() {
+  local queen_path="${1:-$GLOBAL_QUEEN}"
+
+  if [[ ! -f "$queen_path" ]]; then
+    json_err "QUEEN.md not found: $queen_path"
+    return 1
+  fi
+
+  local metadata
+  metadata=$(queen_parse_metadata "$queen_path" 2>/dev/null) || {
+    json_ok '{"total_philosophies":0,"total_patterns":0,"total_redirects":0,"total_stack_entries":0,"total_decrees":0}'
+    return 0
+  }
+
+  echo "$metadata" | jq '.stats // {
+    "total_philosophies": 0,
+    "total_patterns": 0,
+    "total_redirects": 0,
+    "total_stack_entries": 0,
+    "total_decrees": 0
+  }'
+}
+
+# --- queen_promote_instincts ---
+# Promote validated instincts from COLONY_STATE.json to QUEEN.md patterns
+# Usage: queen_promote_instincts <queen_md_path> <colony_state_path>
+# Returns: JSON with count of promoted instincts
+queen_promote_instincts() {
+  local queen_md_path="$1"
+  local colony_state_path="$2"
+
+  # Validate inputs
+  if [[ -z "$queen_md_path" || -z "$colony_state_path" ]]; then
+    json_err "Usage: queen_promote_instincts <queen_md_path> <colony_state_path>"
+    return 1
+  fi
+
+  if [[ ! -f "$queen_md_path" ]]; then
+    json_err "QUEEN.md not found: $queen_md_path"
+    return 1
+  fi
+
+  if [[ ! -f "$colony_state_path" ]]; then
+    json_err "COLONY_STATE.json not found: $colony_state_path"
+    return 1
+  fi
+
+  # Extract validated instincts with confidence >= 0.8
+  local instincts_json
+  instincts_json=$(jq -r '
+    .memory.instincts // [] |
+    map(select(.confidence >= 0.8 and .status == "validated")) |
+    map({id, trigger, action, confidence, domain, evidence})
+  ' "$colony_state_path" 2>/dev/null) || {
+    json_err "Failed to parse COLONY_STATE.json"
+    return 1
+  }
+
+  # Count instincts to promote
+  local instinct_count
+  instinct_count=$(echo "$instincts_json" | jq 'length')
+
+  if [[ "$instinct_count" -eq 0 ]]; then
+    json_ok '{"promoted":0,"duplicates_skipped":0,"queen_md_path":"'"$queen_md_path"'","reason":"no_eligible_instincts"}'
+    return 0
+  fi
+
+  # Get existing patterns from QUEEN.md to check for duplicates
+  # Extract trigger+action combinations already in patterns section
+  local existing_patterns
+  existing_patterns=$(sed -n '/## 🧭 Patterns/,/## ⚠️ Redirects/p' "$queen_md_path" | \
+    grep -E '^\*\*Trigger:\*\*' | \
+    sed 's/^\*\*Trigger:\*\* //' | \
+    tr '\n' '|')
+
+  local promoted=0
+  local duplicates_skipped=0
+  local timestamp
+  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Process each instinct
+  local i
+  for ((i=0; i<instinct_count; i++)); do
+    local instinct trigger action domain evidence
+    instinct=$(echo "$instincts_json" | jq -r ".[$i]")
+    trigger=$(echo "$instinct" | jq -r '.trigger')
+    action=$(echo "$instinct" | jq -r '.action')
+    domain=$(echo "$instinct" | jq -r '.domain // "general"')
+    evidence=$(echo "$instinct" | jq -r '.evidence | if type == "array" then join("; ") else . end')
+
+    # Check for duplicate (trigger+action combination)
+    local pattern_key="${trigger}${action}"
+    if echo "$existing_patterns" | grep -qF "$trigger" 2>/dev/null; then
+      # Additional check: verify action also matches
+      local existing_action
+      existing_action=$(sed -n '/## 🧭 Patterns/,/## ⚠️ Redirects/p' "$queen_md_path" | \
+        grep -A1 "\\*\\*Trigger:\\*\\* ${trigger}$" | \
+        grep "\\*\\*Action:\\*\\*" | \
+        sed 's/^.*\\*\\*Action:\\*\\* //' | head -1)
+      if [[ "$existing_action" == "$action" ]]; then
+        duplicates_skipped=$((duplicates_skipped + 1))
+        continue
+      fi
+    fi
+
+    # Format the pattern entry
+    local pattern_entry="
+**Trigger:** ${trigger}
+**Action:** ${action}
+**Domain:** ${domain}
+**Evidence:** ${evidence}
+*Promoted: ${timestamp}*
+"
+
+    # Insert before the "*No patterns recorded yet*" line or at end of patterns section
+    local temp_file
+    temp_file=$(mktemp)
+
+    if grep -q "\\*No patterns recorded yet\\*" "$queen_md_path"; then
+      # Replace the placeholder with the pattern
+      awk -v entry="$pattern_entry" '
+        /## 🧭 Patterns/ { in_patterns=1 }
+        in_patterns && /\*No patterns recorded yet\*/ {
+          print entry
+          in_patterns=0
+          next
+        }
+        { print }
+      ' "$queen_md_path" > "$temp_file"
+    else
+      # Insert before the next section header
+      awk -v entry="$pattern_entry" '
+        /## 🧭 Patterns/ { in_patterns=1 }
+        in_patterns && /^## / && !/## 🧭 Patterns/ {
+          print entry
+          in_patterns=0
+        }
+        { print }
+      ' "$queen_md_path" > "$temp_file"
+    fi
+
+    mv "$temp_file" "$queen_md_path"
+    promoted=$((promoted + 1))
+  done
+
+  # Update stats in metadata if any were promoted
+  if [[ "$promoted" -gt 0 ]]; then
+    local current_stats new_stats
+    current_stats=$(queen_get_stats "$queen_md_path")
+    local current_patterns
+    current_patterns=$(echo "$current_stats" | jq -r '.total_patterns // 0')
+    local new_pattern_count=$((current_patterns + promoted))
+
+    # Update the metadata block
+    local temp_file
+    temp_file=$(mktemp)
+    local metadata new_metadata
+    metadata=$(queen_parse_metadata "$queen_md_path")
+    new_metadata=$(echo "$metadata" | jq --argjson count "$new_pattern_count" --arg ts "$timestamp" '
+      .stats.total_patterns = $count | .last_evolved = $ts
+    ')
+
+    awk -v new_metadata="$new_metadata" '
+      /<!-- METADATA/ { print; print new_metadata; in_metadata=1; next }
+      /-->/ && in_metadata { print; in_metadata=0; next }
+      in_metadata { next }
+      { print }
+    ' "$queen_md_path" > "$temp_file"
+
+    mv "$temp_file" "$queen_md_path"
+  fi
+
+  json_ok "{
+    \"promoted\": $promoted,
+    \"duplicates_skipped\": $duplicates_skipped,
+    \"queen_md_path\": \"$queen_md_path\",
+    \"colony_state_path\": \"$colony_state_path\"
+  }"
+}
+
+# --- queen_promote_learnings ---
+# Promote validated phase learnings from COLONY_STATE.json to QUEEN.md patterns
+# Usage: queen_promote_learnings <queen_md_path> <colony_state_path>
+# Returns: JSON with count of promoted learnings
+queen_promote_learnings() {
+  local queen_md_path="$1"
+  local colony_state_path="$2"
+
+  # Validate inputs
+  if [[ -z "$queen_md_path" || -z "$colony_state_path" ]]; then
+    json_err "Usage: queen_promote_learnings <queen_md_path> <colony_state_path>"
+    return 1
+  fi
+
+  if [[ ! -f "$queen_md_path" ]]; then
+    json_err "QUEEN.md not found: $queen_md_path"
+    return 1
+  fi
+
+  if [[ ! -f "$colony_state_path" ]]; then
+    json_err "COLONY_STATE.json not found: $colony_state_path"
+    return 1
+  fi
+
+  # Extract validated and tested learnings from phase_learnings
+  # Learnings are nested under memory.phase_learnings[].learnings[]
+  local learnings_json
+  learnings_json=$(jq -r '
+    .memory.phase_learnings // [] |
+    map(.learnings // [] | map(select(.status == "validated" and .tested == true))) |
+    flatten |
+    map({claim, evidence, source})
+  ' "$colony_state_path" 2>/dev/null) || {
+    json_err "Failed to parse COLONY_STATE.json"
+    return 1
+  }
+
+  # Count learnings to promote
+  local learning_count
+  learning_count=$(echo "$learnings_json" | jq 'length')
+
+  if [[ "$learning_count" -eq 0 ]]; then
+    json_ok '{"promoted":0,"duplicates_skipped":0,"queen_md_path":"'"$queen_md_path"'","reason":"no_eligible_learnings"}'
+    return 0
+  fi
+
+  # Get existing patterns from QUEEN.md to check for duplicates
+  local existing_patterns
+  existing_patterns=$(sed -n '/## 🧭 Patterns/,/## ⚠️ Redirects/p' "$queen_md_path" | \
+    grep -E '^\*\*Pattern\*\*:|^- \*\*Pattern\*\*:' | \
+    sed 's/^\*\*Pattern\*\*: //; s/^- \*\*Pattern\*\*: //' | \
+    cut -d'(' -f1 | \
+    tr '\n' '|')
+
+  local promoted=0
+  local duplicates_skipped=0
+  local timestamp
+  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Process each learning
+  local i
+  for ((i=0; i<learning_count; i++)); do
+    local learning claim evidence source
+    learning=$(echo "$learnings_json" | jq -r ".[$i]")
+    claim=$(echo "$learning" | jq -r '.claim // empty')
+    evidence=$(echo "$learning" | jq -r '.evidence // "Validated in colony session"')
+    source=$(echo "$learning" | jq -r '.source // "unknown"')
+
+    if [[ -z "$claim" ]]; then
+      continue
+    fi
+
+    # Check for duplicate (claim already exists)
+    local claim_prefix
+    claim_prefix=$(echo "$claim" | cut -c1-50)
+    if echo "$existing_patterns" | grep -qF "$claim_prefix" 2>/dev/null; then
+      duplicates_skipped=$((duplicates_skipped + 1))
+      continue
+    fi
+
+    # Format the pattern entry with source attribution
+    local pattern_entry="
+**Pattern**: ${claim} (validated in colony: ${source})
+**Evidence**: ${evidence}
+*Promoted: ${timestamp}*
+"
+
+    # Insert into QUEEN.md patterns section
+    local temp_file
+    temp_file=$(mktemp)
+
+    if grep -q "\\*No patterns recorded yet\\*" "$queen_md_path"; then
+      # Replace the placeholder with the pattern
+      awk -v entry="$pattern_entry" '
+        /## 🧭 Patterns/ { in_patterns=1 }
+        in_patterns && /\*No patterns recorded yet\*/ {
+          print entry
+          in_patterns=0
+          next
+        }
+        { print }
+      ' "$queen_md_path" > "$temp_file"
+    else
+      # Insert before the next section header
+      awk -v entry="$pattern_entry" '
+        /## 🧭 Patterns/ { in_patterns=1 }
+        in_patterns && /^## / && !/## 🧭 Patterns/ {
+          print entry
+          in_patterns=0
+        }
+        { print }
+      ' "$queen_md_path" > "$temp_file"
+    fi
+
+    mv "$temp_file" "$queen_md_path"
+    promoted=$((promoted + 1))
+  done
+
+  # Update stats in metadata if any were promoted
+  if [[ "$promoted" -gt 0 ]]; then
+    local current_stats current_patterns new_pattern_count
+    current_stats=$(queen_get_stats "$queen_md_path")
+    current_patterns=$(echo "$current_stats" | jq -r '.total_patterns // 0')
+    new_pattern_count=$((current_patterns + promoted))
+
+    # Update the metadata block
+    local temp_file metadata new_metadata
+    temp_file=$(mktemp)
+    metadata=$(queen_parse_metadata "$queen_md_path")
+    new_metadata=$(echo "$metadata" | jq --argjson count "$new_pattern_count" --arg ts "$timestamp" '
+      .stats.total_patterns = $count | .last_evolved = $ts
+    ')
+
+    awk -v new_metadata="$new_metadata" '
+      /<!-- METADATA/ { print; print new_metadata; in_metadata=1; next }
+      /-->/ && in_metadata { print; in_metadata=0; next }
+      in_metadata { next }
+      { print }
+    ' "$queen_md_path" > "$temp_file"
+
+    mv "$temp_file" "$queen_md_path"
+  fi
+
+  json_ok "{
+    \"promoted\": $promoted,
+    \"duplicates_skipped\": $duplicates_skipped,
+    \"queen_md_path\": \"$queen_md_path\",
+    \"colony_state_path\": \"$colony_state_path\"
+  }"
+}
+
+# --- queen_promote_all ---
+# Promote all validated pheromones (instincts + learnings) from COLONY_STATE.json to QUEEN.md
+# Usage: queen_promote_all <queen_md_path> <colony_state_path>
+# Returns: JSON with combined promotion results
+queen_promote_all() {
+  local queen_md_path="$1"
+  local colony_state_path="$2"
+
+  # Validate inputs
+  if [[ -z "$queen_md_path" || -z "$colony_state_path" ]]; then
+    json_err "Usage: queen_promote_all <queen_md_path> <colony_state_path>"
+    return 1
+  fi
+
+  if [[ ! -f "$queen_md_path" ]]; then
+    json_err "QUEEN.md not found: $queen_md_path"
+    return 1
+  fi
+
+  if [[ ! -f "$colony_state_path" ]]; then
+    json_err "COLONY_STATE.json not found: $colony_state_path"
+    return 1
+  fi
+
+  local instincts_result learnings_result
+  local instincts_promoted=0
+  local learnings_promoted=0
+  local instincts_error=""
+  local learnings_error=""
+
+  # Promote instincts (with error handling)
+  if instincts_result=$(queen_promote_instincts "$queen_md_path" "$colony_state_path" 2>&1); then
+    instincts_promoted=$(echo "$instincts_result" | jq -r '.promoted // 0')
+  else
+    instincts_error=$(echo "$instincts_result" | jq -r '.error // "unknown error"' 2>/dev/null || echo "failed to promote instincts")
+  fi
+
+  # Promote learnings (with error handling - continues even if instincts failed)
+  if learnings_result=$(queen_promote_learnings "$queen_md_path" "$colony_state_path" 2>&1); then
+    learnings_promoted=$(echo "$learnings_result" | jq -r '.promoted // 0')
+  else
+    learnings_error=$(echo "$learnings_result" | jq -r '.error // "unknown error"' 2>/dev/null || echo "failed to promote learnings")
+  fi
+
+  local total=$((instincts_promoted + learnings_promoted))
+
+  # Build result JSON
+  local result_json
+  result_json=$(jq -n \
+    --argjson instincts "$instincts_promoted" \
+    --argjson learnings "$learnings_promoted" \
+    --argjson total "$total" \
+    --arg queen_md "$queen_md_path" \
+    --arg colony_state "$colony_state_path" \
+    --arg instincts_err "$instincts_error" \
+    --arg learnings_err "$learnings_error" \
+    '{
+      instincts_promoted: $instincts,
+      learnings_promoted: $learnings,
+      total: $total,
+      queen_md_path: $queen_md,
+      colony_state_path: $colony_state,
+      errors: {
+        instincts: (if $instincts_err == "" then null else $instincts_err end),
+        learnings: (if $learnings_err == "" then null else $learnings_err end)
+      }
+    }')
+
+  json_ok "$result_json"
+}
+
+# --- Main entry point for command-line usage ---
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  cmd="${1:-help}"
+  shift 2>/dev/null || true
+
+  case "$cmd" in
+    init-global)
+      queen_init_global
+      ;;
+    init-local)
+      queen_init_local "${1:-$(pwd)}"
+      ;;
+    ensure-both)
+      queen_ensure_both "${1:-$(pwd)}"
+      ;;
+    parse-metadata)
+      queen_parse_metadata "${1:-$GLOBAL_QUEEN}"
+      ;;
+    get-version)
+      result=$(queen_get_version "${1:-$GLOBAL_QUEEN}")
+      json_ok "\"$result\""
+      ;;
+    increment-version)
+      queen_increment_version "${1:-$GLOBAL_QUEEN}" "${2:-patch}"
+      ;;
+    merge)
+      queen_merge_global_local "${1:-$(pwd)}"
+      ;;
+    stats)
+      queen_get_stats "${1:-$GLOBAL_QUEEN}"
+      ;;
+    promote-instincts)
+      queen_promote_instincts "${1:-}" "${2:-}"
+      ;;
+    promote-learnings)
+      queen_promote_learnings "${1:-}" "${2:-}"
+      ;;
+    promote-all)
+      queen_promote_all "${1:-}" "${2:-}"
+      ;;
+    help|*)
+      cat <<'EOF'
+{"ok":true,"commands":[
+  "init-global","init-local","ensure-both",
+  "parse-metadata","get-version","increment-version",
+  "merge","stats","promote-instincts","promote-learnings","promote-all"
+],"description":"Queen Utilities — QUEEN.md management for Aether colonies"}
+EOF
+      ;;
+  esac
+fi