aether-colony 1.1.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 (207) hide show
  1. package/.aether/CONTEXT.md +160 -0
  2. package/.aether/QUEEN.md +84 -0
  3. package/.aether/aether-utils.sh +7749 -0
  4. package/.aether/docs/QUEEN-SYSTEM.md +211 -0
  5. package/.aether/docs/README.md +68 -0
  6. package/.aether/docs/caste-system.md +48 -0
  7. package/.aether/docs/disciplines/DISCIPLINES.md +93 -0
  8. package/.aether/docs/disciplines/coding-standards.md +197 -0
  9. package/.aether/docs/disciplines/debugging.md +207 -0
  10. package/.aether/docs/disciplines/learning.md +254 -0
  11. package/.aether/docs/disciplines/tdd.md +257 -0
  12. package/.aether/docs/disciplines/verification-loop.md +167 -0
  13. package/.aether/docs/disciplines/verification.md +116 -0
  14. package/.aether/docs/error-codes.md +268 -0
  15. package/.aether/docs/known-issues.md +233 -0
  16. package/.aether/docs/pheromones.md +205 -0
  17. package/.aether/docs/queen-commands.md +97 -0
  18. package/.aether/exchange/colony-registry.xml +11 -0
  19. package/.aether/exchange/pheromone-xml.sh +575 -0
  20. package/.aether/exchange/pheromones.xml +87 -0
  21. package/.aether/exchange/queen-wisdom.xml +14 -0
  22. package/.aether/exchange/registry-xml.sh +273 -0
  23. package/.aether/exchange/wisdom-xml.sh +319 -0
  24. package/.aether/midden/approach-changes.md +5 -0
  25. package/.aether/midden/build-failures.md +5 -0
  26. package/.aether/midden/test-failures.md +5 -0
  27. package/.aether/model-profiles.yaml +100 -0
  28. package/.aether/rules/aether-colony.md +134 -0
  29. package/.aether/schemas/aether-types.xsd +255 -0
  30. package/.aether/schemas/colony-registry.xsd +309 -0
  31. package/.aether/schemas/example-prompt-builder.xml +234 -0
  32. package/.aether/schemas/pheromone.xsd +163 -0
  33. package/.aether/schemas/prompt.xsd +416 -0
  34. package/.aether/schemas/queen-wisdom.xsd +325 -0
  35. package/.aether/schemas/worker-priming.xsd +276 -0
  36. package/.aether/templates/QUEEN.md.template +79 -0
  37. package/.aether/templates/colony-state-reset.jq.template +22 -0
  38. package/.aether/templates/colony-state.template.json +35 -0
  39. package/.aether/templates/constraints.template.json +9 -0
  40. package/.aether/templates/crowned-anthill.template.md +36 -0
  41. package/.aether/templates/handoff-build-error.template.md +30 -0
  42. package/.aether/templates/handoff-build-success.template.md +39 -0
  43. package/.aether/templates/handoff.template.md +40 -0
  44. package/.aether/templates/learning-observations.template.json +6 -0
  45. package/.aether/templates/midden.template.json +7 -0
  46. package/.aether/templates/pheromones.template.json +6 -0
  47. package/.aether/templates/session.template.json +9 -0
  48. package/.aether/utils/atomic-write.sh +219 -0
  49. package/.aether/utils/chamber-compare.sh +193 -0
  50. package/.aether/utils/chamber-utils.sh +297 -0
  51. package/.aether/utils/colorize-log.sh +132 -0
  52. package/.aether/utils/error-handler.sh +212 -0
  53. package/.aether/utils/file-lock.sh +158 -0
  54. package/.aether/utils/queen-to-md.xsl +395 -0
  55. package/.aether/utils/semantic-cli.sh +413 -0
  56. package/.aether/utils/spawn-tree.sh +428 -0
  57. package/.aether/utils/spawn-with-model.sh +56 -0
  58. package/.aether/utils/state-loader.sh +215 -0
  59. package/.aether/utils/swarm-display.sh +268 -0
  60. package/.aether/utils/watch-spawn-tree.sh +253 -0
  61. package/.aether/utils/xml-compose.sh +253 -0
  62. package/.aether/utils/xml-convert.sh +273 -0
  63. package/.aether/utils/xml-core.sh +186 -0
  64. package/.aether/utils/xml-query.sh +201 -0
  65. package/.aether/utils/xml-utils.sh +110 -0
  66. package/.aether/workers.md +765 -0
  67. package/.claude/agents/ant/aether-ambassador.md +264 -0
  68. package/.claude/agents/ant/aether-archaeologist.md +322 -0
  69. package/.claude/agents/ant/aether-auditor.md +266 -0
  70. package/.claude/agents/ant/aether-builder.md +187 -0
  71. package/.claude/agents/ant/aether-chaos.md +268 -0
  72. package/.claude/agents/ant/aether-chronicler.md +304 -0
  73. package/.claude/agents/ant/aether-gatekeeper.md +325 -0
  74. package/.claude/agents/ant/aether-includer.md +373 -0
  75. package/.claude/agents/ant/aether-keeper.md +271 -0
  76. package/.claude/agents/ant/aether-measurer.md +317 -0
  77. package/.claude/agents/ant/aether-probe.md +210 -0
  78. package/.claude/agents/ant/aether-queen.md +325 -0
  79. package/.claude/agents/ant/aether-route-setter.md +173 -0
  80. package/.claude/agents/ant/aether-sage.md +353 -0
  81. package/.claude/agents/ant/aether-scout.md +142 -0
  82. package/.claude/agents/ant/aether-surveyor-disciplines.md +416 -0
  83. package/.claude/agents/ant/aether-surveyor-nest.md +354 -0
  84. package/.claude/agents/ant/aether-surveyor-pathogens.md +288 -0
  85. package/.claude/agents/ant/aether-surveyor-provisions.md +359 -0
  86. package/.claude/agents/ant/aether-tracker.md +265 -0
  87. package/.claude/agents/ant/aether-watcher.md +244 -0
  88. package/.claude/agents/ant/aether-weaver.md +247 -0
  89. package/.claude/commands/ant/archaeology.md +341 -0
  90. package/.claude/commands/ant/build.md +1160 -0
  91. package/.claude/commands/ant/chaos.md +349 -0
  92. package/.claude/commands/ant/colonize.md +270 -0
  93. package/.claude/commands/ant/continue.md +1070 -0
  94. package/.claude/commands/ant/council.md +309 -0
  95. package/.claude/commands/ant/dream.md +265 -0
  96. package/.claude/commands/ant/entomb.md +487 -0
  97. package/.claude/commands/ant/feedback.md +78 -0
  98. package/.claude/commands/ant/flag.md +139 -0
  99. package/.claude/commands/ant/flags.md +155 -0
  100. package/.claude/commands/ant/focus.md +58 -0
  101. package/.claude/commands/ant/help.md +122 -0
  102. package/.claude/commands/ant/history.md +137 -0
  103. package/.claude/commands/ant/init.md +409 -0
  104. package/.claude/commands/ant/interpret.md +267 -0
  105. package/.claude/commands/ant/lay-eggs.md +201 -0
  106. package/.claude/commands/ant/maturity.md +102 -0
  107. package/.claude/commands/ant/memory-details.md +77 -0
  108. package/.claude/commands/ant/migrate-state.md +165 -0
  109. package/.claude/commands/ant/oracle.md +387 -0
  110. package/.claude/commands/ant/organize.md +227 -0
  111. package/.claude/commands/ant/pause-colony.md +247 -0
  112. package/.claude/commands/ant/phase.md +126 -0
  113. package/.claude/commands/ant/plan.md +544 -0
  114. package/.claude/commands/ant/redirect.md +58 -0
  115. package/.claude/commands/ant/resume-colony.md +182 -0
  116. package/.claude/commands/ant/resume.md +363 -0
  117. package/.claude/commands/ant/seal.md +306 -0
  118. package/.claude/commands/ant/status.md +272 -0
  119. package/.claude/commands/ant/swarm.md +361 -0
  120. package/.claude/commands/ant/tunnels.md +425 -0
  121. package/.claude/commands/ant/update.md +209 -0
  122. package/.claude/commands/ant/verify-castes.md +95 -0
  123. package/.claude/commands/ant/watch.md +238 -0
  124. package/.opencode/agents/aether-ambassador.md +140 -0
  125. package/.opencode/agents/aether-archaeologist.md +108 -0
  126. package/.opencode/agents/aether-auditor.md +144 -0
  127. package/.opencode/agents/aether-builder.md +184 -0
  128. package/.opencode/agents/aether-chaos.md +115 -0
  129. package/.opencode/agents/aether-chronicler.md +122 -0
  130. package/.opencode/agents/aether-gatekeeper.md +116 -0
  131. package/.opencode/agents/aether-includer.md +117 -0
  132. package/.opencode/agents/aether-keeper.md +177 -0
  133. package/.opencode/agents/aether-measurer.md +128 -0
  134. package/.opencode/agents/aether-probe.md +133 -0
  135. package/.opencode/agents/aether-queen.md +286 -0
  136. package/.opencode/agents/aether-route-setter.md +130 -0
  137. package/.opencode/agents/aether-sage.md +106 -0
  138. package/.opencode/agents/aether-scout.md +101 -0
  139. package/.opencode/agents/aether-surveyor-disciplines.md +386 -0
  140. package/.opencode/agents/aether-surveyor-nest.md +324 -0
  141. package/.opencode/agents/aether-surveyor-pathogens.md +259 -0
  142. package/.opencode/agents/aether-surveyor-provisions.md +329 -0
  143. package/.opencode/agents/aether-tracker.md +137 -0
  144. package/.opencode/agents/aether-watcher.md +174 -0
  145. package/.opencode/agents/aether-weaver.md +130 -0
  146. package/.opencode/commands/ant/archaeology.md +338 -0
  147. package/.opencode/commands/ant/build.md +1200 -0
  148. package/.opencode/commands/ant/chaos.md +346 -0
  149. package/.opencode/commands/ant/colonize.md +202 -0
  150. package/.opencode/commands/ant/continue.md +938 -0
  151. package/.opencode/commands/ant/council.md +305 -0
  152. package/.opencode/commands/ant/dream.md +262 -0
  153. package/.opencode/commands/ant/entomb.md +367 -0
  154. package/.opencode/commands/ant/feedback.md +80 -0
  155. package/.opencode/commands/ant/flag.md +137 -0
  156. package/.opencode/commands/ant/flags.md +153 -0
  157. package/.opencode/commands/ant/focus.md +56 -0
  158. package/.opencode/commands/ant/help.md +124 -0
  159. package/.opencode/commands/ant/history.md +127 -0
  160. package/.opencode/commands/ant/init.md +337 -0
  161. package/.opencode/commands/ant/interpret.md +256 -0
  162. package/.opencode/commands/ant/lay-eggs.md +141 -0
  163. package/.opencode/commands/ant/maturity.md +92 -0
  164. package/.opencode/commands/ant/memory-details.md +77 -0
  165. package/.opencode/commands/ant/migrate-state.md +153 -0
  166. package/.opencode/commands/ant/oracle.md +338 -0
  167. package/.opencode/commands/ant/organize.md +224 -0
  168. package/.opencode/commands/ant/pause-colony.md +220 -0
  169. package/.opencode/commands/ant/phase.md +123 -0
  170. package/.opencode/commands/ant/plan.md +531 -0
  171. package/.opencode/commands/ant/redirect.md +67 -0
  172. package/.opencode/commands/ant/resume-colony.md +178 -0
  173. package/.opencode/commands/ant/resume.md +363 -0
  174. package/.opencode/commands/ant/seal.md +247 -0
  175. package/.opencode/commands/ant/status.md +272 -0
  176. package/.opencode/commands/ant/swarm.md +357 -0
  177. package/.opencode/commands/ant/tunnels.md +406 -0
  178. package/.opencode/commands/ant/update.md +191 -0
  179. package/.opencode/commands/ant/verify-castes.md +85 -0
  180. package/.opencode/commands/ant/watch.md +220 -0
  181. package/.opencode/opencode.json +3 -0
  182. package/CHANGELOG.md +325 -0
  183. package/DISCLAIMER.md +74 -0
  184. package/LICENSE +21 -0
  185. package/README.md +258 -0
  186. package/bin/cli.js +2436 -0
  187. package/bin/generate-commands.sh +291 -0
  188. package/bin/lib/caste-colors.js +57 -0
  189. package/bin/lib/colors.js +76 -0
  190. package/bin/lib/errors.js +255 -0
  191. package/bin/lib/event-types.js +190 -0
  192. package/bin/lib/file-lock.js +695 -0
  193. package/bin/lib/init.js +454 -0
  194. package/bin/lib/logger.js +242 -0
  195. package/bin/lib/model-profiles.js +445 -0
  196. package/bin/lib/model-verify.js +288 -0
  197. package/bin/lib/nestmate-loader.js +130 -0
  198. package/bin/lib/proxy-health.js +253 -0
  199. package/bin/lib/spawn-logger.js +266 -0
  200. package/bin/lib/state-guard.js +602 -0
  201. package/bin/lib/state-sync.js +516 -0
  202. package/bin/lib/telemetry.js +441 -0
  203. package/bin/lib/update-transaction.js +1454 -0
  204. package/bin/npx-install.js +178 -0
  205. package/bin/sync-to-runtime.sh +6 -0
  206. package/bin/validate-package.sh +88 -0
  207. package/package.json +70 -0
@@ -0,0 +1,233 @@
1
+ # Known Issues and Workarounds
2
+
3
+ Documented issues from Oracle research findings. These are known limitations and bugs in the Aether system.
4
+
5
+ ---
6
+
7
+ ## Fixed Issues
8
+
9
+ ### Checkpoint Allowlist System (Fixed 2026-02-15)
10
+
11
+ **Issue:** Build checkpoint could stash user work (TO-DOs.md, dreams, Oracle specs)
12
+
13
+ **Root Cause:** `git stash` touched files outside system allowlist, stashing 1,145 lines of user work
14
+
15
+ **Fix:** Explicit allowlist system implemented
16
+ - Created `.aether/data/checkpoint-allowlist.json` defining safe system files
17
+ - Added `checkpoint-check` helper to `.aether/aether-utils.sh`
18
+ - Updated `build.md` (Claude and OpenCode) to use allowlist
19
+ - User data (`.aether/data/`, `.aether/dreams/`, `TO-DOs.md`) is never touched
20
+ - Warning displayed if user files are present during checkpoint
21
+
22
+ **System Files (Safe):**
23
+ - `.aether/aether-utils.sh`, `.aether/workers.md`, `.aether/docs/**/*.md`
24
+ - `.claude/commands/ant/**/*.md`, `.claude/commands/st/**/*.md`
25
+ - `.opencode/commands/ant/**/*.md`, `.opencode/agents/**/*.md`
26
+ - `bin/**/*`
27
+
28
+ **User Data (Never Touch):**
29
+ - `.aether/data/`, `.aether/dreams/`, `.aether/oracle/`
30
+ - `TO-DOs.md`, `COLONY_STATE.json`, `.env`, `*.log`
31
+
32
+ ---
33
+
34
+ ## Critical Issues (Fix Immediately)
35
+
36
+ ### BUG-005: Missing lock release in flag-auto-resolve — FIXED (Phase 16)
37
+ **Location:** `.aether/aether-utils.sh:1022`
38
+ **Severity:** HIGH
39
+ **Status:** FIXED — Fixed in Phase 16: unified trap pattern (`trap 'release_lock 2>/dev/null || true' EXIT`) applied across all flag commands ensures lock release on all exit paths including jq failure.
40
+ **Symptom:** If jq command fails during flag resolution, lock is never released
41
+ **Impact:** Deadlock on flags.json if jq fails (malformed JSON, disk full, etc.)
42
+ **Workaround:** ~~Restart the colony session if commands hang on flag operations~~ — no longer needed
43
+ **Regression test:** `tests/bash/test-lock-lifecycle.sh` — test_flag_auto_resolve_jq_failure_releases_lock
44
+
45
+ ### BUG-011: Missing error handling in flag-auto-resolve jq — FIXED (Phase 16)
46
+ **Location:** `.aether/aether-utils.sh:1022`
47
+ **Severity:** HIGH
48
+ **Status:** FIXED — Fixed in Phase 16: unified trap pattern across all flag commands. See BUG-005.
49
+ **Symptom:** jq failure during auto-resolve not handled
50
+ **Impact:** Combined with BUG-005, causes deadlock
51
+ **Fix:** ~~Add `|| { release_lock; json_err ... }` pattern~~ — implemented via EXIT trap
52
+
53
+ ---
54
+
55
+ ## Medium Priority Issues
56
+
57
+ ### BUG-002: Missing release_lock in flag-add error path — FIXED (Phase 16)
58
+ **Location:** `.aether/aether-utils.sh:814`
59
+ **Severity:** MEDIUM
60
+ **Status:** FIXED — Fixed in Phase 16: trap-based EXIT cleanup (`trap 'release_lock 2>/dev/null || true' EXIT`) ensures lock release on all exit paths including jq failure. Trap is cleared on the success path.
61
+ **Symptom:** If acquire_lock succeeds but jq fails, lock is never released
62
+ **Impact:** Potential deadlock on file operations
63
+ **Regression test:** `tests/bash/test-lock-lifecycle.sh` — test_flag_add_jq_failure_releases_lock
64
+
65
+ ### BUG-003: Race condition in backup creation — FIXED (Phase 16)
66
+ **Location:** `.aether/utils/atomic-write.sh:75`
67
+ **Severity:** MEDIUM
68
+ **Status:** FIXED — Backup is now created BEFORE JSON validation in both `atomic_write` and `atomic_write_from_file`. Verified in Phase 16 with regression tests confirming backup contains pre-write content.
69
+ **Symptom:** Backup created AFTER temp file validation but BEFORE atomic move
70
+ **Impact:** If process crashes between validation and backup, inconsistent state
71
+ **Regression test:** `tests/bash/test-lock-lifecycle.sh` — test_atomic_write_backup_before_validate, test_atomic_write_from_file_backup_before_validate
72
+
73
+ ### BUG-004: Missing error code in flag-acknowledge
74
+ **Location:** `.aether/aether-utils.sh:930`
75
+ **Severity:** MEDIUM
76
+ **Symptom:** Uses hardcoded string instead of `$E_VALIDATION_FAILED`
77
+ **Impact:** Inconsistent error handling
78
+ **Fix:** Change to `json_err "$E_VALIDATION_FAILED" "Usage: ..."`
79
+
80
+ ### BUG-006: No lock release on JSON validation failure
81
+ **Location:** `.aether/utils/atomic-write.sh:66`
82
+ **Severity:** MEDIUM
83
+ **Symptom:** If JSON validation fails, temp file cleaned but lock not released
84
+ **Impact:** Lock remains held if caller had acquired it
85
+ **Fix:** Document lock ownership contract clearly
86
+
87
+ ### BUG-007: 17+ instances of missing error codes
88
+ **Location:** `.aether/aether-utils.sh` various lines
89
+ **Severity:** MEDIUM
90
+ **Symptom:** Commands use hardcoded strings instead of error constants
91
+ **Impact:** Inconsistent error handling, harder programmatic processing
92
+ **Fix:** Standardize all to use `json_err "$E_*" "message"` pattern
93
+
94
+ ### BUG-008: Missing error code in flag-add jq failure
95
+ **Location:** `.aether/aether-utils.sh:856`
96
+ **Severity:** HIGH
97
+ **Symptom:** Lock released but error code missing on jq failure
98
+ **Impact:** Error response lacks proper error code
99
+ **Fix:** Change to `json_err "$E_JSON_INVALID" "Failed to add flag"`
100
+
101
+ ### BUG-009: Missing error codes in file checks
102
+ **Location:** `.aether/aether-utils.sh:899, 933`
103
+ **Severity:** MEDIUM
104
+ **Symptom:** File not found errors use hardcoded strings
105
+ **Impact:** Inconsistent with other file not found errors
106
+ **Fix:** Use `json_err "$E_FILE_NOT_FOUND" "..."`
107
+
108
+ ### BUG-010: Missing error codes in context-update
109
+ **Location:** `.aether/aether-utils.sh:1758+`
110
+ **Severity:** MEDIUM
111
+ **Symptom:** Various error paths lack error code constants
112
+ **Impact:** Inconsistent error handling
113
+
114
+ ### BUG-012: Missing error code in unknown command
115
+ **Location:** `.aether/aether-utils.sh:2947`
116
+ **Severity:** LOW
117
+ **Symptom:** Unknown command handler uses bare string
118
+ **Impact:** Inconsistent error response
119
+
120
+ ---
121
+
122
+ ## Architecture Issues
123
+
124
+ ### ISSUE-001: Inconsistent error code usage
125
+ **Location:** Multiple locations
126
+ **Severity:** MEDIUM
127
+ **Description:** Some `json_err` calls use hardcoded strings instead of constants
128
+ **Pattern:** Commands added early use strings; later commands use constants
129
+
130
+ ### ISSUE-002: Missing exec error handling — FIXED (Phase 18-02)
131
+ **Location:** `.aether/aether-utils.sh:2132-2144`
132
+ **Severity:** LOW
133
+ **Description:** `model-get` and `model-list` use `exec` without fallback
134
+ **Impact:** If exec fails, script continues to unknown command handler
135
+ **Status:** FIXED — Phase 18-02: subprocess error handling added to model-get and model-list with structured E_* error codes on failure.
136
+
137
+ ### ISSUE-003: Incomplete help command — FIXED (Phase 18-03)
138
+ **Location:** `.aether/aether-utils.sh:106-111`
139
+ **Severity:** LOW
140
+ **Description:** Help command missing newer commands like queen-*, view-state-*, swarm-timing-*
141
+ **Impact:** Users cannot discover all available commands
142
+ **Status:** FIXED — Phase 18-03: help command sections key added with all command groups including Queen Commands, Model Routing, Swarm Operations, and all newer commands.
143
+
144
+ ### ISSUE-004: Template path hardcoded to staging directory — FIXED (Phase 20)
145
+ **Location:** `.aether/aether-utils.sh:2689`
146
+ **Severity:** MEDIUM
147
+ **Status:** FIXED — Phase 20: stale staging template path removed from queen-init lookup array. Template is now found via hub path (`~/.aether/system/templates/`) or dev repo path (`.aether/templates/`) or legacy hub fallback.
148
+ **Description:** queen-init used a staging directory path that did not exist in npm installs
149
+ **Impact:** ~~queen-init will fail when Aether is installed as npm package~~
150
+ **~~Workaround:~~** ~~Use git clone instead of npm install~~ — no longer needed
151
+
152
+ ### ISSUE-005: Potential infinite loop in spawn-tree
153
+ **Location:** `.aether/aether-utils.sh:402-448`, `spawn-tree.sh:222-263`
154
+ **Severity:** LOW
155
+ **Description:** Edge case with circular parent chain could cause issues
156
+ **Mitigation:** Safety limit of 5 exists
157
+
158
+ ### ISSUE-006: Fallback json_err incompatible
159
+ **Location:** `.aether/aether-utils.sh:65-72`
160
+ **Severity:** LOW
161
+ **Description:** Fallback json_err doesn't accept error code parameter
162
+ **Impact:** If error-handler.sh fails to load, error codes are lost
163
+
164
+ ### ISSUE-007: Feature detection race condition — FIXED (Phase 18-01)
165
+ **Location:** `.aether/aether-utils.sh:33-45`
166
+ **Severity:** LOW
167
+ **Description:** Feature detection runs before error handler fully sourced
168
+ **Status:** FIXED — Phase 18-01 (ARCH-09): feature detection block moved after fallback json_err definition (line 68 -> 81) so all fallback infrastructure available when feature detection runs.
169
+
170
+ ---
171
+
172
+ ## Architecture Gaps
173
+
174
+ ### GAP-001: No schema version validation — FIXED (Phase 18-04)
175
+ **Description:** Commands assume state structure without validating version
176
+ **Impact:** Silent failures when state structure changes
177
+ **Status:** FIXED — Phase 18-04: `_migrate_colony_state` added to validate-state colony; auto-migrates pre-3.0 state files to v3.0 (additive only), notifies via W_MIGRATED warning; corrupt state files backed up before error.
178
+
179
+ ### GAP-002: No cleanup for stale spawn-tree entries — FIXED (Phase 18-01)
180
+ **Description:** spawn-tree.txt grows indefinitely
181
+ **Impact:** File could grow very large over many sessions
182
+ **Status:** FIXED — Phase 18-01: `_rotate_spawn_tree` added to session-init; rotates spawn-tree.txt on each session start with timestamped archives; 5-archive cap; in-place truncation preserves tail -f file handles.
183
+
184
+ ### GAP-003: No retry logic for failed spawns — RESOLVED (Phase 18-02)
185
+ **Description:** Task tool calls don't have retry logic
186
+ **Impact:** Transient failures cause build failures
187
+ **Status:** RESOLVED — User decision: fail-fast with rich error context (Phase 18-02). Retry logic adds complexity without clear benefit; subprocess errors now emit structured E_* codes with actionable Try: suggestions, allowing callers to decide on retry strategy.
188
+
189
+ ### GAP-004: Missing queen-* documentation — FIXED (Phase 18-03)
190
+ **Description:** No docs for queen-init, queen-read, queen-promote
191
+ **Impact:** Users cannot discover wisdom feedback loop
192
+ **Status:** FIXED — Phase 18-03: queen-commands.md created in .aether/docs/; help command sections key added with Queen Commands section listing all three commands with descriptions.
193
+
194
+ ### GAP-005: No validation of queen-read JSON output — FIXED (Phase 18-04)
195
+ **Description:** queen-read builds JSON but doesn't validate before returning
196
+ **Impact:** Could return malformed response
197
+ **Status:** FIXED — Phase 18-04: Two validation gates added to queen-read: Gate 1 validates METADATA JSON before --argjson use; Gate 2 validates assembled result before json_ok. Both emit E_JSON_INVALID with actionable Try: suggestion.
198
+
199
+ ### GAP-006: Missing queen-* command documentation — FIXED (Phase 18-03)
200
+ **Description:** Duplicate of GAP-004 - no documentation exists
201
+ **Impact:** Commands are undiscoverable
202
+ **Status:** FIXED — Phase 18-03: See GAP-004.
203
+
204
+ ### GAP-007: No error code standards documentation
205
+ **Description:** Error codes exist but aren't documented
206
+ **Impact:** Developers don't know which codes to use
207
+
208
+ ### GAP-008: Missing error path test coverage
209
+ **Description:** Error handling paths not tested
210
+ **Impact:** Bugs in error handling go undetected
211
+
212
+ ### GAP-009: context-update has no file locking — FIXED (Phase 16)
213
+ **Description:** Race condition possible during concurrent context updates
214
+ **Status:** FIXED — Fixed in Phase 16: context-update wraps all 11 action handlers in a single acquire_lock/release_lock pair. Lock is held for the duration of the update and released on both success and error paths via EXIT trap. force-unlock subcommand added for emergency recovery.
215
+ **Impact:** Potential data corruption
216
+ **Regression test:** `tests/bash/test-lock-lifecycle.sh` — test_context_update_acquires_lock, test_force_unlock_clears_locks
217
+
218
+ ### GAP-010: Missing error code standards documentation
219
+ **Description:** Duplicate of GAP-007
220
+
221
+ ---
222
+
223
+ ## Workarounds Summary
224
+
225
+ | Issue | Workaround |
226
+ |-------|------------|
227
+ | ~~Lock-related deadlocks (BUG-005, BUG-002)~~ | ~~Restart colony session~~ — FIXED in Phase 16 |
228
+ | ~~Template path issue (ISSUE-004)~~ | ~~Use git clone instead of npm~~ — FIXED in Phase 20 |
229
+ | Missing command docs (GAP-004) | Read source code directly |
230
+
231
+ ---
232
+
233
+ *Generated from Oracle Research findings - 2026-02-15*
@@ -0,0 +1,205 @@
1
+ # Pheromone Signals -- User Guide
2
+
3
+ Pheromones are how you communicate with the colony. Instead of micromanaging individual ants, you emit chemical signals that influence their behavior. Signals have a TTL (time-to-live) and priority level. By default, signals last until the current phase completes.
4
+
5
+ ## How Pheromones Work
6
+
7
+ - **You emit** signals using `/ant:focus`, `/ant:redirect`, `/ant:feedback`
8
+ - **The colony also emits** signals automatically after builds (FEEDBACK after every phase, REDIRECT when error patterns recur)
9
+ - **Signals expire** based on their `expires_at` field -- default is `"phase_end"` (lasts until phase completes)
10
+ - **Optional TTL** -- use `--ttl` flag for wall-clock expiration (e.g., `--ttl 2h` for 2 hours)
11
+ - **Priority levels** determine worker attention: high (REDIRECT), normal (FOCUS), low (FEEDBACK)
12
+ - **Expired signals** are filtered on read -- no cleanup process needed
13
+
14
+ Run `/ant:status` at any time to see all active pheromones.
15
+
16
+ ---
17
+
18
+ ## FOCUS -- Guide Attention
19
+
20
+ **Command:** `/ant:focus "<area>"`
21
+ **Priority:** normal | **Default expiration:** end of phase
22
+
23
+ **What it does:** Tells the colony "pay extra attention here." Workers read FOCUS signals and weight this area higher in their task execution.
24
+
25
+ ### When to use FOCUS
26
+
27
+ **Scenario 1: Steering the next build phase**
28
+ You're about to run `/ant:build 3` and Phase 3 has tasks touching both the API layer and the database layer. You know the database schema is fragile:
29
+
30
+ ```
31
+ /ant:focus "database schema -- handle migrations carefully"
32
+ /ant:build 3
33
+ ```
34
+
35
+ **Scenario 2: Time-limited focus**
36
+ You want attention on auth for the next 2 hours, then let it fade:
37
+
38
+ ```
39
+ /ant:focus "auth middleware correctness" --ttl 2h
40
+ ```
41
+
42
+ **Scenario 3: Directing colonization**
43
+ You're colonizing a new project and want the colonizer to pay special attention to testing:
44
+
45
+ ```
46
+ /ant:focus "test framework and coverage gaps"
47
+ /ant:colonize
48
+ ```
49
+
50
+ ### When NOT to use FOCUS
51
+
52
+ - Don't stack 5+ FOCUS signals -- the colony can't prioritize everything
53
+ - Don't FOCUS on things the colony already handles (like "write good code") -- be specific
54
+ - Don't FOCUS after a phase completes if you're about to `/clear` context -- emit it fresh before the next build
55
+
56
+ ---
57
+
58
+ ## REDIRECT -- Warn Away
59
+
60
+ **Command:** `/ant:redirect "<pattern to avoid>"`
61
+ **Priority:** high | **Default expiration:** end of phase
62
+
63
+ **What it does:** Acts as a hard constraint. Workers with high priority signal awareness will actively avoid the specified pattern. This is the strongest signal type.
64
+
65
+ ### When to use REDIRECT
66
+
67
+ **Scenario 1: Preventing a known bad approach**
68
+ Your project uses Next.js Edge Runtime, and you know `jsonwebtoken` doesn't work there:
69
+
70
+ ```
71
+ /ant:redirect "Don't use jsonwebtoken -- use jose library instead (Edge Runtime compatible)"
72
+ /ant:build 2
73
+ ```
74
+
75
+ **Scenario 2: Long-lived constraint**
76
+ You want to enforce a constraint across multiple phases (24 hours):
77
+
78
+ ```
79
+ /ant:redirect "No global mutable state -- use request-scoped context" --ttl 1d
80
+ ```
81
+
82
+ **Scenario 3: Steering away from a previous failure**
83
+ Phase 1 tried to use synchronous file reads and caused performance issues:
84
+
85
+ ```
86
+ /ant:redirect "No synchronous file I/O -- use async fs/promises"
87
+ ```
88
+
89
+ ### When NOT to use REDIRECT
90
+
91
+ - Don't REDIRECT for preferences -- use it for hard constraints ("will break" not "I don't like")
92
+ - Don't REDIRECT on vague patterns ("don't write bad code") -- be specific
93
+ - Don't use REDIRECT when FOCUS would suffice
94
+
95
+ ---
96
+
97
+ ## FEEDBACK -- Adjust Course
98
+
99
+ **Command:** `/ant:feedback "<observation>"`
100
+ **Priority:** low | **Default expiration:** end of phase
101
+
102
+ **What it does:** Provides gentle course correction. Unlike FOCUS (attention) or REDIRECT (avoidance), FEEDBACK adjusts the colony's approach based on your observations.
103
+
104
+ ### When to use FEEDBACK
105
+
106
+ **Scenario 1: Mid-project course correction**
107
+ After building Phase 2, you notice the code is over-engineered:
108
+
109
+ ```
110
+ /ant:feedback "Code is too abstract -- prefer simple, direct implementations over clever abstractions"
111
+ ```
112
+
113
+ **Scenario 2: Positive reinforcement**
114
+ Phase 3 produced clean, well-tested code. You want more of the same:
115
+
116
+ ```
117
+ /ant:feedback "Great test coverage in Phase 3 -- maintain this level of testing"
118
+ ```
119
+
120
+ **Scenario 3: Quality emphasis shift**
121
+ You're noticing the code lacks error handling:
122
+
123
+ ```
124
+ /ant:feedback "Need more error handling -- happy path works but edge cases are unhandled"
125
+ ```
126
+
127
+ ### When NOT to use FEEDBACK
128
+
129
+ - Don't use FEEDBACK for hard constraints -- that's REDIRECT's job
130
+ - Don't use FEEDBACK before the colony has produced anything
131
+ - Don't emit multiple conflicting FEEDBACK signals
132
+
133
+ ---
134
+
135
+ ## Auto-Emitted Pheromones
136
+
137
+ The colony emits pheromones automatically during builds. You don't need to manage these:
138
+
139
+ - **FEEDBACK after every phase:** build.md (Step 7b) emits a FEEDBACK pheromone summarizing what worked and what failed
140
+ - **REDIRECT on error patterns:** If errors.json has recurring flagged patterns, build.md and continue.md auto-emit REDIRECT signals
141
+ - **FEEDBACK from global learnings:** When colonizing a new project, colonize.md injects relevant global learnings as FEEDBACK pheromones
142
+
143
+ Auto-emitted signals have their `source` field set to indicate origin: `"worker:builder"`, `"worker:continue"`, or `"global:inject"`.
144
+
145
+ ---
146
+
147
+ ## Signal Combinations
148
+
149
+ Pheromones combine. Workers check all active signals and respond accordingly:
150
+
151
+ | Combination | Effect |
152
+ |-------------|--------|
153
+ | FOCUS + FEEDBACK | Workers concentrate on the focused area and adjust approach based on feedback |
154
+ | FOCUS + REDIRECT | Workers prioritize the focused area while avoiding the redirected pattern |
155
+ | FEEDBACK + REDIRECT | Workers adjust approach (feedback) and avoid specific patterns (redirect) |
156
+ | All three | Full steering: attention (FOCUS), avoidance (REDIRECT), and adjustment (FEEDBACK) |
157
+
158
+ **Priority processing:** Workers check high priority signals first, then normal, then low.
159
+
160
+ ---
161
+
162
+ ## TTL Options
163
+
164
+ By default, signals expire at phase end (`expires_at: "phase_end"`). Use `--ttl` flag for wall-clock expiration:
165
+
166
+ ```
167
+ /ant:focus "database schema" # expires at phase end
168
+ /ant:focus "API layer" --ttl 2h # expires in 2 hours
169
+ /ant:redirect "No JWT" --ttl 1d # expires in 1 day
170
+ /ant:feedback "keep tests simple" --ttl 30m # expires in 30 minutes
171
+ ```
172
+
173
+ **Duration format:** `<number><unit>` where unit is:
174
+ - `m` = minutes (e.g., `30m`)
175
+ - `h` = hours (e.g., `2h`)
176
+ - `d` = days (e.g., `1d`)
177
+
178
+ ---
179
+
180
+ ## Pause-Aware TTL
181
+
182
+ When the colony is paused (`paused_at` timestamp recorded):
183
+
184
+ - **Wall-clock TTLs** are extended by the pause duration on resume
185
+ - **Phase-scoped signals** (`expires_at: "phase_end"`) are unaffected by pause
186
+
187
+ This ensures signals don't expire while you're away from the project.
188
+
189
+ ---
190
+
191
+ ## Quick Reference
192
+
193
+ | Signal | Command | Priority | Default Expiration | Use for |
194
+ |--------|---------|----------|-------------------|---------|
195
+ | FOCUS | `/ant:focus "<area>"` | normal | phase end | "Pay attention to this" |
196
+ | REDIRECT | `/ant:redirect "<avoid>"` | high | phase end | "Don't do this" |
197
+ | FEEDBACK | `/ant:feedback "<note>"` | low | phase end | "Adjust based on this" |
198
+
199
+ **Rule of thumb:**
200
+ - Before a build: FOCUS + REDIRECT to steer
201
+ - After a build: FEEDBACK to adjust
202
+ - For hard constraints: REDIRECT (high priority)
203
+ - For gentle nudges: FEEDBACK (low priority)
204
+ - For attention: FOCUS (normal priority)
205
+ - For short-lived signals: use `--ttl` flag
@@ -0,0 +1,97 @@
1
+ # Queen Commands Reference
2
+
3
+ The queen-* commands manage the QUEEN.md wisdom file — a persistent cross-colony knowledge base that accumulates philosophies, patterns, redirects, stack wisdom, and decrees across sessions.
4
+
5
+ For the QUEEN.md file format and wisdom feedback loop, see [QUEEN-SYSTEM.md](./QUEEN-SYSTEM.md).
6
+
7
+ ## Commands
8
+
9
+ ### queen-init
10
+
11
+ **Purpose:** Initialize a new QUEEN.md from the system template.
12
+
13
+ **Usage:**
14
+ ```bash
15
+ bash .aether/aether-utils.sh queen-init
16
+ ```
17
+
18
+ **Returns:** JSON with creation status, file path, and template source.
19
+
20
+ **Example output:**
21
+ ```json
22
+ {"ok":true,"result":{"created":true,"path":".aether/docs/QUEEN.md","source":"~/.aether/system/docs/QUEEN.md.template"}}
23
+ ```
24
+
25
+ **Behavior:**
26
+ - If QUEEN.md already exists, returns `{"created":false}` without overwriting
27
+ - Searches for template in: hub system path, then local .aether/templates/
28
+ - Creates `.aether/docs/` directory if it doesn't exist
29
+
30
+ ---
31
+
32
+ ### queen-read
33
+
34
+ **Purpose:** Read QUEEN.md wisdom as structured JSON for worker priming.
35
+
36
+ **Usage:**
37
+ ```bash
38
+ bash .aether/aether-utils.sh queen-read
39
+ ```
40
+
41
+ **Returns:** JSON with metadata, wisdom sections, and priming flags.
42
+
43
+ **Example output:**
44
+ ```json
45
+ {"ok":true,"result":{"metadata":{...},"wisdom":{"philosophies":"...","patterns":"...","redirects":"...","stack_wisdom":"...","decrees":"..."},"priming":{"has_philosophies":true,...}}}
46
+ ```
47
+
48
+ **Behavior:**
49
+ - Extracts METADATA JSON block from `<!-- METADATA ... -->` comment
50
+ - Parses each wisdom section (Philosophies, Patterns, Redirects, Stack Wisdom, Decrees)
51
+ - Returns priming flags indicating which sections have content
52
+ - Returns E_JSON_INVALID if METADATA block contains malformed JSON
53
+ - Returns E_FILE_NOT_FOUND if QUEEN.md doesn't exist
54
+
55
+ ---
56
+
57
+ ### queen-promote
58
+
59
+ **Purpose:** Promote a validated learning to QUEEN.md wisdom.
60
+
61
+ **Usage:**
62
+ ```bash
63
+ bash .aether/aether-utils.sh queen-promote <type> <content> <colony_name>
64
+ ```
65
+
66
+ **Arguments:**
67
+
68
+ | Argument | Required | Description |
69
+ |----------|----------|-------------|
70
+ | type | Yes | Wisdom category: `philosophy`, `pattern`, `redirect`, `stack`, `decree` |
71
+ | content | Yes | The wisdom text to add |
72
+ | colony_name | Yes | Name of the colony contributing the wisdom |
73
+
74
+ **Returns:** JSON confirming the promotion with details.
75
+
76
+ **Behavior:**
77
+ - Appends the wisdom entry to the appropriate section in QUEEN.md
78
+ - Includes attribution (colony name) and timestamp
79
+ - Updates the METADATA block's stats
80
+
81
+ ---
82
+
83
+ ## For Contributors
84
+
85
+ The queen commands are part of the colony lifecycle:
86
+
87
+ 1. **Colony startup:** `/ant:colonize` calls `queen-init` to ensure QUEEN.md exists
88
+ 2. **Worker priming:** `/ant:swarm` calls `queen-read` to inject wisdom into worker prompts
89
+ 3. **Colony end:** `/ant:seal` can call `queen-promote` to persist learnings
90
+
91
+ ### Adding a New Queen Command
92
+
93
+ 1. Add the case block in `aether-utils.sh` (alongside existing `queen-*` blocks)
94
+ 2. Add it to the flat `commands` array in the `help)` case block
95
+ 3. Add it to the "Queen Commands" section in help's `sections` JSON
96
+ 4. Update this file with usage documentation
97
+ 5. Add tests in `tests/bash/test-aether-utils.sh`
@@ -0,0 +1,11 @@
1
+ <?xml version="1.0" encoding="UTF-8"?>
2
+ <colony-registry xmlns="http://aether.colony/schemas/registry/1.0"
3
+ version="1.0.0"
4
+ generated_at="2026-02-18T01:48:47Z">
5
+ <colony id="Remove Aether developing Aether self-reference while preserving findings" status="active" created_at="2026-02-15T15:59:13Z">
6
+ <name>Remove Aether developing Aether self-reference while preserving findings</name>
7
+ </colony>
8
+ <colony id="v1.1 Bug Fixes &amp; Update System Repair" status="active" created_at="unknown">
9
+ <name>v1.1 Bug Fixes &amp; Update System Repair</name>
10
+ </colony>
11
+ </colony-registry>