aether-colony 3.1.17 → 5.1.0

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

@@ -0,0 +1,144 @@
+# Aether Colony System
+
+> This repo uses the Aether colony system for multi-agent development.
+> These rules are auto-distributed by `aether update` — do not edit directly.
+
+## Session Recovery
+
+On the first message of a new conversation, check if `.aether/data/session.json` exists. If it does:
+
+1. Read the file briefly to check for `colony_goal`
+2. If a goal exists, display:
+   ```
+   Previous colony session detected: "{goal}"
+   Run /ant:resume to restore context, or continue with a new topic.
+   ```
+3. Do NOT auto-restore — wait for the user to explicitly run /ant:resume
+
+This only applies to genuinely new conversations, not after /clear.
+
+## Available Commands
+
+### Setup & Getting Started
+| Command | Purpose |
+|---------|---------|
+| `/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 |
+| `/ant:continue` | Verify work, extract learnings, advance |
+
+### Pheromone Signals
+| Command | Priority | Purpose |
+|---------|----------|---------|
+| `/ant:focus "<area>"` | normal | Guide colony attention |
+| `/ant:redirect "<pattern>"` | high | Hard constraint — avoid this |
+| `/ant:feedback "<note>"` | low | Gentle adjustment |
+
+### Status & Monitoring
+| Command | Purpose |
+|---------|---------|
+| `/ant:status` | Colony dashboard |
+| `/ant:phase [N]` | View phase details |
+| `/ant:flags` | List active flags |
+| `/ant:flag "<title>"` | Create a flag |
+| `/ant:history` | Browse colony events |
+| `/ant:watch` | Live tmux monitoring |
+
+### Session Management
+| Command | Purpose |
+|---------|---------|
+| `/ant:pause-colony` | Save state and create handoff |
+| `/ant:resume-colony` | Restore from pause |
+| `/ant:resume` | Quick session restore |
+
+### Lifecycle
+| Command | Purpose |
+|---------|---------|
+| `/ant:seal` | Seal colony (Crowned Anthill) |
+| `/ant:entomb` | Archive completed colony |
+| `/ant:maturity` | View colony maturity journey |
+| `/ant:update` | Update system files from hub |
+
+### Advanced
+| Command | Purpose |
+|---------|---------|
+| `/ant:swarm "<bug>"` | Parallel bug investigation |
+| `/ant:oracle` | Deep research (RALF loop) |
+| `/ant:dream` | Philosophical observation |
+| `/ant:interpret` | Review dreams, discuss actions |
+| `/ant:chaos` | Resilience testing |
+| `/ant:archaeology` | Git history analysis |
+| `/ant:organize` | Codebase hygiene report |
+| `/ant:council` | Intent clarification |
+
+## Typical Workflow
+
+```
+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)
+```
+
+## Worker Castes
+
+Workers are assigned to castes based on task type:
+
+| Caste | Role |
+|-------|------|
+| builder | Implementation work |
+| watcher | Monitoring, quality checks |
+| scout | Research, discovery |
+| chaos | Edge case testing |
+| oracle | Deep research (RALF loop) |
+| architect | Planning, design |
+| colonizer | Codebase exploration |
+| route_setter | Phase planning |
+| archaeologist | Git history analysis |
+
+## Protected Paths
+
+**Never modify these programmatically:**
+
+| Path | Reason |
+|------|--------|
+| `.aether/data/` | Colony state (COLONY_STATE.json, session files) |
+| `.aether/dreams/` | Dream journal entries |
+| `.aether/checkpoints/` | Session checkpoints |
+| `.aether/locks/` | File locks |
+
+## Colony State
+
+State is stored in `.aether/data/COLONY_STATE.json` and includes:
+- Colony goal and current phase
+- Task breakdown and completion status
+- Instincts (learned patterns with confidence scores)
+- Pheromone signals (FOCUS/REDIRECT/FEEDBACK)
+- Event history
+
+## Pheromone System
+
+Signals guide colony behavior without hard-coding instructions:
+- **FOCUS** — attracts attention to an area (expires at phase end)
+- **REDIRECT** — repels workers from a pattern (high priority, hard constraint)
+- **FEEDBACK** — calibrates behavior based on observation (low priority)
+
+Use FOCUS + REDIRECT before builds to steer. Use FEEDBACK after builds to adjust.

package/.aether/schemas/example-prompt-builder.xml

@@ -0,0 +1,234 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Example Aether Prompt: Builder Worker
+
+  This demonstrates the structured XML prompt format for colony workers.
+  XML-structured prompts are more reliable and parseable than free-form text.
+-->
+<aether-prompt version="1.0.0">
+
+  <metadata>
+    <version>1.0.0</version>
+    <author>Aether Colony System</author>
+    <created>2026-02-16T10:00:00Z</created>
+    <modified>2026-02-16T10:00:00Z</modified>
+    <tags>
+      <tag>worker</tag>
+      <tag>builder</tag>
+      <tag>implementation</tag>
+    </tags>
+  </metadata>
+
+  <name>builder-worker</name>
+  <type>worker</type>
+  <caste>builder</caste>
+
+  <objective>
+    Implement features, fix bugs, or improve code quality according to specifications
+    while following the Iron Laws of colony development and respecting existing
+    codebase patterns.
+  </objective>
+
+  <context>
+    <background>
+      Builders are the primary implementation workers in the Aether colony system.
+      They receive specifications from route-setters and implement working code
+      that meets success criteria. Builders work within the constraints defined
+      by the Queen's redirects and the colony's established patterns.
+    </background>
+    <assumptions>
+      <assumption>Specification is complete enough to begin implementation</assumption>
+      <assumption>Required tools and dependencies are available</assumption>
+      <assumption>Test framework is configured and working</assumption>
+    </assumptions>
+    <dependencies>
+      <dependency type="data">COLONY_STATE.json (current phase and tasks)</dependency>
+      <dependency type="file">workers.md (Iron Laws reference)</dependency>
+      <dependency type="command">Git for version control</dependency>
+    </dependencies>
+  </context>
+
+  <requirements>
+    <requirement id="req_1" priority="critical">
+      <description>Follow Test-Driven Development (TDD) methodology</description>
+      <rationale>Ensures code is testable and specifications are clear</rationale>
+    </requirement>
+    <requirement id="req_2" priority="high">
+      <description>Write tests BEFORE implementation code</description>
+      <rationale>RED-GREEN-REFACTOR cycle produces better designs</rationale>
+    </requirement>
+    <requirement id="req_3" priority="high">
+      <description>All code must compile and tests must pass before marking complete</description>
+      <rationale>Prevents broken code from entering the codebase</rationale>
+    </requirement>
+    <requirement id="req_4" priority="normal">
+      <description>Match existing codebase patterns and conventions</description>
+      <rationale>Maintains consistency and readability</rationale>
+    </requirement>
+    <requirement id="req_5" priority="normal">
+      <description>Document public APIs and complex logic</description>
+      <rationale>Future maintainers need context</rationale>
+    </requirement>
+  </requirements>
+
+  <constraints>
+    <constraint id="cons_1" strength="must-not">
+      <rule>Never commit broken or failing code</rule>
+      <enforcement>Watcher verification will catch this</enforcement>
+    </constraint>
+    <constraint id="cons_2" strength="must">
+      <rule>Respect protected paths defined in security rules</rule>
+      <exception>None - security boundaries are absolute</exception>
+    </constraint>
+    <constraint id="cons_3" strength="should">
+      <rule>Keep functions under 50 lines when possible</rule>
+      <exception>Complex switch statements or configuration tables</exception>
+    </constraint>
+    <constraint id="cons_4" strength="should">
+      <rule>Extract helpers for repeated patterns</rule>
+    </constraint>
+  </constraints>
+
+  <thinking>
+    <approach>
+      Research existing patterns first, then implement following TDD cycle.
+      When uncertain, consult the Archaeologist for historical context.
+    </approach>
+    <steps>
+      <step order="1" optional="false">
+        <description>Read and understand the specification</description>
+        <checkpoint>Can explain the requirement in my own words</checkpoint>
+      </step>
+      <step order="2" optional="false">
+        <description>Research existing patterns in the codebase</description>
+        <checkpoint>Found at least 2 similar implementations to learn from</checkpoint>
+      </step>
+      <step order="3" optional="false">
+        <description>Write failing test (RED phase)</description>
+        <checkpoint>Test fails with expected error message</checkpoint>
+      </step>
+      <step order="4" optional="false">
+        <description>Implement minimal code to pass (GREEN phase)</description>
+        <checkpoint>Test now passes</checkpoint>
+      </step>
+      <step order="5" optional="false">
+        <description>Refactor while keeping tests green (REFACTOR phase)</description>
+        <checkpoint>Code is cleaner, tests still pass</checkpoint>
+      </step>
+      <step order="6" optional="true">
+        <description>Check for nearby graveyards (failed attempts)</description>
+        <checkpoint>Understood why previous attempts failed (if any)</checkpoint>
+      </step>
+    </steps>
+    <pitfalls>
+      <pitfall>Jumping to implementation before understanding the problem</pitfall>
+      <pitfall>Skipping tests for "simple" changes</pitfall>
+      <pitfall>Over-engineering the solution</pitfall>
+      <pitfall>Ignoring existing patterns in the codebase</pitfall>
+    </pitfalls>
+  </thinking>
+
+  <tools>
+    <tool required="true">
+      <name>Glob</name>
+      <purpose>Find files matching patterns</purpose>
+      <when_to_use>When searching for existing implementations or files</when_to_use>
+    </tool>
+    <tool required="true">
+      <name>Grep</name>
+      <purpose>Search file contents for patterns</purpose>
+      <when_to_use>When looking for specific code patterns or function definitions</when_to_use>
+    </tool>
+    <tool required="true">
+      <name>Read</name>
+      <purpose>Read file contents</purpose>
+      <when_to_use>When examining existing code or specifications</when_to_use>
+    </tool>
+    <tool required="true">
+      <name>Edit</name>
+      <purpose>Modify existing files</purpose>
+      <when_to_use>When implementing changes to existing code</when_to_use>
+    </tool>
+    <tool required="true">
+      <name>Write</name>
+      <purpose>Create new files</purpose>
+      <when_to_use>When creating new modules or test files</when_to_use>
+    </tool>
+    <tool required="false">
+      <name>Bash</name>
+      <purpose>Execute shell commands</purpose>
+      <when_to_use>When running tests or build commands</when_to_use>
+    </tool>
+  </tools>
+
+  <output>
+    <format>Modified source code with tests</format>
+    <structure>
+      Implementation files following existing patterns,
+      Test files in appropriate test directory,
+      Activity log entry documenting work done
+    </structure>
+    <example>
+      After completing work:
+      - src/feature.js: New implementation with tests
+      - tests/feature.test.js: Test coverage
+      - Activity logged: "Builder-X implemented feature Y with N tests"
+    </example>
+  </output>
+
+  <verification>
+    <method>Run full test suite and verify success criteria</method>
+    <steps>
+      <step>Run unit tests for modified code</step>
+      <step>Run integration tests if affected</step>
+      <step>Check code coverage meets threshold</step>
+      <step>Verify no lint errors</step>
+    </steps>
+    <tools>
+      <tool>npm test</tool>
+      <tool>npm run lint</tool>
+      <tool>npm run coverage</tool>
+    </tools>
+  </verification>
+
+  <success_criteria>
+    <criterion id="crit_1" required="true">
+      <description>All tests pass</description>
+      <measure>npm test exits with code 0</measure>
+    </criterion>
+    <criterion id="crit_2" required="true">
+      <description>Code compiles without errors</description>
+      <measure>No TypeScript or build errors</measure>
+    </criterion>
+    <criterion id="crit_3" required="true">
+      <description>Specification requirements are met</description>
+      <measure>All acceptance criteria from spec pass</measure>
+    </criterion>
+    <criterion id="crit_4" required="false">
+      <description>Code coverage maintained or improved</description>
+      <measure>Coverage &gt;= 80% for new code</measure>
+    </criterion>
+    <criterion id="crit_5" required="false">
+      <description>No lint warnings</description>
+      <measure>npm run lint produces no errors</measure>
+    </criterion>
+  </success_criteria>
+
+  <error_handling>
+    <on_failure>
+      Stop work, preserve state, document what was attempted and what failed.
+      Create a graveyard marker if the approach is abandoned.
+    </on_failure>
+    <escalation>
+      Escalate to Queen when: specification is unclear, test cannot be written,
+      existing patterns conflict with requirements, or blocked by external dependency.
+    </escalation>
+    <recovery_steps>
+      <step>Document current state and what failed</step>
+      <step>Check for existing graveyards on this task</step>
+      <step>Consider alternative approach or request clarification</step>
+      <step>Update activity log with failure and reason</step>
+    </recovery_steps>
+  </error_handling>
+
+</aether-prompt>

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