aether-colony 3.1.17 → 5.0.0

package/.opencode/commands/ant/resume.md

@@ -0,0 +1,334 @@
+---
+name: ant:resume
+description: "Resume Previous Session"
+---
+
+# /ant:resume — Resume Previous Session
+
+Resume work after `/clear` or in a new session. Reads colony state, detects codebase drift, and gives you a clear "do this next" recommendation.
+
+## Usage
+
+```bash
+/ant:resume
+```
+
+---
+
+## Implementation
+
+Execute the following steps in order when the user runs `/ant:resume`.
+
+---
+
+### Step 1: Read Session State
+
+Run using the Bash tool with description "Restoring colony session...":
+```bash
+bash .aether/aether-utils.sh session-read
+```
+
+Parse the JSON result.
+
+- If `exists` is `false`: display the following and **stop**:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+RESUME SESSION
+
+No previous session found.
+
+Start fresh: /ant:init "your goal"
+Or check: /ant:status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+- If `exists` is `true`: extract from the session data:
+  - `colony_goal`
+  - `current_phase`
+  - `last_command`
+  - `suggested_next`
+  - `baseline_commit`
+  - `session_id`
+
+---
+
+### Step 2: Read COLONY_STATE.json (Authoritative Source)
+
+Use the Read tool to read `.aether/data/COLONY_STATE.json`.
+
+COLONY_STATE.json is the authoritative source for goal and state (session.json may be stale). Extract:
+- `goal` (use this as authoritative, overriding session.json colony_goal)
+- `state` (READY, PLANNING, EXECUTING, PAUSED)
+- `current_phase`
+- `plan.phases` (array with id, name, status for each phase)
+- `plan.generated_at`
+- `memory.decisions` (flat list — do NOT distinguish user vs Claude origin)
+- `events` (last 5 for recent activity context)
+
+If the file is missing or the JSON cannot be parsed, **stop immediately** and display:
+
+```
+State file missing or corrupted.
+
+Options:
+1. Start fresh with /ant:init "goal"
+2. Try to recover (I'll look for backup files)
+
+What would you like to do?
+```
+
+Do NOT proceed with stale or fabricated data.
+
+---
+
+### Step 3: Read Pheromone Signals
+
+Use the Read tool to read `.aether/data/constraints.json`.
+
+Extract the following top-level keys:
+- `focus` array — active focus signals (if key missing, treat as empty array)
+- `constraints` array — active redirect/constraint signals (if key missing, treat as empty array)
+
+If the file is missing: skip silently (no pheromones active).
+
+Pheromones persist until explicitly cleared — no decay.
+
+---
+
+### Step 4: Read CONTEXT.md
+
+Use the Read tool to read `.aether/CONTEXT.md` if it exists.
+
+If missing: fall back to COLONY_STATE.json for narrative context. Note: "Context document not found — reconstructing from state."
+
+---
+
+### Step 5: Drift Detection
+
+Extract `baseline_commit` from the session.json data read in Step 1.
+
+```bash
+current_commit=$(git rev-parse HEAD 2>/dev/null || echo "")
+```
+
+If `baseline_commit` is non-empty and differs from `current_commit`:
+
+```bash
+commit_count=$(git rev-list --count "$baseline_commit..HEAD" 2>/dev/null || echo "0")
+changed_count=$(git diff --stat "$baseline_commit" HEAD 2>/dev/null | tail -1 | grep -oE '[0-9]+ file' | grep -oE '[0-9]+' || echo "0")
+```
+
+Store `drift_detected=true`, `commit_count`, `changed_count` for dashboard rendering.
+
+If `baseline_commit` is empty or matches `current_commit`: set `drift_detected=false`.
+
+Restore identically regardless of time elapsed — no warnings about session age.
+
+---
+
+### Step 6: Compute Workflow Position and Next-Step Guidance
+
+Compute `suggested_next` dynamically from COLONY_STATE.json data. Do not use the static value from session.json.
+
+Use this decision tree:
+
+```
+Case 1 — No plan created yet:
+  Check: plan.phases is empty AND plan.generated_at is null
+  recommended = "/ant:plan"
+  reason = "No plan created yet"
+  alternatives = ["/ant:colonize — analyze codebase first"]
+
+Case 2 — Plan ready, first phase not started:
+  Check: plan.phases is not empty AND state == "READY" AND current_phase == 0
+  recommended = "/ant:build 1"
+  reason = "Plan ready, first phase not started"
+  alternatives = ["/ant:plan — review or regenerate plan"]
+
+Case 3 — Build in progress:
+  Check: state == "EXECUTING"
+  recommended = "/ant:continue"
+  reason = "Build in progress"
+  alternatives = ["/ant:build {current_phase} — rebuild current phase", "/ant:flags — check for blockers"]
+
+Case 4 — Phase complete, next phase available:
+  Check: state == "READY" AND current_phase > 0 AND current_phase < plan.phases.length
+  next = current_phase + 1
+  recommended = "/ant:build {next}"
+  reason = "Phase {current_phase} complete, ready for next"
+  alternatives = ["/ant:plan — regenerate plan", "/ant:phase {next} — preview next phase"]
+
+Case 5 — All phases complete:
+  Check: state == "READY" AND current_phase > 0 AND current_phase >= plan.phases.length
+  recommended = "/ant:seal"
+  reason = "All phases complete"
+  alternatives = ["/ant:status — view final state"]
+
+Case 6 — Colony paused:
+  Check: state == "PAUSED"
+  recommended = "/ant:resume-colony"
+  reason = "Colony is paused"
+  alternatives = ["/ant:status — check state first"]
+
+Default:
+  recommended = "/ant:status"
+  reason = "Check colony status"
+  alternatives = []
+```
+
+---
+
+### Step 7: Workflow-Step Blocking (Early-Return Guards)
+
+Run these guards BEFORE rendering the dashboard. If a blocking condition is detected, output the block message and STOP. Do not render the dashboard. Do not offer alternative commands.
+
+**BLOCK CONDITION 1: No plan exists**
+
+Check: plan.phases is empty AND plan.generated_at is null
+
+Output and STOP:
+
+```
+BLOCKED: No plan exists yet.
+Required: Run /ant:plan to create a build plan.
+Goal: {goal}
+```
+
+Stop here — do not continue to Step 8 or render the dashboard.
+
+---
+
+**BLOCK CONDITION 2: Plan attempted but failed**
+
+Check: plan.phases is empty AND plan.generated_at is not null
+
+Output and STOP:
+
+```
+BLOCKED: Plan was attempted but has no phases.
+Required: Run /ant:plan to regenerate the plan.
+Goal: {goal}
+```
+
+Stop here — do not continue to Step 8 or render the dashboard.
+
+---
+
+**BLOCK CONDITION 3: Build interrupted**
+
+Check: state == "EXECUTING" AND the last 3 events show no recent build activity
+
+Output and STOP:
+
+```
+BLOCKED: Build may have been interrupted.
+Required: Run /ant:continue to check and advance.
+Goal: {goal}
+```
+
+Stop here — do not continue to Step 8 or render the dashboard.
+
+---
+
+### Step 8: Render Dashboard
+
+Lead with the next-step recommendation. Context follows underneath ("straight to action" ordering).
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+RESUME SESSION
+
+Next: {recommended}
+      {reason}
+{if alternatives exist:}
+Also: {alternatives, comma-separated}
+{end}
+
+{if drift_detected:}
+Note: Codebase changed since last session ({commit_count} commit(s), {changed_count} file(s) modified)
+{end}
+
+Goal: {goal}
+State: {state}
+Phase: {current_phase}/{total_phases}
+
+Phase Progress:
+{for each phase in plan.phases:}
+  [{status_icon}] Phase {id}: {name}
+{end}
+```
+
+Status icons:
+- completed: `v` (checkmark)
+- in_progress: `~` (tilde)
+- pending: ` ` (space)
+
+```
+{if memory.decisions is not empty:}
+Recent Decisions:
+{for each of the last 5 decisions:}
+  - {decision text}
+{end}
+{end}
+
+{if focus array or constraints array is not empty:}
+Active Signals:
+{for each focus signal:}
+  FOCUS: {focus text}
+{end}
+{for each constraint signal:}
+  REDIRECT: {constraint text}
+{end}
+{end}
+
+Last Command: {last_command}
+Session: {session_id}
+```
+
+---
+
+### Step 9: Mark Session Resumed
+
+Run using the Bash tool with description "Marking session as resumed...":
+```bash
+bash .aether/aether-utils.sh session-mark-resumed
+```
+
+### Step 10: Next Up
+
+Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json)
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
+```
+
+---
+
+## Error Handling Reference
+
+| Condition | Response |
+|-----------|----------|
+| session.json missing (exists=false) | "No previous session found" — offer /ant:init and /ant:status |
+| COLONY_STATE.json missing or corrupted | Pause, ask user: start fresh or recover |
+| constraints.json missing | Skip silently (no pheromones) |
+| CONTEXT.md missing | Fall back to COLONY_STATE.json narrative |
+| No plan phases, no generated_at | BLOCK — redirect to /ant:plan |
+| Plan attempted but no phases | BLOCK — redirect to /ant:plan |
+| State EXECUTING, events show no activity | BLOCK — redirect to /ant:continue |
+| baseline_commit matches current HEAD | No drift warning shown |
+| baseline_commit differs from current HEAD | Show informational drift note |
+
+---
+
+## Key Constraints
+
+- Use Read tool for COLONY_STATE.json and constraints.json (not bash cat/jq)
+- Use Bash tool only for aether-utils.sh commands and git commands
+- Handle ALL missing/corrupted file cases gracefully
+- Time-agnostic: restore identically regardless of how long ago the session was
+- Decisions shown as flat list — no user vs Claude distinction
+- Blocking guards run BEFORE dashboard rendering (early-return pattern)
+- Drift detection is informational only — not alarming, not a blocker

package/.opencode/commands/ant/seal.md

@@ -150,36 +150,44 @@ Update COLONY_STATE.json:
 
 After archiving, write the final handoff documenting the completed colony:
 
-```bash
-cat > .aether/HANDOFF.md << 'HANDOFF_EOF'
-# Colony Session — SEALED (Crowned Anthill)
+Resolve the handoff template path:
+  Check ~/.aether/system/templates/handoff.template.md first,
+  then .aether/templates/handoff.template.md.
 
-## 🏆 Colony Complete
-**Status:** Crowned Anthill — All phases completed and archived
+If no template found: output "Template missing: handoff.template.md. Run aether update to fix." and stop.
 
-## Archive Location
-{archive_dir}
+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
 
-## Colony Summary
-- Goal: "{goal}"
-- Total Phases: {total_phases}
-- Milestone: Crowned Anthill
-- Sealed At: {timestamp}
+Remove the HTML comment lines at the top of the template.
+Write the result to .aether/HANDOFF.md using the Write tool.
 
-## Files Archived
-- COLONY_STATE.json
-- activity.log
-- spawn-tree.txt
-- flags.json (if existed)
-- constraints.json (if existed)
+This handoff serves as the final record of the completed colony.
 
-## Session Note
-This colony has been sealed and archived. The anthill stands crowned.
-To start anew, run: /ant:lay-eggs "<new goal>"
-HANDOFF_EOF
-```
+### Step 5.75: Export XML Archive (best-effort)
 
-This handoff serves as the final record of the completed colony.
+Export colony data as a combined XML archive. This is 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
+else
+  xml_export_line="XML Archive: skipped (xmllint not available)"
+fi
+```
 
 ### Step 6: Display Result
 
@@ -207,6 +215,7 @@ Output:
    - spawn-tree.txt
    - flags.json (if existed)
    - constraints.json (if existed)
+{xml_export_line}
 
 🐜 The colony has reached its final form.
    The anthill stands crowned and sealed.

package/.opencode/commands/ant/status.md

@@ -114,6 +114,14 @@ Extract:
 - Issues count (high, warnings)
 - Notes count (low, informational)
 
+**Escalation state:**
+Count escalated flags by checking for blocker flags with source "escalation":
+
+```bash
+escalated_count=$(bash .aether/aether-utils.sh flag-list --type blocker 2>/dev/null | jq '[.result.flags[] | select(.source == "escalation")] | length' 2>/dev/null || echo "0")
+echo "escalated_count=$escalated_count"
+```
+
 **Instincts:**
 From `memory.instincts`:
 - Total count: `instincts.length`
@@ -156,6 +164,9 @@ Output format:
 🎯 Focus: <focus_count> areas | 🚫 Avoid: <constraints_count> patterns
 🧠 Instincts: <total> learned (<high_confidence> strong)
 🚩 Flags: <blockers> blockers | <issues> issues | <notes> notes
+{if escalated_count > 0:}
+⚠️  Escalated: {escalated_count} task(s) awaiting your decision
+{end if}
 🏆 Milestone: <milestone> (<version>)
 💭 Dreams: <dream_count> recorded (latest: <latest_dream>)
 

package/.opencode/commands/ant/tunnels.md

@@ -106,6 +106,37 @@ To get the counts and hash status:
 - If not verified: hash_status = "⚠️ hash mismatch"
 - If error: hash_status = "⚠️ error"
 
+Check if `colony-archive.xml` exists in the chamber:
+
+```bash
+chamber_has_xml=false
+[[ -f ".aether/chambers/{chamber_name}/colony-archive.xml" ]] && chamber_has_xml=true
+```
+
+**If `colony-archive.xml` exists**, add import option to the detail view footer:
+```
+📁 Files:
+   - COLONY_STATE.json (verified: {hash_status})
+   - manifest.json
+   - colony-archive.xml (XML Archive)
+
+Actions:
+  1. Import signals from this colony into current colony
+  2. Return to chamber list
+
+Select an action (1/2)
+```
+
+Use AskUserQuestion with two options.
+
+If option 1 selected: proceed to Step 6 (Import Signals from Chamber).
+If option 2 selected: return to chamber list (run /ant:tunnels).
+
+**If `colony-archive.xml` does NOT exist**, show existing footer unchanged:
+```
+Run /ant:tunnels to return to chamber list.
+```
+
 Stop here.
 
 ### Step 5: Chamber Comparison Mode (Two Arguments)
@@ -231,6 +262,124 @@ Run /ant:tunnels <chamber_name> to view details
 - Missing COLONY_STATE.json: show "⚠️  Incomplete chamber" for that chamber
 - Very long chamber list: display all (no pagination for now)
 
+### Step 6: Import Signals from Chamber
+
+When user selects "Import signals" from Step 3:
+
+**Step 6.1: Check XML tools**
+```bash
+if command -v xmllint >/dev/null 2>&1; then
+  xmllint_available=true
+else
+  xmllint_available=false
+fi
+```
+
+If xmllint not available:
+```
+Import requires xmllint. Install it first:
+  macOS: xcode-select --install
+  Linux: apt-get install libxml2-utils
+```
+Stop here (return to chamber list).
+
+**Step 6.2: Extract source colony name**
+```bash
+chamber_xml=".aether/chambers/{chamber_name}/colony-archive.xml"
+# Extract colony_id from the archive root element
+source_colony=$(xmllint --xpath "string(/*/@colony_id)" "$chamber_xml" 2>/dev/null)
+[[ -z "$source_colony" ]] && source_colony="{chamber_name}"
+```
+
+**Step 6.3: Extract pheromone section and show import preview**
+
+The combined `colony-archive.xml` contains pheromones, wisdom, and registry sections. Extract the pheromone section to a temp file before counting or importing. This prevents over-counting signals from wisdom/registry sections and ensures `pheromone-import-xml` receives the format it expects (`<pheromones>` as root element).
+
+```bash
+# Extract the <pheromones> section from the combined archive into a standalone temp file
+import_tmp_dir=$(mktemp -d)
+import_tmp_pheromones="$import_tmp_dir/pheromones-extracted.xml"
+
+# Use xmllint to extract the pheromones element (with its namespace)
+xmllint --xpath "//*[local-name()='pheromones']" "$chamber_xml" > "$import_tmp_pheromones" 2>/dev/null
+
+# Add XML declaration to make it a standalone well-formed document
+if [[ -s "$import_tmp_pheromones" ]]; then
+  # Portable approach: prepend declaration via temp file (avoids macOS/Linux sed -i differences)
+  { echo '<?xml version="1.0" encoding="UTF-8"?>'; cat "$import_tmp_pheromones"; } > "$import_tmp_dir/tmp_decl.xml"
+  mv "$import_tmp_dir/tmp_decl.xml" "$import_tmp_pheromones"
+fi
+
+# Count pheromone signals in extracted pheromone-only XML
+# Scoped to pheromone section only — no over-counting from wisdom/registry sections
+pheromone_count=$(xmllint --xpath "count(//*[local-name()='signal'])" "$import_tmp_pheromones" 2>/dev/null || echo "unknown")
+```
+
+Display:
+```
+IMPORT FROM COLONY: {source_colony}
+
+Source: .aether/chambers/{chamber_name}/colony-archive.xml
+Signals available: ~{pheromone_count} pheromone signals
+
+Import behavior:
+  - Signals tagged with prefix "{source_colony}:" to identify origin
+  - Additive merge — your current signals are never overwritten
+  - On conflict, your current colony wins
+
+Import these signals? (yes/no)
+```
+
+Use AskUserQuestion with yes/no options.
+
+If no: "Import cancelled." Clean up: `rm -rf "$import_tmp_dir"`. Return to chamber list.
+
+**Step 6.4: Perform import**
+
+Pass the extracted pheromone-only temp file (NOT the combined `colony-archive.xml`) to `pheromone-import-xml`, along with `$source_colony` as the second argument. This ensures:
+1. `pheromone-import-xml` receives XML with `<pheromones>` as root element (the format it expects)
+2. The prefix-tagging logic prepends `${source_colony}:` to each imported signal's ID before the merge
+
+```bash
+# Import the EXTRACTED pheromone-only XML (NOT the combined colony-archive.xml)
+# $import_tmp_pheromones has <pheromones> as root — the format pheromone-import-xml expects
+# Second argument triggers prefix-tagging — imported signal IDs become "{source_colony}:original_id"
+import_result=$(bash .aether/aether-utils.sh pheromone-import-xml "$import_tmp_pheromones" "$source_colony" 2>&1)
+import_ok=$(echo "$import_result" | jq -r '.ok // false' 2>/dev/null)
+
+if [[ "$import_ok" == "true" ]]; then
+  imported_count=$(echo "$import_result" | jq -r '.result.signal_count // 0' 2>/dev/null)
+else
+  imported_count=0
+  import_error=$(echo "$import_result" | jq -r '.error // "Unknown error"' 2>/dev/null)
+fi
+
+# Clean up temp files
+rm -rf "$import_tmp_dir"
+```
+
+**Step 6.5: Display result**
+
+If import succeeded:
+```
+SIGNALS IMPORTED
+
+Source: {source_colony}
+Imported: {imported_count} pheromone signals
+Tagged with: "{source_colony}:" prefix
+
+Your colony now carries wisdom from {source_colony}.
+Run /ant:status to see current colony state.
+```
+
+If import failed:
+```
+Import failed: {import_error}
+
+The archive may be malformed. Check:
+  .aether/chambers/{chamber_name}/colony-archive.xml
+```
+
 ## Implementation Notes
 
 The `chamber-list` utility returns JSON in this format: