aether-colony 3.1.4 → 3.1.15

package/runtime/docs/known-issues.md

@@ -0,0 +1,217 @@
+# Known Issues and Workarounds
+
+Documented issues from Oracle research findings. These are known limitations and bugs in the Aether system.
+
+---
+
+## Fixed Issues
+
+### Checkpoint Allowlist System (Fixed 2026-02-15)
+
+**Issue:** Build checkpoint could stash user work (TO-DOs.md, dreams, Oracle specs)
+
+**Root Cause:** `git stash` touched files outside system allowlist, stashing 1,145 lines of user work
+
+**Fix:** Explicit allowlist system implemented
+- Created `.aether/data/checkpoint-allowlist.json` defining safe system files
+- Added `checkpoint-check` helper to `.aether/aether-utils.sh`
+- Updated `build.md` (Claude and OpenCode) to use allowlist
+- User data (`.aether/data/`, `.aether/dreams/`, `TO-DOs.md`) is never touched
+- Warning displayed if user files are present during checkpoint
+
+**System Files (Safe):**
+- `.aether/aether-utils.sh`, `.aether/workers.md`, `.aether/docs/**/*.md`
+- `.claude/commands/ant/**/*.md`, `.claude/commands/st/**/*.md`
+- `.opencode/commands/ant/**/*.md`, `.opencode/agents/**/*.md`
+- `runtime/**/*`, `bin/**/*`
+
+**User Data (Never Touch):**
+- `.aether/data/`, `.aether/dreams/`, `.aether/oracle/`
+- `TO-DOs.md`, `COLONY_STATE.json`, `.env`, `*.log`
+
+---
+
+## Critical Issues (Fix Immediately)
+
+### BUG-005: Missing lock release in flag-auto-resolve
+**Location:** `.aether/aether-utils.sh:1022`
+**Severity:** HIGH
+**Symptom:** If jq command fails during flag resolution, lock is never released
+**Impact:** Deadlock on flags.json if jq fails (malformed JSON, disk full, etc.)
+**Workaround:** Restart the colony session if commands hang on flag operations
+**Fix:** Add error handling with lock release before json_err
+
+### BUG-011: Missing error handling in flag-auto-resolve jq
+**Location:** `.aether/aether-utils.sh:1022`
+**Severity:** HIGH
+**Symptom:** jq failure during auto-resolve not handled
+**Impact:** Combined with BUG-005, causes deadlock
+**Fix:** Add `|| { release_lock; json_err ... }` pattern
+
+---
+
+## Medium Priority Issues
+
+### BUG-002: Missing release_lock in flag-add error path
+**Location:** `.aether/aether-utils.sh:814`
+**Severity:** MEDIUM
+**Symptom:** If acquire_lock succeeds but jq fails, lock is never released
+**Impact:** Potential deadlock on file operations
+**Fix:** Use trap-based cleanup or ensure release_lock in all exit paths
+
+### BUG-003: Race condition in backup creation
+**Location:** `.aether/utils/atomic-write.sh:75`
+**Severity:** MEDIUM
+**Symptom:** Backup created AFTER temp file validation but BEFORE atomic move
+**Impact:** If process crashes between validation and backup, inconsistent state
+**Fix:** Create backup BEFORE validation, or use transactional approach
+
+### BUG-004: Missing error code in flag-acknowledge
+**Location:** `.aether/aether-utils.sh:930`
+**Severity:** MEDIUM
+**Symptom:** Uses hardcoded string instead of `$E_VALIDATION_FAILED`
+**Impact:** Inconsistent error handling
+**Fix:** Change to `json_err "$E_VALIDATION_FAILED" "Usage: ..."`
+
+### BUG-006: No lock release on JSON validation failure
+**Location:** `.aether/utils/atomic-write.sh:66`
+**Severity:** MEDIUM
+**Symptom:** If JSON validation fails, temp file cleaned but lock not released
+**Impact:** Lock remains held if caller had acquired it
+**Fix:** Document lock ownership contract clearly
+
+### BUG-007: 17+ instances of missing error codes
+**Location:** `.aether/aether-utils.sh` various lines
+**Severity:** MEDIUM
+**Symptom:** Commands use hardcoded strings instead of error constants
+**Impact:** Inconsistent error handling, harder programmatic processing
+**Fix:** Standardize all to use `json_err "$E_*" "message"` pattern
+
+### BUG-008: Missing error code in flag-add jq failure
+**Location:** `.aether/aether-utils.sh:856`
+**Severity:** HIGH
+**Symptom:** Lock released but error code missing on jq failure
+**Impact:** Error response lacks proper error code
+**Fix:** Change to `json_err "$E_JSON_INVALID" "Failed to add flag"`
+
+### BUG-009: Missing error codes in file checks
+**Location:** `.aether/aether-utils.sh:899, 933`
+**Severity:** MEDIUM
+**Symptom:** File not found errors use hardcoded strings
+**Impact:** Inconsistent with other file not found errors
+**Fix:** Use `json_err "$E_FILE_NOT_FOUND" "..."`
+
+### BUG-010: Missing error codes in context-update
+**Location:** `.aether/aether-utils.sh:1758+`
+**Severity:** MEDIUM
+**Symptom:** Various error paths lack error code constants
+**Impact:** Inconsistent error handling
+
+### BUG-012: Missing error code in unknown command
+**Location:** `.aether/aether-utils.sh:2947`
+**Severity:** LOW
+**Symptom:** Unknown command handler uses bare string
+**Impact:** Inconsistent error response
+
+---
+
+## Architecture Issues
+
+### ISSUE-001: Inconsistent error code usage
+**Location:** Multiple locations
+**Severity:** MEDIUM
+**Description:** Some `json_err` calls use hardcoded strings instead of constants
+**Pattern:** Commands added early use strings; later commands use constants
+
+### ISSUE-002: Missing exec error handling
+**Location:** `.aether/aether-utils.sh:2132-2144`
+**Severity:** LOW
+**Description:** `model-get` and `model-list` use `exec` without fallback
+**Impact:** If exec fails, script continues to unknown command handler
+
+### ISSUE-003: Incomplete help command
+**Location:** `.aether/aether-utils.sh:106-111`
+**Severity:** LOW
+**Description:** Help command missing newer commands like queen-*, view-state-*, swarm-timing-*
+**Impact:** Users cannot discover all available commands
+
+### ISSUE-004: Template path hardcoded to runtime/
+**Location:** `.aether/aether-utils.sh:2689`
+**Severity:** MEDIUM
+**Description:** queen-init uses runtime/ directory which may not exist in npm installs
+**Impact:** queen-init will fail when Aether is installed as npm package
+**Workaround:** Use git clone instead of npm install
+
+### ISSUE-005: Potential infinite loop in spawn-tree
+**Location:** `.aether/aether-utils.sh:402-448`, `spawn-tree.sh:222-263`
+**Severity:** LOW
+**Description:** Edge case with circular parent chain could cause issues
+**Mitigation:** Safety limit of 5 exists
+
+### ISSUE-006: Fallback json_err incompatible
+**Location:** `.aether/aether-utils.sh:65-72`
+**Severity:** LOW
+**Description:** Fallback json_err doesn't accept error code parameter
+**Impact:** If error-handler.sh fails to load, error codes are lost
+
+### ISSUE-007: Feature detection race condition
+**Location:** `.aether/aether-utils.sh:33-45`
+**Severity:** LOW
+**Description:** Feature detection runs before error handler fully sourced
+
+---
+
+## Architecture Gaps
+
+### GAP-001: No schema version validation
+**Description:** Commands assume state structure without validating version
+**Impact:** Silent failures when state structure changes
+
+### GAP-002: No cleanup for stale spawn-tree entries
+**Description:** spawn-tree.txt grows indefinitely
+**Impact:** File could grow very large over many sessions
+
+### GAP-003: No retry logic for failed spawns
+**Description:** Task tool calls don't have retry logic
+**Impact:** Transient failures cause build failures
+
+### GAP-004: Missing queen-* documentation
+**Description:** No docs for queen-init, queen-read, queen-promote
+**Impact:** Users cannot discover wisdom feedback loop
+
+### GAP-005: No validation of queen-read JSON output
+**Description:** queen-read builds JSON but doesn't validate before returning
+**Impact:** Could return malformed response
+
+### GAP-006: Missing queen-* command documentation
+**Description:** Duplicate of GAP-004 - no documentation exists
+**Impact:** Commands are undiscoverable
+
+### GAP-007: No error code standards documentation
+**Description:** Error codes exist but aren't documented
+**Impact:** Developers don't know which codes to use
+
+### GAP-008: Missing error path test coverage
+**Description:** Error handling paths not tested
+**Impact:** Bugs in error handling go undetected
+
+### GAP-009: context-update has no file locking
+**Description:** Race condition possible during concurrent context updates
+**Impact:** Potential data corruption
+
+### GAP-010: Missing error code standards documentation
+**Description:** Duplicate of GAP-007
+
+---
+
+## Workarounds Summary
+
+| Issue | Workaround |
+|-------|------------|
+| Lock-related deadlocks (BUG-005, BUG-002) | Restart colony session |
+| Template path issue (ISSUE-004) | Use git clone instead of npm |
+| Missing command docs (GAP-004) | Read source code directly |
+
+---
+
+*Generated from Oracle Research findings - 2026-02-15*

package/runtime/docs/namespace.md

@@ -0,0 +1,148 @@
+# Namespace Distinctiveness -- Command System
+
+This document explains how Aether's command namespace (`ant`) is distinct from other agent namespaces in the global Claude Code configuration, ensuring bulletproof isolation and preventing command collisions.
+
+---
+
+## Overview
+
+Aether uses a directory-based command namespace system that is distinct from other agent systems. The namespace is designed to be bulletproof against collisions with other agent frameworks.
+
+---
+
+## Existing Agent Namespaces
+
+The global Claude Code commands directory (`~/.claude/commands/`) contains multiple agent namespaces:
+
+| Namespace | Type | Location | Example Commands |
+|-----------|------|----------|-------------------|
+| `ant` | Directory | `ant/` | `/ant:build`, `/ant:plan`, `/ant:focus` |
+| `cds` | Directory | `cds/` | `/cds:new-project`, `/cds:execute-phase` |
+| `mds` | Directory | `mds/` | `/mds:build`, `/mds:plan`, `/mds:test` |
+| `st:` | Prefix | Root files | `/st:caption`, `/st:research` |
+
+---
+
+## How Commands Are Invoked
+
+### Claude Code (Slash Commands)
+
+Claude Code uses a slash-based command syntax with namespace prefixing:
+
+```
+/ant:build 1                    # Aether build command
+/ant:focus "auth"               # Aether focus command
+/ant:plan                       # Aether plan command
+
+/cds:new-project "myapp"       # Claude Development System
+/mds:build                      # MDS system
+/st:caption "image.png"        # ST system (prefix in filename)
+```
+
+**Format:** `/<namespace>:<command> <arguments>`
+
+### OpenCode
+
+OpenCode uses a different syntax with namespace prefixes:
+
+```
+mds:ant:build 1                 # Build using Aether in OpenCode
+mds:cds:new-project myapp       # CDS in OpenCode
+```
+
+**Format:** `<tool>:<namespace>:<command> <arguments>`
+
+---
+
+## Why 'ant' Won't Collide
+
+### 1. Directory-Based Isolation
+
+The `ant` namespace is stored in a dedicated directory (`~/.claude/commands/ant/`). This provides:
+
+- **Physical separation**: Files exist in a distinct directory, not mixed with other commands
+- **Clear ownership**: The `ant/` directory is explicitly owned by Aether
+- **No filename conflicts**: Each command is a separate file in the `ant/` subdirectory
+
+### 2. Unique Naming Convention
+
+Aether commands use biological/colony metaphors that don't overlap with other systems:
+
+| Aether Commands | Other Systems |
+|-----------------|---------------|
+| `/ant:build` | `/cds:execute-phase` |
+| `/ant:plan` | `/mds:plan` |
+| `/ant:focus` | `/st:research` |
+| `/ant:colonize` | `/cds:new-milestone` |
+
+**Key distinction:** The `ant:` prefix is unique to Aether. No other agent system uses this prefix.
+
+### 3. File Extension Pattern
+
+Aether commands are `.md` files within the `ant/` directory:
+
+```
+.claude/commands/ant/build.md      # Invoked as /ant:build
+.claude/commands/ant/plan.md      # Invoked as /ant:plan
+.claude/commands/ant/focus.md     # Invoked as /ant:focus
+```
+
+This is distinct from:
+- `st:*` commands which use prefixes in filenames (e.g., `st:caption.md`)
+- Root-level commands which have no namespace prefix (e.g., `create-prompt.md`)
+
+### 4. Sync Mechanism Provides Safety
+
+The Aether CLI (`bin/cli.js`) implements hash-based idempotent sync:
+
+- **Source**: `.claude/commands/ant/` in the package
+- **Destination**: `~/.aether/commands/claude/` (hub) and `~/.claude/commands/ant/` (global)
+- **Behavior**: Files are only copied when content changes (hash comparison)
+- **Cleanup**: Stale files are automatically removed
+
+This ensures:
+- Local modifications are preserved
+- Only Aether-owned files exist in the `ant/` directory
+- No cross-contamination from other namespaces
+
+---
+
+## Collision Prevention Checklist
+
+When adding new commands to Aether, verify:
+
+- [ ] Command file is in `.claude/commands/ant/` directory
+- [ ] Filename uses lowercase alphanumeric with hyphens (e.g., `build.md`)
+- [ ] Frontmatter uses `ant:` prefix (e.g., `name: ant:build`)
+- [ ] No naming overlap with existing commands in `cds/`, `mds/`, or root
+
+---
+
+## Command Count
+
+| Namespace | Command Count | Files |
+|-----------|---------------|-------|
+| `ant` | 29 commands | `ant/*.md` |
+| `cds` | 20 commands | `cds/*.md` |
+| `mds` | 19 commands | `mds/*.md` |
+| `st:` | 13 commands | `st:*.md` |
+
+---
+
+## Best Practices
+
+1. **Never modify commands outside the `ant/` directory** - This maintains clear ownership
+2. **Use the sync mechanism** - Let `aether-cli` handle global distribution
+3. **Follow naming conventions** - Use lowercase, hyphens, biological metaphors
+4. **Keep commands atomic** - Each command should do one thing well
+
+---
+
+## Summary
+
+The `ant` namespace is bulletproof because:
+
+1. **Directory isolation** - Commands live in `~/.claude/commands/ant/`, separate from other namespaces
+2. **Unique prefix** - `/ant:` is exclusively used by Aether
+3. **Hash-based sync** - Idempotent updates prevent drift and contamination
+4. **Clear ownership** - No other system uses the `ant` prefix or directory

package/runtime/docs/planning-discipline.md

@@ -0,0 +1,159 @@
+# Planning Discipline
+
+## Purpose
+
+Write comprehensive implementation plans with bite-sized tasks, assuming workers have zero context. Each task should be one action (2-5 minutes of work).
+
+## Core Principles
+
+- **DRY** - Don't Repeat Yourself
+- **YAGNI** - You Aren't Gonna Need It
+- **TDD** - Test-Driven Development (test first, always)
+- **Frequent Commits** - One commit per feature/fix
+
+## Bite-Sized Task Granularity
+
+**Each step is ONE action:**
+
+```
+"Write the failing test" - step
+"Run it to make sure it fails" - step
+"Implement the minimal code to make the test pass" - step
+"Run the tests and make sure they pass" - step
+"Commit" - step
+```
+
+**NOT acceptable:**
+- "Implement authentication with tests" (too big)
+- "Add validation" (too vague)
+- "Set up the project" (needs breakdown)
+
+## Task Structure
+
+Each task should include:
+
+### 1. Files Section
+
+```markdown
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+```
+
+Always use exact paths. No "somewhere in src/" ambiguity.
+
+### 2. Steps with TDD Flow
+
+```markdown
+**Step 1: Write the failing test**
+
+\`\`\`python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+\`\`\`
+
+**Step 2: Run test to verify it fails**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: FAIL with "function not defined"
+
+**Step 3: Write minimal implementation**
+
+\`\`\`python
+def function(input):
+    return expected
+\`\`\`
+
+**Step 4: Run test to verify it passes**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+\`\`\`bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+\`\`\`
+```
+
+### 3. Expected Output
+
+For every command, specify expected output:
+
+```markdown
+Run: `npm test`
+Expected: 47 passing, 0 failing
+```
+
+Not just "run tests" - specify what success looks like.
+
+## Phase Structure
+
+```markdown
+### Phase N: [Component Name]
+
+**Goal:** [One sentence describing what this phase achieves]
+
+**Dependencies:** [What must exist before this phase]
+
+**Tasks:**
+
+#### Task N.1: [Specific action]
+
+**Files:**
+- Create: `src/components/Button.tsx`
+- Test: `tests/components/Button.test.tsx`
+
+**Steps:**
+(TDD steps as above)
+
+**Success Criteria:**
+- Tests pass for Button component
+- Component renders without errors
+```
+
+## Quality Checks
+
+Before a plan is complete, verify:
+
+1. **Exact paths** - Every file reference is complete path
+2. **Complete code** - No "add appropriate code" placeholders
+3. **Expected outputs** - Every command has expected result
+4. **TDD flow** - Test before implementation for each feature
+5. **No assumptions** - Worker could execute with zero context
+6. **Commit points** - Clear where to commit
+
+## Integration with Colony
+
+The Route-Setter Ant follows this discipline when generating plans.
+
+Each task in `plan.phases[N].tasks` should be:
+- Executable in 2-5 minutes
+- Self-contained with file paths
+- Verifiable with specific success criteria
+
+## Red Flags
+
+**Never in a plan:**
+- "Add tests" (which tests? for what?)
+- "Implement feature" (what specifically?)
+- "Update file" (which file? what changes?)
+- "Handle edge cases" (which cases?)
+
+**Always in a plan:**
+- Exact file paths
+- Complete code snippets
+- Exact commands to run
+- Expected outputs/results
+- One action per step
+
+## Why This Matters
+
+- Workers can execute without asking questions
+- Progress is measurable (step by step)
+- Debugging is easier (clear steps to trace)
+- Commits are atomic and meaningful
+- Quality is built in (TDD from start)