aether-colony 3.1.16 → 5.0.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/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)
-```

package/runtime/docs/planning-discipline.md

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