aether-colony 3.1.17 → 5.1.0

package/runtime/docs/implementation-learnings.md

@@ -1,89 +0,0 @@
-# Implementation Learnings
-
-Valuable findings from Aether v3.1 development that apply to other projects.
-
-## Workflow Patterns
-
-1. **Claude Code global sync** works by copying commands from `.claude/commands/` to `~/.claude/commands/`
-   - This enables sharing commands across all projects
-   - Source of truth is the repo, hub is the distribution mechanism
-
-2. **OpenCode requires repo-local setup**
-   - Each repo that wants ant commands must set them up locally
-   - Unlike Claude Code, there's no global command directory
-
-3. **Hash comparison prevents unnecessary file writes**
-   - Comparing SHA-1 hashes before writes preserves file timestamps
-   - Reduces git noise from unchanged files
-
-4. **Namespace isolation via 'ant:' prefix**
-   - Prevents collisions with other agents
-   - Creates clear command ownership
-
-5. **CLI sync verification catches content drift**
-   - `generate-commands.sh check` uses SHA-1 checksums
-   - Detects when .claude/ and .opencode/ mirrors diverge
-
-## Error Handling Patterns
-
-- Use `json_err "$E_*" "message"` consistently (not bare strings)
-- Always release locks in error paths (use trap or explicit release)
-- Validate JSON before atomic writes
-- Use fallback json_err for backward compatibility
-
-## File Operation Patterns
-
-- Use `atomic_write()` for all state modifications
-- Acquire locks before reading/writing shared state
-- Create backups BEFORE validation for true atomicity
-- Use temp file + mv pattern for atomic operations
-
-## Model Routing Patterns
-
-- Validate LiteLLM proxy health before spawning
-- Support CLI --model override for one-time changes
-- Log actual model used per spawn for telemetry
-- Use task-based routing keywords for automatic selection
-
-## Codebase Patterns Discovered
-
-### Pattern 1: JSON Error Response Standard
-All commands output JSON with `{"ok": true/false, "result": ...}` or `{"ok": false, "error": ...}`
-
-### Pattern 2: Feature Degradation Pattern
-```bash
-if type feature_enabled &>/dev/null && ! feature_enabled "file_locking"; then
-  json_warn "W_DEGRADED" "File locking disabled - proceeding without lock"
-else
-  acquire_lock ...
-fi
-```
-
-### Pattern 3: Atomic Write Pattern
-All state modifications use `atomic_write()` from atomic-write.sh (temp file + mv)
-
-### Pattern 4: Trap-based Cleanup
-file-lock.sh uses `trap cleanup_locks EXIT TERM INT` for lock cleanup
-
-### Pattern 5: Inconsistent Error Code Evolution
-Commands added early use hardcoded strings; commands added later use `$E_VALIDATION_FAILED` constant. This creates inconsistency that should be standardized.
-
-## Connections Between Issues
-
-1. **BUG-005** (flag-auto-resolve lock leak) and **BUG-002** (flag-add lock leak) share the same root cause: inconsistent error handling patterns
-2. **BUG-004** and **ISSUE-001** are the same issue: missing error code constants
-3. **ISSUE-004** (template path) affects **GAP-006** (missing docs) - both relate to queen-* command usability
-4. **BUG-001** (awk apostrophes) affects the same lines that use Pattern 2 (feature degradation)
-
-## Fix Priority Matrix
-
-| Priority | Issues | Effort | Impact |
-|----------|--------|--------|--------|
-| Critical | BUG-005, BUG-011 | Low | Deadlock prevention |
-| High | BUG-002, BUG-008 | Low | Lock safety |
-| Medium | BUG-003, BUG-006, BUG-007 | Medium | Code quality |
-| Low | ISSUE-001 through ISSUE-007 | Medium | Consistency |
-
----
-
-*Preserved from Phase 0 cleanup - 2026-02-15*

package/runtime/docs/known-issues.md

@@ -1,217 +0,0 @@
-# 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

@@ -1,148 +0,0 @@
-# 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/pathogen-schema-example.json

@@ -1,36 +0,0 @@
-{
-  "pathogens": [
-    {
-      "name": "unchecked_error_return",
-      "description": "Function return value not checked for error condition",
-      "severity": "critical",
-      "first_seen": "2026-02-11T12:00:00Z",
-      "last_seen": "2026-02-11T14:30:00Z",
-      "occurrences": 5,
-      "projects": ["Aether"],
-      "resolved": false,
-      "signature_type": "fuzzy",
-      "pattern_string": "\\|\\| true$",
-      "confidence_threshold": 0.9,
-      "escalation_level": "swarm"
-    },
-    {
-      "name": "hardcoded_path",
-      "description": "Absolute path hardcoded instead of using variable",
-      "severity": "warning",
-      "first_seen": "2026-02-11T12:00:00Z",
-      "last_seen": "2026-02-11T12:00:00Z",
-      "occurrences": 1,
-      "projects": ["Aether"],
-      "resolved": false,
-      "signature_type": "exact",
-      "pattern_string": "/Users/",
-      "confidence_threshold": 0.5,
-      "escalation_level": "log"
-    }
-  ],
-  "metadata": {
-    "version": "1.0",
-    "last_updated": "2026-02-11T14:30:00Z"
-  }
-}

package/runtime/docs/pathogen-schema.md

@@ -1,111 +0,0 @@
-# Pathogen Signature Schema
-
-## Overview
-
-Pathogen signatures extend the existing error pattern format (`.aether/error-patterns.json`) with fields for automated detection and escalation. The schema is backward-compatible: existing jq queries on core fields (`name`, `description`, `severity`, `occurrences`, etc.) work unchanged on pathogen entries.
-
-## Storage
-
-- **File:** `.aether/data/pathogens.json` (project-local)
-- **Format:** JSON, jq-compatible
-- **Relationship:** Extends `error-patterns.json` field set; stored separately to avoid polluting global pattern data
-
-## Schema
-
-### Root Object
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `pathogens` | array | Array of pathogen signature objects |
-| `metadata` | object | File-level metadata |
-
-### Metadata Object
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `version` | string | Schema version (currently `"1.0"`) |
-| `last_updated` | string\|null | ISO 8601 UTC timestamp of last modification |
-
-### Pathogen Signature Object
-
-#### Inherited Fields (from error-patterns format)
-
-These fields match the existing `error-patterns.json` schema exactly. Any jq query that works on error patterns will work on pathogen entries.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | string | Unique identifier for the pathogen |
-| `description` | string | Human-readable description |
-| `severity` | string | `"warning"` \| `"critical"` |
-| `first_seen` | string | ISO 8601 UTC timestamp |
-| `last_seen` | string | ISO 8601 UTC timestamp |
-| `occurrences` | number | Count of times detected |
-| `projects` | array[string] | Project names where detected |
-| `resolved` | boolean | Whether the pathogen has been resolved |
-
-#### New Fields (pathogen-specific)
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `signature_type` | string | `"exact"` \| `"fuzzy"` — matching strategy |
-| `pattern_string` | string | The literal string or regex to match against |
-| `confidence_threshold` | number | Float 0.0–1.0, minimum confidence for a match |
-| `escalation_level` | string | `"log"` \| `"elevated"` \| `"swarm"` — response tier |
-
-## Escalation Thresholds (Hardcoded)
-
-| Confidence | Escalation Level | Action |
-|------------|-----------------|--------|
-| >= 0.9 | `"swarm"` | Immediate swarm response |
-| 0.7–0.89 | `"elevated"` | Elevated scrutiny |
-| < 0.7 | `"log"` | Log only |
-
-## Backward Compatibility
-
-### Existing queries that still work
-
-```bash
-# Select by name (works on both error patterns and pathogens)
-jq '.pathogens[] | select(.name == "some_name")' pathogens.json
-
-# Filter by severity
-jq '.pathogens[] | select(.severity == "critical")' pathogens.json
-
-# Filter recurring (2+ occurrences, unresolved)
-jq '[.pathogens[] | select(.occurrences >= 2 and .resolved == false)]' pathogens.json
-
-# Get all names
-jq '[.pathogens[].name]' pathogens.json
-```
-
-### New queries for pathogen-specific fields
-
-```bash
-# Filter by confidence threshold
-jq '.pathogens[] | select(.confidence_threshold >= 0.7)' pathogens.json
-
-# Get all exact-match pathogens
-jq '[.pathogens[] | select(.signature_type == "exact")]' pathogens.json
-
-# Get pathogens requiring swarm escalation
-jq '[.pathogens[] | select(.escalation_level == "swarm")]' pathogens.json
-
-# Search for a specific pattern string
-jq --arg pat "error_string" '.pathogens[] | select(.pattern_string == $pat)' pathogens.json
-```
-
-## Validation
-
-Validate the file structure:
-
-```bash
-# Check file is valid JSON
-jq empty pathogens.json
-
-# Verify required fields exist on all entries
-jq '.pathogens[] | has("name", "signature_type", "pattern_string", "confidence_threshold", "escalation_level")' pathogens.json
-
-# Verify confidence is in range
-jq '.pathogens[] | select(.confidence_threshold < 0 or .confidence_threshold > 1)' pathogens.json
-# (should return empty if all valid)
-```