aether-colony 5.0.0 → 5.2.1

package/.aether/commands/seal.yaml

@@ -0,0 +1,1214 @@
+name: "ant:seal"
+description: "🏺🐜🏺 Seal the colony with Crowned Anthill milestone"
+body_claude: |
+  You are the **Queen**. Seal the colony with a ceremony — no archiving.
+
+  ## Instructions
+
+  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:
+  ### Step 1: Read State
+
+  Read `.aether/data/COLONY_STATE.json`.
+
+  If file missing or `goal: null`:
+  ```
+  No colony initialized. Run /ant:init first.
+  ```
+  Stop here.
+
+  Extract: `goal`, `state`, `current_phase`, `plan.phases`, `milestone`, `version`, `initialized_at`.
+
+  ### Step 2: Maturity Gate
+
+  Run `bash .aether/aether-utils.sh milestone-detect` to get `milestone`, `phases_completed`, `total_phases`.
+
+  **If milestone is already "Crowned Anthill":**
+  ```
+  Colony already sealed at Crowned Anthill.
+  Run /ant:entomb to archive this colony to chambers.
+  ```
+  Stop here.
+
+  **If state is "EXECUTING":**
+  ```
+  Colony is still executing. Run /ant:continue first.
+  ```
+  Stop here.
+
+  **If all phases complete** (phases_completed == total_phases, or milestone is "Sealed Chambers"):
+  - Set `incomplete_warning = ""` (no warning needed)
+  - Proceed to Step 3.
+
+  **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).
+
+  ### Step 3: Confirmation
+
+  Display what will be sealed:
+  ```
+  SEAL COLONY
+
+  Goal: {goal}
+  Phases: {phases_completed} of {total_phases} completed
+  Current Milestone: {milestone}
+
+  {If incomplete_warning is not empty, display it here}
+
+  This will:
+    - Award the Crowned Anthill milestone
+    - Write CROWNED-ANTHILL.md ceremony record
+    - Promote colony wisdom to QUEEN.md
+
+  Seal this colony? (yes/no)
+  ```
+
+  Use `AskUserQuestion with yes/no options`.
+
+  If not "yes":
+  ```
+  Sealing cancelled. Colony remains active.
+  ```
+  Stop here.
+
+  ### Step 3.5: Analytics Review
+
+  Before wisdom approval, spawn Sage to analyze colony trends and provide data-driven insights.
+
+  **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
+  ```
+
+  **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>
+  ```
+
+  **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."
+
+  **Parse Sage JSON output:**
+  After spawn, extract from response: `key_findings`, `trends`, `recommendations`
+
+  Log completion and update swarm display:
+  ```bash
+  bash .aether/aether-utils.sh spawn-complete "$sage_name" "completed" "Analytics review complete"
+  ```
+
+  **Display Sage completion line:**
+  ```
+  📜 {sage_name}: Colony analytics review complete ✓
+     Velocity: {trend} | Bug density: {level} | Review turnaround: {speed}
+  ```
+
+  **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"
+  ```
+
+  **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.
+
+  ### Step 3.6: Wisdom Approval
+
+  Before sealing, review wisdom proposals accumulated during this colony's lifecycle.
+
+  ```bash
+  # --- 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
+
+  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 ---
+
+  # 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
+
+  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.4: Checkpoint State
+
+  Before modifying colony state, create a rolling backup:
+
+  Run using the Bash tool with description "Checkpointing colony state before seal...":
+  ```bash
+  bash .aether/aether-utils.sh state-checkpoint "pre-seal" 2>/dev/null || echo "Warning: State checkpoint failed -- continuing without backup" >&2
+  ```
+
+  ### 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.
+
+  ### Step 5: Update Milestone to Crowned Anthill
+
+  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" \
+    ""
+  ```
+
+  - `{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.
+
+  ### 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
+  ```
+
+  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"
+  ```
+
+  **Display:**
+  ```
+  ━━━ 📝🐜 C H R O N I C L E R ━━━
+  ──── 📝🐜 Spawning {chronicler_name} — documentation coverage audit ────
+  ```
+
+  **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):
+  {
+    "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
+  ```
+
+  **Continue to Step 6 (non-blocking):**
+  Proceed to Step 6 regardless of Chronicler findings — Chronicler is strictly non-blocking.
+
+  ### Step 6: Write CROWNED-ANTHILL.md
+
+  Calculate colony age:
+  ```bash
+  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
+    colony_age_days=0
+  fi
+  ```
+
+  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)
+  ```
+
+  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.
+
+  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)
+
+  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
+  # 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
+
+    # 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
+
+    # 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
+
+    # 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
+  ```
+
+  ### Step 7: Display Ceremony
+
+
+  Display the ASCII art ceremony:
+  ```
+          .     .
+         /|\   /|\
+        / | \ / | \
+       /  |  X  |  \
+      /   | / \ |   \
+     /    |/   \|    \
+    /     /     \     \
+   /____ /  ___  \ ____\
+        / /   \ \
+       / /     \ \
+      /_/       \_\
+       |  CROWNED |
+       | ANTHILL  |
+       |__________|
+  ```
+
+  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)
+
+  After the ceremony, offer to commit all colony work.
+
+  **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
+  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 // ""')
+  ```
+
+  Display the suggestion:
+  ```
+  ──────────────────────────────────────────────────
+  Commit suggestion:
+
+    $seal_message
+
+    $seal_body
+  ──────────────────────────────────────────────────
+  ```
+
+  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
+
+  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`.
+
+  **Error handling:** If `generate-commit-message` fails, fall back to message `"aether-seal: colony sealed"`. Never let commit suggestion failures stop the seal flow.
+
+  ### Step 7.6: Push Suggestion (Non-blocking)
+
+  Only show if a commit was just made in Step 7.5 (`seal_committed == true`) OR if there are unpushed commits.
+
+  **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
+
+  **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).
+
+  **Missing initialized_at:**
+  - Colony age defaults to 0 days.
+
+  **Empty phases array:**
+  - Can seal a colony with 0 phases (rare but valid). phases_completed = 0, total_phases = 0.
+
+body_opencode: |
+  You are the **Queen**. Seal the colony when all work is complete.
+
+  ## Instructions
+
+  Parse `$normalized_args`:
+  - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+  - Otherwise: set `visual_mode = true`
+
+  ### Step 1: Read State
+
+  Read `.aether/data/COLONY_STATE.json`.
+
+  If file missing or `goal: null`:
+  ```
+  No colony initialized. Run /ant:init first.
+  ```
+  Stop here.
+
+  ### Step 2: Validate Colony Is Complete
+
+  Extract: `goal`, `current_phase`, `plan.phases`, `milestone`, `state`.
+
+  **Precondition 1: All phases must be completed**
+
+  Check if all phases in `plan.phases` have `status: "completed"`:
+  ```
+  all_completed = all(phase.status == "completed" for phase in plan.phases)
+  ```
+
+  If NOT all completed:
+  ```
+  Cannot archive colony with incomplete phases.
+
+  Completed phases: X of Y
+  Remaining: {list of incomplete phase names}
+
+  Run /ant:continue to complete remaining phases first.
+  ```
+  Stop here.
+
+  **Precondition 2: State must not be EXECUTING**
+
+  If `state == "EXECUTING"`:
+  ```
+  Colony is still executing. Run /ant:continue to reconcile first.
+  ```
+  Stop here.
+
+  ### Step 3: Check Milestone Eligibility
+
+  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)
+
+  **If current milestone is "Crowned Anthill":**
+  ```
+  Colony is already at Crowned Anthill milestone.
+  No further archiving needed.
+
+  Use /ant:status to view colony state.
+  ```
+  Stop here.
+
+  **If current milestone is "Sealed Chambers":**
+  - Proceed to Step 4 (will upgrade to Crowned Anthill)
+
+  **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
+
+  **If milestone is unrecognized (not in the 6 known stages):**
+  ```
+  Unknown milestone: {milestone}
+
+  The milestone "{milestone}" is not recognized.
+  Known milestones: First Mound, Open Chambers, Brood Stable, Ventilated Nest, Sealed Chambers, Crowned Anthill
+
+  Run /ant:status to check colony state.
+  ```
+  Stop here.
+
+  ### Step 4: Archive Colony State
+
+  Create archive directory:
+  ```
+  archive_dir=".aether/data/archive/session_$(date -u +%s)_archive"
+  mkdir -p "$archive_dir"
+  ```
+
+  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)
+
+  Create archive manifest file `$archive_dir/manifest.json`:
+  ```json
+  {
+    "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"
+    ]
+  }
+  ```
+
+  ### 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.
+
+  ### Step 5: Update Milestone to Crowned Anthill
+
+  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"`
+
+  ### 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" \
+    ""
+  ```
+
+  - `{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.
+
+  ### 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
+  ```
+
+  If the command fails, proceed silently. This is optional bookkeeping.
+
+  ### Step 5.25: Hive Promotion (NON-BLOCKING)
+
+  After wisdom 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
+
+  if [[ "$hive_promoted_count" -gt 0 ]]; then
+    echo "Hive promotion: $hive_promoted_count instinct(s) promoted to cross-colony hive"
+  fi
+  ```
+
+  **Continue to Step 5.5 (non-blocking):**
+  Proceed to Step 5.5 regardless of hive promotion results — hive promotion is strictly non-blocking.
+
+  ### Step 5.5: Write Final Handoff
+
+  After archiving, write the final handoff documenting the completed colony:
+
+  Resolve the handoff template path:
+    Check ~/.aether/system/templates/handoff.template.md first,
+    then .aether/templates/handoff.template.md.
+
+  If no template found: output "Template missing: handoff.template.md. Run aether update to fix." and stop.
+
+  Read the template file. Fill all {{PLACEHOLDER}} values:
+    - {{CHAMBER_NAME}} → archive directory name
+    - {{GOAL}} → goal
+    - {{PHASES_COMPLETED}} → total_phases (OpenCode seal archives completed colonies)
+    - {{TOTAL_PHASES}} → total_phases
+    - {{MILESTONE}} → "Crowned Anthill"
+    - {{ENTOMB_TIMESTAMP}} → seal timestamp
+
+  Remove the HTML comment lines at the top of the template.
+  Write the result to .aether/HANDOFF.md using the Write tool.
+
+  This handoff serves as the final record of the completed colony.
+
+  ### Step 5.75: 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
+  # 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
+
+    # 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
+
+    # 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
+
+    # 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
+  ```
+
+  ### Step 6: Display Result
+
+  Output:
+  ```
+  🏺 ════════════════════════════════════════════════════
+     C R O W N E D   A N T H I L L   v{colony_version}
+  ══════════════════════════════════════════════════ 🏺
+
+  ✅ Colony archived successfully!
+
+  👑 Goal: {goal (truncated to 60 chars)}
+  📍 Phases: {total_phases} completed
+  🏆 Milestone: Crowned Anthill v{colony_version}
+
+  📦 Archive Location: {archive_dir}
+     - COLONY_STATE.json
+     - activity.log
+     - spawn-tree.txt
+     - flags.json (if existed)
+     - constraints.json (if existed)
+  {xml_export_line}
+  {pher_export_line}
+  {wisdom_export_line}
+  {registry_export_line}
+
+  🐜 The colony has reached its final form.
+     The anthill stands crowned and sealed.
+     History is preserved. The colony rests.
+
+  💾 State persisted — safe to /clear
+
+  🐜 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
+
+  Use AskUserQuestion with these three options.
+
+  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"
+  ```
+
+  ### Step 6.5: Commit Suggestion (Non-blocking)
+
+  After the ceremony, offer to commit all colony work.
+
+  **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 6.6
+
+  **If uncommitted changes exist:**
+
+  Generate a seal commit message:
+  ```bash
+  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 // ""')
+  ```
+
+  Display the suggestion:
+  ```
+  Commit suggestion:
+    $seal_message
+    $seal_body
+  ```
+
+  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
+
+  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`.
+
+  **Error handling:** If `generate-commit-message` fails, fall back to message `"aether-seal: colony sealed"`. Never let commit suggestion failures stop the seal flow.
+
+  ### Step 6.6: Push Suggestion (Non-blocking)
+
+  Only show if a commit was just made in Step 6.5 (`seal_committed == true`) OR if there are unpushed commits.
+
+  **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
+
+  **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 on success or skip.
+
+  **Error handling:** If push fails, display the error but do not stop the seal flow.
+
+  **Safety:** Never auto-push. Always require explicit user approval.
+
+  ### Edge Cases
+
+  **If milestone is already "Sealed Chambers" but phases are complete:**
+  - Proceed with archiving and upgrade to Crowned Anthill
+
+  **If any archive files are missing:**
+  - Archive what exists, note in manifest which files were missing
+
+  **If archive directory already exists:**
+  - Append timestamp to make unique: `session_<ts>_archive_<random>`
+