aether-colony 5.0.0 → 5.2.1

package/.aether/commands/entomb.yaml

@@ -0,0 +1,863 @@
+name: "ant:entomb"
+description: "⚰️🐜⚰️ Entomb completed colony in chambers"
+body_claude: |
+  You are the **Queen**. Archive the sealed colony to chambers.
+
+  ## Instructions
+
+  Parse `$ARGUMENTS`:
+  - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+  - Otherwise: set `visual_mode = true`
+
+  <failure_modes>
+  ### Archive Write Failure
+  If writing to chambers/ archive fails partway:
+  - Do NOT delete source data (the active colony) until archive is verified
+  - Report what was archived vs. what failed
+  - Recovery: the original colony data is intact -- user can retry
+
+  ### Seal Verification Failure
+  If the colony was not properly sealed before entomb:
+  - STOP -- do not archive an incomplete colony
+  - Direct user to run /ant:seal first
+  - This is a hard gate, not a suggestion
+
+  ### Chamber Naming Conflict
+  If the target chamber directory already exists:
+  - STOP -- do not overwrite an existing archive
+  - Report the conflict
+  - Options: (1) Use a different name, (2) Merge with existing, (3) Cancel
+  </failure_modes>
+
+  <success_criteria>
+  Command is complete when:
+  - Colony data is fully copied to chambers/ archive directory
+  - Archive integrity is verified (all expected files present)
+  - Active colony state is cleared only after archive verification
+  - User sees confirmation with archive location
+  </success_criteria>
+
+  <read_only>
+  Do not touch during entomb:
+  - .aether/dreams/ (user notes -- not archived)
+  - Source code files
+  - .env* files
+  - .claude/settings.json
+  - .github/workflows/
+  - Other chamber directories (only write to the new chamber)
+  </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 to entomb. Run /ant:init first.
+  ```
+  Stop here.
+
+  Extract: `goal`, `state`, `current_phase`, `plan.phases`, `milestone`, `version`, `initialized_at`, `memory.decisions`, `memory.phase_learnings`, `memory.instincts`.
+
+  Read `colony_version` for display (default to 1 for backward compat with older colonies):
+  ```bash
+  colony_version=$(jq -r '.colony_version // 1' .aether/data/COLONY_STATE.json 2>/dev/null || echo 1)
+  [[ "$colony_version" =~ ^[0-9]+$ ]] || colony_version=1
+  ```
+
+  ### Step 2: Seal-First Enforcement
+
+  Check `milestone` in COLONY_STATE.json.
+
+  **If milestone != "Crowned Anthill":**
+  ```
+  Colony has not been sealed.
+
+  Current milestone: {milestone}
+  Required: Crowned Anthill
+
+  Run /ant:seal first to complete the sealing ceremony.
+  ```
+  Stop here.
+
+  **Belt-and-suspenders:** Also check `.aether/CROWNED-ANTHILL.md` exists. If milestone is Crowned Anthill but file is missing:
+  ```
+  CROWNED-ANTHILL.md not found — seal may have been interrupted. Run /ant:seal again.
+  ```
+  Stop here.
+
+  ### Step 3: User Confirmation
+
+  Show what will be archived:
+  ```
+  ENTOMB COLONY
+
+  Goal: {goal}
+  Version: v{colony_version}
+  Milestone: Crowned Anthill
+  Phases: {phases_completed} of {total_phases}
+
+  This will:
+    - Archive ALL colony data to .aether/chambers/
+    - Copy CROWNED-ANTHILL.md, pheromones, dreams, session data
+    - Promote colony wisdom to QUEEN.md (cross-generational learning)
+    - Reset COLONY_STATE.json for a fresh start
+    - Clear session data
+
+  This action is permanent. The archived colony can be browsed via /ant:tunnels.
+
+  Entomb this colony? (yes/no)
+  ```
+
+  Use `AskUserQuestion with yes/no options`.
+
+  If not "yes":
+  ```
+  Entombment cancelled. Colony remains active.
+  ```
+  Stop here.
+
+  ### Step 3.25: Wisdom Approval
+
+  Before archiving, review wisdom proposals accumulated during this colony's lifecycle.
+
+  ```bash
+  # 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 "   🧠 FINAL WISDOM REVIEW"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+    echo "Review wisdom proposals before archiving 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 entombment..."
+    echo ""
+  else
+    echo "No wisdom proposals to review."
+  fi
+  ```
+
+  ### Step 3.5: Check XML Tools
+
+  XML archiving is required for entombment. Check tool availability before proceeding.
+  Uses `command -v xmllint` directly — consistent with seal.md's tool check.
+
+  ```bash
+  if command -v xmllint >/dev/null 2>&1; then
+    xmllint_available=true
+  else
+    xmllint_available=false
+  fi
+  ```
+
+  **If xmllint is NOT available:**
+
+  Ask the user:
+  ```
+  xmllint is not installed — XML archiving requires it.
+
+  Install now?
+    - macOS: xcode-select --install (or brew install libxml2)
+    - Linux: apt-get install libxml2-utils
+
+  Install xmllint? (yes/no)
+  ```
+
+  Use AskUserQuestion with yes/no options.
+
+  If yes:
+  - On macOS: Run `xcode-select --install` or `brew install libxml2`
+  - On Linux: Run `sudo apt-get install -y libxml2-utils`
+  - After install attempt, re-check: `command -v xmllint >/dev/null 2>&1`
+  - If still not available after install:
+    ```
+    xmllint installation failed. Cannot entomb without XML archiving.
+    Install xmllint manually and try again.
+    ```
+    Stop here.
+
+  If no:
+  ```
+  Entombment requires XML archiving. Install xmllint and try again.
+  ```
+  Stop here.
+
+  ### Step 4: Ensure QUEEN.md Exists
+
+  Verify QUEEN.md is initialized for wisdom storage:
+
+  ```bash
+  queen_file=".aether/QUEEN.md"
+  if [[ ! -f "$queen_file" ]]; then
+    init_result=$(bash .aether/aether-utils.sh queen-init 2>/dev/null || echo '{"ok":false}')
+    init_ok=$(echo "$init_result" | jq -r '.ok // false')
+    if [[ "$init_ok" == "true" ]]; then
+      created=$(echo "$init_result" | jq -r '.result.created // false')
+      if [[ "$created" == "true" ]]; then
+        bash .aether/aether-utils.sh activity-log "CREATED" "Queen" "Initialized QUEEN.md for wisdom storage"
+      fi
+    fi
+  fi
+  ```
+
+  ### Step 5: Generate Chamber Name
+
+  Date-first naming:
+  ```bash
+  date_prefix=$(date -u +%Y-%m-%d)
+  sanitized_goal=$(echo "$goal" | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]' '-' | sed 's/^-//;s/-$//' | cut -c1-40)
+  chamber_name="${date_prefix}-${sanitized_goal}"
+  ```
+
+  Collision handling:
+  ```bash
+  counter=1
+  original_name="$chamber_name"
+  while [[ -d ".aether/chambers/$chamber_name" ]]; do
+    chamber_name="${original_name}-${counter}"
+    counter=$((counter + 1))
+  done
+  ```
+
+  ### Step 6: Create Chamber
+
+  Extract decisions and learnings as JSON arrays:
+  ```bash
+  decisions_json=$(jq -c '.memory.decisions // []' .aether/data/COLONY_STATE.json)
+  learnings_json=$(jq -c '.memory.phase_learnings // []' .aether/data/COLONY_STATE.json)
+  phases_completed=$(jq '[.plan.phases[] | select(.status == "completed")] | length' .aether/data/COLONY_STATE.json)
+  total_phases=$(jq '.plan.phases | length' .aether/data/COLONY_STATE.json)
+  version=$(jq -r '.version // "3.0"' .aether/data/COLONY_STATE.json)
+  ```
+
+  Create the chamber:
+  ```bash
+  bash .aether/aether-utils.sh chamber-create \
+    ".aether/chambers/$chamber_name" \
+    ".aether/data/COLONY_STATE.json" \
+    "$goal" \
+    "$phases_completed" \
+    "$total_phases" \
+    "$milestone" \
+    "$version" \
+    "$decisions_json" \
+    "$learnings_json"
+  ```
+
+  ### Step 7: Archive Additional Files
+
+  AFTER chamber-create succeeds, copy additional data files:
+  ```bash
+  chamber_dir=".aether/chambers/$chamber_name"
+
+  # Archive data files (if they exist)
+  for f in pheromones.json session.json activity.log flags.json constraints.json spawn-tree.txt timing.log view-state.json; do
+    [[ -f ".aether/data/$f" ]] && cp ".aether/data/$f" "$chamber_dir/" 2>/dev/null || true
+  done
+
+  # Archive seal document (critical — this is the ceremony record)
+  [[ -f ".aether/CROWNED-ANTHILL.md" ]] && cp ".aether/CROWNED-ANTHILL.md" "$chamber_dir/"
+
+  # Archive HANDOFF.md if it exists
+  [[ -f ".aether/HANDOFF.md" ]] && cp ".aether/HANDOFF.md" "$chamber_dir/"
+
+  # Archive dreams directory (optional — may not exist)
+  [[ -d ".aether/dreams" ]] && cp -r ".aether/dreams" "$chamber_dir/dreams" 2>/dev/null || true
+
+  # Archive XML exchange files to chamber (per D-04, D-05)
+  xml_archived=0
+  for xml_file in .aether/exchange/*.xml; do
+    [[ -f "$xml_file" ]] && cp "$xml_file" "$chamber_dir/" && xml_archived=$((xml_archived + 1))
+  done
+  if [[ "$xml_archived" -gt 0 ]]; then
+    echo "XML Archive: ${xml_archived} exchange file(s) copied to chamber"
+  fi
+  ```
+
+  Do NOT copy: `.aether/data/backups/`, `.aether/data/locks/`, `.aether/data/midden/`, `.aether/data/survey/`.
+
+  ### Step 7.5: Export XML Archive (hard-stop)
+
+  Export combined XML archive to the chamber. This is a HARD REQUIREMENT — entomb fails if XML export fails.
+
+  ```bash
+  chamber_dir=".aether/chambers/$chamber_name"
+  xml_result=$(bash .aether/aether-utils.sh colony-archive-xml "$chamber_dir/colony-archive.xml" 2>&1)
+  xml_ok=$(echo "$xml_result" | jq -r '.ok // false' 2>/dev/null)
+
+  if [[ "$xml_ok" != "true" ]]; then
+    # HARD STOP — remove the chamber and abort
+    rm -rf "$chamber_dir"
+    echo "XML archive export failed. Colony NOT entombed."
+    echo ""
+    echo "Error: $(echo "$xml_result" | jq -r '.error // "Unknown error"' 2>/dev/null)"
+    echo ""
+    echo "The chamber has been cleaned up. Fix the XML issue and try again."
+    # Do NOT proceed to state reset or any further steps
+  fi
+  ```
+
+  If xml_ok is true, store for display:
+  ```bash
+  xml_pheromone_count=$(echo "$xml_result" | jq -r '.result.pheromone_count // 0' 2>/dev/null)
+  xml_exchange_count=$(find .aether/exchange -maxdepth 1 -name "*.xml" 2>/dev/null | wc -l | tr -d ' ')
+  xml_archive_line="XML Archive: colony-archive.xml (${xml_pheromone_count} signals) + ${xml_exchange_count} exchange file(s)"
+  ```
+
+  **Critical behavior:** If XML export fails, entomb STOPS. The chamber directory is removed (cleanup). The colony state is NOT reset. The user sees a clear error and can retry after fixing the issue.
+
+  ### Step 8: Verify Chamber Integrity
+
+  Run verification:
+  ```bash
+  bash .aether/aether-utils.sh chamber-verify ".aether/chambers/$chamber_name"
+  ```
+
+  If verification fails, display error and stop:
+  ```
+  Chamber verification failed.
+
+  Error: {verification_error}
+
+  The colony has NOT been reset. Please check the chamber directory:
+  .aether/chambers/{chamber_name}/
+  ```
+  Stop here.
+
+  ### Step 9: Record in Eternal Memory
+
+  Write colony summary to eternal memory:
+  ```bash
+  bash .aether/aether-utils.sh eternal-init  # idempotent
+  eternal_file="$HOME/.aether/eternal/memory.json"
+  if [[ -f "$eternal_file" ]]; then
+    colony_entry=$(jq -n \
+      --arg goal "$goal" \
+      --arg milestone "$milestone" \
+      --arg sealed_at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+      --arg chamber ".aether/chambers/$chamber_name" \
+      '{goal: $goal, milestone: $milestone, sealed_at: $sealed_at, chamber: $chamber}')
+    tmp_eternal="$(mktemp /tmp/aether-eternal.XXXXXX)"
+    jq --argjson colony_entry "$colony_entry" '.colonies = ((.colonies // []) + [$colony_entry])' "$eternal_file" > "$tmp_eternal" \
+      && mv "$tmp_eternal" "$eternal_file"
+  fi
+  ```
+
+  ### Step 10: Reset Colony State
+
+  Backup current state:
+  ```bash
+  cp .aether/data/COLONY_STATE.json .aether/data/COLONY_STATE.json.bak
+  ```
+
+  Reset state, clearing everything including promoted wisdom (already in QUEEN.md):
+  ```bash
+  # Resolve jq template path (hub-first)
+  jq_template=""
+  for path in \
+    "$HOME/.aether/system/templates/colony-state-reset.jq.template" \
+    ".aether/templates/colony-state-reset.jq.template"; do
+    if [[ -f "$path" ]]; then
+      jq_template="$path"
+      break
+    fi
+  done
+
+  if [[ -z "$jq_template" ]]; then
+    echo "Template missing: colony-state-reset.jq.template. Run aether update to fix."
+    exit 1
+  fi
+
+  jq -f "$jq_template" .aether/data/COLONY_STATE.json.bak > .aether/data/COLONY_STATE.json
+  ```
+
+  Verify reset succeeded:
+  ```bash
+  new_goal=$(jq -r '.goal' .aether/data/COLONY_STATE.json)
+  if [[ "$new_goal" != "null" ]]; then
+    # Restore from backup
+    mv .aether/data/COLONY_STATE.json.bak .aether/data/COLONY_STATE.json
+    echo "Error: State reset failed. Restored from backup."
+    exit 1
+  fi
+  ```
+
+  Remove backup after successful reset:
+  ```bash
+  rm -f .aether/data/COLONY_STATE.json.bak
+  ```
+
+  Clear session data:
+  ```bash
+  rm -f .aether/data/session.json
+  ```
+
+  Clean up seal document (it's now in the chamber):
+  ```bash
+  rm -f .aether/CROWNED-ANTHILL.md
+  ```
+
+  Clean up exchange XML files (now archived in chamber per D-06):
+  ```bash
+  rm -f .aether/exchange/*.xml 2>/dev/null || true
+  ```
+
+  ### Step 11: Write HANDOFF.md
+
+  Write handoff documenting the entombed 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}} → chamber_name
+    - {{GOAL}} → goal
+    - {{PHASES_COMPLETED}} → phases completed count
+    - {{TOTAL_PHASES}} → total phases count
+    - {{MILESTONE}} → milestone
+    - {{ENTOMB_TIMESTAMP}} → current ISO-8601 UTC timestamp
+
+  Remove the HTML comment lines at the top of the template.
+  Write the result to .aether/HANDOFF.md using the Write tool.
+
+  ### Step 12: Display Result
+
+  Display:
+  ```
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+     C O L O N Y   E N T O M B E D
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Entombed v{colony_version}
+
+  Goal: {goal}
+  Phases: {completed} completed
+  Milestone: {milestone}
+
+  Chamber: .aether/chambers/{chamber_name}/
+  {xml_archive_line}
+
+  The colony rests. Its learnings live on in QUEEN.md.
+
+  ──────────────────────────────────────────────────
+  🐜 Next Up
+  ──────────────────────────────────────────────────
+     /ant:lay-eggs            🥚 Start a new colony
+     /ant:tunnels             🗄️  Browse archived chambers
+  ```
+
+  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"
+  ```
+
+  ### Edge Cases
+
+  **Colony not sealed:**
+  - Refuse with guidance to run /ant:seal first. This is the primary gate.
+
+  **Chamber name collision:**
+  - Automatically append counter to make unique.
+
+  **Missing files during archive:**
+  - Note in output but continue with available files. The `|| true` in the copy loop handles this.
+
+  **State reset failure:**
+  - Restore from backup, display error, do not claim success.
+
+  **Empty phases array:**
+  - Can entomb a colony that was initialized but had no phases planned (treat as 0 of 0 completed).
+
+  **Missing CROWNED-ANTHILL.md:**
+  - Refuse with guidance to run /ant:seal again.
+
+body_opencode: |
+  You are the **Queen**. Archive the completed colony to chambers.
+
+  ## 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 to entomb. Run /ant:init first.
+  ```
+  Stop here.
+
+  ### Step 2: Validate Colony Can Be Entombed
+
+  Extract: `goal`, `state`, `current_phase`, `plan.phases`, `memory.decisions`, `memory.phase_learnings`.
+
+  Read `colony_version` for display (default to 1 for backward compat with older colonies):
+  ```bash
+  colony_version=$(jq -r '.colony_version // 1' .aether/data/COLONY_STATE.json 2>/dev/null || echo 1)
+  [[ "$colony_version" =~ ^[0-9]+$ ]] || colony_version=1
+  ```
+
+  **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 entomb incomplete colony.
+
+  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.
+
+  **Precondition 3: No critical errors**
+
+  Check `errors.records` for any entries with `severity: "critical"`.
+
+  If critical errors exist:
+  ```
+  Cannot entomb colony with critical errors.
+
+  Critical errors: {count}
+  Run /ant:continue to resolve errors first.
+  ```
+  Stop here.
+
+  ### Step 3: Compute Milestone
+
+  Determine milestone based on phases completed:
+  - 0 phases: "Fresh Start"
+  - 1 phase: "First Mound"
+  - 2-4 phases: "Open Chambers"
+  - 5+ phases: "Sealed Chambers"
+
+  If all phases completed AND user explicitly sealing: "Crowned Anthill"
+
+  For entombment, use the computed milestone or extract from state if already set.
+
+  ### Step 4: User Confirmation
+
+  Display:
+  ```
+  🏺 ═══════════════════════════════════════════════════
+     E N T O M B   C O L O N Y
+  ══════════════════════════════════════════════════ 🏺
+
+  Goal: {goal}
+  Version: v{colony_version}
+  Phases: {completed}/{total} completed
+  Milestone: {milestone}
+
+  Archive will include:
+    - COLONY_STATE.json
+    - manifest.json (pheromone trails)
+
+  This will reset the active colony. Continue? (yes/no)
+  ```
+
+  Wait for explicit "yes" response before proceeding.
+
+  If user responds with anything other than "yes", display:
+  ```
+  Entombment cancelled. Colony remains active.
+  ```
+  Stop here.
+
+  ### Step 4.5: Check XML Tools
+
+  XML archiving is required for entombment. Check tool availability before proceeding.
+  Uses `command -v xmllint` directly — consistent with seal.md's tool check.
+
+  ```bash
+  if command -v xmllint >/dev/null 2>&1; then
+    xmllint_available=true
+  else
+    xmllint_available=false
+  fi
+  ```
+
+  **If xmllint is NOT available:**
+
+  Ask the user:
+  ```
+  xmllint is not installed — XML archiving requires it.
+
+  Install now?
+    - macOS: xcode-select --install (or brew install libxml2)
+    - Linux: apt-get install libxml2-utils
+
+  Install xmllint? (yes/no)
+  ```
+
+  Use AskUserQuestion with yes/no options.
+
+  If yes:
+  - On macOS: Run `xcode-select --install` or `brew install libxml2`
+  - On Linux: Run `sudo apt-get install -y libxml2-utils`
+  - After install attempt, re-check: `command -v xmllint >/dev/null 2>&1`
+  - If still not available after install:
+    ```
+    xmllint installation failed. Cannot entomb without XML archiving.
+    Install xmllint manually and try again.
+    ```
+    Stop here.
+
+  If no:
+  ```
+  Entombment requires XML archiving. Install xmllint and try again.
+  ```
+  Stop here.
+
+  ### Step 5: Create Chamber
+
+  Generate chamber name:
+  ```bash
+  sanitized_goal=$(echo "{goal}" | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]' '-' | sed 's/^-//;s/-$//' | cut -c1-50)
+  timestamp=$(date -u +%Y%m%d-%H%M%S)
+  chamber_name="${sanitized_goal}-${timestamp}"
+  ```
+
+  Handle name collision: if directory exists, append counter:
+  ```bash
+  counter=1
+  original_name="$chamber_name"
+  while [[ -d ".aether/chambers/$chamber_name" ]]; do
+    chamber_name="${original_name}-${counter}"
+    counter=$((counter + 1))
+  done
+  ```
+
+  ### Step 6: Create Chamber Using Utilities
+
+  Extract decisions and learnings as JSON arrays:
+  ```bash
+  decisions_json=$(jq -c '.memory.decisions // []' .aether/data/COLONY_STATE.json)
+  learnings_json=$(jq -c '.memory.phase_learnings // []' .aether/data/COLONY_STATE.json)
+  phases_completed=$(jq '[.plan.phases[] | select(.status == "completed")] | length' .aether/data/COLONY_STATE.json)
+  total_phases=$(jq '.plan.phases | length' .aether/data/COLONY_STATE.json)
+  version=$(jq -r '.version // "3.0"' .aether/data/COLONY_STATE.json)
+  ```
+
+  Create the chamber:
+  ```bash
+  bash .aether/aether-utils.sh chamber-create \
+    ".aether/chambers/{chamber_name}" \
+    ".aether/data/COLONY_STATE.json" \
+    "{goal}" \
+    {phases_completed} \
+    {total_phases} \
+    "{milestone}" \
+    "{version}" \
+    '{decisions_json}' \
+    '{learnings_json}'
+  ```
+
+  ### Step 6.5: Export XML Archive (hard-stop)
+
+  Export combined XML archive to the chamber. This is a HARD REQUIREMENT — entomb fails if XML export fails.
+
+  ```bash
+  chamber_dir=".aether/chambers/$chamber_name"
+  xml_result=$(bash .aether/aether-utils.sh colony-archive-xml "$chamber_dir/colony-archive.xml" 2>&1)
+  xml_ok=$(echo "$xml_result" | jq -r '.ok // false' 2>/dev/null)
+
+  if [[ "$xml_ok" != "true" ]]; then
+    # HARD STOP — remove the chamber and abort
+    rm -rf "$chamber_dir"
+    echo "XML archive export failed. Colony NOT entombed."
+    echo ""
+    echo "Error: $(echo "$xml_result" | jq -r '.error // "Unknown error"' 2>/dev/null)"
+    echo ""
+    echo "The chamber has been cleaned up. Fix the XML issue and try again."
+    # Do NOT proceed to state reset or any further steps
+  fi
+  ```
+
+  If xml_ok is true, store for display:
+  ```bash
+  xml_pheromone_count=$(echo "$xml_result" | jq -r '.result.pheromone_count // 0' 2>/dev/null)
+  xml_exchange_count=$(find .aether/exchange -maxdepth 1 -name "*.xml" 2>/dev/null | wc -l | tr -d ' ')
+  xml_archive_line="XML Archive: colony-archive.xml (${xml_pheromone_count} signals) + ${xml_exchange_count} exchange file(s)"
+  ```
+
+  **Critical behavior:** If XML export fails, entomb STOPS. The chamber directory is removed (cleanup). The colony state is NOT reset. The user sees a clear error and can retry after fixing the issue.
+
+  **Copy exchange XML files to chamber (per D-04, D-05):**
+  ```bash
+  xml_archived=0
+  for xml_file in .aether/exchange/*.xml; do
+    [[ -f "$xml_file" ]] && cp "$xml_file" ".aether/chambers/$chamber_name/" && xml_archived=$((xml_archived + 1))
+  done
+  ```
+
+  ### Step 7: Verify Chamber Integrity
+
+  Run verification:
+  ```bash
+  bash .aether/aether-utils.sh chamber-verify ".aether/chambers/{chamber_name}"
+  ```
+
+  If verification fails, display error and stop:
+  ```
+  ❌ Chamber verification failed.
+
+  Error: {verification_error}
+
+  The colony has NOT been reset. Please check the chamber directory:
+  .aether/chambers/{chamber_name}/
+  ```
+  Stop here.
+
+  ### Step 8: Reset Colony State
+
+  Backup current state:
+  ```bash
+  cp .aether/data/COLONY_STATE.json .aether/data/COLONY_STATE.json.bak
+  ```
+
+  Reset state (including memory fields, already promoted to QUEEN.md):
+  ```bash
+  # Resolve jq template path (hub-first)
+  jq_template=""
+  for path in \
+    "$HOME/.aether/system/templates/colony-state-reset.jq.template" \
+    ".aether/templates/colony-state-reset.jq.template"; do
+    if [[ -f "$path" ]]; then
+      jq_template="$path"
+      break
+    fi
+  done
+
+  if [[ -z "$jq_template" ]]; then
+    echo "Template missing: colony-state-reset.jq.template. Run aether update to fix."
+    exit 1
+  fi
+
+  jq -f "$jq_template" .aether/data/COLONY_STATE.json.bak > .aether/data/COLONY_STATE.json
+  ```
+
+  Verify reset succeeded:
+  ```bash
+  new_goal=$(jq -r '.goal' .aether/data/COLONY_STATE.json)
+  if [[ "$new_goal" != "null" ]]; then
+    # Restore from backup
+    mv .aether/data/COLONY_STATE.json.bak .aether/data/COLONY_STATE.json
+    echo "Error: State reset failed. Restored from backup."
+    exit 1
+  fi
+  ```
+
+  Remove backup after successful reset:
+  ```bash
+  rm -f .aether/data/COLONY_STATE.json.bak
+  ```
+
+  Clean up exchange XML files (now archived in chamber per D-06):
+  ```bash
+  rm -f .aether/exchange/*.xml 2>/dev/null || true
+  ```
+
+  ### Step 8.5: Write Final Handoff
+
+  After entombing the colony, write the final handoff documenting the archived 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}} → chamber_name
+    - {{GOAL}} → goal
+    - {{PHASES_COMPLETED}} → phases completed count
+    - {{TOTAL_PHASES}} → total phases count
+    - {{MILESTONE}} → milestone
+    - {{ENTOMB_TIMESTAMP}} → current ISO-8601 UTC 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 record of the entombed colony.
+
+  ### Step 9: Display Result
+
+  ```
+  🏺 ═══════════════════════════════════════════════════
+     C O L O N Y   E N T O M B E D
+  ══════════════════════════════════════════════════ 🏺
+
+  ✅ Entombed v{colony_version}
+
+  👑 Goal: {goal}
+  📍 Phases: {completed} completed
+  🏆 Milestone: {milestone}
+
+  📦 Chamber: .aether/chambers/{chamber_name}/
+  {xml_archive_line}
+
+  🐜 The colony rests. Its learnings are preserved.
+
+  💾 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"
+  ```
+
+  ### Edge Cases
+
+  **Chamber name collision:** Automatically append counter to make unique.
+
+  **Missing files during archive:** Note in output but continue with available files.
+
+  **State reset failure:** Restore from backup, display error, do not claim success.
+
+  **Empty phases array:** Can entomb a colony that was initialized but had no phases planned (treat as 0 of 0 completed).
+