aether-colony 3.1.17 → 5.1.0

package/.aether/docs/error-codes.md

@@ -0,0 +1,268 @@
+# Aether Error Code Reference
+
+This document is the complete reference for all `E_*` error constants used in Aether's bash utilities and Node.js CLI. When a command fails, the error output includes a `code` field that maps to one of the entries below.
+
+**How to read this document:** Find the code you see in the error output, then check the meaning, when it happens, and what to do.
+
+---
+
+## File Errors
+
+### E_FILE_NOT_FOUND
+
+- **Meaning:** A required file or directory doesn't exist at the expected path.
+- **When it happens:**
+  - A command is invoked but the data file it needs (e.g., `COLONY_STATE.json`, `flags.json`, `CONTEXT.md`) hasn't been created yet.
+  - A directory path passed as an argument doesn't exist.
+- **Suggested fix:** Check that `aether init` (or the relevant setup command) has been run. Verify the path exists and is spelled correctly.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_FILE_NOT_FOUND","message":"Couldn't find CONTEXT.md. Try: run context-update init first.","details":null,"recovery":"Check file path and permissions","timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+---
+
+## Lock Errors
+
+### E_LOCK_FAILED
+
+- **Meaning:** Couldn't acquire a file lock — another process is currently holding it.
+- **When it happens:**
+  - Two commands try to write to the same file (e.g., `flags.json`) at the same time.
+  - A previous command crashed and didn't release its lock. Use `force-unlock` to clear stale locks.
+- **Suggested fix:** Wait for any running operations to finish, then retry. If you're sure nothing else is running, use `aether force-unlock` to clear the lock manually.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_LOCK_FAILED","message":"Failed to acquire lock on flags.json","details":null,"recovery":"Wait for other operations to complete","timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+### E_LOCK_STALE
+
+- **Meaning:** A lock file exists but belongs to a process that is no longer running, or has exceeded the maximum lock timeout (5 minutes). This differs from `E_LOCK_FAILED` (which means another process holds a live lock) — `E_LOCK_STALE` means the lock is abandoned.
+- **When it happens:**
+  - A previous command crashed without releasing its lock.
+  - The locking process was killed by the OS (e.g., OOM) or terminated by the user (Ctrl+C) before the trap handler could fire.
+  - The lock is older than the configured timeout (300 seconds).
+- **Suggested fix:** Run `aether force-unlock` to clear stale locks, or manually remove the lock file shown in the error message.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_LOCK_STALE","message":"Stale lock found. Remove manually: .aether/locks/flags.json.lock"}}
+  ```
+
+---
+
+## Tool / Dependency Errors
+
+### E_FEATURE_UNAVAILABLE
+
+- **Meaning:** A feature or optional tool required for this operation isn't installed or enabled.
+- **When it happens:**
+  - XML operations are attempted but `xmllint` isn't installed.
+  - A feature has been disabled due to a missing dependency or configuration.
+- **Suggested fix:** Install the required tool (e.g., `brew install libxml2` for xmllint on macOS) or check the feature's documentation for setup steps.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_FEATURE_UNAVAILABLE","message":"xmllint not available. Try: brew install libxml2","details":null,"recovery":null,"timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+### E_DEPENDENCY_MISSING
+
+- **Meaning:** A required utility script or binary is missing from the expected location.
+- **When it happens:**
+  - A utility script in `.aether/utils/` (e.g., `error-handler.sh`, `file-lock.sh`) can't be found.
+  - A required binary (e.g., `jq`, `git`) isn't installed or isn't on `$PATH`.
+- **Suggested fix:** Run `aether install` to restore missing system files, or install the missing binary via your system package manager.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_DEPENDENCY_MISSING","message":"Couldn't load error-handler.sh. Try: run aether install to restore system files.","details":null,"recovery":"Install the required dependency","timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+---
+
+## JSON / Data Errors
+
+### E_JSON_INVALID
+
+- **Meaning:** A JSON file is malformed or is missing required fields.
+- **When it happens:**
+  - A data file (`COLONY_STATE.json`, `flags.json`, etc.) has been manually edited and contains a syntax error.
+  - A write operation was interrupted, leaving a partially-written file.
+- **Suggested fix:** Open the file and fix the JSON syntax, or delete it and re-run the initialization command to regenerate a fresh copy.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_JSON_INVALID","message":"Failed to parse COLONY_STATE.json. Try: validate with jq '.'' .aether/data/COLONY_STATE.json","details":null,"recovery":"Validate JSON syntax","timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+---
+
+## Validation Errors
+
+### E_VALIDATION_FAILED
+
+- **Meaning:** The command was called with missing or invalid arguments.
+- **When it happens:**
+  - A required argument (e.g., flag type, flag ID, spawn summary) is missing.
+  - An argument value is outside the allowed range or format.
+- **Suggested fix:** Check the usage message in the error output. The error message typically includes the correct usage syntax.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_VALIDATION_FAILED","message":"Usage: flag-add <type> <title> <description> [source] [phase]","details":null,"recovery":null,"timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+---
+
+## System Errors
+
+### E_BASH_ERROR
+
+- **Meaning:** An unexpected system command failure occurred — a bash command returned a non-zero exit code where one wasn't expected.
+- **When it happens:**
+  - A system command (e.g., `cp`, `mkdir`, `git`) fails unexpectedly.
+  - A script runs under `set -e` and a command exits non-zero.
+- **Suggested fix:** Check the `details` field in the error output for the exact command and line number. Fix the underlying system issue (permissions, disk space, etc.) and retry.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_BASH_ERROR","message":"Bash command failed","details":{"line":42,"command":"cp src dst","exit_code":1},"recovery":null,"timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+### E_UNKNOWN
+
+- **Meaning:** An unclassified error occurred — something went wrong that doesn't fit a more specific category.
+- **When it happens:**
+  - An error path that hasn't been given a specific code yet.
+  - A catch-all for unexpected failure conditions.
+- **Suggested fix:** Check the error message for context. If you see this frequently, please report it so a specific code can be added.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_UNKNOWN","message":"An unknown error occurred","details":null,"recovery":null,"timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+---
+
+## Hub / Repository Errors
+
+### E_HUB_NOT_FOUND
+
+- **Meaning:** The Aether hub (`~/.aether/`) doesn't exist on this machine.
+- **When it happens:**
+  - Aether hasn't been installed yet.
+  - The hub directory was accidentally deleted.
+- **Suggested fix:** Run `npm install -g aether` to install Aether. This creates the hub at `~/.aether/`.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_HUB_NOT_FOUND","message":"Couldn't find the Aether hub. Try: npm install -g aether","details":null,"recovery":"Run: aether install","timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+### E_REPO_NOT_INITIALIZED
+
+- **Meaning:** The current repository hasn't been initialized with Aether.
+- **When it happens:**
+  - Running an Aether command in a repo before running `/ant:init`.
+  - The `.aether/` directory or `COLONY_STATE.json` is missing from the current repo.
+- **Suggested fix:** Run `/ant:init` in Claude Code to initialize Aether in this repository.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_REPO_NOT_INITIALIZED","message":"Couldn't find Aether initialization in this repo. Try: run /ant:init first.","details":null,"recovery":"Run /ant:init in this repo first","timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+### E_GIT_ERROR
+
+- **Meaning:** A git operation failed.
+- **When it happens:**
+  - `git stash`, `git commit`, `git log`, or another git command returns an error.
+  - The directory isn't a git repository.
+  - There are merge conflicts or a detached HEAD state.
+- **Suggested fix:** Run `git status` to see the current state of your repository. Resolve any conflicts or uncommitted changes, then retry the command.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_GIT_ERROR","message":"Git operation failed. Try: run git status to check repository state.","details":null,"recovery":"Check git status and resolve conflicts","timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+---
+
+## Resource Errors
+
+### E_RESOURCE_NOT_FOUND
+
+- **Meaning:** A runtime resource (e.g., an active session, a worker, a swarm) doesn't exist.
+- **When it happens:**
+  - A command refers to a session ID, worker name, or swarm ID that doesn't exist or has already completed.
+  - Attempting to read or update a resource that hasn't been created yet.
+- **Suggested fix:** Check that the resource was created first. List available resources with the relevant `list` command (e.g., `flag-list`, `swarm-findings-read`).
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_RESOURCE_NOT_FOUND","message":"Couldn't find the requested resource. Try: check that it was created first.","details":null,"recovery":"Check that the resource exists and try again","timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+---
+
+## For Contributors
+
+### Adding a New Error Code
+
+When you need a new error code, follow this checklist:
+
+1. **Define the constant** in `.aether/utils/error-handler.sh` at the top of the file:
+   ```bash
+   E_MY_NEW_CODE="E_MY_NEW_CODE"
+   ```
+
+2. **Add a recovery function** in `error-handler.sh`:
+   ```bash
+   _recovery_my_new_code() { echo '"Description of how to fix this"'; }
+   ```
+
+3. **Add a case entry** in the `_get_recovery` function in `error-handler.sh`:
+   ```bash
+   "$E_MY_NEW_CODE") _recovery_my_new_code ;;
+   ```
+
+4. **Add a fallback definition** at the top of `aether-utils.sh` (in the fallback constants block):
+   ```bash
+   : "${E_MY_NEW_CODE:=E_MY_NEW_CODE}"
+   ```
+
+5. **Export the constant and function** at the bottom of `error-handler.sh`:
+   ```bash
+   export E_MY_NEW_CODE
+   export -f _recovery_my_new_code
+   ```
+
+6. **Document the code** in this file (`docs/error-codes.md`) following the existing format.
+
+### Naming Convention
+
+- **Prefix:** Always start with `E_`
+- **Case:** SCREAMING_SNAKE_CASE (e.g., `E_FILE_NOT_FOUND`, `E_LOCK_FAILED`)
+- **Be specific:** Prefer `E_FILE_NOT_FOUND` over `E_ERROR` — the code should communicate the failure category
+
+### Category Selection Guide
+
+| Category | Use when... |
+|----------|-------------|
+| File Errors | A file or directory path doesn't exist |
+| Lock Errors | Lock acquisition fails |
+| Tool/Dependency Errors | A required tool or script is missing |
+| JSON/Data Errors | File content is malformed or invalid |
+| Validation Errors | Arguments are wrong or missing |
+| System Errors | Unexpected bash command failure |
+| Hub/Repository Errors | Aether infrastructure is missing or not set up |
+| Resource Errors | A named runtime object doesn't exist |
+
+### Message Style Requirements
+
+Every `json_err` call **must** include a "Try:" suggestion in the message:
+
+```bash
+# Correct — includes Try: suggestion
+json_err "$E_FILE_NOT_FOUND" "Couldn't find flags.json. Try: run flag-add first to create it."
+
+# Wrong — no actionable suggestion
+json_err "$E_FILE_NOT_FOUND" "flags.json not found"
+```
+
+**Tone:** Use plain, friendly language. "Couldn't find..." is better than "File not found". Users are not experts in bash internals.
+
+---
+
+*Last updated: 2026-03-29*

package/.aether/docs/known-issues.md

@@ -0,0 +1,94 @@
+# Known Issues and Workarounds
+
+Documented issues from Oracle research findings. These are known limitations and bugs in the Aether system.
+
+---
+
+## Medium Priority Issues
+
+### BUG-004: Missing error code in flag-acknowledge
+**Location:** `flag-acknowledge` subcommand in `.aether/utils/flag.sh`
+**Severity:** MEDIUM
+**Status:** [FIXED in v2.1 -- Phase 10 error triage + Phase 13 modularization]
+`flag-acknowledge` now uses `$E_VALIDATION_FAILED`, `$E_FILE_NOT_FOUND`, `$E_LOCK_FAILED`, and `$E_JSON_INVALID` appropriately.
+
+### BUG-006: No lock release on JSON validation failure
+**Location:** `atomic_write` in `.aether/utils/atomic-write.sh`
+**Severity:** MEDIUM
+**Symptom:** If JSON validation fails in `atomic_write`, temp file is cleaned but any lock held by the caller is not released
+**Impact:** Lock remains held if caller had acquired it before calling `atomic_write`
+**Fix:** Document lock ownership contract clearly -- callers must use trap-based cleanup
+**Status:** Open -- `atomic_write` itself does not manage locks; callers are responsible for lock release via EXIT traps
+
+### BUG-007: 17+ instances of missing error codes
+**Location:** Various subcommands across `.aether/aether-utils.sh` and domain modules
+**Severity:** MEDIUM
+**Status:** [Mostly FIXED in v2.1 -- Phase 10 error triage]
+Phase 10 replaced ~110 lazy error suppressions with proper fallbacks and added `$E_*` constants to ~48 dangerous paths. A small number of uncommented `2>/dev/null` idioms remain (SUPPRESS:OK annotated).
+
+### BUG-008: Missing error code in flag-add jq failure
+**Location:** `flag-add` subcommand in `.aether/utils/flag.sh`
+**Severity:** HIGH
+**Status:** [FIXED in v2.1 -- Phase 10 error triage + Phase 13 modularization]
+`flag-add` now uses `$E_VALIDATION_FAILED`, `$E_JSON_INVALID`, and proper error handling throughout.
+
+### BUG-009: Missing error codes in file checks
+**Location:** `flag-acknowledge` and related subcommands in `.aether/utils/flag.sh`
+**Severity:** MEDIUM
+**Status:** [FIXED in v2.1 -- Phase 10 error triage + Phase 13 modularization]
+File-not-found errors now use `json_err "$E_FILE_NOT_FOUND" "..."` consistently.
+
+### BUG-010: Missing error codes in context-update
+**Location:** `context-update` subcommand in `.aether/aether-utils.sh`
+**Severity:** MEDIUM
+**Status:** [FIXED in v2.1 -- Phase 10 error triage]
+All error paths now use `$E_FILE_NOT_FOUND`, `$E_LOCK_FAILED`, and `$E_VALIDATION_FAILED` consistently.
+
+### BUG-012: Missing error code in unknown command
+**Location:** Default case (`*`) in `.aether/aether-utils.sh` dispatch
+**Severity:** LOW
+**Status:** [FIXED in v2.1 -- Phase 10 error triage]
+Unknown command handler now uses `json_err "$E_VALIDATION_FAILED" "Unknown command: $cmd"`.
+
+---
+
+## Architecture Issues
+
+### ISSUE-001: Inconsistent error code usage
+**Location:** Multiple locations
+**Severity:** MEDIUM
+**Description:** Some `json_err` calls use hardcoded strings instead of constants
+**Status:** [Mostly FIXED in v2.1 -- Phase 10 error triage]
+The majority of error paths now use `$E_*` constants. Remaining intentional suppressions are annotated with SUPPRESS:OK comments.
+
+### ISSUE-005: Potential infinite loop in spawn-tree
+**Location:** `spawn-tree-depth` in `.aether/utils/spawn.sh`
+**Severity:** LOW
+**Description:** Edge case with circular parent chain could cause issues
+**Mitigation:** Safety limit of 5 exists
+**Status:** Open -- low risk due to safety limit; code extracted to `spawn.sh` during Phase 13 modularization
+
+### ISSUE-006: Fallback json_err incompatible
+**Location:** `.aether/aether-utils.sh` (lines ~65-72, fallback error handler)
+**Severity:** LOW
+**Description:** Fallback json_err doesn't accept error code parameter
+**Impact:** If error-handler.sh fails to load, error codes are lost
+**Status:** Open -- low risk since error-handler.sh is a stable infrastructure module
+
+---
+
+## Architecture Gaps
+
+### GAP-007: No error code standards documentation
+**Description:** Error codes exist but aren't documented for external consumers
+**Impact:** Developers don't know which codes to use
+**Status:** Partially addressed -- `_aether_log_error` infrastructure added in Phase 10, but no standalone error code reference doc exists yet
+
+### GAP-008: Missing error path test coverage
+**Description:** Error handling paths not fully tested
+**Impact:** Bugs in error handling go undetected
+**Status:** Partially addressed -- Phase 12 added state-api tests; 580+ tests now pass, but error-specific path coverage remains incomplete
+
+---
+
+*Generated from Oracle Research findings -- Updated 2026-03-24 during v2.1 documentation accuracy phase*

package/{runtime → .aether}/docs/pheromones.md

@@ -10,17 +10,31 @@ Pheromones are how you communicate with the colony. Instead of micromanaging ind
 - **Optional TTL** -- use `--ttl` flag for wall-clock expiration (e.g., `--ttl 2h` for 2 hours)
 - **Priority levels** determine worker attention: high (REDIRECT), normal (FOCUS), low (FEEDBACK)
 - **Expired signals** are filtered on read -- no cleanup process needed
+- **Compact priming path** (`pheromone-prime --compact`) injects only top signals by priority/strength for low token usage
 
 Run `/ant:status` at any time to see all active pheromones.
 
 ---
 
+## How Signals Reach Workers
+
+Workers do not independently read or query pheromone files. Instead, colony-prime handles signal delivery:
+
+1. **colony-prime assembles signals** via `pheromone-prime --compact`, collecting all active signals sorted by priority and strength
+2. **Signals are injected into the `prompt_section`** of the worker spawn context -- they become part of the worker's prompt, not something the worker looks up
+3. **Workers see signals as part of their instructions**, not by reading `.aether/data/pheromones.json` directly
+4. **Builder, Watcher, and Scout** have `pheromone_protocol` sections in their agent definitions (`.claude/agents/ant/`) that instruct them how to act on the injected signals
+
+This injection model means pheromones influence worker behavior through prompt context, the same way any other instruction reaches a worker.
+
+---
+
 ## FOCUS -- Guide Attention
 
 **Command:** `/ant:focus "<area>"`
 **Priority:** normal | **Default expiration:** end of phase
 
-**What it does:** Tells the colony "pay extra attention here." Workers read FOCUS signals and weight this area higher in their task execution.
+**What it does:** Tells the colony "pay extra attention here." FOCUS signals are injected into worker prompts via colony-prime, weighting the indicated area higher in task execution.
 
 ### When to use FOCUS
 
@@ -146,16 +160,16 @@ Auto-emitted signals have their `source` field set to indicate origin: `"worker:
 
 ## Signal Combinations
 
-Pheromones combine. Workers check all active signals and respond accordingly:
+Pheromones combine. colony-prime injects all active signals into worker prompts, ordered by priority:
 
 | Combination | Effect |
 |-------------|--------|
-| FOCUS + FEEDBACK | Workers concentrate on the focused area and adjust approach based on feedback |
-| FOCUS + REDIRECT | Workers prioritize the focused area while avoiding the redirected pattern |
-| FEEDBACK + REDIRECT | Workers adjust approach (feedback) and avoid specific patterns (redirect) |
+| FOCUS + FEEDBACK | The focused area is weighted higher and approach is adjusted based on feedback |
+| FOCUS + REDIRECT | The focused area is prioritized while the redirected pattern is flagged for avoidance |
+| FEEDBACK + REDIRECT | Approach adjustments (feedback) and avoidance patterns (redirect) are both injected |
 | All three | Full steering: attention (FOCUS), avoidance (REDIRECT), and adjustment (FEEDBACK) |
 
-**Priority processing:** Workers check high priority signals first, then normal, then low.
+**Priority processing:** High priority signals appear first in the injected context, then normal, then low.
 
 ---
 
@@ -188,6 +202,70 @@ This ensures signals don't expire while you're away from the project.
 
 ---
 
+## Viewing Active Pheromones
+
+**Command:** `/ant:pheromones [filter]`
+
+Displays all active signals in a formatted table with:
+- Signal type (FOCUS/REDIRECT/FEEDBACK)
+- Current strength percentage (accounting for decay)
+- Elapsed time since creation
+- Remaining time before expiration
+
+**Filters:**
+- `/ant:pheromones` — Show all active signals
+- `/ant:pheromones focus` — Show only FOCUS signals
+- `/ant:pheromones redirect` — Show only REDIRECT signals
+- `/ant:pheromones feedback` — Show only FEEDBACK signals
+- `/ant:pheromones clear` — Clear expired/inactive signals
+
+---
+
+## Automatic Suggestions
+
+The colony can analyze your codebase and suggest pheromones worth capturing.
+
+**During builds:** At Step 4.2, the colony automatically analyzes the codebase and proposes relevant signals:
+- Detects hardcoded values that should be configurable
+- Finds error-prone patterns from the midden
+- Identifies architectural constraints from directory structure
+- Suggests FOCUS areas based on file modification patterns
+- Proposes REDIRECT signals for anti-patterns
+
+**Tick-to-approve UI:** When suggestions are found, the build pauses to show:
+
+```
+🎯 Proposed Pheromone 1 of 3
+
+Type: FOCUS
+Content: "Audio processing — maintain thread safety"
+Confidence: High (3 similar patterns found)
+
+[A]pprove  [R]eject  [S]kip  [D]ismiss All
+```
+
+**Actions:**
+- **A**pprove — Creates the pheromone signal
+- **R**eject — Discards this suggestion (logs reason)
+- **S**kip — Defer decision (shown again next build)
+- **D**ismiss All — Skip all remaining suggestions
+
+---
+
+## Signal Decay
+
+Pheromones lose strength over time (natural decay):
+
+| Signal Type | Half-life | Full decay |
+|-------------|-----------|------------|
+| FOCUS | 15 days | 30 days |
+| REDIRECT | 30 days | 60 days |
+| FEEDBACK | 45 days | 90 days |
+
+Signals below 10% strength are considered inactive but remain in history.
+
+---
+
 ## Quick Reference
 
 | Signal | Command | Priority | Default Expiration | Use for |
@@ -203,3 +281,5 @@ This ensures signals don't expire while you're away from the project.
 - For gentle nudges: FEEDBACK (low priority)
 - For attention: FOCUS (normal priority)
 - For short-lived signals: use `--ttl` flag
+- To see current signals: `/ant:pheromones`
+- To clear expired: `/ant:pheromones clear`