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.
- package/.aether/CONTEXT.md +160 -0
- package/.aether/QUEEN.md +84 -0
- package/.aether/aether-utils.sh +7749 -0
- package/.aether/docs/QUEEN-SYSTEM.md +211 -0
- package/.aether/docs/README.md +68 -0
- package/.aether/docs/caste-system.md +48 -0
- package/.aether/docs/disciplines/DISCIPLINES.md +93 -0
- package/.aether/docs/disciplines/coding-standards.md +197 -0
- package/.aether/docs/disciplines/debugging.md +207 -0
- package/.aether/docs/disciplines/learning.md +254 -0
- package/.aether/docs/disciplines/tdd.md +257 -0
- package/.aether/docs/disciplines/verification-loop.md +167 -0
- package/.aether/docs/disciplines/verification.md +116 -0
- package/.aether/docs/error-codes.md +268 -0
- package/.aether/docs/known-issues.md +233 -0
- package/.aether/docs/pheromones.md +205 -0
- package/.aether/docs/queen-commands.md +97 -0
- package/.aether/exchange/colony-registry.xml +11 -0
- package/.aether/exchange/pheromone-xml.sh +575 -0
- package/.aether/exchange/pheromones.xml +87 -0
- package/.aether/exchange/queen-wisdom.xml +14 -0
- package/.aether/exchange/registry-xml.sh +273 -0
- package/.aether/exchange/wisdom-xml.sh +319 -0
- package/.aether/midden/approach-changes.md +5 -0
- package/.aether/midden/build-failures.md +5 -0
- package/.aether/midden/test-failures.md +5 -0
- package/.aether/model-profiles.yaml +100 -0
- package/.aether/rules/aether-colony.md +134 -0
- package/.aether/schemas/aether-types.xsd +255 -0
- package/.aether/schemas/colony-registry.xsd +309 -0
- package/.aether/schemas/example-prompt-builder.xml +234 -0
- package/.aether/schemas/pheromone.xsd +163 -0
- package/.aether/schemas/prompt.xsd +416 -0
- package/.aether/schemas/queen-wisdom.xsd +325 -0
- package/.aether/schemas/worker-priming.xsd +276 -0
- package/.aether/templates/QUEEN.md.template +79 -0
- package/.aether/templates/colony-state-reset.jq.template +22 -0
- package/.aether/templates/colony-state.template.json +35 -0
- package/.aether/templates/constraints.template.json +9 -0
- package/.aether/templates/crowned-anthill.template.md +36 -0
- package/.aether/templates/handoff-build-error.template.md +30 -0
- package/.aether/templates/handoff-build-success.template.md +39 -0
- package/.aether/templates/handoff.template.md +40 -0
- package/.aether/templates/learning-observations.template.json +6 -0
- package/.aether/templates/midden.template.json +7 -0
- package/.aether/templates/pheromones.template.json +6 -0
- package/.aether/templates/session.template.json +9 -0
- package/.aether/utils/atomic-write.sh +219 -0
- package/.aether/utils/chamber-compare.sh +193 -0
- package/.aether/utils/chamber-utils.sh +297 -0
- package/.aether/utils/colorize-log.sh +132 -0
- package/.aether/utils/error-handler.sh +212 -0
- package/.aether/utils/file-lock.sh +158 -0
- package/.aether/utils/queen-to-md.xsl +395 -0
- package/.aether/utils/semantic-cli.sh +413 -0
- package/.aether/utils/spawn-tree.sh +428 -0
- package/.aether/utils/spawn-with-model.sh +56 -0
- package/.aether/utils/state-loader.sh +215 -0
- package/.aether/utils/swarm-display.sh +268 -0
- package/.aether/utils/watch-spawn-tree.sh +253 -0
- package/.aether/utils/xml-compose.sh +253 -0
- package/.aether/utils/xml-convert.sh +273 -0
- package/.aether/utils/xml-core.sh +186 -0
- package/.aether/utils/xml-query.sh +201 -0
- package/.aether/utils/xml-utils.sh +110 -0
- package/.aether/workers.md +765 -0
- package/.claude/agents/ant/aether-ambassador.md +264 -0
- package/.claude/agents/ant/aether-archaeologist.md +322 -0
- package/.claude/agents/ant/aether-auditor.md +266 -0
- package/.claude/agents/ant/aether-builder.md +187 -0
- package/.claude/agents/ant/aether-chaos.md +268 -0
- package/.claude/agents/ant/aether-chronicler.md +304 -0
- package/.claude/agents/ant/aether-gatekeeper.md +325 -0
- package/.claude/agents/ant/aether-includer.md +373 -0
- package/.claude/agents/ant/aether-keeper.md +271 -0
- package/.claude/agents/ant/aether-measurer.md +317 -0
- package/.claude/agents/ant/aether-probe.md +210 -0
- package/.claude/agents/ant/aether-queen.md +325 -0
- package/.claude/agents/ant/aether-route-setter.md +173 -0
- package/.claude/agents/ant/aether-sage.md +353 -0
- package/.claude/agents/ant/aether-scout.md +142 -0
- package/.claude/agents/ant/aether-surveyor-disciplines.md +416 -0
- package/.claude/agents/ant/aether-surveyor-nest.md +354 -0
- package/.claude/agents/ant/aether-surveyor-pathogens.md +288 -0
- package/.claude/agents/ant/aether-surveyor-provisions.md +359 -0
- package/.claude/agents/ant/aether-tracker.md +265 -0
- package/.claude/agents/ant/aether-watcher.md +244 -0
- package/.claude/agents/ant/aether-weaver.md +247 -0
- package/.claude/commands/ant/archaeology.md +341 -0
- package/.claude/commands/ant/build.md +1160 -0
- package/.claude/commands/ant/chaos.md +349 -0
- package/.claude/commands/ant/colonize.md +270 -0
- package/.claude/commands/ant/continue.md +1070 -0
- package/.claude/commands/ant/council.md +309 -0
- package/.claude/commands/ant/dream.md +265 -0
- package/.claude/commands/ant/entomb.md +487 -0
- package/.claude/commands/ant/feedback.md +78 -0
- package/.claude/commands/ant/flag.md +139 -0
- package/.claude/commands/ant/flags.md +155 -0
- package/.claude/commands/ant/focus.md +58 -0
- package/.claude/commands/ant/help.md +122 -0
- package/.claude/commands/ant/history.md +137 -0
- package/.claude/commands/ant/init.md +409 -0
- package/.claude/commands/ant/interpret.md +267 -0
- package/.claude/commands/ant/lay-eggs.md +201 -0
- package/.claude/commands/ant/maturity.md +102 -0
- package/.claude/commands/ant/memory-details.md +77 -0
- package/.claude/commands/ant/migrate-state.md +165 -0
- package/.claude/commands/ant/oracle.md +387 -0
- package/.claude/commands/ant/organize.md +227 -0
- package/.claude/commands/ant/pause-colony.md +247 -0
- package/.claude/commands/ant/phase.md +126 -0
- package/.claude/commands/ant/plan.md +544 -0
- package/.claude/commands/ant/redirect.md +58 -0
- package/.claude/commands/ant/resume-colony.md +182 -0
- package/.claude/commands/ant/resume.md +363 -0
- package/.claude/commands/ant/seal.md +306 -0
- package/.claude/commands/ant/status.md +272 -0
- package/.claude/commands/ant/swarm.md +361 -0
- package/.claude/commands/ant/tunnels.md +425 -0
- package/.claude/commands/ant/update.md +209 -0
- package/.claude/commands/ant/verify-castes.md +95 -0
- package/.claude/commands/ant/watch.md +238 -0
- package/.opencode/agents/aether-ambassador.md +140 -0
- package/.opencode/agents/aether-archaeologist.md +108 -0
- package/.opencode/agents/aether-auditor.md +144 -0
- package/.opencode/agents/aether-builder.md +184 -0
- package/.opencode/agents/aether-chaos.md +115 -0
- package/.opencode/agents/aether-chronicler.md +122 -0
- package/.opencode/agents/aether-gatekeeper.md +116 -0
- package/.opencode/agents/aether-includer.md +117 -0
- package/.opencode/agents/aether-keeper.md +177 -0
- package/.opencode/agents/aether-measurer.md +128 -0
- package/.opencode/agents/aether-probe.md +133 -0
- package/.opencode/agents/aether-queen.md +286 -0
- package/.opencode/agents/aether-route-setter.md +130 -0
- package/.opencode/agents/aether-sage.md +106 -0
- package/.opencode/agents/aether-scout.md +101 -0
- package/.opencode/agents/aether-surveyor-disciplines.md +386 -0
- package/.opencode/agents/aether-surveyor-nest.md +324 -0
- package/.opencode/agents/aether-surveyor-pathogens.md +259 -0
- package/.opencode/agents/aether-surveyor-provisions.md +329 -0
- package/.opencode/agents/aether-tracker.md +137 -0
- package/.opencode/agents/aether-watcher.md +174 -0
- package/.opencode/agents/aether-weaver.md +130 -0
- package/.opencode/commands/ant/archaeology.md +338 -0
- package/.opencode/commands/ant/build.md +1200 -0
- package/.opencode/commands/ant/chaos.md +346 -0
- package/.opencode/commands/ant/colonize.md +202 -0
- package/.opencode/commands/ant/continue.md +938 -0
- package/.opencode/commands/ant/council.md +305 -0
- package/.opencode/commands/ant/dream.md +262 -0
- package/.opencode/commands/ant/entomb.md +367 -0
- package/.opencode/commands/ant/feedback.md +80 -0
- package/.opencode/commands/ant/flag.md +137 -0
- package/.opencode/commands/ant/flags.md +153 -0
- package/.opencode/commands/ant/focus.md +56 -0
- package/.opencode/commands/ant/help.md +124 -0
- package/.opencode/commands/ant/history.md +127 -0
- package/.opencode/commands/ant/init.md +337 -0
- package/.opencode/commands/ant/interpret.md +256 -0
- package/.opencode/commands/ant/lay-eggs.md +141 -0
- package/.opencode/commands/ant/maturity.md +92 -0
- package/.opencode/commands/ant/memory-details.md +77 -0
- package/.opencode/commands/ant/migrate-state.md +153 -0
- package/.opencode/commands/ant/oracle.md +338 -0
- package/.opencode/commands/ant/organize.md +224 -0
- package/.opencode/commands/ant/pause-colony.md +220 -0
- package/.opencode/commands/ant/phase.md +123 -0
- package/.opencode/commands/ant/plan.md +531 -0
- package/.opencode/commands/ant/redirect.md +67 -0
- package/.opencode/commands/ant/resume-colony.md +178 -0
- package/.opencode/commands/ant/resume.md +363 -0
- package/.opencode/commands/ant/seal.md +247 -0
- package/.opencode/commands/ant/status.md +272 -0
- package/.opencode/commands/ant/swarm.md +357 -0
- package/.opencode/commands/ant/tunnels.md +406 -0
- package/.opencode/commands/ant/update.md +191 -0
- package/.opencode/commands/ant/verify-castes.md +85 -0
- package/.opencode/commands/ant/watch.md +220 -0
- package/.opencode/opencode.json +3 -0
- package/CHANGELOG.md +325 -0
- package/DISCLAIMER.md +74 -0
- package/LICENSE +21 -0
- package/README.md +258 -0
- package/bin/cli.js +2436 -0
- package/bin/generate-commands.sh +291 -0
- package/bin/lib/caste-colors.js +57 -0
- package/bin/lib/colors.js +76 -0
- package/bin/lib/errors.js +255 -0
- package/bin/lib/event-types.js +190 -0
- package/bin/lib/file-lock.js +695 -0
- package/bin/lib/init.js +454 -0
- package/bin/lib/logger.js +242 -0
- package/bin/lib/model-profiles.js +445 -0
- package/bin/lib/model-verify.js +288 -0
- package/bin/lib/nestmate-loader.js +130 -0
- package/bin/lib/proxy-health.js +253 -0
- package/bin/lib/spawn-logger.js +266 -0
- package/bin/lib/state-guard.js +602 -0
- package/bin/lib/state-sync.js +516 -0
- package/bin/lib/telemetry.js +441 -0
- package/bin/lib/update-transaction.js +1454 -0
- package/bin/npx-install.js +178 -0
- package/bin/sync-to-runtime.sh +6 -0
- package/bin/validate-package.sh +88 -0
- 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 & Update System Repair" status="active" created_at="unknown">
|
|
9
|
+
<name>v1.1 Bug Fixes & Update System Repair</name>
|
|
10
|
+
</colony>
|
|
11
|
+
</colony-registry>
|