aether-colony 3.1.17 → 5.1.0

package/.claude/commands/ant/seal.md

@@ -1,9 +1,10 @@
+<!-- Generated from .aether/commands/seal.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:seal
 description: "🏺🐜🏺 Seal the colony with Crowned Anthill milestone"
 ---
 
-You are the **Queen**. Seal the colony when all work is complete.
+You are the **Queen**. Seal the colony with a ceremony — no archiving.
 
 ## Instructions
 
@@ -11,18 +12,40 @@ Parse `$ARGUMENTS`:
 - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
 - Otherwise: set `visual_mode = true`
 
+<failure_modes>
+### Crowned Anthill Write Failure
+If writing the Crowned Anthill milestone document fails:
+- Do not mark the colony as sealed in state
+- Report the error -- sealing is incomplete
+- Recovery: user can re-run /ant:seal after fixing the issue
+
+### State Update Failure After Seal
+If COLONY_STATE.json update fails after seal document is written:
+- The seal document exists but state doesn't reflect it
+- Report the inconsistency
+- Options: (1) Retry state update only, (2) Manual state fix, (3) Re-run /ant:seal
+</failure_modes>
+
+<success_criteria>
+Command is complete when:
+- Crowned Anthill milestone document is written
+- COLONY_STATE.json reflects sealed status
+- All phase evidence is summarized in the seal document
+- User sees confirmation of successful seal
+</success_criteria>
+
+<read_only>
+Do not touch during seal:
+- .aether/dreams/ (user notes)
+- .aether/chambers/ (archived colonies -- seal does NOT archive)
+- Source code files
+- .env* files
+- .claude/settings.json
+</read_only>
+
 ### Step 0: Initialize Visual Mode (if enabled)
 
 If `visual_mode` is true:
-```bash
-# Generate session ID
-seal_id="seal-$(date +%s)"
-
-# Initialize swarm display
-bash .aether/aether-utils.sh swarm-display-init "$seal_id"
-bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Sealing colony" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
-```
-
 ### Step 1: Read State
 
 Read `.aether/data/COLONY_STATE.json`.
@@ -33,304 +56,710 @@ No colony initialized. Run /ant:init first.
 ```
 Stop here.
 
-#### Step 1.5: Check for Concurrent Seal Operations
+Extract: `goal`, `state`, `current_phase`, `plan.phases`, `milestone`, `version`, `initialized_at`.
 
-Capture session start time:
-```bash
-SEAL_START=$(date +%s)
-```
+### Step 2: Maturity Gate
 
-Check for existing seal operations (in-progress archives):
-```bash
-# Check for incomplete archive directories (no manifest.json)
-incomplete_archives=$(find .aether/data/archive -type d -name "session_*_archive" 2>/dev/null | while read dir; do
-  if [[ ! -f "$dir/manifest.json" ]]; then
-    echo "$dir"
-  fi
-done)
+Run `bash .aether/aether-utils.sh milestone-detect` to get `milestone`, `phases_completed`, `total_phases`.
 
-if [[ -n "$incomplete_archives" ]]; then
-  echo "Warning: Incomplete archive operations detected:"
-  echo "$incomplete_archives"
-  echo ""
-  echo "These may be from interrupted seal operations."
-  echo "Proceeding will create a new archive."
-fi
+**If milestone is already "Crowned Anthill":**
 ```
+Colony already sealed at Crowned Anthill.
+Run /ant:entomb to archive this colony to chambers.
+```
+Stop here.
 
-### Step 2: Validate Colony Is Complete
+**If state is "EXECUTING":**
+```
+Colony is still executing. Run /ant:continue first.
+```
+Stop here.
 
-Extract: `goal`, `current_phase`, `plan.phases`, `milestone`, `state`.
+**If all phases complete** (phases_completed == total_phases, or milestone is "Sealed Chambers"):
+- Set `incomplete_warning = ""` (no warning needed)
+- Proceed to Step 3.
 
-**Precondition 1: All phases must be completed**
+**If phases are incomplete** (any other milestone — First Mound, Open Chambers, Brood Stable, Ventilated Nest, etc.):
+- Set `incomplete_warning = "WARNING: {phases_completed} of {total_phases} phases complete. Sealing now will mark incomplete work as the final state."`
+- Proceed to Step 3 (warn but DO NOT block).
 
-Check if all phases in `plan.phases` have `status: "completed"`:
-```
-all_completed = all(phase.status == "completed" for phase in plan.phases)
-```
+### Step 3: Confirmation
 
-If NOT all completed:
+Display what will be sealed:
 ```
-Cannot archive colony with incomplete phases.
+SEAL COLONY
+
+Goal: {goal}
+Phases: {phases_completed} of {total_phases} completed
+Current Milestone: {milestone}
+
+{If incomplete_warning is not empty, display it here}
 
-Completed phases: X of Y
-Remaining: {list of incomplete phase names}
+This will:
+  - Award the Crowned Anthill milestone
+  - Write CROWNED-ANTHILL.md ceremony record
+  - Promote colony wisdom to QUEEN.md
 
-Run /ant:continue to complete remaining phases first.
+Seal this colony? (yes/no)
 ```
-Stop here.
 
-**Precondition 2: State must not be EXECUTING**
+Use `AskUserQuestion with yes/no options`.
 
-If `state == "EXECUTING"`:
+If not "yes":
 ```
-Colony is still executing. Run /ant:continue to reconcile first.
+Sealing cancelled. Colony remains active.
 ```
 Stop here.
 
-### Step 3: Check Milestone Eligibility
+### Step 3.5: Analytics Review
 
-The full milestone progression is:
-- **First Mound** — Phase 1 complete (first runnable)
-- **Open Chambers** — Feature work underway (2+ phases complete)
-- **Brood Stable** — Tests consistently green
-- **Ventilated Nest** — Perf/latency acceptable (build + lint clean)
-- **Sealed Chambers** — All phases complete (interfaces frozen)
-- **Crowned Anthill** — Release-ready (user confirms via /ant:seal)
+Before wisdom approval, spawn Sage to analyze colony trends and provide data-driven insights.
 
-**If current milestone is "Crowned Anthill":**
+**Check phase threshold and spawn Sage:**
+```bash
+# Check if colony has enough history for meaningful analytics
+phases_completed=$(jq '[.plan.phases[] | select(.status == "completed")] | length' .aether/data/COLONY_STATE.json 2>/dev/null || echo "0")
+
+if [[ "$phases_completed" -ge 3 ]]; then
+  # Generate Sage name and dispatch
+  sage_name=$(bash .aether/aether-utils.sh generate-ant-name "sage")
+  bash .aether/aether-utils.sh spawn-log "Queen" "sage" "$sage_name" "Colony analytics review"
+
+  # Display spawn notification
+  echo ""
+  echo "━━━ 📜🐜 S A G E ━━━"
+  echo "──── 📜🐜 Spawning $sage_name — Colony analytics review ────"
+fi
 ```
-Colony is already at Crowned Anthill milestone.
-No further archiving needed.
 
-Use /ant:status to view colony state.
+**Spawn Sage using Task tool when threshold is met:**
+If phases_completed >= 3, spawn the Sage agent using Task tool with `subagent_type="aether-sage"`:
+
+```xml
+<task>
+  <description>📜 Sage {sage_name}: Colony analytics review</description>
+  <prompt>
+You are {sage_name}, a 📜 Sage Ant.
+
+Mission: Analyze colony history and provide data-driven insights for wisdom promotion
+
+Data Sources:
+- COLONY_STATE.json: Colony configuration, phases, learnings, instincts
+- activity.log: Activity history with timestamps
+- midden.json: Failure patterns and flagged issues
+
+Analysis Areas:
+1. Velocity Trends: Phase completion rate over time
+2. Bug Density: Error frequency and patterns from midden
+3. Review Turnaround: Time from build to continue
+
+Work:
+1. Read COLONY_STATE.json for phase history and learnings
+2. Read activity.log for velocity patterns
+3. Read midden.json for bug density analysis
+4. Calculate metrics and identify trends
+5. Provide recommendations for wisdom promotion
+
+**IMPORTANT:** You are strictly read-only. Do not modify any files.
+
+Log activity: bash .aether/aether-utils.sh activity-log "ANALYZING" "{sage_name}" "description"
+
+Return ONLY this JSON (no other text):
+{{
+  "ant_name": "{sage_name}",
+  "caste": "sage",
+  "status": "completed" | "failed" | "blocked",
+  "summary": "What you analyzed and found",
+  "key_findings": [],
+  "trends": {{
+    "velocity": "increasing|stable|decreasing",
+    "bug_density": "high|medium|low",
+    "review_turnaround": "fast|moderate|slow"
+  }},
+  "metrics_analyzed": [],
+  "predictions": [],
+  "recommendations": [
+    {{"priority": 1, "action": "", "expected_impact": ""}}
+  ],
+  "next_steps": [],
+  "blockers": []
+}}
+  </prompt>
+</task>
 ```
-Stop here.
 
-**If current milestone is "Sealed Chambers":**
-- Proceed to Step 4 (will upgrade to Crowned Anthill)
+**FALLBACK:** If "Agent type not found", use general-purpose agent and inject role: "You are a Sage Ant - analytics specialist that extracts trends from history to guide decisions."
 
-**If current milestone is "First Mound", "Open Chambers", "Brood Stable", "Ventilated Nest", or any intermediate milestone:**
-- Since all phases are complete, the colony qualifies for both Sealed Chambers and Crowned Anthill
-- The current logic allows proceeding to Step 4 (seal as Crowned Anthill)
-- If user wants to explicitly achieve Sealed Chambers first, they can manually update milestone via COLONY_STATE.json
+**Parse Sage JSON output:**
+After spawn, extract from response: `key_findings`, `trends`, `recommendations`
 
-**If milestone is unrecognized (not in the 6 known stages):**
+Log completion and update swarm display:
+```bash
+bash .aether/aether-utils.sh spawn-complete "$sage_name" "completed" "Analytics review complete"
 ```
-Unknown milestone: {milestone}
 
-The milestone "{milestone}" is not recognized.
-Known milestones: First Mound, Open Chambers, Brood Stable, Ventilated Nest, Sealed Chambers, Crowned Anthill
+**Display Sage completion line:**
+```
+📜 {sage_name}: Colony analytics review complete ✓
+   Velocity: {trend} | Bug density: {level} | Review turnaround: {speed}
+```
 
-Run /ant:status to check colony state.
+**Log high-priority recommendations to midden (non-blocking):**
+For each recommendation with priority <= 2:
+```bash
+bash .aether/aether-utils.sh midden-write "analytics" "Sage recommendation (P{priority}): {action}" "sage"
 ```
-Stop here.
 
-### Step 4: Promote Colony Wisdom to QUEEN.md
+**Display insights summary:**
+```
+📜 Sage Insights:
+   Key Findings: {count}
+   Top Recommendation: {first recommendation action}
+```
+
+**Continue to Step 3.6 (non-blocking):**
+Proceed to Step 3.6 regardless of Sage findings — Sage is strictly non-blocking.
+
+**If phases_completed < 3:**
+Skip silently (no output) — proceed directly to Step 3.6.
 
-Before archiving, extract and promote significant patterns and decisions from the colony:
+### Step 3.6: Wisdom Approval
+
+Before sealing, review wisdom proposals accumulated during this colony's lifecycle.
 
 ```bash
-# Ensure QUEEN.md exists
-if [[ ! -f ".aether/docs/QUEEN.md" ]]; then
-  bash .aether/aether-utils.sh queen-init >/dev/null 2>&1
+# --- Batch auto-promotion for auto-threshold observations (QUEEN-02) ---
+# Auto-promote observations meeting higher recurrence thresholds
+# before presenting the interactive review for lower-threshold proposals.
+
+obs_file=".aether/data/learning-observations.json"
+auto_promoted_count=0
+
+if [[ -f "$obs_file" ]]; then
+  for encoded in $(jq -r '.observations[] | @base64' "$obs_file" 2>/dev/null); do
+    content=$(echo "$encoded" | base64 -d | jq -r '.content // empty')
+    wisdom_type=$(echo "$encoded" | base64 -d | jq -r '.wisdom_type // "pattern"')
+    colony=$(echo "$encoded" | base64 -d | jq -r '.colonies[0] // "unknown"')
+    [[ -z "$content" ]] && continue
+
+    result=$(bash .aether/aether-utils.sh learning-promote-auto "$wisdom_type" "$content" "$colony" "learning" 2>/dev/null || echo '{}')
+    was_promoted=$(echo "$result" | jq -r '.result.promoted // false' 2>/dev/null || echo "false")
+    if [[ "$was_promoted" == "true" ]]; then
+      auto_promoted_count=$((auto_promoted_count + 1))
+    fi
+  done
 fi
 
-# Extract colony name from session_id or goal
-colony_name=$(jq -r '.session_id // empty' .aether/data/COLONY_STATE.json | sed 's/^session_//' | cut -d'_' -f1-3)
-[[ -z "$colony_name" ]] && colony_name=$(jq -r '.goal' .aether/data/COLONY_STATE.json | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | cut -c1-30)
-
-# Track promotion results
-promotions_made=0
-promotion_details=""
-
-# Extract and promote phase learnings (validated learnings with high confidence)
-while IFS= read -r learning; do
-  claim=$(echo "$learning" | jq -r '.claim // empty')
-  status=$(echo "$learning" | jq -r '.status // empty')
-
-  if [[ -n "$claim" && "$status" == "validated" ]]; then
-    # Determine type based on content patterns
-    if echo "$claim" | grep -qi "never\|avoid\|don't\|do not"; then
-      type="redirect"
-    elif echo "$claim" | grep -qi "always\|should\|must\|pattern\|approach"; then
-      type="pattern"
-    elif echo "$claim" | grep -qi "use\|prefer\|technology\|tool\|library"; then
-      type="stack"
-    else
-      type="philosophy"
-    fi
+if [[ "$auto_promoted_count" -gt 0 ]]; then
+  echo "Auto-promoted $auto_promoted_count observation(s) to QUEEN.md (met recurrence thresholds)"
+  echo ""
+fi
+# --- END Batch auto-promotion ---
 
-    result=$(bash .aether/aether-utils.sh queen-promote "$type" "$claim" "$colony_name" 2>/dev/null)
-    if echo "$result" | jq -e '.ok' >/dev/null 2>&1; then
-      promotions_made=$((promotions_made + 1))
-      promotion_details="${promotion_details}  - Promoted ${type}: ${claim:0:60}...\n"
-    fi
-  fi
-done < <(jq -c '.memory.phase_learnings[]?.learnings[]? // empty' .aether/data/COLONY_STATE.json 2>/dev/null)
-
-# Extract and promote decisions
-while IFS= read -r decision; do
-  description=$(echo "$decision" | jq -r '.description // .rationale // empty')
-  [[ -z "$description" ]] && description=$(echo "$decision" | jq -r '.decision // empty')
-
-  if [[ -n "$description" ]]; then
-    result=$(bash .aether/aether-utils.sh queen-promote "pattern" "$description" "$colony_name" 2>/dev/null)
-    if echo "$result" | jq -e '.ok' >/dev/null 2>&1; then
-      promotions_made=$((promotions_made + 1))
-      promotion_details="${promotion_details}  - Promoted pattern from decision: ${description:0:60}...\n"
-    fi
+# Check for pending proposals
+proposals=$(bash .aether/aether-utils.sh learning-check-promotion 2>/dev/null || echo '{"proposals":[]}')
+proposal_count=$(echo "$proposals" | jq '.proposals | length')
+
+if [[ "$proposal_count" -gt 0 ]]; then
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "   🧠 WISDOM REVIEW"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo ""
+  echo "Review wisdom proposals before sealing this colony."
+  echo "Approved proposals will be promoted to QUEEN.md."
+  echo ""
+
+  # Run approval workflow (blocking)
+  bash .aether/aether-utils.sh learning-approve-proposals
+
+  echo ""
+  echo "Wisdom review complete. Proceeding with sealing ceremony..."
+  echo ""
+else
+  echo "No wisdom proposals to review."
+fi
+```
+
+### Step 3.7: Hive Promotion (NON-BLOCKING)
+
+After QUEEN.md promotion, promote abstracted instincts to the cross-colony hive.
+
+**Extract high-confidence instincts for hive promotion:**
+```bash
+# Get instincts with confidence >= 0.8
+high_conf_instincts=$(jq -r '.memory.instincts[] | select(.confidence >= 0.8) | @base64' .aether/data/COLONY_STATE.json 2>/dev/null || echo "")
+
+# Derive source repo name from current directory
+source_repo="$(pwd)"
+
+# Read domain tags from registry (NOT from instinct.domain which is a category, not a repo domain)
+repo_domain_tags=$(jq -r --arg repo "$(pwd)" \
+  '[.repos[] | select(.path == $repo) | .domain_tags // []] | .[0] // [] | join(",")' \
+  "$HOME/.aether/registry.json" 2>/dev/null || echo "")
+
+hive_promoted_count=0
+hive_errors=0
+for encoded in $high_conf_instincts; do
+  [[ -z "$encoded" ]] && continue
+
+  # Extract trigger and action fields from the instinct object
+  trigger=$(echo "$encoded" | base64 -d | jq -r '.trigger // empty')
+  action=$(echo "$encoded" | base64 -d | jq -r '.action // empty')
+  confidence=$(echo "$encoded" | base64 -d | jq -r '.confidence // 0.7')
+
+  [[ -z "$trigger" || -z "$action" ]] && continue
+
+  # Strip leading "When " or "when " from trigger to avoid "When When..." stutter
+  trigger_clean=$(echo "$trigger" | sed 's/^[Ww]hen //')
+
+  # Build the promotion text in "When {trigger}: {action}" format
+  promote_text="When ${trigger_clean}: ${action}"
+
+  # Build hive-promote args with --text and --source-repo (required)
+  promote_args=(hive-promote --text "$promote_text" --source-repo "$source_repo" --confidence "$confidence")
+  [[ -n "$repo_domain_tags" ]] && promote_args+=(--domain "$repo_domain_tags")
+
+  # Call hive-promote which orchestrates abstract + store
+  result=$(bash .aether/aether-utils.sh "${promote_args[@]}" 2>/dev/null || echo '{}')
+  was_promoted=$(echo "$result" | jq -r '.result.action // "skipped"' 2>/dev/null || echo "skipped")
+
+  if [[ "$was_promoted" == "promoted" || "$was_promoted" == "merged" ]]; then
+    hive_promoted_count=$((hive_promoted_count + 1))
   fi
-done < <(jq -c '.memory.decisions[]? // empty' .aether/data/COLONY_STATE.json 2>/dev/null)
+done
+
+if [[ "$hive_promoted_count" -gt 0 ]]; then
+  echo "Hive promotion: $hive_promoted_count instinct(s) promoted to cross-colony hive"
+fi
+```
+
+**Continue to Step 4 (non-blocking):**
+Proceed to Step 4 regardless of hive promotion results — hive promotion is strictly non-blocking.
+
+### Step 4: Log Seal Activity
+
+Log the seal ceremony to activity log:
+```bash
+bash .aether/aether-utils.sh activity-log "MODIFIED" "Queen" "Colony sealed - wisdom review completed"
+```
+
+### Step 4.5: Increment Colony Version
+
+Before writing the Crowned Anthill milestone, increment `colony_version` in COLONY_STATE.json.
+
+```bash
+# Read current colony_version (default to 0 for backward compat with older colonies)
+current_colony_version=$(jq -r '.colony_version // 0' .aether/data/COLONY_STATE.json 2>/dev/null || echo 0)
+# Guard against non-integer values (floats, strings)
+[[ "$current_colony_version" =~ ^[0-9]+$ ]] || current_colony_version=0
+new_colony_version=$(( current_colony_version + 1 ))
+
+# Write incremented value back — guard against empty output destroying the file
+updated=$(jq --argjson v "$new_colony_version" '.colony_version = $v' .aether/data/COLONY_STATE.json 2>/dev/null)
+if [[ -n "$updated" && ${#updated} -gt 10 ]]; then
+  echo "$updated" > .aether/data/COLONY_STATE.json
+else
+  echo "Warning: jq update failed — colony_version defaults to 1, state file unchanged"
+  new_colony_version=1
+fi
+```
+
+Use `new_colony_version` as `{colony_version}` throughout the rest of the seal ceremony (e.g., display as "Crowned Anthill v{colony_version}").
+
+**Error handling:** If jq fails or produces empty/short output, COLONY_STATE.json is NOT overwritten and `new_colony_version` defaults to 1. Never let version increment failures block the seal.
 
-# Log promotion results to activity log
-bash .aether/aether-utils.sh activity-log "MODIFIED" "Queen" "Promoted ${promotions_made} learnings/decisions to QUEEN.md from colony ${colony_name}"
+### Step 5: Update Milestone to Crowned Anthill
 
-# Store promotion summary for display
-promotion_summary="${promotions_made} wisdom entries promoted"
+Update COLONY_STATE.json:
+1. Set `milestone` to `"Crowned Anthill"`
+2. Set `milestone_updated_at` to current ISO-8601 timestamp
+3. Append event: `"<timestamp>|milestone_reached|seal|Achieved Crowned Anthill milestone"`
+
+Run `bash .aether/aether-utils.sh validate-state colony` after write.
+
+### Step 5.1: Update Changelog
+
+**MANDATORY: Record the seal in the project changelog. This step is never skipped.**
+
+If no `CHANGELOG.md` exists, `changelog-append` creates one automatically.
+
+Build a summary of what the colony accomplished across all phases:
+- Collect completed phase names from COLONY_STATE.json
+- Summarize the goal and key outcomes in one line
+
+```bash
+bash .aether/aether-utils.sh changelog-append \
+  "$(date +%Y-%m-%d)" \
+  "seal-crowned-anthill" \
+  "00" \
+  "{key_files_csv}" \
+  "Colony sealed at Crowned Anthill;{goal}" \
+  "{phases_completed} phases completed;Colony wisdom promoted to QUEEN.md" \
+  ""
 ```
 
-### Step 5: Archive Colony State
+- `{key_files_csv}` — list the most significant files created or modified across the colony's lifetime (derive from phase plans or git log)
+- `{goal}` — the colony goal from COLONY_STATE.json
+
+**Error handling:** If `changelog-append` fails, log to midden and continue — changelog failure never blocks sealing.
 
-Create archive directory:
+### Step 5.2: Update Registry (Silent)
+
+Mark the colony as inactive in the global registry. This is silent on failure — registry is not required for the colony to work.
+
+Run using the Bash tool (ignore errors):
+```bash
+bash .aether/aether-utils.sh registry-add "$(pwd)" "$(jq -r '.version // "unknown"' ~/.aether/version.json 2>/dev/null || echo 'unknown')" --active false 2>/dev/null || true
 ```
-archive_dir=".aether/data/archive/session_$(date -u +%s)_archive"
-mkdir -p "$archive_dir"
+
+If the command fails, proceed silently. This is optional bookkeeping.
+
+### Step 5.5: Documentation Coverage Audit
+
+Before writing the seal document, spawn a Chronicler to survey documentation coverage.
+
+**Generate Chronicler name and dispatch:**
+```bash
+# Generate unique chronicler name
+chronicler_name=$(bash .aether/aether-utils.sh generate-ant-name "chronicler")
+
+# Log spawn and update swarm display
+bash .aether/aether-utils.sh spawn-log "Queen" "chronicler" "$chronicler_name" "Documentation coverage audit"
 ```
 
-Copy the following files to the archive directory:
-1. `.aether/data/COLONY_STATE.json` → `$archive_dir/COLONY_STATE.json`
-2. `.aether/data/activity.log` → `$archive_dir/activity.log`
-3. `.aether/data/spawn-tree.txt` → `$archive_dir/spawn-tree.txt`
-4. `.aether/data/flags.json` → `$archive_dir/flags.json` (if exists)
-5. `.aether/data/constraints.json` → `$archive_dir/constraints.json` (if exists)
+**Display:**
+```
+━━━ 📝🐜 C H R O N I C L E R ━━━
+──── 📝🐜 Spawning {chronicler_name} — documentation coverage audit ────
+```
 
-Create archive manifest file `$archive_dir/manifest.json`:
-```json
+**Spawn Chronicler using Task tool:**
+Spawn the Chronicler using Task tool with `subagent_type="aether-chronicler"`:
+
+```xml
+<task>
+  <description>📝 Chronicler {chronicler_name}: Documentation coverage audit</description>
+  <prompt>
+You are {chronicler_name}, a 📝 Chronicler Ant.
+
+Mission: Documentation coverage audit before seal ceremony
+
+Survey the following documentation types:
+- README.md (project overview, quick start)
+- API documentation (endpoints, parameters, responses)
+- Guides (tutorials, how-tos, best practices)
+- Changelogs (version history, release notes)
+- Code comments (JSDoc, TSDoc inline documentation)
+- Architecture docs (system design, decisions)
+
+Work:
+1. Check if README.md exists and covers: installation, usage, examples
+2. Look for docs/ directory and survey guide coverage
+3. Check for API documentation (OpenAPI, README sections, etc.)
+4. Verify CHANGELOG.md exists and has recent entries
+5. Sample source files for inline documentation coverage
+6. Identify documentation gaps (missing, outdated, incomplete)
+
+**IMPORTANT:** You are strictly read-only. Do not modify any files.
+
+Log activity: bash .aether/aether-utils.sh activity-log "SURVEYING" "{chronicler_name}" "description"
+
+Return ONLY this JSON (no other text):
 {
-  "archived_at": "<ISO-8601 timestamp>",
-  "goal": "<colony goal>",
-  "total_phases": <number>,
-  "milestone": "Crowned Anthill",
-  "files": [
-    "COLONY_STATE.json",
-    "activity.log",
-    "spawn-tree.txt",
-    "flags.json",
-    "constraints.json"
-  ]
+  "ant_name": "{chronicler_name}",
+  "caste": "chronicler",
+  "status": "completed" | "failed" | "blocked",
+  "summary": "What you surveyed and found",
+  "documentation_created": [],
+  "documentation_updated": [],
+  "pages_documented": 0,
+  "code_examples_verified": [],
+  "coverage_percent": 0,
+  "gaps_identified": [
+    {"type": "README|API|Guide|Changelog|Comments|Architecture", "severity": "high|medium|low", "description": "...", "location": "..."}
+  ],
+  "blockers": []
 }
+  </prompt>
+</task>
+```
+
+**FALLBACK:** If "Agent type not found", use general-purpose agent and inject role: "You are a Chronicler Ant - documentation specialist that surveys and identifies documentation gaps."
+
+**Parse Chronicler JSON output:**
+Extract from response: `coverage_percent`, `gaps_identified`, `pages_documented`
+
+Log completion and update swarm display:
+```bash
+bash .aether/aether-utils.sh spawn-complete "$chronicler_name" "completed" "Documentation audit complete"
+```
+
+**Display Chronicler completion line:**
+```
+📝 {chronicler_name}: Documentation coverage audit ({pages_documented} pages, {coverage_percent}% coverage) ✓
+```
+
+**Log gaps to midden (non-blocking):**
+For each gap in `gaps_identified` with severity "high" or "medium":
+```bash
+bash .aether/aether-utils.sh midden-write "documentation" "Gap ({severity}): {description} at {location}" "chronicler"
+```
+
+**Display summary:**
+```
+📝 Chronicler complete — {coverage_percent}% coverage, {gap_count} gaps logged to midden
 ```
 
-#### Step 5.5: Verify Archive Integrity
+**Continue to Step 6 (non-blocking):**
+Proceed to Step 6 regardless of Chronicler findings — Chronicler is strictly non-blocking.
 
-Verify the archive was created successfully:
+### Step 6: Write CROWNED-ANTHILL.md
+
+Calculate colony age:
 ```bash
-if [[ -f "$archive_dir/manifest.json" ]]; then
-  echo "Archive verified: $archive_dir"
+initialized_at=$(jq -r '.initialized_at // empty' .aether/data/COLONY_STATE.json)
+if [[ -n "$initialized_at" ]]; then
+  init_epoch=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$initialized_at" +%s 2>/dev/null || echo 0)
+  now_epoch=$(date +%s)
+  if [[ "$init_epoch" -gt 0 ]]; then
+    colony_age_days=$(( (now_epoch - init_epoch) / 86400 ))
+  else
+    colony_age_days=0
+  fi
 else
-  echo "Error: Archive creation incomplete"
-  # Don't proceed with milestone update
-  exit 1
+  colony_age_days=0
 fi
 ```
 
-### Step 6: Update Milestone to Crowned Anthill
+Extract phase recap:
+```bash
+phase_recap=""
+while IFS= read -r phase_line; do
+  phase_name=$(echo "$phase_line" | jq -r '.name')
+  phase_status=$(echo "$phase_line" | jq -r '.status')
+  phase_recap="${phase_recap}  - ${phase_name}: ${phase_status}\n"
+done < <(jq -c '.plan.phases[]' .aether/data/COLONY_STATE.json 2>/dev/null)
+```
 
-Update COLONY_STATE.json:
-1. Set `milestone` to `"Crowned Anthill"`
-2. Set `milestone_updated_at` to current ISO-8601 timestamp
-3. Append event: `"<timestamp>|milestone_reached|archive|Achieved Crowned Anthill milestone - colony archived"`
+Write the seal document:
+```bash
+version=$(jq -r '.version // "3.0"' .aether/data/COLONY_STATE.json)
+seal_date=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+```
+
+Resolve the crowned-anthill template path:
+  Check ~/.aether/system/templates/crowned-anthill.template.md first,
+  then .aether/templates/crowned-anthill.template.md.
+
+If no template found: output "Template missing: crowned-anthill.template.md. Run aether update to fix." and stop.
 
-### Step 7: Write Final Handoff
+Read the template file. Fill all {{PLACEHOLDER}} values:
+  - {{GOAL}} → goal (from colony state)
+  - {{SEAL_DATE}} → seal_date (ISO-8601 UTC timestamp)
+  - {{VERSION}} → version (from colony state)
+  - {{TOTAL_PHASES}} → total_phases
+  - {{PHASES_COMPLETED}} → phases_completed
+  - {{COLONY_AGE_DAYS}} → colony_age_days
+  - {{PROMOTIONS_MADE}} → promotions_made
+  - {{PHASE_RECAP}} → phase recap list (one entry per line, formatted from the bash loop above)
 
-After archiving and promoting wisdom, write the final handoff documenting the completed colony:
+Remove the HTML comment lines at the top of the template (lines starting with <!--).
+Write the result to .aether/CROWNED-ANTHILL.md using the Write tool.
+
+### Step 6.5: Export XML Archive (best-effort)
+
+Export colony data as a combined XML archive and a standalone pheromones.xml. Both are best-effort — seal proceeds even if XML export fails.
 
 ```bash
-cat > .aether/HANDOFF.md << 'HANDOFF_EOF'
-# Colony Session — SEALED (Crowned Anthill)
+# Check if xmllint is available
+if command -v xmllint >/dev/null 2>&1; then
+  xml_result=$(bash .aether/aether-utils.sh colony-archive-xml ".aether/exchange/colony-archive.xml" 2>&1)
+  xml_ok=$(echo "$xml_result" | jq -r '.ok // false' 2>/dev/null)
+  if [[ "$xml_ok" == "true" ]]; then
+    xml_pheromone_count=$(echo "$xml_result" | jq -r '.result.pheromone_count // 0' 2>/dev/null)
+    xml_export_line="XML Archive: colony-archive.xml (${xml_pheromone_count} active signals)"
+  else
+    xml_export_line="XML Archive: export failed (non-blocking)"
+  fi
 
-## 🏆 Colony Complete
-**Status:** Crowned Anthill — All phases completed and archived
+  # Also export standalone pheromones.xml for cross-colony sharing
+  pher_result=$(bash .aether/aether-utils.sh pheromone-export-xml ".aether/exchange/pheromones.xml" 2>&1)
+  pher_ok=$(echo "$pher_result" | jq -r '.ok // false' 2>/dev/null)
+  if [[ "$pher_ok" == "true" ]]; then
+    pher_signal_count=$(jq '[.signals[] | select(.active != false)] | length' .aether/data/pheromones.json 2>/dev/null || echo "0")
+    pher_export_line="Signal Export: pheromones.xml (${pher_signal_count} signals, importable by other colonies)"
+  else
+    pher_export_line="Signal Export: failed (non-blocking)"
+  fi
 
-## Archive Location
-{archive_dir}
+  # Export standalone queen-wisdom.xml for cross-colony wisdom sharing
+  wisdom_result=$(bash .aether/aether-utils.sh wisdom-export-xml ".aether/exchange/queen-wisdom.xml" 2>&1)
+  wisdom_ok=$(echo "$wisdom_result" | jq -r '.ok // false' 2>/dev/null)
+  if [[ "$wisdom_ok" == "true" ]]; then
+    wisdom_count=$(echo "$wisdom_result" | jq -r '.result.entries // 0' 2>/dev/null)
+    wisdom_export_line="Wisdom Export: queen-wisdom.xml (${wisdom_count} entries)"
+  else
+    wisdom_export_line="Wisdom Export: failed (non-blocking)"
+  fi
 
-## Colony Summary
-- Goal: "{goal}"
-- Total Phases: {total_phases}
-- Milestone: Crowned Anthill
-- Sealed At: {timestamp}
-- Wisdom Promoted: {promotion_summary}
+  # Export standalone colony-registry.xml for lineage tracking
+  registry_result=$(bash .aether/aether-utils.sh registry-export-xml ".aether/exchange/colony-registry.xml" 2>&1)
+  registry_ok=$(echo "$registry_result" | jq -r '.ok // false' 2>/dev/null)
+  if [[ "$registry_ok" == "true" ]]; then
+    registry_count=$(echo "$registry_result" | jq -r '.result.colonies // 0' 2>/dev/null)
+    registry_export_line="Registry Export: colony-registry.xml (${registry_count} colonies)"
+  else
+    registry_export_line="Registry Export: failed (non-blocking)"
+  fi
+else
+  xml_export_line="XML Archive: skipped (xmllint not available)"
+  pher_export_line="Signal Export: skipped (xmllint not available)"
+  wisdom_export_line="Wisdom Export: skipped (xmllint not available)"
+  registry_export_line="Registry Export: skipped (xmllint not available)"
+fi
+```
 
-## Files Archived
-- COLONY_STATE.json
-- activity.log
-- spawn-tree.txt
-- flags.json (if existed)
-- constraints.json (if existed)
+### Step 7: Display Ceremony
 
-## Session Note
-This colony has been sealed and archived. The anthill stands crowned.
-To start anew, run: /ant:lay-eggs "<new goal>"
-HANDOFF_EOF
+
+Display the ASCII art ceremony:
+```
+        .     .
+       /|\   /|\
+      / | \ / | \
+     /  |  X  |  \
+    /   | / \ |   \
+   /    |/   \|    \
+  /     /     \     \
+ /____ /  ___  \ ____\
+      / /   \ \
+     / /     \ \
+    /_/       \_\
+     |  CROWNED |
+     | ANTHILL  |
+     |__________|
 ```
 
-This handoff serves as the final record of the completed colony.
+Below the ASCII art, display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   C R O W N E D   A N T H I L L   v{colony_version}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Goal: {goal}
+Phases: {phases_completed} of {total_phases} completed
+Milestone: Crowned Anthill v{colony_version}
+{If incomplete_warning is not empty: display it}
+Wisdom Promoted: {promotion_summary}
+
+Seal Document: .aether/CROWNED-ANTHILL.md
+{xml_export_line}
+{pher_export_line}
+{wisdom_export_line}
+{registry_export_line}
+
+The colony stands crowned and sealed.
+Its wisdom lives on in QUEEN.md.
+The anthill has reached its final form.
+
+──────────────────────────────────────────────────
+🐜 Next Up
+──────────────────────────────────────────────────
+   /ant:entomb              🏺 Archive colony to chambers
+   /ant:lay-eggs            🥚 Start a new colony
+   /ant:tunnels             🗄️  Browse archived chambers
+```
+
+### Step 7.5: Commit Suggestion (Non-blocking)
 
-### Step 8: Display Result
+After the ceremony, offer to commit all colony work.
 
-**If visual_mode is true, render final swarm display:**
+**Gate check — skip silently if any fail:**
+1. Not a git repo: `git rev-parse --git-dir 2>/dev/null` fails → skip
+2. Clean working tree: `git status --porcelain 2>/dev/null` is empty → skip to Step 7.6 (may still want to push)
+
+**If uncommitted changes exist:**
+
+Generate a seal commit message:
 ```bash
-bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Colony sealed" "Colony" '{"read":3,"grep":0,"edit":2,"bash":3}' 100 "fungus_garden" 100
-bash .aether/aether-utils.sh swarm-display-inline "$seal_id"
+seal_commit=$(bash .aether/aether-utils.sh generate-commit-message seal "$phases_completed" "$goal" "$colony_age_days" 2>/dev/null)
+seal_message=$(echo "$seal_commit" | jq -r '.result.message // "aether-seal: colony sealed"')
+seal_body=$(echo "$seal_commit" | jq -r '.result.body // ""')
 ```
 
-Output:
+Display the suggestion:
 ```
-🏺 ════════════════════════════════════════════════════
-   C R O W N E D   A N T H I L L
-══════════════════════════════════════════════════ 🏺
+──────────────────────────────────────────────────
+Commit suggestion:
 
-✅ Colony archived successfully!
+  $seal_message
 
-👑 Goal: {goal (truncated to 60 chars)}
-📍 Phases: {total_phases} completed
-🏆 Milestone: Crowned Anthill
-📚 Wisdom Promoted: {promotion_summary}
+  $seal_body
+──────────────────────────────────────────────────
+```
 
-📦 Archive Location: {archive_dir}
-   - COLONY_STATE.json
-   - activity.log
-   - spawn-tree.txt
-   - flags.json (if existed)
-   - constraints.json (if existed)
+Prompt with AskUserQuestion (3 options):
+1. **Commit with this message** — Run `git add -A && git commit -m "$seal_message" -m "$seal_body"`
+2. **Edit message** — Ask user for their preferred message, then commit with that
+3. **Skip** — Do not commit
 
-🐜 The colony has reached its final form.
-   The anthill stands crowned and sealed.
-   History is preserved. The colony rests.
+If the user chooses option 1 or 2 and the commit succeeds, set `seal_committed = true`.
+If the commit fails or user skips, set `seal_committed = false`.
 
-💾 State persisted — safe to /clear
+**Error handling:** If `generate-commit-message` fails, fall back to message `"aether-seal: colony sealed"`. Never let commit suggestion failures stop the seal flow.
 
-🐜 What would you like to do next?
-   1. /ant:lay-eggs "<new goal>"  — Start a new colony
-   2. /ant:tunnels                — Browse archived colonies
-   3. /clear                      — Clear context and continue
+### Step 7.6: Push Suggestion (Non-blocking)
 
-Use AskUserQuestion with these three options.
+Only show if a commit was just made in Step 7.5 (`seal_committed == true`) OR if there are unpushed commits.
 
-If option 1 selected: proceed to run /ant:lay-eggs flow
-If option 2 selected: run /ant:tunnels
-If option 3 selected: display "Run /ant:lay-eggs to begin anew after clearing"
+**Gate check — skip silently if any fail:**
+1. Not a git repo → skip
+2. No remote configured: `git remote -v 2>/dev/null` is empty → skip
+
+**Check for unpushed commits:**
+```bash
+unpushed=$(git log --oneline @{u}..HEAD 2>/dev/null | wc -l | tr -d ' ')
 ```
+If `unpushed == 0` and `seal_committed == false` → skip (nothing to push)
+
+**If there are commits to push:**
+
+Detect current branch and upstream status:
+```bash
+current_branch=$(git branch --show-current)
+has_upstream=$(git rev-parse --abbrev-ref @{u} 2>/dev/null && echo "yes" || echo "no")
+```
+
+Display:
+```
+Push {unpushed} commit(s) to remote?
+  Branch: {current_branch}
+```
+
+Prompt with AskUserQuestion (2 options):
+1. **Push now** — If upstream exists: `git push`. If no upstream: `git push -u origin $current_branch`
+2. **I'll push later** — Skip
+
+Display result: `Pushed to origin/{current_branch}` on success, or `Push skipped` if declined.
+
+**Error handling:** If push fails, display the error message but do not stop the seal flow. Suggest: "You can push manually with `git push`."
+
+**Safety:** Never auto-push. Always require explicit user approval via AskUserQuestion.
 
 ### Edge Cases
 
-**If milestone is already "Sealed Chambers" but phases are complete:**
-- Proceed with archiving and upgrade to Crowned Anthill
+**Colony already at Crowned Anthill:**
+- Display message and guide to /ant:entomb. Do NOT re-seal.
+
+**Phases incomplete:**
+- Warn but allow. The seal proceeds after confirmation.
+
+**Missing QUEEN.md:**
+- queen-init creates it. If that fails, skip promotion (non-fatal).
 
-**If any archive files are missing:**
-- Archive what exists, note in manifest which files were missing
+**Missing initialized_at:**
+- Colony age defaults to 0 days.
 
-**If archive directory already exists:**
-- Append timestamp to make unique: `session_<ts>_archive_<random>`
+**Empty phases array:**
+- Can seal a colony with 0 phases (rare but valid). phases_completed = 0, total_phases = 0.