aether-colony 5.0.0 → 5.2.1

package/.aether/docs/queen-commands.md

@@ -19,13 +19,13 @@ bash .aether/aether-utils.sh queen-init
 
 **Example output:**
 ```json
-{"ok":true,"result":{"created":true,"path":".aether/docs/QUEEN.md","source":"~/.aether/system/docs/QUEEN.md.template"}}
+{"ok":true,"result":{"created":true,"path":".aether/QUEEN.md","source":"~/.aether/system/templates/QUEEN.md.template"}}
 ```
 
 **Behavior:**
 - If QUEEN.md already exists, returns `{"created":false}` without overwriting
 - Searches for template in: hub system path, then local .aether/templates/
-- Creates `.aether/docs/` directory if it doesn't exist
+- Creates `.aether/` directory if it doesn't exist
 
 ---
 
@@ -84,14 +84,15 @@ bash .aether/aether-utils.sh queen-promote <type> <content> <colony_name>
 
 The queen commands are part of the colony lifecycle:
 
-1. **Colony startup:** `/ant:colonize` calls `queen-init` to ensure QUEEN.md exists
-2. **Worker priming:** `/ant:swarm` calls `queen-read` to inject wisdom into worker prompts
+1. **Colony startup:** `/ant:init` calls `queen-init` to ensure QUEEN.md exists
+2. **Worker priming:** `/ant:build` loads `colony-prime --compact`, which includes QUEEN wisdom + compact context capsule + top signals
 3. **Colony end:** `/ant:seal` can call `queen-promote` to persist learnings
 
 ### Adding a New Queen Command
 
-1. Add the case block in `aether-utils.sh` (alongside existing `queen-*` blocks)
-2. Add it to the flat `commands` array in the `help)` case block
-3. Add it to the "Queen Commands" section in help's `sections` JSON
-4. Update this file with usage documentation
-5. Add tests in `tests/bash/test-aether-utils.sh`
+1. Add the function implementation in `.aether/utils/queen.sh` (domain module)
+2. Add the dispatch case in `aether-utils.sh` (alongside existing `queen-*` blocks)
+3. Add it to the flat `commands` array in the `help)` case block
+4. Add it to the "Queen Commands" section in help's `sections` JSON
+5. Update this file with usage documentation
+6. Add tests in `tests/bash/test-aether-utils.sh`

package/.aether/docs/source-of-truth-map.md

@@ -0,0 +1,132 @@
+# Aether Source-of-Truth Map
+
+Updated: 2026-03-24 (v2.1 accuracy sweep -- post-modularization counts, domain modules, playbook corrections)
+
+## Purpose
+
+Define which files are authoritative for system behavior, which files are derived, and where documentation is currently out of sync.
+
+## Authority Precedence (Highest to Lowest)
+
+1. **Executable runtime**
+- `.aether/aether-utils.sh` and sourced scripts in `.aether/utils/`
+- Node CLI runtime in `bin/cli.js` and `bin/lib/*`
+- Why: these files are what actually execute.
+
+2. **Command execution specifications**
+- `.claude/commands/ant/*.md`
+- Why: these drive slash-command behavior in Claude Code.
+
+2.5. **Agent behavior specifications**
+- `.claude/agents/ant/*.md` and `.opencode/agents/*.md`
+- Why: these define worker behavior when commands spawn subagents.
+
+3. **State/data artifacts (runtime outputs, not policy)**
+- `.aether/data/*` (state, pheromones, observations, flags)
+- Why: these represent current colony state, not command intent.
+
+4. **Human-facing documentation**
+- Root `README.md`
+- `.aether/docs/*.md`
+- Why: explanatory, not executable.
+
+## Ownership Map
+
+| Domain | Authoritative Files | Notes |
+|---|---|---|
+| Core deterministic operations | `.aether/aether-utils.sh` | Dispatcher that loads domain modules on demand (~5,200 lines) |
+| Slash command orchestration | `.claude/commands/ant/*.md` | Includes build/continue orchestrators |
+| Worker behavior specs | `.claude/agents/ant/*.md` | 22 Claude agent definitions (Builder, Watcher, etc.) |
+| Packaged Claude agent mirror | `.aether/agents-claude/*.md` | Distribution mirror; must stay byte-identical with `.claude/agents/ant/*.md` |
+| OpenCode command surface | `.opencode/commands/ant/*.md` | 44 OpenCode command files; structure parity with Claude commands |
+| OpenCode worker behavior specs | `.opencode/agents/*.md` | 22 OpenCode agent definitions |
+| Domain modules | `.aether/utils/{flag,spawn,session,suggest,queen,swarm,learning,pheromone,state-api}.sh` | Extracted from aether-utils.sh in Phase 13; sourced on demand |
+| Build/continue split stages | `.aether/docs/command-playbooks/*.md` | Loaded by orchestrators; executable instruction docs |
+| Output templates | `.aether/templates/*` | Templates for generated state/handoff/wisdom/session artifacts |
+| Colony wisdom source | `.aether/QUEEN.md` + `~/.aether/QUEEN.md` | Read by `queen-read`/`colony-prime` |
+| User preferences | `~/.aether/QUEEN.md` (User Preferences section) | Managed by `/ant:preferences`; read by `queen-read`/`colony-prime` |
+| Hive wisdom (cross-repo) | `~/.aether/eternal/memory.json` | High-value signals shared across colonies; read by `colony-prime` |
+| Pheromone runtime state | `.aether/data/pheromones.json` | Active signals with TTL/decay semantics |
+| Autopilot run state | `.aether/data/run-state.json` | Tracks autopilot phase, pause reasons, iteration count |
+| Session/state | `.aether/data/COLONY_STATE.json`, `.aether/data/*.json` | Mutable runtime state |
+| Colony registry | `~/.aether/registry.json` | All registered repos with metadata and domain tags |
+| Package/distribution scope | `package.json` (`files`) + `.npmignore` | Defines what ships vs excluded |
+| Repo-level onboarding docs | `README.md`, `CLAUDE.md` | Should reflect runtime/commands, never override them |
+
+## Confirmed Implementation Facts
+
+- Utility dispatcher and subcommands are implemented in `.aether/aether-utils.sh` (`case "$cmd" in`).
+- Context continuity primitives are runtime-backed in `.aether/aether-utils.sh`:
+  - `context-capsule` (compact prompt context),
+  - `rolling-summary` (bounded narrative log),
+  - `pheromone-prime --compact` and `colony-prime --compact`.
+- `queen-init` creates `.aether/QUEEN.md` (not `.aether/docs/QUEEN.md`).
+- `queen-read` and `colony-prime` read from `~/.aether/QUEEN.md` and `.aether/QUEEN.md`.
+- `queen-promote` writes to `.aether/QUEEN.md`.
+- `build.md` and `continue.md` are now orchestrators that load split playbooks under `.aether/docs/command-playbooks/`.
+- Orchestrators run playbooks as staged instruction sets (Read-tool execution model), not as bash subcommand wrappers.
+- Cross-platform surfaces are present:
+  - 44 Claude commands and 44 OpenCode commands
+  - 22 Claude agents and 22 OpenCode agents
+- Autopilot subcommands (`autopilot-init`, `autopilot-update`, `autopilot-status`, `autopilot-stop`, `autopilot-check-replan`) manage autonomous build/continue cycles via `/ant:run`.
+- `registry-list` lists all registered repos with metadata including domain tags.
+- `.aether/agents-claude/*.md` mirrors `.claude/agents/ant/*.md` for packaging/distribution.
+- `npm run lint:sync` enforces:
+  - command parity checks,
+  - Claude/OpenCode agent structural parity (count + filenames),
+  - Claude/`.aether` agent mirror exact parity (count + filenames + content hash).
+- File contents between Claude and OpenCode command/agent files currently differ; parity is structural, not byte-identical.
+
+## Verified Inventory Snapshot
+
+| Category | Location | Count | Status |
+|---|---|---:|---|
+| Core utility entrypoint | `.aether/aether-utils.sh` | 1 | Active |
+| Sourced shell utilities | `.aether/utils/*.sh` | ~29 | Active (9 domain modules + infrastructure + XML) |
+| XML utility scripts | `.aether/utils/xml-*.sh` | 5 | Active (see drift note) |
+| Slash commands (Claude) | `.claude/commands/ant/*.md` | 44 | Active |
+| Slash commands (OpenCode) | `.opencode/commands/ant/*.md` | 44 | Active (content differs from Claude variants) |
+| Agent definitions (Claude) | `.claude/agents/ant/*.md` | 22 | Active |
+| Agent mirror (packaging) | `.aether/agents-claude/*.md` | 22 | Active mirror (must match Claude agent files exactly) |
+| Agent definitions (OpenCode) | `.opencode/agents/*.md` | 22 | Active (content differs from Claude variants) |
+| Command playbooks | `.aether/docs/command-playbooks/*.md` | 9 | Active (5 build + 4 continue; excludes full/README) |
+| Templates (all types) | `.aether/templates/*` | 12 | Active |
+| Disciplines | `.aether/docs/disciplines/*.md` | 7 | Active |
+| Tests (all files) | `tests/**` | ~140 | Active |
+
+## Drift Findings (Docs vs Implementation)
+
+No high-confidence drift items currently tracked in this document after the 2026-02-22 alignment pass.
+
+## Canonical Read Order (For Contributors)
+
+When determining "how Aether works now", read in this order:
+
+1. `.aether/aether-utils.sh`
+2. `.claude/commands/ant/build.md` and `.claude/commands/ant/continue.md`
+3. `.aether/docs/command-playbooks/*.md`
+4. `.claude/agents/ant/*.md`
+5. Remaining `.claude/commands/ant/*.md`
+6. `.opencode/commands/ant/*.md` and `.opencode/agents/*.md` (for cross-surface checks)
+7. `README.md` and `.aether/docs/*.md`
+
+## Maintenance Rules
+
+1. If runtime behavior changes, update command specs in the same PR.
+2. If command specs change, update docs in the same PR.
+3. Docs must never introduce paths/types not accepted by runtime.
+4. Treat this file as the index of authority boundaries.
+5. Keep `.aether/agents-claude/*.md` synchronized with `.claude/agents/ant/*.md` (enforced by `npm run lint:sync`).
+
+## Immediate Follow-up Checklist
+
+1. [x] Fix QUEEN path references in `.aether/docs/QUEEN-SYSTEM.md` and `.aether/docs/queen-commands.md`.
+2. [x] Update threshold descriptions in `.aether/docs/QUEEN-SYSTEM.md` to match runtime defaults.
+3. [x] Update root `README.md` command count (35 -> 36 -> 37 -> 40 after Phases 2, 6, 7).
+4. [x] Update `.aether/docs/README.md` to include `command-playbooks/` and clarify docs-vs-runtime authority.
+5. [x] Review `bootstrap-system` allowlist in `.aether/aether-utils.sh` for stale doc entries.
+6. [x] Add agent definitions to Ownership Map and authority hierarchy.
+7. [x] Document playbook staged Read-tool execution model.
+8. [x] Clarify OpenCode structural parity and non-identical content status.
+9. [x] Add template ownership and verified inventory snapshot.
+10. [x] Clarify XML utility status in dedicated docs (`.aether/docs/xml-utilities.md`).

package/.aether/docs/xml-utilities.md

@@ -0,0 +1,47 @@
+# XML Utilities
+
+## Status
+
+Active and supported.
+
+These utilities back XML export/import/validation flows used by runtime subcommands and by user-facing commands such as `/ant:seal`, `/ant:entomb`, and `/ant:tunnels`.
+
+## Utility Files
+
+- `.aether/utils/xml-utils.sh`
+- `.aether/utils/xml-core.sh`
+- `.aether/utils/xml-compose.sh`
+- `.aether/utils/xml-convert.sh`
+- `.aether/utils/xml-query.sh`
+
+## Runtime Integration
+
+Core XML subcommands in `.aether/aether-utils.sh`:
+
+- `pheromone-export-xml`
+- `pheromone-import-xml`
+- `pheromone-validate-xml`
+- `wisdom-export-xml`
+- `wisdom-import-xml`
+- `registry-export-xml`
+- `registry-import-xml`
+- `colony-archive-xml`
+
+These subcommands source exchange modules:
+
+- `.aether/exchange/pheromone-xml.sh`
+- `.aether/exchange/wisdom-xml.sh`
+- `.aether/exchange/registry-xml.sh`
+
+## Schema Dependencies
+
+- `.aether/schemas/pheromone.xsd`
+- `.aether/schemas/queen-wisdom.xsd`
+- `.aether/schemas/colony-registry.xsd`
+- `.aether/schemas/aether-types.xsd`
+
+## Operational Notes
+
+- `xmllint` is required for validation/import/export flows that parse XML.
+- XML features degrade gracefully when dependencies are missing, returning structured JSON errors.
+- These utilities are included in `bootstrap-system` allowlist for recovery/update flows.

package/.aether/rules/aether-colony.md

@@ -19,10 +19,11 @@ This only applies to genuinely new conversations, not after /clear.
 
 ## Available Commands
 
-### Getting Started
+### Setup & Getting Started
 | Command | Purpose |
 |---------|---------|
-| `/ant:init "<goal>"` | Set colony intention and initialize |
+| `/ant:lay-eggs` | Set up Aether in this repo (one-time, creates .aether/) |
+| `/ant:init "<goal>"` | Start a colony with a goal |
 | `/ant:colonize` | Analyze existing codebase |
 | `/ant:plan` | Generate project phases |
 | `/ant:build <phase>` | Execute a phase with parallel workers |
@@ -75,19 +76,28 @@ This only applies to genuinely new conversations, not after /clear.
 ## Typical Workflow
 
 ```
-/ant:init "Build feature X"    → Set colony goal
-/ant:colonize                  → Understand existing code (optional)
-/ant:plan                      → Generate phases
-/ant:focus "security"          → Steer attention (optional)
-/ant:build 1                   → Execute phase 1
-/ant:continue                  → Verify, learn, advance
-/ant:build 2                   → Execute phase 2
-...repeat until complete...
-/ant:seal                      → Seal completed colony
+First time in a repo:
+0. /ant:lay-eggs                           (set up Aether in this repo)
+
+Starting a colony:
+1. /ant:init "Build feature X"             (start colony with a goal)
+2. /ant:colonize                           (if existing code)
+3. /ant:plan                               (generates phases)
+4. /ant:focus "security"                   (optional guidance)
+5. /ant:build 1                            (workers execute phase 1)
+6. /ant:continue                           (verify, learn, advance)
+7. /ant:build 2                            (repeat until complete)
+
+After /clear or session break:
+8. /ant:resume-colony                      (restore full context)
+9. /ant:status                             (see where you left off)
+
+After completing a colony:
+10. /ant:seal                              (mark as complete)
+11. /ant:entomb                            (archive to chambers)
+12. /ant:init "next project goal"          (start fresh colony)
 ```
 
-After `/clear` or session break: `/ant:resume-colony` to restore context.
-
 ## Worker Castes
 
 Workers are assigned to castes based on task type:

package/.aether/scripts/incident-test-add.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Create a scaffold regression test for an incident fix.
+# Usage:
+#   bash .aether/scripts/incident-test-add.sh <incident_id> <description> "<command>" "<expected_pattern>"
+
+set -euo pipefail
+
+incident_id="${1:-}"
+description="${2:-}"
+command_string="${3:-}"
+expected_pattern="${4:-}"
+
+if [[ -z "$incident_id" || -z "$description" || -z "$command_string" || -z "$expected_pattern" ]]; then
+  echo "Usage: bash .aether/scripts/incident-test-add.sh <incident_id> <description> \"<command>\" \"<expected_pattern>\""
+  exit 1
+fi
+
+tests_dir=".aether/tests"
+mkdir -p "$tests_dir"
+test_file="$tests_dir/incident-${incident_id}.sh"
+
+cat > "$test_file" <<EOF
+#!/usr/bin/env bash
+# Regression test for incident ${incident_id}
+# Description: ${description}
+
+set -euo pipefail
+
+result=\$(bash -lc '${command_string}' 2>&1 || true)
+
+if echo "\$result" | grep -q '${expected_pattern}'; then
+  echo "PASS: ${description}"
+  exit 0
+fi
+
+echo "FAIL: Expected pattern '${expected_pattern}' not found"
+echo ""
+echo "Command:"
+echo "  ${command_string}"
+echo ""
+echo "Output:"
+echo "\$result"
+exit 1
+EOF
+
+chmod +x "$test_file"
+echo "Created: $test_file"

package/.aether/scripts/weekly-audit.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Weekly Colony Health Audit
+# Run: bash .aether/scripts/weekly-audit.sh
+
+set -euo pipefail
+
+AETHER_ROOT="${AETHER_ROOT:-$(pwd)}"
+DATA_DIR="$AETHER_ROOT/.aether/data"
+UTILS="$AETHER_ROOT/.aether/aether-utils.sh"
+
+echo "# Colony Audit Report - $(date -u +%Y-%m-%d)"
+echo ""
+
+state_size=$(wc -c < "$DATA_DIR/COLONY_STATE.json" 2>/dev/null || echo 0)
+pheromone_size=$(wc -c < "$DATA_DIR/pheromones.json" 2>/dev/null || echo 0)
+observations_size=$(wc -c < "$DATA_DIR/learning-observations.json" 2>/dev/null || echo 0)
+echo "## Memory Sizes"
+echo "- COLONY_STATE.json: $state_size bytes"
+echo "- pheromones.json: $pheromone_size bytes"
+echo "- learning-observations.json: $observations_size bytes"
+echo ""
+
+signal_count=$(jq '.signals | length' "$DATA_DIR/pheromones.json" 2>/dev/null || echo 0)
+expired_count=$(jq '[.signals[]? | select(.active == false)] | length' "$DATA_DIR/pheromones.json" 2>/dev/null || echo 0)
+echo "## Pheromone Health"
+echo "- Total signals: $signal_count"
+echo "- Expired signals: $expired_count"
+echo ""
+
+spawn_eff=$(bash "$UTILS" spawn-efficiency 2>/dev/null | jq -c '.result // {}' 2>/dev/null || echo '{}')
+total_spawned=$(echo "$spawn_eff" | jq -r '.total // 0')
+completed_spawned=$(echo "$spawn_eff" | jq -r '.completed // 0')
+efficiency_pct=$(echo "$spawn_eff" | jq -r '.efficiency_pct // 0')
+echo "## Spawn Efficiency"
+echo "- Total spawned: $total_spawned"
+echo "- Completed: $completed_spawned"
+echo "- Efficiency: ${efficiency_pct}%"
+echo ""
+
+blocker_count=$(jq '[.flags[]? | select(.type == "blocker" and (.resolved_at == null))] | length' "$DATA_DIR/flags.json" 2>/dev/null || echo 0)
+echo "## Gate Failures"
+echo "- Unresolved blockers: $blocker_count"
+echo ""
+
+if [[ -f "$DATA_DIR/midden/midden.json" ]]; then
+  oracle_avg=$(jq '
+    [
+      (.entries[]? | select(.category == "oracle") | (.iterations // 0)),
+      (.signals[]? | select(.type == "oracle") | (.iterations // 0))
+    ] | flatten | if length > 0 then (add / length) else null end
+  ' "$DATA_DIR/midden/midden.json" 2>/dev/null || echo "null")
+  echo "## Oracle Metrics"
+  if [[ "$oracle_avg" == "null" ]]; then
+    echo "- Average iterations: N/A"
+  else
+    echo "- Average iterations: $oracle_avg"
+  fi
+  echo ""
+fi
+
+entropy=$(bash "$UTILS" entropy-score 2>/dev/null | jq -r '.result.score // "N/A"' 2>/dev/null || echo "N/A")
+echo "## Entropy Score"
+echo "- Current: $entropy"
+echo "- Threshold: 75 (organize required if exceeded)"
+echo ""
+
+echo "## Recommendations"
+if [[ "$efficiency_pct" =~ ^[0-9]+$ ]] && [[ "$efficiency_pct" -lt 70 ]]; then
+  echo "- [HIGH] Spawn efficiency below 70% - review worker task decomposition"
+fi
+if [[ "$signal_count" =~ ^[0-9]+$ ]] && [[ "$signal_count" -gt 20 ]]; then
+  echo "- [MEDIUM] High pheromone count - consider consolidation or expiry acceleration"
+fi
+if [[ "$blocker_count" =~ ^[0-9]+$ ]] && [[ "$blocker_count" -gt 3 ]]; then
+  echo "- [HIGH] Multiple unresolved blockers - run /ant:swarm for auto-repair"
+fi
+if [[ "$entropy" =~ ^[0-9]+$ ]] && [[ "$entropy" -gt 75 ]]; then
+  echo "- [CRITICAL] High entropy - run /ant:organize before next build"
+fi