aether-colony 3.1.17 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (183) hide show
  1. package/{runtime → .aether}/CONTEXT.md +1 -1
  2. package/{runtime → .aether}/aether-utils.sh +1772 -98
  3. package/.aether/docs/QUEEN-SYSTEM.md +211 -0
  4. package/.aether/docs/QUEEN.md +84 -0
  5. package/.aether/docs/README.md +68 -0
  6. package/.aether/docs/caste-system.md +48 -0
  7. package/{runtime → .aether/docs/disciplines}/DISCIPLINES.md +8 -8
  8. package/.aether/docs/error-codes.md +268 -0
  9. package/{runtime → .aether}/docs/known-issues.md +42 -26
  10. package/.aether/docs/queen-commands.md +97 -0
  11. package/.aether/exchange/colony-registry.xml +11 -0
  12. package/{runtime → .aether}/exchange/pheromone-xml.sh +2 -1
  13. package/.aether/exchange/pheromones.xml +87 -0
  14. package/.aether/exchange/queen-wisdom.xml +14 -0
  15. package/{runtime → .aether}/exchange/registry-xml.sh +7 -3
  16. package/{runtime → .aether}/exchange/wisdom-xml.sh +11 -4
  17. package/.aether/rules/aether-colony.md +134 -0
  18. package/.aether/schemas/example-prompt-builder.xml +234 -0
  19. package/.aether/templates/colony-state-reset.jq.template +22 -0
  20. package/.aether/templates/colony-state.template.json +35 -0
  21. package/.aether/templates/constraints.template.json +9 -0
  22. package/.aether/templates/crowned-anthill.template.md +36 -0
  23. package/.aether/templates/handoff-build-error.template.md +30 -0
  24. package/.aether/templates/handoff-build-success.template.md +39 -0
  25. package/.aether/templates/handoff.template.md +40 -0
  26. package/{runtime → .aether}/utils/atomic-write.sh +5 -5
  27. package/{runtime → .aether}/utils/chamber-compare.sh +23 -10
  28. package/{runtime → .aether}/utils/chamber-utils.sh +32 -20
  29. package/{runtime → .aether}/utils/error-handler.sh +13 -1
  30. package/{runtime → .aether}/utils/file-lock.sh +49 -13
  31. package/.aether/utils/semantic-cli.sh +413 -0
  32. package/{runtime → .aether}/utils/xml-compose.sh +7 -1
  33. package/.aether/utils/xml-convert.sh +273 -0
  34. package/.aether/utils/xml-query.sh +201 -0
  35. package/.aether/utils/xml-utils.sh +110 -0
  36. package/{runtime → .aether}/workers.md +14 -17
  37. package/.claude/agents/ant/aether-ambassador.md +264 -0
  38. package/.claude/agents/ant/aether-archaeologist.md +322 -0
  39. package/.claude/agents/ant/aether-auditor.md +266 -0
  40. package/.claude/agents/ant/aether-builder.md +187 -0
  41. package/.claude/agents/ant/aether-chaos.md +268 -0
  42. package/.claude/agents/ant/aether-chronicler.md +304 -0
  43. package/.claude/agents/ant/aether-gatekeeper.md +325 -0
  44. package/.claude/agents/ant/aether-includer.md +373 -0
  45. package/.claude/agents/ant/aether-keeper.md +271 -0
  46. package/.claude/agents/ant/aether-measurer.md +317 -0
  47. package/.claude/agents/ant/aether-probe.md +210 -0
  48. package/.claude/agents/ant/aether-queen.md +325 -0
  49. package/.claude/agents/ant/aether-route-setter.md +173 -0
  50. package/.claude/agents/ant/aether-sage.md +353 -0
  51. package/.claude/agents/ant/aether-scout.md +142 -0
  52. package/.claude/agents/ant/aether-surveyor-disciplines.md +416 -0
  53. package/.claude/agents/ant/aether-surveyor-nest.md +354 -0
  54. package/.claude/agents/ant/aether-surveyor-pathogens.md +288 -0
  55. package/.claude/agents/ant/aether-surveyor-provisions.md +359 -0
  56. package/.claude/agents/ant/aether-tracker.md +265 -0
  57. package/.claude/agents/ant/aether-watcher.md +244 -0
  58. package/.claude/agents/ant/aether-weaver.md +247 -0
  59. package/.claude/commands/ant/archaeology.md +16 -7
  60. package/.claude/commands/ant/build.md +415 -284
  61. package/.claude/commands/ant/chaos.md +19 -10
  62. package/.claude/commands/ant/colonize.md +58 -24
  63. package/.claude/commands/ant/continue.md +155 -145
  64. package/.claude/commands/ant/council.md +15 -5
  65. package/.claude/commands/ant/dream.md +16 -7
  66. package/.claude/commands/ant/entomb.md +274 -157
  67. package/.claude/commands/ant/feedback.md +33 -29
  68. package/.claude/commands/ant/flag.md +18 -10
  69. package/.claude/commands/ant/flags.md +14 -6
  70. package/.claude/commands/ant/focus.md +29 -21
  71. package/.claude/commands/ant/help.md +11 -1
  72. package/.claude/commands/ant/history.md +10 -0
  73. package/.claude/commands/ant/init.md +91 -65
  74. package/.claude/commands/ant/interpret.md +15 -4
  75. package/.claude/commands/ant/lay-eggs.md +55 -7
  76. package/.claude/commands/ant/maturity.md +11 -1
  77. package/.claude/commands/ant/migrate-state.md +14 -2
  78. package/.claude/commands/ant/oracle.md +23 -15
  79. package/.claude/commands/ant/organize.md +29 -20
  80. package/.claude/commands/ant/pause-colony.md +17 -7
  81. package/.claude/commands/ant/phase.md +17 -8
  82. package/.claude/commands/ant/plan.md +20 -9
  83. package/.claude/commands/ant/redirect.md +29 -32
  84. package/.claude/commands/ant/resume-colony.md +19 -9
  85. package/.claude/commands/ant/resume.md +272 -96
  86. package/.claude/commands/ant/seal.md +201 -191
  87. package/.claude/commands/ant/status.md +71 -32
  88. package/.claude/commands/ant/swarm.md +26 -44
  89. package/.claude/commands/ant/tunnels.md +279 -105
  90. package/.claude/commands/ant/update.md +81 -20
  91. package/.claude/commands/ant/verify-castes.md +14 -4
  92. package/.claude/commands/ant/watch.md +13 -12
  93. package/.opencode/agents/aether-ambassador.md +63 -20
  94. package/.opencode/agents/aether-archaeologist.md +29 -12
  95. package/.opencode/agents/aether-auditor.md +51 -18
  96. package/.opencode/agents/aether-builder.md +69 -19
  97. package/.opencode/agents/aether-chaos.md +29 -12
  98. package/.opencode/agents/aether-chronicler.md +60 -18
  99. package/.opencode/agents/aether-gatekeeper.md +27 -18
  100. package/.opencode/agents/aether-includer.md +27 -18
  101. package/.opencode/agents/aether-keeper.md +89 -18
  102. package/.opencode/agents/aether-measurer.md +27 -18
  103. package/.opencode/agents/aether-probe.md +60 -18
  104. package/.opencode/agents/aether-queen.md +172 -24
  105. package/.opencode/agents/aether-route-setter.md +57 -12
  106. package/.opencode/agents/aether-sage.md +26 -18
  107. package/.opencode/agents/aether-scout.md +27 -19
  108. package/.opencode/agents/aether-surveyor-disciplines.md +53 -1
  109. package/.opencode/agents/aether-surveyor-nest.md +53 -1
  110. package/.opencode/agents/aether-surveyor-pathogens.md +51 -1
  111. package/.opencode/agents/aether-surveyor-provisions.md +53 -1
  112. package/.opencode/agents/aether-tracker.md +64 -18
  113. package/.opencode/agents/aether-watcher.md +66 -19
  114. package/.opencode/agents/aether-weaver.md +61 -18
  115. package/.opencode/commands/ant/build.md +406 -192
  116. package/.opencode/commands/ant/continue.md +66 -76
  117. package/.opencode/commands/ant/entomb.md +106 -45
  118. package/.opencode/commands/ant/init.md +46 -48
  119. package/.opencode/commands/ant/organize.md +5 -5
  120. package/.opencode/commands/ant/resume.md +334 -0
  121. package/.opencode/commands/ant/seal.md +33 -24
  122. package/.opencode/commands/ant/status.md +11 -0
  123. package/.opencode/commands/ant/tunnels.md +149 -0
  124. package/.opencode/commands/ant/update.md +59 -16
  125. package/CHANGELOG.md +79 -0
  126. package/README.md +135 -353
  127. package/bin/cli.js +243 -122
  128. package/bin/generate-commands.sh +2 -2
  129. package/bin/lib/init.js +13 -3
  130. package/bin/lib/update-transaction.js +119 -117
  131. package/bin/sync-to-runtime.sh +5 -137
  132. package/bin/validate-package.sh +84 -0
  133. package/package.json +9 -6
  134. package/.opencode/agents/aether-architect.md +0 -66
  135. package/.opencode/agents/aether-guardian.md +0 -107
  136. package/.opencode/agents/workers.md +0 -1034
  137. package/runtime/QUEEN_ANT_ARCHITECTURE.md +0 -402
  138. package/runtime/data/signatures.json +0 -41
  139. package/runtime/docs/AETHER-2.0-IMPLEMENTATION-PLAN.md +0 -1343
  140. package/runtime/docs/AETHER-PHEROMONE-SYSTEM-MASTER-SPEC.md +0 -2642
  141. package/runtime/docs/PHEROMONE-INJECTION.md +0 -240
  142. package/runtime/docs/PHEROMONE-INTEGRATION.md +0 -192
  143. package/runtime/docs/PHEROMONE-SYSTEM-DESIGN.md +0 -426
  144. package/runtime/docs/README.md +0 -94
  145. package/runtime/docs/VISUAL-OUTPUT-SPEC.md +0 -219
  146. package/runtime/docs/biological-reference.md +0 -272
  147. package/runtime/docs/codebase-review.md +0 -399
  148. package/runtime/docs/command-sync.md +0 -164
  149. package/runtime/docs/constraints.md +0 -116
  150. package/runtime/docs/implementation-learnings.md +0 -89
  151. package/runtime/docs/namespace.md +0 -148
  152. package/runtime/docs/pathogen-schema-example.json +0 -36
  153. package/runtime/docs/pathogen-schema.md +0 -111
  154. package/runtime/docs/planning-discipline.md +0 -159
  155. package/runtime/docs/progressive-disclosure.md +0 -184
  156. package/runtime/lib/queen-utils.sh +0 -729
  157. package/runtime/planning.md +0 -159
  158. package/runtime/recover.sh +0 -136
  159. package/runtime/utils/xml-utils.sh +0 -2196
  160. package/runtime/workers-new-castes.md +0 -516
  161. /package/{runtime → .aether/docs/disciplines}/coding-standards.md +0 -0
  162. /package/{runtime → .aether/docs/disciplines}/debugging.md +0 -0
  163. /package/{runtime → .aether/docs/disciplines}/learning.md +0 -0
  164. /package/{runtime → .aether/docs/disciplines}/tdd.md +0 -0
  165. /package/{runtime → .aether/docs/disciplines}/verification-loop.md +0 -0
  166. /package/{runtime → .aether/docs/disciplines}/verification.md +0 -0
  167. /package/{runtime → .aether}/docs/pheromones.md +0 -0
  168. /package/{runtime → .aether}/model-profiles.yaml +0 -0
  169. /package/{runtime → .aether}/schemas/aether-types.xsd +0 -0
  170. /package/{runtime → .aether}/schemas/colony-registry.xsd +0 -0
  171. /package/{runtime → .aether}/schemas/pheromone.xsd +0 -0
  172. /package/{runtime → .aether}/schemas/prompt.xsd +0 -0
  173. /package/{runtime → .aether}/schemas/queen-wisdom.xsd +0 -0
  174. /package/{runtime → .aether}/schemas/worker-priming.xsd +0 -0
  175. /package/{runtime → .aether}/templates/QUEEN.md.template +0 -0
  176. /package/{runtime → .aether}/utils/colorize-log.sh +0 -0
  177. /package/{runtime → .aether}/utils/queen-to-md.xsl +0 -0
  178. /package/{runtime → .aether}/utils/spawn-tree.sh +0 -0
  179. /package/{runtime → .aether}/utils/spawn-with-model.sh +0 -0
  180. /package/{runtime → .aether}/utils/state-loader.sh +0 -0
  181. /package/{runtime → .aether}/utils/swarm-display.sh +0 -0
  182. /package/{runtime → .aether}/utils/watch-spawn-tree.sh +0 -0
  183. /package/{runtime → .aether}/utils/xml-core.sh +0 -0
@@ -37,7 +37,7 @@ Parse `$ARGUMENTS`:
37
37
 
38
38
  ### Step 0.5: Initialize Visual Mode (if enabled)
39
39
 
40
- If `visual_mode` is true:
40
+ If `visual_mode` is true, run using the Bash tool with description "Initializing dream display...":
41
41
  ```bash
42
42
  # Generate session ID
43
43
  dream_id="dream-$(date +%s)"
@@ -67,9 +67,9 @@ Read these files in parallel to understand the world you're dreaming about:
67
67
 
68
68
  Display awakening:
69
69
  ```
70
- 💭🐜🌙🐜💭 ═══════════════════════════════════════════════
71
- T H E D R E A M E R A W A K E N S
72
- ═══════════════════════════════════════════════ 💭🐜🌙🐜💭
70
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
71
+ 💭🐜🌙🐜💭 T H E D R E A M E R A W A K E N S
72
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
73
73
 
74
74
  Colony: {goal}
75
75
  Phase: {current_phase}/{total_phases} — {phase_name}
@@ -198,9 +198,9 @@ Concerns raised: {count}
198
198
  Output to the terminal:
199
199
 
200
200
  ```
201
- 💭🐜🌙🐜💭 ═══════════════════════════════════════════════
202
- D R E A M C O M P L E T E
203
- ═══════════════════════════════════════════════ 💭🐜🌙🐜💭
201
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
202
+ 💭🐜🌙🐜💭 D R E A M C O M P L E T E
203
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
204
204
 
205
205
  📓 {N} dreams recorded → .aether/dreams/{filename}.md
206
206
 
@@ -224,10 +224,19 @@ Colony status: /ant:status
224
224
 
225
225
  ### Step 6: Log Activity
226
226
 
227
+ Run using the Bash tool with description "Logging dream activity...":
227
228
  ```bash
228
229
  bash .aether/aether-utils.sh activity-log "DREAM" "Dreamer" "Dream session: {N} observations, {concerns} concerns, {pheromones} pheromone suggestions"
229
230
  ```
230
231
 
232
+ Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
233
+ ```bash
234
+ state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json)
235
+ current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
236
+ total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
237
+ bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
238
+ ```
239
+
231
240
  ## Dream Categories
232
241
 
233
242
  Use these categories and their emoji consistently:
@@ -3,7 +3,7 @@ name: ant:entomb
3
3
  description: "⚰️🐜⚰️ Entomb completed colony in chambers"
4
4
  ---
5
5
 
6
- You are the **Queen**. Archive the completed colony to chambers.
6
+ You are the **Queen**. Archive the sealed colony to chambers.
7
7
 
8
8
  ## Instructions
9
9
 
@@ -11,6 +11,44 @@ Parse `$ARGUMENTS`:
11
11
  - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
12
12
  - Otherwise: set `visual_mode = true`
13
13
 
14
+ <failure_modes>
15
+ ### Archive Write Failure
16
+ If writing to chambers/ archive fails partway:
17
+ - Do NOT delete source data (the active colony) until archive is verified
18
+ - Report what was archived vs. what failed
19
+ - Recovery: the original colony data is intact -- user can retry
20
+
21
+ ### Seal Verification Failure
22
+ If the colony was not properly sealed before entomb:
23
+ - STOP -- do not archive an incomplete colony
24
+ - Direct user to run /ant:seal first
25
+ - This is a hard gate, not a suggestion
26
+
27
+ ### Chamber Naming Conflict
28
+ If the target chamber directory already exists:
29
+ - STOP -- do not overwrite an existing archive
30
+ - Report the conflict
31
+ - Options: (1) Use a different name, (2) Merge with existing, (3) Cancel
32
+ </failure_modes>
33
+
34
+ <success_criteria>
35
+ Command is complete when:
36
+ - Colony data is fully copied to chambers/ archive directory
37
+ - Archive integrity is verified (all expected files present)
38
+ - Active colony state is cleared only after archive verification
39
+ - User sees confirmation with archive location
40
+ </success_criteria>
41
+
42
+ <read_only>
43
+ Do not touch during entomb:
44
+ - .aether/dreams/ (user notes -- not archived)
45
+ - Source code files
46
+ - .env* files
47
+ - .claude/settings.json
48
+ - .github/workflows/
49
+ - Other chamber directories (only write to the new chamber)
50
+ </read_only>
51
+
14
52
  ### Step 0: Initialize Visual Mode (if enabled)
15
53
 
16
54
  If `visual_mode` is true:
@@ -18,9 +56,8 @@ If `visual_mode` is true:
18
56
  # Generate session ID
19
57
  entomb_id="entomb-$(date +%s)"
20
58
 
21
- # Initialize swarm display
22
- bash .aether/aether-utils.sh swarm-display-init "$entomb_id"
23
- bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Entombing colony" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
59
+ # Initialize swarm display (consolidated)
60
+ bash .aether/aether-utils.sh swarm-display-init "$entomb_id" && bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Entombing colony" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
24
61
  ```
25
62
 
26
63
  ### Step 1: Read State
@@ -33,115 +70,109 @@ No colony to entomb. Run /ant:init first.
33
70
  ```
34
71
  Stop here.
35
72
 
36
- #### Step 1.5: Check for Concurrent Entomb Operations
73
+ Extract: `goal`, `state`, `current_phase`, `plan.phases`, `milestone`, `version`, `initialized_at`, `memory.decisions`, `memory.phase_learnings`, `memory.instincts`.
37
74
 
38
- Capture session start time:
39
- ```bash
40
- ENTOMB_START=$(date +%s)
41
- ```
75
+ ### Step 2: Seal-First Enforcement
42
76
 
43
- Check for incomplete chamber operations:
44
- ```bash
45
- # Check for incomplete chambers (no colony-state.json)
46
- incomplete_chambers=$(find .aether/chambers -type d -mindepth 1 -maxdepth 1 2>/dev/null | while read dir; do
47
- if [[ ! -f "$dir/colony-state.json" ]]; then
48
- echo "$dir"
49
- fi
50
- done)
77
+ Check `milestone` in COLONY_STATE.json.
51
78
 
52
- if [[ -n "$incomplete_chambers" ]]; then
53
- echo "Warning: Incomplete chamber operations detected:"
54
- echo "$incomplete_chambers"
55
- fi
79
+ **If milestone != "Crowned Anthill":**
56
80
  ```
81
+ Colony has not been sealed.
57
82
 
58
- ### Step 2: Validate Colony Can Be Entombed
59
-
60
- Extract: `goal`, `state`, `current_phase`, `plan.phases`, `memory.decisions`, `memory.phase_learnings`.
61
-
62
- **Precondition 1: All phases must be completed**
83
+ Current milestone: {milestone}
84
+ Required: Crowned Anthill
63
85
 
64
- Check if all phases in `plan.phases` have `status: "completed"`:
65
- ```
66
- all_completed = all(phase.status == "completed" for phase in plan.phases)
86
+ Run /ant:seal first to complete the sealing ceremony.
67
87
  ```
88
+ Stop here.
68
89
 
69
- If NOT all completed:
90
+ **Belt-and-suspenders:** Also check `.aether/CROWNED-ANTHILL.md` exists. If milestone is Crowned Anthill but file is missing:
70
91
  ```
71
- Cannot entomb incomplete colony.
72
-
73
- Completed phases: X of Y
74
- Remaining: {list of incomplete phase names}
75
-
76
- Run /ant:continue to complete remaining phases first.
92
+ CROWNED-ANTHILL.md not found — seal may have been interrupted. Run /ant:seal again.
77
93
  ```
78
94
  Stop here.
79
95
 
80
- **Precondition 2: State must not be EXECUTING**
96
+ ### Step 3: User Confirmation
81
97
 
82
- If `state == "EXECUTING"`:
83
- ```
84
- Colony is still executing. Run /ant:continue to reconcile first.
98
+ Show what will be archived:
85
99
  ```
86
- Stop here.
100
+ ENTOMB COLONY
87
101
 
88
- **Precondition 3: No critical errors**
102
+ Goal: {goal}
103
+ Milestone: Crowned Anthill
104
+ Phases: {phases_completed} of {total_phases}
89
105
 
90
- Check `errors.records` for any entries with `severity: "critical"`.
106
+ This will:
107
+ - Archive ALL colony data to .aether/chambers/
108
+ - Copy CROWNED-ANTHILL.md, pheromones, dreams, session data
109
+ - Promote colony wisdom to QUEEN.md (cross-generational learning)
110
+ - Reset COLONY_STATE.json for a fresh start
111
+ - Clear session data
91
112
 
92
- If critical errors exist:
113
+ This action is permanent. The archived colony can be browsed via /ant:tunnels.
114
+
115
+ Entomb this colony? (yes/no)
93
116
  ```
94
- Cannot entomb colony with critical errors.
95
117
 
96
- Critical errors: {count}
97
- Run /ant:continue to resolve errors first.
118
+ Use `AskUserQuestion with yes/no options`.
119
+
120
+ If not "yes":
121
+ ```
122
+ Entombment cancelled. Colony remains active.
98
123
  ```
99
124
  Stop here.
100
125
 
101
- ### Step 3: Compute Milestone
126
+ ### Step 3.5: Check XML Tools
102
127
 
103
- Determine milestone based on phases completed:
104
- - 0 phases: "Fresh Start"
105
- - 1 phase: "First Mound"
106
- - 2-4 phases: "Open Chambers"
107
- - 5+ phases: "Sealed Chambers"
128
+ XML archiving is required for entombment. Check tool availability before proceeding.
129
+ Uses `command -v xmllint` directly consistent with seal.md's tool check.
108
130
 
109
- If all phases completed AND user explicitly sealing: "Crowned Anthill"
110
-
111
- For entombment, use the computed milestone or extract from state if already set.
131
+ ```bash
132
+ if command -v xmllint >/dev/null 2>&1; then
133
+ xmllint_available=true
134
+ else
135
+ xmllint_available=false
136
+ fi
137
+ ```
112
138
 
113
- ### Step 4: User Confirmation
139
+ **If xmllint is NOT available:**
114
140
 
115
- Display:
141
+ Ask the user:
116
142
  ```
117
- 🏺 ═══════════════════════════════════════════════════
118
- E N T O M B C O L O N Y
119
- ══════════════════════════════════════════════════ 🏺
143
+ xmllint is not installed — XML archiving requires it.
120
144
 
121
- Goal: {goal}
122
- Phases: {completed}/{total} completed
123
- Milestone: {milestone}
124
-
125
- Archive will include:
126
- - COLONY_STATE.json
127
- - manifest.json (pheromone trails)
145
+ Install now?
146
+ - macOS: xcode-select --install (or brew install libxml2)
147
+ - Linux: apt-get install libxml2-utils
128
148
 
129
- This will reset the active colony. Continue? (yes/no)
149
+ Install xmllint? (yes/no)
130
150
  ```
131
151
 
132
- Wait for explicit "yes" response before proceeding.
152
+ Use AskUserQuestion with yes/no options.
133
153
 
134
- If user responds with anything other than "yes", display:
154
+ If yes:
155
+ - On macOS: Run `xcode-select --install` or `brew install libxml2`
156
+ - On Linux: Run `sudo apt-get install -y libxml2-utils`
157
+ - After install attempt, re-check: `command -v xmllint >/dev/null 2>&1`
158
+ - If still not available after install:
159
+ ```
160
+ xmllint installation failed. Cannot entomb without XML archiving.
161
+ Install xmllint manually and try again.
162
+ ```
163
+ Stop here.
164
+
165
+ If no:
135
166
  ```
136
- Entombment cancelled. Colony remains active.
167
+ Entombment requires XML archiving. Install xmllint and try again.
137
168
  ```
138
169
  Stop here.
139
170
 
140
- ### Step 5: Promote Wisdom to QUEEN.md
171
+ ### Step 4: Promote Wisdom to QUEEN.md
141
172
 
142
173
  Before creating the chamber, promote validated learnings to QUEEN.md for future colonies.
143
174
 
144
- **Step 5.1: Ensure QUEEN.md exists**
175
+ **Step 4.1: Ensure QUEEN.md exists**
145
176
 
146
177
  ```bash
147
178
  queen_file=".aether/docs/QUEEN.md"
@@ -157,7 +188,7 @@ if [[ ! -f "$queen_file" ]]; then
157
188
  fi
158
189
  ```
159
190
 
160
- **Step 5.2: Extract and promote validated learnings**
191
+ **Step 4.2: Extract and promote validated learnings**
161
192
 
162
193
  ```bash
163
194
  # Extract colony name from goal (sanitized)
@@ -210,7 +241,7 @@ if [[ -f "$queen_file" ]]; then
210
241
  fi
211
242
  ```
212
243
 
213
- **Step 5.3: Display promotion summary**
244
+ **Step 4.3: Display promotion summary**
214
245
 
215
246
  ```
216
247
  ---
@@ -221,16 +252,16 @@ Promoted: {promotion_count} validated patterns to QUEEN.md
221
252
  ---
222
253
  ```
223
254
 
224
- ### Step 6: Create Chamber
255
+ ### Step 5: Generate Chamber Name
225
256
 
226
- Generate chamber name:
257
+ Date-first naming:
227
258
  ```bash
228
- sanitized_goal=$(echo "{goal}" | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]' '-' | sed 's/^-//;s/-$//' | cut -c1-50)
229
- timestamp=$(date -u +%Y%m%d-%H%M%S)
230
- chamber_name="${sanitized_goal}-${timestamp}"
259
+ date_prefix=$(date -u +%Y-%m-%d)
260
+ sanitized_goal=$(echo "$goal" | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]' '-' | sed 's/^-//;s/-$//' | cut -c1-40)
261
+ chamber_name="${date_prefix}-${sanitized_goal}"
231
262
  ```
232
263
 
233
- Handle name collision: if directory exists, append counter:
264
+ Collision handling:
234
265
  ```bash
235
266
  counter=1
236
267
  original_name="$chamber_name"
@@ -240,7 +271,7 @@ while [[ -d ".aether/chambers/$chamber_name" ]]; do
240
271
  done
241
272
  ```
242
273
 
243
- ### Step 7: Create Chamber Using Utilities
274
+ ### Step 6: Create Chamber
244
275
 
245
276
  Extract decisions and learnings as JSON arrays:
246
277
  ```bash
@@ -254,27 +285,79 @@ version=$(jq -r '.version // "3.0"' .aether/data/COLONY_STATE.json)
254
285
  Create the chamber:
255
286
  ```bash
256
287
  bash .aether/aether-utils.sh chamber-create \
257
- ".aether/chambers/{chamber_name}" \
288
+ ".aether/chambers/$chamber_name" \
258
289
  ".aether/data/COLONY_STATE.json" \
259
- "{goal}" \
260
- {phases_completed} \
261
- {total_phases} \
262
- "{milestone}" \
263
- "{version}" \
264
- '{decisions_json}' \
265
- '{learnings_json}'
290
+ "$goal" \
291
+ "$phases_completed" \
292
+ "$total_phases" \
293
+ "$milestone" \
294
+ "$version" \
295
+ "$decisions_json" \
296
+ "$learnings_json"
297
+ ```
298
+
299
+ ### Step 7: Archive Additional Files
300
+
301
+ AFTER chamber-create succeeds, copy additional data files:
302
+ ```bash
303
+ chamber_dir=".aether/chambers/$chamber_name"
304
+
305
+ # Archive data files (if they exist)
306
+ for f in pheromones.json session.json activity.log flags.json constraints.json spawn-tree.txt timing.log view-state.json; do
307
+ [[ -f ".aether/data/$f" ]] && cp ".aether/data/$f" "$chamber_dir/" 2>/dev/null || true
308
+ done
309
+
310
+ # Archive seal document (critical — this is the ceremony record)
311
+ [[ -f ".aether/CROWNED-ANTHILL.md" ]] && cp ".aether/CROWNED-ANTHILL.md" "$chamber_dir/"
312
+
313
+ # Archive HANDOFF.md if it exists
314
+ [[ -f ".aether/HANDOFF.md" ]] && cp ".aether/HANDOFF.md" "$chamber_dir/"
315
+
316
+ # Archive dreams directory (optional — may not exist)
317
+ [[ -d ".aether/dreams" ]] && cp -r ".aether/dreams" "$chamber_dir/dreams" 2>/dev/null || true
318
+ ```
319
+
320
+ Do NOT copy: `.aether/data/backups/`, `.aether/data/locks/`, `.aether/data/midden/`, `.aether/data/survey/`.
321
+
322
+ ### Step 7.5: Export XML Archive (hard-stop)
323
+
324
+ Export combined XML archive to the chamber. This is a HARD REQUIREMENT — entomb fails if XML export fails.
325
+
326
+ ```bash
327
+ chamber_dir=".aether/chambers/$chamber_name"
328
+ xml_result=$(bash .aether/aether-utils.sh colony-archive-xml "$chamber_dir/colony-archive.xml" 2>&1)
329
+ xml_ok=$(echo "$xml_result" | jq -r '.ok // false' 2>/dev/null)
330
+
331
+ if [[ "$xml_ok" != "true" ]]; then
332
+ # HARD STOP — remove the chamber and abort
333
+ rm -rf "$chamber_dir"
334
+ echo "XML archive export failed. Colony NOT entombed."
335
+ echo ""
336
+ echo "Error: $(echo "$xml_result" | jq -r '.error // "Unknown error"' 2>/dev/null)"
337
+ echo ""
338
+ echo "The chamber has been cleaned up. Fix the XML issue and try again."
339
+ # Do NOT proceed to state reset or any further steps
340
+ fi
266
341
  ```
267
342
 
343
+ If xml_ok is true, store for display:
344
+ ```bash
345
+ xml_pheromone_count=$(echo "$xml_result" | jq -r '.result.pheromone_count // 0' 2>/dev/null)
346
+ xml_archive_line="XML Archive: colony-archive.xml (${xml_pheromone_count} active signals)"
347
+ ```
348
+
349
+ **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.
350
+
268
351
  ### Step 8: Verify Chamber Integrity
269
352
 
270
353
  Run verification:
271
354
  ```bash
272
- bash .aether/aether-utils.sh chamber-verify ".aether/chambers/{chamber_name}"
355
+ bash .aether/aether-utils.sh chamber-verify ".aether/chambers/$chamber_name"
273
356
  ```
274
357
 
275
358
  If verification fails, display error and stop:
276
359
  ```
277
- Chamber verification failed.
360
+ Chamber verification failed.
278
361
 
279
362
  Error: {verification_error}
280
363
 
@@ -283,31 +366,50 @@ The colony has NOT been reset. Please check the chamber directory:
283
366
  ```
284
367
  Stop here.
285
368
 
286
- ### Step 9: Reset Colony State
369
+ ### Step 9: Record in Eternal Memory
370
+
371
+ Write colony summary to eternal memory:
372
+ ```bash
373
+ bash .aether/aether-utils.sh eternal-init # idempotent
374
+ eternal_file="$HOME/.aether/eternal/memory.json"
375
+ if [[ -f "$eternal_file" ]]; then
376
+ colony_entry=$(jq -n \
377
+ --arg goal "$goal" \
378
+ --arg milestone "$milestone" \
379
+ --arg sealed_at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
380
+ --arg chamber ".aether/chambers/$chamber_name" \
381
+ '{goal: $goal, milestone: $milestone, sealed_at: $sealed_at, chamber: $chamber}')
382
+ jq --argjson entry "$colony_entry" '.colonies += [$entry]' "$eternal_file" > /tmp/eternal-tmp.json \
383
+ && mv /tmp/eternal-tmp.json "$eternal_file"
384
+ fi
385
+ ```
386
+
387
+ ### Step 10: Reset Colony State
287
388
 
288
389
  Backup current state:
289
390
  ```bash
290
391
  cp .aether/data/COLONY_STATE.json .aether/data/COLONY_STATE.json.bak
291
392
  ```
292
393
 
293
- Reset state while preserving memory (pheromones):
394
+ Reset state, clearing everything including promoted wisdom (already in QUEEN.md):
294
395
  ```bash
295
- jq '
296
- .goal = null |
297
- .state = "IDLE" |
298
- .current_phase = 0 |
299
- .plan.phases = [] |
300
- .plan.generated_at = null |
301
- .plan.confidence = null |
302
- .build_started_at = null |
303
- .session_id = null |
304
- .initialized_at = null |
305
- .events = [] |
306
- .errors.records = [] |
307
- .errors.flagged_patterns = [] |
308
- .signals = [] |
309
- .graveyards = []
310
- ' .aether/data/COLONY_STATE.json.bak > .aether/data/COLONY_STATE.json
396
+ # Resolve jq template path (hub-first)
397
+ jq_template=""
398
+ for path in \
399
+ "$HOME/.aether/system/templates/colony-state-reset.jq.template" \
400
+ ".aether/templates/colony-state-reset.jq.template"; do
401
+ if [[ -f "$path" ]]; then
402
+ jq_template="$path"
403
+ break
404
+ fi
405
+ done
406
+
407
+ if [[ -z "$jq_template" ]]; then
408
+ echo "Template missing: colony-state-reset.jq.template. Run aether update to fix."
409
+ exit 1
410
+ fi
411
+
412
+ jq -f "$jq_template" .aether/data/COLONY_STATE.json.bak > .aether/data/COLONY_STATE.json
311
413
  ```
312
414
 
313
415
  Verify reset succeeded:
@@ -326,67 +428,72 @@ Remove backup after successful reset:
326
428
  rm -f .aether/data/COLONY_STATE.json.bak
327
429
  ```
328
430
 
329
- ### Step 9.5: Write Final Handoff
330
-
331
- After entombing the colony, write the final handoff documenting the archived colony:
431
+ Clear session data:
432
+ ```bash
433
+ rm -f .aether/data/session.json
434
+ ```
332
435
 
436
+ Clean up seal document (it's now in the chamber):
333
437
  ```bash
334
- cat > .aether/HANDOFF.md << 'HANDOFF_EOF'
335
- # Colony Session — ENTOMBED
438
+ rm -f .aether/CROWNED-ANTHILL.md
439
+ ```
336
440
 
337
- ## ⚰️ Colony Archived
338
- **Status:** Entombed in Chambers — Colony work preserved
441
+ ### Step 11: Write HANDOFF.md
339
442
 
340
- ## Chamber Location
341
- .aether/chambers/{chamber_name}/
443
+ Write handoff documenting the entombed colony:
342
444
 
343
- ## Colony Summary
344
- - Goal: "{goal}"
345
- - Phases: {completed} completed of {total}
346
- - Milestone: {milestone}
347
- - Entombed At: {timestamp}
445
+ Resolve the handoff template path:
446
+ Check ~/.aether/system/templates/handoff.template.md first,
447
+ then .aether/templates/handoff.template.md.
348
448
 
349
- ## Chamber Contents
350
- - colony-state.json — Full colony state
351
- - manifest.json — Archive metadata
352
- - activity.log — Colony activity history
353
- - spawn-tree.txt — Worker spawn records
354
- - flags.json — Project flags (if existed)
449
+ If no template found: output "Template missing: handoff.template.md. Run aether update to fix." and stop.
355
450
 
356
- ## Session Note
357
- This colony has been entombed and the active state reset.
358
- The colony rests. Its learnings are preserved in the chamber.
451
+ Read the template file. Fill all {{PLACEHOLDER}} values:
452
+ - {{CHAMBER_NAME}} chamber_name
453
+ - {{GOAL}} goal
454
+ - {{PHASES_COMPLETED}} → phases completed count
455
+ - {{TOTAL_PHASES}} → total phases count
456
+ - {{MILESTONE}} → milestone
457
+ - {{ENTOMB_TIMESTAMP}} → current ISO-8601 UTC timestamp
359
458
 
360
- To start anew: /ant:lay-eggs "<new goal>"
361
- To explore chambers: /ant:tunnels
362
- HANDOFF_EOF
363
- ```
459
+ Remove the HTML comment lines at the top of the template.
460
+ Write the result to .aether/HANDOFF.md using the Write tool.
364
461
 
365
- This handoff serves as the record of the entombed colony.
462
+ ### Step 12: Display Result
366
463
 
367
- ### Step 10: Display Result
464
+ **If visual_mode is true, render swarm display (consolidated):**
465
+ ```bash
466
+ bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Colony entombed" "Colony" '{"read":3,"grep":0,"edit":2,"bash":5}' 100 "fungus_garden" 100 && bash .aether/aether-utils.sh swarm-display-inline "$entomb_id"
467
+ ```
368
468
 
469
+ Display:
369
470
  ```
370
- 🏺 ═══════════════════════════════════════════════════
471
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
371
472
  C O L O N Y E N T O M B E D
372
- ══════════════════════════════════════════════════ 🏺
473
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
373
474
 
374
- Colony archived successfully
475
+ Colony archived successfully
375
476
 
376
- 👑 Goal: {goal}
377
- 📍 Phases: {completed} completed
378
- 🏆 Milestone: {milestone}
477
+ Goal: {goal}
478
+ Phases: {completed} completed
479
+ Milestone: {milestone}
379
480
 
380
- 📦 Chamber: .aether/chambers/{chamber_name}/
481
+ Chamber: .aether/chambers/{chamber_name}/
482
+ {xml_archive_line}
381
483
 
382
- 🐜 The colony rests. Its learnings are preserved.
484
+ The colony rests. Its learnings live on in QUEEN.md.
383
485
 
384
- 💾 State persisted — safe to /clear
486
+ ──────────────────────────────────────────────────
487
+ 🐜 Next Up
488
+ ──────────────────────────────────────────────────
489
+ /ant:lay-eggs 🥚 Start a new colony
490
+ /ant:tunnels 🗄️ Browse archived chambers
491
+ ```
385
492
 
386
- 🐜 What would you like to do next?
387
- 1. /ant:lay-eggs "<new goal>" — Start a new colony
388
- 2. /ant:tunnels — Browse archived colonies
389
- 3. /clear — Clear context and continue
493
+ What would you like to do next?
494
+ 1. /ant:lay-eggs "<new goal>" — Start a new colony
495
+ 2. /ant:tunnels — Browse archived colonies
496
+ 3. /clear — Clear context and continue
390
497
 
391
498
  Use AskUserQuestion with these three options.
392
499
 
@@ -397,10 +504,20 @@ If option 3 selected: display "Run /ant:lay-eggs to begin anew after clearing"
397
504
 
398
505
  ### Edge Cases
399
506
 
400
- **Chamber name collision:** Automatically append counter to make unique.
507
+ **Colony not sealed:**
508
+ - Refuse with guidance to run /ant:seal first. This is the primary gate.
509
+
510
+ **Chamber name collision:**
511
+ - Automatically append counter to make unique.
512
+
513
+ **Missing files during archive:**
514
+ - Note in output but continue with available files. The `|| true` in the copy loop handles this.
401
515
 
402
- **Missing files during archive:** Note in output but continue with available files.
516
+ **State reset failure:**
517
+ - Restore from backup, display error, do not claim success.
403
518
 
404
- **State reset failure:** Restore from backup, display error, do not claim success.
519
+ **Empty phases array:**
520
+ - Can entomb a colony that was initialized but had no phases planned (treat as 0 of 0 completed).
405
521
 
406
- **Empty phases array:** Can entomb a colony that was initialized but had no phases planned (treat as 0 of 0 completed).
522
+ **Missing CROWNED-ANTHILL.md:**
523
+ - Refuse with guidance to run /ant:seal again.