aether-colony 1.1.0

package/.aether/templates/colony-state-reset.jq.template

@@ -0,0 +1,22 @@
+# colony-state-reset.jq.template — Reset colony state fields for entomb
+# Usage: jq -f .aether/templates/colony-state-reset.jq.template STATE.json.bak > STATE.json
+# Version: 1.0
+
+.goal = null |
+.state = "IDLE" |
+.current_phase = 0 |
+.plan.phases = [] |
+.plan.generated_at = null |
+.plan.confidence = null |
+.build_started_at = null |
+.session_id = null |
+.initialized_at = null |
+.milestone = null |
+.events = [] |
+.errors.records = [] |
+.errors.flagged_patterns = [] |
+.signals = [] |
+.graveyards = [] |
+.memory.instincts = [] |
+.memory.phase_learnings = [] |
+.memory.decisions = []

package/.aether/templates/colony-state.template.json

@@ -0,0 +1,35 @@
+{
+  "_template": "colony-state",
+  "_version": "3.0",
+  "_instructions": "Write this file to .aether/data/COLONY_STATE.json. Replace every __PLACEHOLDER__ value with real data (see _comment_* fields for details). After filling all placeholders, remove every key whose name starts with underscore (_template, _version, _instructions, and all _comment_*) before writing the final file.",
+  "_comment_goal": "Replace __GOAL__ with the user's goal string exactly as provided to /ant:init.",
+  "_comment_session": "Replace __SESSION_ID__ with a generated ID in the format: session_{unix_timestamp}_{random}. Replace __ISO8601_TIMESTAMP__ with the current UTC time in ISO-8601 format (e.g., 2026-02-20T00:00:00Z). The same timestamp value is used in both 'initialized_at' and the events array entry.",
+  "_comment_memory": "Replace __PHASE_LEARNINGS__ with a JSON array (e.g., [] if no prior colony found, or [{...}, ...] if inherited from completion-report.md). Replace __INSTINCTS__ with a JSON array (e.g., [] or [{...}, ...]). IMPORTANT: both must be JSON arrays, not strings — write [] not \"[]\".",
+  "_comment_events": "The events array records colony lifecycle events. Each entry is a pipe-delimited string: 'ISO8601_TIMESTAMP|event_type|source|description'. The initialization event uses the same __ISO8601_TIMESTAMP__ as 'initialized_at'. Do not add extra events during init — the single initialization entry is correct.",
+  "version": "3.0",
+  "goal": "__GOAL__",
+  "state": "READY",
+  "current_phase": 0,
+  "session_id": "__SESSION_ID__",
+  "initialized_at": "__ISO8601_TIMESTAMP__",
+  "build_started_at": null,
+  "plan": {
+    "generated_at": null,
+    "confidence": null,
+    "phases": []
+  },
+  "memory": {
+    "phase_learnings": "__PHASE_LEARNINGS__",
+    "decisions": [],
+    "instincts": "__INSTINCTS__"
+  },
+  "errors": {
+    "records": [],
+    "flagged_patterns": []
+  },
+  "signals": [],
+  "graveyards": [],
+  "events": [
+    "__ISO8601_TIMESTAMP__|colony_initialized|init|Colony initialized with goal: __GOAL__"
+  ]
+}

package/.aether/templates/constraints.template.json

@@ -0,0 +1,9 @@
+{
+  "_template": "constraints",
+  "_version": "1.0",
+  "_instructions": "Write this file to .aether/data/constraints.json. No placeholder substitution needed — copy the data keys as-is. Remove all keys whose names start with underscore (_template, _version, _instructions, _comment_*) before writing the final file.",
+  "_comment_purpose": "constraints.json stores user pheromone signals. 'focus' holds FOCUS signals (areas of attention set via /ant:focus). 'constraints' holds REDIRECT signals (hard constraints set via /ant:redirect). Both start as empty arrays and accumulate signals over the colony's lifetime.",
+  "version": "1.0",
+  "focus": [],
+  "constraints": []
+}

package/.aether/templates/crowned-anthill.template.md

@@ -0,0 +1,36 @@
+<!-- Template: crowned-anthill | Version: 2.0 -->
+<!-- Instructions: Fill all {{PLACEHOLDER}} values with real colony data. Remove this comment block before writing to .aether/CROWNED-ANTHILL.md -->
+
+# Crowned Anthill — {{GOAL}}
+
+**Sealed:** {{SEAL_DATE}}
+**Milestone:** Crowned Anthill
+**Version:** {{VERSION}}
+
+## The Achievement
+
+This colony set out to accomplish something real — and it did. Every phase pushed the anthill higher. Now it stands crowned.
+
+## Colony Stats
+- Total Phases: {{TOTAL_PHASES}}
+- Phases Completed: {{PHASES_COMPLETED}} of {{TOTAL_PHASES}}
+- Colony Age: {{COLONY_AGE_DAYS}} days of focused work
+- Wisdom Promoted: {{PROMOTIONS_MADE}} entries carried forward
+
+## Phase Recap
+
+Every phase below is a chapter in the story of this anthill's rise:
+
+{{PHASE_RECAP}}
+
+## Pheromone Legacy
+
+The colony's hard-won wisdom doesn't stop here. {{PROMOTIONS_MADE}} validated learnings and instincts have been promoted to QUEEN.md — a living record that will guide future colonies before they take their first steps.
+
+What this colony learned, the next colony inherits.
+
+## The Work
+
+{{GOAL}}
+
+The anthill stands crowned. The work endures.

package/.aether/templates/handoff-build-error.template.md

@@ -0,0 +1,30 @@
+<!-- Template: handoff-build-error | Version: 1.0 -->
+<!-- Instructions: Fill all {{PLACEHOLDER}} values with real colony data. Remove this comment block before writing to .aether/HANDOFF.md -->
+
+# Colony Session — Build Errors
+
+## Build Status: ISSUES DETECTED
+
+**Phase:** {{PHASE_NUMBER}} — {{PHASE_NAME}}
+**Status:** Build completed with failures
+**Updated:** {{BUILD_TIMESTAMP}}
+
+## Failed Workers
+
+{{FAILED_WORKERS}}
+
+## Grave Markers Placed
+
+{{GRAVE_MARKERS}}
+
+## Recovery Options
+
+1. Review failures: Check `.aether/data/activity.log`
+2. Fix and retry: `/ant:build {{PHASE_NUMBER}}`
+3. Swarm fix: `/ant:swarm` for auto-repair
+4. Manual fix: Address issues, then `/ant:continue`
+
+## Session Note
+
+Build completed but workers failed. Grave markers placed.
+Review failures before advancing.

package/.aether/templates/handoff-build-success.template.md

@@ -0,0 +1,39 @@
+<!-- Template: handoff-build-success | Version: 1.0 -->
+<!-- Instructions: Fill all {{PLACEHOLDER}} values with real colony data. Remove this comment block before writing to .aether/HANDOFF.md -->
+
+# Colony Session — Build Complete
+
+## Quick Resume
+
+Run `/ant:continue` to advance phase, or `/ant:resume-colony` to restore full context.
+
+## State at Build Completion
+
+- Goal: "{{GOAL}}"
+- Phase: {{PHASE_NUMBER}} — {{PHASE_NAME}}
+- Build Status: {{BUILD_STATUS}}
+- Updated: {{BUILD_TIMESTAMP}}
+
+## Build Summary
+
+{{BUILD_SUMMARY}}
+
+## Tasks
+
+- Completed: {{TASKS_COMPLETED}}
+- Failed: {{TASKS_FAILED}}
+
+## Files Changed
+
+- Created: {{FILES_CREATED}} files
+- Modified: {{FILES_MODIFIED}} files
+
+## Next Steps
+
+- If verification passed: `/ant:continue` to advance to next phase
+- If issues found: `/ant:flags` to review blockers
+- To pause: `/ant:pause-colony`
+
+## Session Note
+
+{{SESSION_NOTE}}

package/.aether/templates/handoff.template.md

@@ -0,0 +1,40 @@
+<!-- Template: handoff | Version: 2.0 -->
+<!-- Instructions: Fill all {{PLACEHOLDER}} values with real colony data. Remove this comment block before writing to .aether/HANDOFF.md -->
+
+# Colony Session — {{CHAMBER_NAME}}
+
+## A Colony's Rest
+
+This colony has been entombed. Its work is complete, its story told.
+What began with a goal has ended with a chamber — a place of quiet preservation.
+
+**Chamber:** .aether/chambers/{{CHAMBER_NAME}}/
+
+## Colony Summary
+
+- Goal: "{{GOAL}}"
+- Phases: {{PHASES_COMPLETED}} completed of {{TOTAL_PHASES}}
+- Milestone reached: {{MILESTONE}}
+- Entombed at: {{ENTOMB_TIMESTAMP}}
+
+## Chamber Contents
+
+Everything the colony built and learned rests here now:
+
+- colony-state.json — Full colony state
+- manifest.json — Archive metadata
+- CROWNED-ANTHILL.md — Seal ceremony record
+- pheromones.json — Pheromone signals
+- activity.log — Colony activity history
+- spawn-tree.txt — Worker spawn records
+- dreams/ — Dream journal (if existed)
+
+## Session Note
+
+The active colony has been reset. The chambers hold what was.
+The learnings have been carried forward to QUEEN.md — the next colony won't start from nothing.
+
+When you are ready to begin again:
+
+To start anew: /ant:lay-eggs "<new goal>"
+To revisit what came before: /ant:tunnels

package/.aether/templates/learning-observations.template.json

@@ -0,0 +1,6 @@
+{
+  "_template": "learning-observations",
+  "_version": "1.0",
+  "_instructions": "Write to .aether/data/learning-observations.json. No substitution needed. Remove underscore-prefixed keys.",
+  "observations": []
+}

package/.aether/templates/midden.template.json

@@ -0,0 +1,7 @@
+{
+  "_template": "midden",
+  "_version": "1.0",
+  "_instructions": "Write to .aether/data/midden/midden.json. No substitution needed. Remove underscore-prefixed keys.",
+  "version": "1.0.0",
+  "signals": []
+}

package/.aether/templates/pheromones.template.json

@@ -0,0 +1,6 @@
+{
+  "_template": "pheromones",
+  "_version": "1.0",
+  "_instructions": "Write to .aether/data/pheromones.json. No substitution needed. Remove underscore-prefixed keys.",
+  "signals": []
+}

package/.aether/templates/session.template.json

@@ -0,0 +1,9 @@
+{
+  "_template": "session",
+  "_version": "1.0",
+  "_instructions": "Write to .aether/data/session.json. Replace __SESSION_ID__, __GOAL__, __TIMESTAMP__. Remove underscore-prefixed keys.",
+  "session_id": "__SESSION_ID__",
+  "colony_goal": "__GOAL__",
+  "started_at": "__TIMESTAMP__",
+  "last_activity": "__TIMESTAMP__"
+}

package/.aether/utils/atomic-write.sh

@@ -0,0 +1,219 @@
+#!/bin/bash
+# Aether Atomic Write Utility
+# Implements atomic write pattern (temp file + rename) for corruption safety
+#
+# Usage:
+#   source .aether/utils/atomic-write.sh
+#   atomic_write /path/to/file.json "content"
+#   atomic_write_from_file /path/to/target.json /path/to/temp.json
+
+# Source required utilities
+# Get the directory where this script is located
+_AETHER_UTILS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# If BASH_SOURCE[0] is empty (can happen in some contexts), use repo-local path
+if [ -z "$_AETHER_UTILS_DIR" ] || [ "$_AETHER_UTILS_DIR" = "$(pwd)" ]; then
+    if git rev-parse --show-toplevel >/dev/null 2>&1; then
+        _AETHER_UTILS_DIR="$(git rev-parse --show-toplevel)/.aether/utils"
+    else
+        _AETHER_UTILS_DIR="$PWD/.aether/utils"
+    fi
+fi
+# Verify the path exists and file-lock.sh is there
+if [ ! -f "$_AETHER_UTILS_DIR/file-lock.sh" ]; then
+    # Try one more fallback - relative to script location
+    _AETHER_UTILS_DIR="$(dirname "${BASH_SOURCE[0]}")"
+fi
+source "$_AETHER_UTILS_DIR/file-lock.sh"
+
+# Aether root detection - use git root if available, otherwise use current directory
+if git rev-parse --show-toplevel >/dev/null 2>&1; then
+    AETHER_ROOT="$(git rev-parse --show-toplevel)"
+else
+    AETHER_ROOT="$(pwd)"
+fi
+
+TEMP_DIR="$AETHER_ROOT/.aether/temp"
+BACKUP_DIR="$AETHER_ROOT/.aether/data/backups"
+
+# Create directories
+mkdir -p "$TEMP_DIR" "$BACKUP_DIR"
+
+# Number of backups to keep
+MAX_BACKUPS=3
+
+# Atomic write: write content to file via temporary file
+# Arguments: target_file, content
+# Returns: 0 on success, 1 on failure
+atomic_write() {
+    local target_file="$1"
+    local content="$2"
+
+    # Ensure target directory exists
+    local target_dir=$(dirname "$target_file")
+    mkdir -p "$target_dir"
+
+    # Create unique temp file
+    local temp_file="${TEMP_DIR}/$(basename "$target_file").$$.$(date +%s%N).tmp"
+
+    # Write content to temp file
+    if ! echo "$content" > "$temp_file"; then
+        echo "Failed to write to temp file: $temp_file"
+        rm -f "$temp_file"
+        return 1
+    fi
+
+    # Create backup if target exists (do this BEFORE validation to avoid race condition)
+    if [ -f "$target_file" ]; then
+        create_backup "$target_file"
+    fi
+
+    # Validate JSON if it's a JSON file
+    if [[ "$target_file" == *.json ]]; then
+        if ! python3 -c "import json; json.load(open('$temp_file'))" 2>/dev/null; then
+            echo "Invalid JSON in temp file: $temp_file"
+            rm -f "$temp_file"
+            return 1
+        fi
+    fi
+
+    # Atomic rename (overwrites target if exists)
+    if ! mv "$temp_file" "$target_file"; then
+        echo "Failed to rename temp file to target: $target_file"
+        rm -f "$temp_file"
+        return 1
+    fi
+
+    # Sync to disk
+    if command -v sync >/dev/null 2>&1; then
+        sync "$target_file" 2>/dev/null || true
+    fi
+
+    return 0
+}
+
+# Atomic write from source file to target
+# Arguments: target_file, source_file
+# Returns: 0 on success, 1 on failure
+atomic_write_from_file() {
+    local target_file="$1"
+    local source_file="$2"
+
+    if [ ! -f "$source_file" ]; then
+        echo "Source file does not exist: $source_file"
+        return 1
+    fi
+
+    # Ensure target directory exists
+    local target_dir=$(dirname "$target_file")
+    mkdir -p "$target_dir"
+
+    # Create unique temp file
+    local temp_file="${TEMP_DIR}/$(basename "$target_file").$$.$(date +%s%N).tmp"
+
+    # Copy source to temp
+    if ! cp "$source_file" "$temp_file"; then
+        echo "Failed to copy source to temp: $source_file -> $temp_file"
+        rm -f "$temp_file"
+        return 1
+    fi
+
+    # Create backup BEFORE validation (mirrors atomic_write ordering — LOCK-03)
+    if [ -f "$target_file" ]; then
+        create_backup "$target_file"
+    fi
+
+    # Validate JSON if it's a JSON file
+    if [[ "$target_file" == *.json ]]; then
+        if ! python3 -c "import json; json.load(open('$temp_file'))" 2>/dev/null; then
+            echo "Invalid JSON in temp file: $temp_file"
+            rm -f "$temp_file"
+            return 1
+        fi
+    fi
+
+    # Atomic rename
+    if ! mv "$temp_file" "$target_file"; then
+        echo "Failed to rename temp file to target: $target_file"
+        rm -f "$temp_file"
+        return 1
+    fi
+
+    # Sync to disk
+    if command -v sync >/dev/null 2>&1; then
+        sync "$target_file" 2>/dev/null || true
+    fi
+
+    return 0
+}
+
+# Create backup of file
+# Arguments: file_path
+create_backup() {
+    local file_path="$1"
+    local base_name=$(basename "$file_path")
+    local timestamp=$(date +%Y%m%d_%H%M%S)
+    local backup_file="${BACKUP_DIR}/${base_name}.${timestamp}.backup"
+
+    cp "$file_path" "$backup_file" 2>/dev/null || return 1
+
+    # Rotate old backups
+    rotate_backups "$base_name"
+
+    return 0
+}
+
+# Rotate backups, keeping only MAX_BACKUPS
+# Arguments: base_name
+rotate_backups() {
+    local base_name="$1"
+    local backups=$(ls -t "${BACKUP_DIR}/${base_name}".*.backup 2>/dev/null | wc -l)
+
+    if [ "$backups" -gt "$MAX_BACKUPS" ]; then
+        ls -t "${BACKUP_DIR}/${base_name}".*.backup 2>/dev/null \
+            | tail -n +$((MAX_BACKUPS + 1)) \
+            | while IFS= read -r file; do rm -f "$file"; done
+    fi
+}
+
+# Restore from backup
+# Arguments: target_file, [backup_number]
+# Returns: 0 on success, 1 on failure
+restore_backup() {
+    local target_file="$1"
+    local backup_num="${2:-1}"  # Default to most recent backup
+    local base_name=$(basename "$target_file")
+
+    local backup_file=$(ls -t "${BACKUP_DIR}/${base_name}".*.backup 2>/dev/null | sed -n "${backup_num}p")
+
+    if [ -z "$backup_file" ] || [ ! -f "$backup_file" ]; then
+        echo "No backup found for: $target_file"
+        return 1
+    fi
+
+    if ! atomic_write_from_file "$target_file" "$backup_file"; then
+        echo "Failed to restore from backup: $backup_file"
+        return 1
+    fi
+
+    echo "Restored from: $backup_file"
+    return 0
+}
+
+# List available backups
+# Arguments: file_path
+list_backups() {
+    local file_path="$1"
+    local base_name=$(basename "$file_path")
+
+    echo "Available backups for $base_name:"
+    ls -lh "${BACKUP_DIR}/${base_name}".*.backup 2>/dev/null || echo "No backups found"
+}
+
+# Cleanup temp files older than 1 hour
+cleanup_temp_files() {
+    find "$TEMP_DIR" -name "*.tmp" -mtime +1/24 -delete 2>/dev/null || true
+}
+
+# Export functions
+export -f atomic_write atomic_write_from_file create_backup rotate_backups
+export -f restore_backup list_backups cleanup_temp_files

package/.aether/utils/chamber-compare.sh

@@ -0,0 +1,193 @@
+#!/bin/bash
+# Chamber comparison utilities
+# Usage: bash chamber-compare.sh <chamber_a> <chamber_b>
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CHAMBERS_DIR="${CHAMBERS_DIR:-.aether/chambers}"
+
+# Source error-handler.sh for E_* constants and enhanced json_err
+[[ -f "$SCRIPT_DIR/error-handler.sh" ]] && source "$SCRIPT_DIR/error-handler.sh"
+
+# Fallback E_* constants (no-ops when error-handler.sh is already loaded)
+: "${E_UNKNOWN:=E_UNKNOWN}"
+: "${E_FILE_NOT_FOUND:=E_FILE_NOT_FOUND}"
+: "${E_VALIDATION_FAILED:=E_VALIDATION_FAILED}"
+
+# JSON output helpers
+json_ok() { printf '{"ok":true,"result":%s}\n' "$1"; }
+
+# Guard: yield to error-handler.sh's enhanced json_err when already loaded
+if ! type json_err &>/dev/null; then
+  json_err() {
+    local code="${1:-E_UNKNOWN}"
+    local message="${2:-An unknown error occurred}"
+    printf '{"ok":false,"error":{"code":"%s","message":"%s"}}\n' "$code" "$message" >&2
+    exit 1
+  }
+fi
+
+# Load chamber manifest
+load_chamber() {
+  local chamber_name="$1"
+  local manifest_file="$CHAMBERS_DIR/$chamber_name/manifest.json"
+
+  if [[ ! -f "$manifest_file" ]]; then
+    json_err "$E_FILE_NOT_FOUND" "Chamber not found: $chamber_name. Try: check the chamber name with /ant:tunnels."
+  fi
+
+  cat "$manifest_file"
+}
+
+# Compare two chambers
+cmd="${1:-help}"
+shift 2>/dev/null || true
+
+case "$cmd" in
+  help)
+    cat <<'EOF'
+{"ok":true,"commands":["compare","diff","stats"],"description":"Chamber comparison utilities"}
+EOF
+    ;;
+
+  compare)
+    chamber_a="${1:-}"
+    chamber_b="${2:-}"
+    [[ -z "$chamber_a" || -z "$chamber_b" ]] && json_err "$E_VALIDATION_FAILED" "Missing arguments. Try: compare <chamber_a> <chamber_b>."
+
+    # Load both manifests
+    manifest_a=$(load_chamber "$chamber_a")
+    manifest_b=$(load_chamber "$chamber_b")
+
+    # Extract key fields for comparison
+    result=$(jq -n \
+      --arg a_name "$chamber_a" \
+      --arg b_name "$chamber_b" \
+      --argjson a "$manifest_a" \
+      --argjson b "$manifest_b" \
+      '{
+        chamber_a: {
+          name: $a_name,
+          goal: $a.goal,
+          milestone: $a.milestone,
+          version: $a.version,
+          phases_completed: $a.phases_completed,
+          total_phases: $a.total_phases,
+          entombed_at: $a.entombed_at,
+          decisions_count: ($a.decisions | length),
+          learnings_count: ($a.learnings | length)
+        },
+        chamber_b: {
+          name: $b_name,
+          goal: $b.goal,
+          milestone: $b.milestone,
+          version: $b.version,
+          phases_completed: $b.phases_completed,
+          total_phases: $b.total_phases,
+          entombed_at: $b.entombed_at,
+          decisions_count: ($b.decisions | length),
+          learnings_count: ($b.learnings | length)
+        },
+        comparison: {
+          phases_diff: ($b.phases_completed - $a.phases_completed),
+          decisions_diff: (($b.decisions | length) - ($a.decisions | length)),
+          learnings_diff: (($b.learnings | length) - ($a.learnings | length)),
+          same_milestone: ($a.milestone == $b.milestone),
+          time_between: (
+            (($b.entombed_at | fromdateiso8601) - ($a.entombed_at | fromdateiso8601)) / 86400 | floor
+          )
+        }
+      }')
+
+    json_ok "$result"
+    ;;
+
+  diff)
+    chamber_a="${1:-}"
+    chamber_b="${2:-}"
+    [[ -z "$chamber_a" || -z "$chamber_b" ]] && json_err "$E_VALIDATION_FAILED" "Missing arguments. Try: diff <chamber_a> <chamber_b>."
+
+    manifest_a=$(load_chamber "$chamber_a")
+    manifest_b=$(load_chamber "$chamber_b")
+
+    # Find decisions in B but not in A (new decisions)
+    # Find learnings in B but not in A (new learnings)
+    result=$(jq -n \
+      --arg a_name "$chamber_a" \
+      --arg b_name "$chamber_b" \
+      --argjson a "$manifest_a" \
+      --argjson b "$manifest_b" \
+      '{
+        new_decisions: [
+          $b.decisions[] | select(
+            .content as $content |
+            $a.decisions | map(.content) | contains([$content]) | not
+          )
+        ],
+        new_learnings: [
+          $b.learnings[] | select(
+            .content as $content |
+            $a.learnings | map(.content) | contains([$content]) | not
+          )
+        ],
+        preserved_decisions: [
+          $a.decisions[] | select(
+            .content as $content |
+            $b.decisions | map(.content) | contains([$content])
+          )
+        ],
+        preserved_learnings: [
+          $a.learnings[] | select(
+            .content as $content |
+            $b.learnings | map(.content) | contains([$content])
+          )
+        ]
+      }')
+
+    json_ok "$result"
+    ;;
+
+  stats)
+    chamber_a="${1:-}"
+    chamber_b="${2:-}"
+    [[ -z "$chamber_a" || -z "$chamber_b" ]] && json_err "$E_VALIDATION_FAILED" "Missing arguments. Try: stats <chamber_a> <chamber_b>."
+
+    manifest_a=$(load_chamber "$chamber_a")
+    manifest_b=$(load_chamber "$chamber_b")
+
+    # Calculate detailed statistics
+    result=$(jq -n \
+      --arg a_name "$chamber_a" \
+      --arg b_name "$chamber_b" \
+      --argjson a "$manifest_a" \
+      --argjson b "$manifest_b" \
+      '{
+        summary: {
+          a_phases: $a.phases_completed,
+          b_phases: $b.phases_completed,
+          growth: "\($b.phases_completed - $a.phases_completed) phases",
+          a_duration_days: null,
+          b_duration_days: null
+        },
+        knowledge_transfer: {
+          decisions_preserved: ($a.decisions | map(.content) | intersection($b.decisions | map(.content)) | length),
+          decisions_new: ($b.decisions | map(.content) - ($a.decisions | map(.content)) | length),
+          learnings_preserved: ($a.learnings | map(.content) | intersection($b.learnings | map(.content)) | length),
+          learnings_new: ($b.learnings | map(.content) - ($a.learnings | map(.content)) | length)
+        },
+        evolution: {
+          milestone_changed: ($a.milestone != $b.milestone),
+          from_milestone: $a.milestone,
+          to_milestone: $b.milestone,
+          version_delta: "\($a.version) → \($b.version)"
+        }
+      }')
+
+    json_ok "$result"
+    ;;
+
+  *)
+    json_err "$E_VALIDATION_FAILED" "Unknown command: $cmd. Try: compare, diff, or stats."
+    ;;
+esac