aether-colony 1.1.0

package/.aether/docs/disciplines/verification-loop.md

@@ -0,0 +1,167 @@
+# Verification Loop Discipline
+
+## Purpose
+
+A comprehensive 6-phase quality check that runs before phase advancement or PR creation. Complements the core Verification Discipline (evidence before claims) with systematic quality gates.
+
+## When to Invoke
+
+- After completing a phase (via `/ant:continue`)
+- Before creating a PR
+- After significant refactoring
+- After major changes (every 15 minutes in long sessions)
+
+## The 6 Phases
+
+### Phase 1: Build Verification
+
+```bash
+# Detect and run build command
+npm run build 2>&1 | tail -30
+# OR: pnpm build, cargo build, go build ./..., python -m build
+```
+
+**Gate:** If build fails, STOP. Fix before continuing.
+
+### Phase 2: Type Check
+
+```bash
+# TypeScript
+npx tsc --noEmit 2>&1 | head -30
+
+# Python
+pyright . 2>&1 | head -30
+
+# Go
+go vet ./... 2>&1 | head -30
+```
+
+**Gate:** Report all type errors. Fix critical ones before continuing.
+
+### Phase 3: Lint Check
+
+```bash
+# JavaScript/TypeScript
+npm run lint 2>&1 | head -30
+
+# Python
+ruff check . 2>&1 | head -30
+
+# Go
+golangci-lint run 2>&1 | head -30
+```
+
+**Gate:** Report warnings. Fix errors before continuing.
+
+### Phase 4: Test Suite
+
+```bash
+# Run tests with coverage
+npm run test -- --coverage 2>&1 | tail -50
+
+# Python
+pytest --cov=. 2>&1 | tail -50
+```
+
+Report:
+- Total tests: X
+- Passed: X
+- Failed: X
+- Coverage: X% (target: 80%+)
+
+**Gate:** If tests fail, STOP. Fix before continuing.
+
+### Phase 5: Security Scan
+
+```bash
+# Check for exposed secrets
+grep -rn "sk-\|api_key\|password\s*=" --include="*.ts" --include="*.js" --include="*.py" src/ 2>/dev/null | head -10
+
+# Check for debug artifacts
+grep -rn "console\.log\|debugger\|TODO.*REMOVE" --include="*.ts" --include="*.tsx" --include="*.js" src/ 2>/dev/null | head -10
+```
+
+Report:
+- Potential secrets: X
+- Debug artifacts: X
+
+**Gate:** Fix exposed secrets immediately. Debug artifacts are warnings.
+
+### Phase 6: Diff Review
+
+```bash
+# Show what changed
+git diff --stat
+git diff HEAD~1 --name-only
+```
+
+Review each changed file for:
+- Unintended changes (files touched that shouldn't be)
+- Missing error handling
+- Potential edge cases
+- Leftover debugging code
+
+**Gate:** Review before advancing. Flag concerns.
+
+## Verification Report Format
+
+After running all phases, produce a verification report:
+
+```
+VERIFICATION LOOP REPORT
+========================
+
+Phase 1: Build      [PASS/FAIL]
+Phase 2: Types      [PASS/FAIL] (X errors)
+Phase 3: Lint       [PASS/FAIL] (X warnings)
+Phase 4: Tests      [PASS/FAIL] (X/Y passed, Z% coverage)
+Phase 5: Security   [PASS/FAIL] (X issues)
+Phase 6: Diff       [X files changed]
+
+Overall: [READY/NOT READY] for advancement
+
+Issues to Fix:
+1. ...
+2. ...
+```
+
+## Command Detection
+
+Resolve each command (build, test, types, lint) independently using the priority chain below. Use the first source that provides a match for each label; do not mix sources for the same label.
+
+### Command Resolution Priority
+
+1. **CLAUDE.md** — Check the project's CLAUDE.md (in LLM system context) for explicit commands under headings like `Commands`, `Scripts`, `Development`, `Build`, `Testing`, or `Lint`.
+2. **CODEBASE.md** — Read `.aether/data/codebase.md` `## Commands` section for commands detected during `/ant:colonize`. Each entry includes source attribution (`claude_md` or `heuristic`).
+3. **Fallback Heuristic Table** — Use the table below if neither source provides a command for the needed label.
+
+### Fallback Heuristic Table
+
+| File | Build | Test | Types | Lint |
+|------|-------|------|-------|------|
+| `package.json` | `npm run build` | `npm test` | `npx tsc --noEmit` | `npm run lint` |
+| `Cargo.toml` | `cargo build` | `cargo test` | (built-in) | `cargo clippy` |
+| `go.mod` | `go build ./...` | `go test ./...` | `go vet ./...` | `golangci-lint run` |
+| `pyproject.toml` | `python -m build` | `pytest` | `pyright .` | `ruff check .` |
+| `Makefile` | `make build` | `make test` | (check targets) | `make lint` |
+
+## Skip Conditions
+
+If command doesn't exist for project:
+- Skip that phase
+- Note "N/A" in report
+- Don't fail the loop
+
+## Integration with Hooks
+
+This discipline provides comprehensive review. Hooks catch issues immediately during development. Use both:
+- Hooks: Real-time feedback
+- Verification Loop: Comprehensive gate before advancement
+
+## Why This Matters
+
+- Catches issues before they compound
+- Ensures consistent quality gates
+- Prevents shipping broken code
+- Creates audit trail of verification
+- Builds confidence in phase completion

package/.aether/docs/disciplines/verification.md

@@ -0,0 +1,116 @@
+# Verification Discipline
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Task complete | Success criteria verified | "I wrote the code" |
+| Phase ready | All tasks verified | Prime Worker reports success |
+
+## Red Flags - STOP
+
+When you catch yourself:
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Done!")
+- About to report completion without running checks
+- Trusting spawn reports without independent verification
+- Relying on partial verification
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Spawn said success" | Verify independently |
+| "Partial check is enough" | Partial proves nothing |
+
+## Verification Patterns
+
+**Tests:**
+```
+✅ [Run test command] → [See: 34/34 pass] → "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Build:**
+```
+✅ [Run build] → [See: exit 0] → "Build succeeds"
+❌ "Code compiles" (without running build)
+```
+
+**Task Completion:**
+```
+✅ Re-read success criteria → Verify each with evidence → Report with proof
+❌ "Tasks done, phase complete"
+```
+
+**Spawn Verification:**
+```
+✅ Spawn reports success → Check files exist → Run tests → Report actual state
+❌ Trust spawn report blindly
+```
+
+## Phase Advancement Gate
+
+Before `/ant:continue` advances to next phase:
+
+1. **Build Check**: Run project build command (if exists)
+2. **Test Check**: Run test suite, capture pass/fail counts
+3. **Success Criteria**: Line-by-line verification of phase criteria
+4. **Evidence Required**: Each criterion needs specific proof
+
+```
+Phase {N} Verification
+======================
+
+Build: {command} → {exit code}
+Tests: {command} → {pass}/{total} ({fail} failures)
+
+Success Criteria:
+  ✅ Criterion 1: {evidence}
+  ✅ Criterion 2: {evidence}
+  ❌ Criterion 3: {what's missing}
+
+Verdict: PASS / FAIL
+```
+
+If ANY criterion fails verification, phase cannot advance.
+
+## Why This Matters
+
+- False completion claims break trust
+- Unverified code ships bugs
+- Time wasted on rework from premature advancement
+- Colony integrity depends on honest reporting
+
+**Evidence before claims, always.**

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-02-19*