aether-colony 3.1.17 → 5.0.0

package/{runtime → .aether}/exchange/registry-xml.sh

@@ -66,7 +66,7 @@ xml-registry-export() {
         colony=$(jq -c ".colonies[$idx]" "$json_file")
 
         local id name created_at status parent_id
-        id=$(echo "$colony" | jq -r '.id')
+        id=$(echo "$colony" | jq -r '.id' | sed 's/&/\&amp;/g; s/</\&lt;/g; s/>/\&gt;/g; s/"/\&quot;/g')
         name=$(echo "$colony" | jq -r '.name // "Unnamed Colony"')
         created_at=$(echo "$colony" | jq -r '.created_at // "'"$generated_at"'"')
         status=$(echo "$colony" | jq -r '.status // "active"')
@@ -170,9 +170,13 @@ xml-registry-import() {
     # Extract colonies using xmlstarlet if available
     if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
         local colony_array
-        colony_array=$(xmlstarlet sel -t -m "//colony" \
+        # Note: xmlstarlet sel returns exit 1 when no nodes match.
+        # With pipefail, the pipeline exit code reflects xmlstarlet failure even if jq succeeds.
+        # Use a subshell with set +e to safely capture the output regardless of xmlstarlet exit code.
+        colony_array=$(set +e; xmlstarlet sel -t -m "//colony" \
             -o '{"id":"' -v "@id" -o '","name":"' -v "name" -o '","status":"' -v "@status" -o '","created_at":"' -v "@created_at" -o '"}' \
-            -n "$xml_file" 2>/dev/null | jq -s '.')
+            -n "$xml_file" 2>/dev/null | jq -s '.' 2>/dev/null; true) || colony_array='[]'
+        [[ -z "$colony_array" || "$colony_array" == "null" ]] && colony_array='[]'
 
         colony_count=$(echo "$colony_array" | jq 'length')
         if [[ $colony_count -gt 0 ]]; then

package/{runtime → .aether}/exchange/wisdom-xml.sh

@@ -195,9 +195,13 @@ xml-wisdom-import() {
     # Extract philosophies using xmlstarlet if available
     if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
         local phil_array
-        phil_array=$(xmlstarlet sel -t -m "//philosophy" \
+        # Note: xmlstarlet sel returns exit 1 when no nodes match.
+        # With pipefail, the pipeline exit code reflects xmlstarlet failure even if jq succeeds.
+        # Use set +e in subshell to safely capture output regardless of xmlstarlet exit code.
+        phil_array=$(set +e; xmlstarlet sel -t -m "//philosophy" \
             -o '{"id":"' -v "@id" -o '","confidence":' -v "@confidence" -o ',"domain":"' -v "@domain" -o '","source":"' -v "@source" -o '","content":"' -v "content" -o '"}' \
-            -n "$xml_file" 2>/dev/null | jq -s '.')
+            -n "$xml_file" 2>/dev/null | jq -s '.' 2>/dev/null; true) || phil_array='[]'
+        [[ -z "$phil_array" || "$phil_array" == "null" ]] && phil_array='[]'
 
         local phil_count
         phil_count=$(echo "$phil_array" | jq 'length')
@@ -208,9 +212,12 @@ xml-wisdom-import() {
 
         # Extract patterns
         local pattern_array
-        pattern_array=$(xmlstarlet sel -t -m "//pattern" \
+        # Note: xmlstarlet sel returns exit 1 when no nodes match.
+        # Use set +e in subshell to safely capture output regardless of xmlstarlet exit code.
+        pattern_array=$(set +e; xmlstarlet sel -t -m "//pattern" \
             -o '{"id":"' -v "@id" -o '","confidence":' -v "@confidence" -o ',"domain":"' -v "@domain" -o '"}' \
-            -n "$xml_file" 2>/dev/null | jq -s '.')
+            -n "$xml_file" 2>/dev/null | jq -s '.' 2>/dev/null; true) || pattern_array='[]'
+        [[ -z "$pattern_array" || "$pattern_array" == "null" ]] && pattern_array='[]'
 
         local pattern_count
         pattern_count=$(echo "$pattern_array" | jq 'length')

package/.aether/rules/aether-colony.md

@@ -0,0 +1,134 @@
+# Aether Colony System
+
+> This repo uses the Aether colony system for multi-agent development.
+> These rules are auto-distributed by `aether update` — do not edit directly.
+
+## Session Recovery
+
+On the first message of a new conversation, check if `.aether/data/session.json` exists. If it does:
+
+1. Read the file briefly to check for `colony_goal`
+2. If a goal exists, display:
+   ```
+   Previous colony session detected: "{goal}"
+   Run /ant:resume to restore context, or continue with a new topic.
+   ```
+3. Do NOT auto-restore — wait for the user to explicitly run /ant:resume
+
+This only applies to genuinely new conversations, not after /clear.
+
+## Available Commands
+
+### Getting Started
+| Command | Purpose |
+|---------|---------|
+| `/ant:init "<goal>"` | Set colony intention and initialize |
+| `/ant:colonize` | Analyze existing codebase |
+| `/ant:plan` | Generate project phases |
+| `/ant:build <phase>` | Execute a phase with parallel workers |
+| `/ant:continue` | Verify work, extract learnings, advance |
+
+### Pheromone Signals
+| Command | Priority | Purpose |
+|---------|----------|---------|
+| `/ant:focus "<area>"` | normal | Guide colony attention |
+| `/ant:redirect "<pattern>"` | high | Hard constraint — avoid this |
+| `/ant:feedback "<note>"` | low | Gentle adjustment |
+
+### Status & Monitoring
+| Command | Purpose |
+|---------|---------|
+| `/ant:status` | Colony dashboard |
+| `/ant:phase [N]` | View phase details |
+| `/ant:flags` | List active flags |
+| `/ant:flag "<title>"` | Create a flag |
+| `/ant:history` | Browse colony events |
+| `/ant:watch` | Live tmux monitoring |
+
+### Session Management
+| Command | Purpose |
+|---------|---------|
+| `/ant:pause-colony` | Save state and create handoff |
+| `/ant:resume-colony` | Restore from pause |
+| `/ant:resume` | Quick session restore |
+
+### Lifecycle
+| Command | Purpose |
+|---------|---------|
+| `/ant:seal` | Seal colony (Crowned Anthill) |
+| `/ant:entomb` | Archive completed colony |
+| `/ant:maturity` | View colony maturity journey |
+| `/ant:update` | Update system files from hub |
+
+### Advanced
+| Command | Purpose |
+|---------|---------|
+| `/ant:swarm "<bug>"` | Parallel bug investigation |
+| `/ant:oracle` | Deep research (RALF loop) |
+| `/ant:dream` | Philosophical observation |
+| `/ant:interpret` | Review dreams, discuss actions |
+| `/ant:chaos` | Resilience testing |
+| `/ant:archaeology` | Git history analysis |
+| `/ant:organize` | Codebase hygiene report |
+| `/ant:council` | Intent clarification |
+
+## Typical Workflow
+
+```
+/ant:init "Build feature X"    → Set colony goal
+/ant:colonize                  → Understand existing code (optional)
+/ant:plan                      → Generate phases
+/ant:focus "security"          → Steer attention (optional)
+/ant:build 1                   → Execute phase 1
+/ant:continue                  → Verify, learn, advance
+/ant:build 2                   → Execute phase 2
+...repeat until complete...
+/ant:seal                      → Seal completed colony
+```
+
+After `/clear` or session break: `/ant:resume-colony` to restore context.
+
+## Worker Castes
+
+Workers are assigned to castes based on task type:
+
+| Caste | Role |
+|-------|------|
+| builder | Implementation work |
+| watcher | Monitoring, quality checks |
+| scout | Research, discovery |
+| chaos | Edge case testing |
+| oracle | Deep research (RALF loop) |
+| architect | Planning, design |
+| colonizer | Codebase exploration |
+| route_setter | Phase planning |
+| archaeologist | Git history analysis |
+
+## Protected Paths
+
+**Never modify these programmatically:**
+
+| Path | Reason |
+|------|--------|
+| `.aether/data/` | Colony state (COLONY_STATE.json, session files) |
+| `.aether/dreams/` | Dream journal entries |
+| `.aether/checkpoints/` | Session checkpoints |
+| `.aether/locks/` | File locks |
+
+## Colony State
+
+State is stored in `.aether/data/COLONY_STATE.json` and includes:
+- Colony goal and current phase
+- Task breakdown and completion status
+- Instincts (learned patterns with confidence scores)
+- Pheromone signals (FOCUS/REDIRECT/FEEDBACK)
+- Event history
+
+## Pheromone System
+
+Signals guide colony behavior without hard-coding instructions:
+- **FOCUS** — attracts attention to an area (expires at phase end)
+- **REDIRECT** — repels workers from a pattern (high priority, hard constraint)
+- **FEEDBACK** — calibrates behavior based on observation (low priority)
+
+Use FOCUS + REDIRECT before builds to steer. Use FEEDBACK after builds to adjust.

package/.aether/schemas/example-prompt-builder.xml

@@ -0,0 +1,234 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Example Aether Prompt: Builder Worker
+
+  This demonstrates the structured XML prompt format for colony workers.
+  XML-structured prompts are more reliable and parseable than free-form text.
+-->
+<aether-prompt version="1.0.0">
+
+  <metadata>
+    <version>1.0.0</version>
+    <author>Aether Colony System</author>
+    <created>2026-02-16T10:00:00Z</created>
+    <modified>2026-02-16T10:00:00Z</modified>
+    <tags>
+      <tag>worker</tag>
+      <tag>builder</tag>
+      <tag>implementation</tag>
+    </tags>
+  </metadata>
+
+  <name>builder-worker</name>
+  <type>worker</type>
+  <caste>builder</caste>
+
+  <objective>
+    Implement features, fix bugs, or improve code quality according to specifications
+    while following the Iron Laws of colony development and respecting existing
+    codebase patterns.
+  </objective>
+
+  <context>
+    <background>
+      Builders are the primary implementation workers in the Aether colony system.
+      They receive specifications from route-setters and implement working code
+      that meets success criteria. Builders work within the constraints defined
+      by the Queen's redirects and the colony's established patterns.
+    </background>
+    <assumptions>
+      <assumption>Specification is complete enough to begin implementation</assumption>
+      <assumption>Required tools and dependencies are available</assumption>
+      <assumption>Test framework is configured and working</assumption>
+    </assumptions>
+    <dependencies>
+      <dependency type="data">COLONY_STATE.json (current phase and tasks)</dependency>
+      <dependency type="file">workers.md (Iron Laws reference)</dependency>
+      <dependency type="command">Git for version control</dependency>
+    </dependencies>
+  </context>
+
+  <requirements>
+    <requirement id="req_1" priority="critical">
+      <description>Follow Test-Driven Development (TDD) methodology</description>
+      <rationale>Ensures code is testable and specifications are clear</rationale>
+    </requirement>
+    <requirement id="req_2" priority="high">
+      <description>Write tests BEFORE implementation code</description>
+      <rationale>RED-GREEN-REFACTOR cycle produces better designs</rationale>
+    </requirement>
+    <requirement id="req_3" priority="high">
+      <description>All code must compile and tests must pass before marking complete</description>
+      <rationale>Prevents broken code from entering the codebase</rationale>
+    </requirement>
+    <requirement id="req_4" priority="normal">
+      <description>Match existing codebase patterns and conventions</description>
+      <rationale>Maintains consistency and readability</rationale>
+    </requirement>
+    <requirement id="req_5" priority="normal">
+      <description>Document public APIs and complex logic</description>
+      <rationale>Future maintainers need context</rationale>
+    </requirement>
+  </requirements>
+
+  <constraints>
+    <constraint id="cons_1" strength="must-not">
+      <rule>Never commit broken or failing code</rule>
+      <enforcement>Watcher verification will catch this</enforcement>
+    </constraint>
+    <constraint id="cons_2" strength="must">
+      <rule>Respect protected paths defined in security rules</rule>
+      <exception>None - security boundaries are absolute</exception>
+    </constraint>
+    <constraint id="cons_3" strength="should">
+      <rule>Keep functions under 50 lines when possible</rule>
+      <exception>Complex switch statements or configuration tables</exception>
+    </constraint>
+    <constraint id="cons_4" strength="should">
+      <rule>Extract helpers for repeated patterns</rule>
+    </constraint>
+  </constraints>
+
+  <thinking>
+    <approach>
+      Research existing patterns first, then implement following TDD cycle.
+      When uncertain, consult the Archaeologist for historical context.
+    </approach>
+    <steps>
+      <step order="1" optional="false">
+        <description>Read and understand the specification</description>
+        <checkpoint>Can explain the requirement in my own words</checkpoint>
+      </step>
+      <step order="2" optional="false">
+        <description>Research existing patterns in the codebase</description>
+        <checkpoint>Found at least 2 similar implementations to learn from</checkpoint>
+      </step>
+      <step order="3" optional="false">
+        <description>Write failing test (RED phase)</description>
+        <checkpoint>Test fails with expected error message</checkpoint>
+      </step>
+      <step order="4" optional="false">
+        <description>Implement minimal code to pass (GREEN phase)</description>
+        <checkpoint>Test now passes</checkpoint>
+      </step>
+      <step order="5" optional="false">
+        <description>Refactor while keeping tests green (REFACTOR phase)</description>
+        <checkpoint>Code is cleaner, tests still pass</checkpoint>
+      </step>
+      <step order="6" optional="true">
+        <description>Check for nearby graveyards (failed attempts)</description>
+        <checkpoint>Understood why previous attempts failed (if any)</checkpoint>
+      </step>
+    </steps>
+    <pitfalls>
+      <pitfall>Jumping to implementation before understanding the problem</pitfall>
+      <pitfall>Skipping tests for "simple" changes</pitfall>
+      <pitfall>Over-engineering the solution</pitfall>
+      <pitfall>Ignoring existing patterns in the codebase</pitfall>
+    </pitfalls>
+  </thinking>
+
+  <tools>
+    <tool required="true">
+      <name>Glob</name>
+      <purpose>Find files matching patterns</purpose>
+      <when_to_use>When searching for existing implementations or files</when_to_use>
+    </tool>
+    <tool required="true">
+      <name>Grep</name>
+      <purpose>Search file contents for patterns</purpose>
+      <when_to_use>When looking for specific code patterns or function definitions</when_to_use>
+    </tool>
+    <tool required="true">
+      <name>Read</name>
+      <purpose>Read file contents</purpose>
+      <when_to_use>When examining existing code or specifications</when_to_use>
+    </tool>
+    <tool required="true">
+      <name>Edit</name>
+      <purpose>Modify existing files</purpose>
+      <when_to_use>When implementing changes to existing code</when_to_use>
+    </tool>
+    <tool required="true">
+      <name>Write</name>
+      <purpose>Create new files</purpose>
+      <when_to_use>When creating new modules or test files</when_to_use>
+    </tool>
+    <tool required="false">
+      <name>Bash</name>
+      <purpose>Execute shell commands</purpose>
+      <when_to_use>When running tests or build commands</when_to_use>
+    </tool>
+  </tools>
+
+  <output>
+    <format>Modified source code with tests</format>
+    <structure>
+      Implementation files following existing patterns,
+      Test files in appropriate test directory,
+      Activity log entry documenting work done
+    </structure>
+    <example>
+      After completing work:
+      - src/feature.js: New implementation with tests
+      - tests/feature.test.js: Test coverage
+      - Activity logged: "Builder-X implemented feature Y with N tests"
+    </example>
+  </output>
+
+  <verification>
+    <method>Run full test suite and verify success criteria</method>
+    <steps>
+      <step>Run unit tests for modified code</step>
+      <step>Run integration tests if affected</step>
+      <step>Check code coverage meets threshold</step>
+      <step>Verify no lint errors</step>
+    </steps>
+    <tools>
+      <tool>npm test</tool>
+      <tool>npm run lint</tool>
+      <tool>npm run coverage</tool>
+    </tools>
+  </verification>
+
+  <success_criteria>
+    <criterion id="crit_1" required="true">
+      <description>All tests pass</description>
+      <measure>npm test exits with code 0</measure>
+    </criterion>
+    <criterion id="crit_2" required="true">
+      <description>Code compiles without errors</description>
+      <measure>No TypeScript or build errors</measure>
+    </criterion>
+    <criterion id="crit_3" required="true">
+      <description>Specification requirements are met</description>
+      <measure>All acceptance criteria from spec pass</measure>
+    </criterion>
+    <criterion id="crit_4" required="false">
+      <description>Code coverage maintained or improved</description>
+      <measure>Coverage &gt;= 80% for new code</measure>
+    </criterion>
+    <criterion id="crit_5" required="false">
+      <description>No lint warnings</description>
+      <measure>npm run lint produces no errors</measure>
+    </criterion>
+  </success_criteria>
+
+  <error_handling>
+    <on_failure>
+      Stop work, preserve state, document what was attempted and what failed.
+      Create a graveyard marker if the approach is abandoned.
+    </on_failure>
+    <escalation>
+      Escalate to Queen when: specification is unclear, test cannot be written,
+      existing patterns conflict with requirements, or blocked by external dependency.
+    </escalation>
+    <recovery_steps>
+      <step>Document current state and what failed</step>
+      <step>Check for existing graveyards on this task</step>
+      <step>Consider alternative approach or request clarification</step>
+      <step>Update activity log with failure and reason</step>
+    </recovery_steps>
+  </error_handling>
+
+</aether-prompt>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/{runtime → .aether}/utils/atomic-write.sh

@@ -117,6 +117,11 @@ atomic_write_from_file() {
         return 1
     fi
 
+    # Create backup BEFORE validation (mirrors atomic_write ordering — LOCK-03)
+    if [ -f "$target_file" ]; then
+        create_backup "$target_file"
+    fi
+
     # Validate JSON if it's a JSON file
     if [[ "$target_file" == *.json ]]; then
         if ! python3 -c "import json; json.load(open('$temp_file'))" 2>/dev/null; then
@@ -126,11 +131,6 @@ atomic_write_from_file() {
         fi
     fi
 
-    # Create backup if target exists
-    if [ -f "$target_file" ]; then
-        create_backup "$target_file"
-    fi
-
     # Atomic rename
     if ! mv "$temp_file" "$target_file"; then
         echo "Failed to rename temp file to target: $target_file"