aether-colony 5.2.1 → 5.3.0

package/.aether/docs/plans/pheromone-display-plan.md

@@ -1,257 +0,0 @@
-# Pheromone Display Enhancement Plan
-
-**Created:** 2026-02-21
-**Status:** ✅ COMPLETED
-**Priority:** High - User-requested feature gap
-
----
-
-## Problem Statement
-
-The pheromone system works but is invisible:
-
-1. **Council command exists** - `/ant:council` proposes pheromones via multiple choice
-2. **Pheromone signals exist** - Stored in `.aether/data/pheromones.json`
-3. **Colony-prime loads them** - But only shows a count like "Primed: 2 signals"
-4. **User never sees them** - The actual content is hidden
-
-**User's exact words:** "I think it's important to create a significant plan here for how to display the pheromones that are being injected."
-
----
-
-## What Exists (Don't Rebuild)
-
-| Component | Location | Status |
-|-----------|----------|--------|
-| Council command | `.claude/commands/ant/council.md` | ✅ Works - multi-choice pheromone proposal |
-| Focus command | `.claude/commands/ant/focus.md` | ✅ Works - emits FOCUS signal |
-| Redirect command | `.claude/commands/ant/redirect.md` | ✅ Works - emits REDIRECT signal |
-| Feedback command | `.claude/commands/ant/feedback.md` | ✅ Works - emits FEEDBACK signal |
-| Pheromone storage | `.aether/data/pheromones.json` | ✅ Works - stores signals |
-| Pheromone-prime | `aether-utils.sh:6211` | ✅ Works - loads signals with decay |
-| Colony-prime | `aether-utils.sh:6337` | ✅ Works - combines wisdom + signals |
-| Pheromone-count | `aether-utils.sh:6036` | ✅ Works - counts active signals |
-
----
-
-## What's Missing
-
-### 1. **Pheromone Display Function** (aether-utils.sh)
-
-A new `pheromone-display` function that outputs a formatted table:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   A C T I V E   P H E R O M O N E S
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-🎯 FOCUS (Pay attention here)
-   1. [85%] "security" — injected 2d ago
-   2. [72%] "performance optimization" — injected 5d ago
-
-🚫 REDIRECT (Hard constraints - DO NOT do this)
-   1. [90%] "use ORM" — injected 1d ago
-   2. [68%] "jQuery" — injected 7d ago
-
-💬 FEEDBACK (Guidance to consider)
-   1. [65%] "prefer composition over inheritance" — injected 3d ago
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Total: 5 active signals | Decay: FOCUS 30d, REDIRECT 60d, FEEDBACK 90d
-```
-
-### 2. **Build Command Enhancement** (build.md)
-
-After Step 4 (Load Colony Context), add Step 4.1:
-
-```markdown
-### Step 4.1: Display Active Pheromones
-
-Run using the Bash tool:
-```bash
-bash .aether/aether-utils.sh pheromone-display
-```
-
-This displays the formatted pheromone table to the user so they can see what guidance is active.
-```
-
-### 3. **Status Command Enhancement** (status.md)
-
-Add pheromone summary to `/ant:status` output:
-
-```markdown
-### Pheromones Active
-
-🎯 FOCUS: 2 signals
-🚫 REDIRECT: 1 signal
-💬 FEEDBACK: 1 signal
-
-Run /ant:pheromones for full details
-```
-
-### 4. **New Pheromones Command** (pheromones.md)
-
-A dedicated command for viewing/managing pheromones:
-
-```markdown
----
-name: ant:pheromones
-description: "🎯🐜🚫🐜💬 View and manage active pheromone signals"
----
-
-Usage:
-  /ant:pheromones          # Display all active signals
-  /ant:pheromones focus    # Show only FOCUS signals
-  /ant:pheromones redirect # Show only REDIRECT signals
-  /ant:pheromones feedback # Show only FEEDBACK signals
-  /ant:pheromones clear    # Clear all expired signals
-  /ant:pheromones expire <id> # Expire a specific signal
-```
-
----
-
-## Implementation Plan
-
-### Phase 1: pheromone-display Function (aether-utils.sh)
-
-**Location:** After `pheromone-count` (~line 6058)
-
-```bash
-pheromone-display)
-  # Display active pheromones in formatted table
-  # Usage: pheromone-display [type]
-  #   type: Optional filter (focus/redirect/feedback)
-  # Returns: Formatted table string
-
-  pd_file="$DATA_DIR/pheromones.json"
-  pd_type="${1:-all}"
-  pd_now=$(date +%s)
-
-  if [[ ! -f "$pd_file" ]]; then
-    echo "No pheromones file found. Run /ant:init to initialize colony."
-    exit 0
-  fi
-
-  # Build display using same decay logic as pheromone-read
-  # ... (implementation details)
-```
-
-**Output format:**
-- Header with box drawing
-- Grouped by type (FOCUS, REDIRECT, FEEDBACK)
-- Each signal shows: effective strength %, content, age
-- Footer with totals and decay info
-
-### Phase 2: Update build.md
-
-Add Step 4.1 after colony-prime call to display pheromones visibly.
-
-### Phase 3: Update status.md
-
-Add pheromone summary section after memory health display.
-
-### Phase 4: Create pheromones.md Command
-
-New slash command for dedicated pheromone viewing and management.
-
----
-
-## Display Locations
-
-| Where | What | When |
-|-------|------|------|
-| `/ant:build` | Full table | Before spawning workers |
-| `/ant:status` | Summary counts | In colony overview |
-| `/ant:council` | After injection | Show what was added |
-| `/ant:pheromones` | Full table + management | On demand |
-| `/ant:continue` | Summary | After phase completion |
-
----
-
-## Visual Design
-
-### Full Table (for /ant:build, /ant:pheromones)
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   A C T I V E   P H E R O M O N E S
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-🎯 FOCUS (Pay attention here)
-   1. [85%] "security"
-      └── injected 2d ago, expires in 28d
-   2. [72%] "performance optimization"
-      └── injected 5d ago, expires in 25d
-
-🚫 REDIRECT (Hard constraints - DO NOT do this)
-   1. [90%] "use ORM"
-      └── injected 1d ago, expires in 59d
-   2. [68%] "jQuery"
-      └── injected 7d ago, expires in 53d
-
-💬 FEEDBACK (Guidance to consider)
-   1. [65%] "prefer composition over inheritance"
-      └── injected 3d ago, expires in 87d
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-5 signals active | Decay rates: FOCUS 30d, REDIRECT 60d, FEEDBACK 90d
-```
-
-### Summary (for /ant:status)
-
-```
-┌─────────────────────────────────────────────────────────┐
-│ PHEROMONES                                               │
-├─────────────────────────────────────────────────────────┤
-│ 🎯 FOCUS: 2    🚫 REDIRECT: 1    💬 FEEDBACK: 1         │
-│                                                          │
-│ Strongest: "use ORM" [90%]                              │
-│ Newest: "security" [85%] - 2d ago                       │
-│                                                          │
-│ Run /ant:pheromones for details                         │
-└─────────────────────────────────────────────────────────┘
-```
-
-### Injection Confirmation (for /ant:council, /ant:focus, etc.)
-
-```
-✓ Pheromone injected:
-  🎯 FOCUS: "security"
-  Strength: 0.8 | Expires: 30d
-
-Active signals: 5
-```
-
----
-
-## Files to Create/Modify
-
-| File | Action | Purpose |
-|------|--------|---------|
-| `.aether/aether-utils.sh` | Modify | Add `pheromone-display` function |
-| `.claude/commands/ant/build.md` | Modify | Add Step 4.1 - display pheromones |
-| `.claude/commands/ant/status.md` | Modify | Add pheromone summary section |
-| `.claude/commands/ant/pheromones.md` | Create | New command for viewing/managing |
-| `.opencode/commands/ant/pheromones.md` | Create | OpenCode version |
-
----
-
-## Testing
-
-1. Run `/ant:focus "test signal"` and verify it appears in display
-2. Run `/ant:redirect "avoid this"` and verify it appears in display
-3. Run `/ant:build 1` and verify pheromone table shows before workers spawn
-4. Run `/ant:status` and verify pheromone summary appears
-5. Test decay: Create signal, wait, verify strength decreases
-
----
-
-## Success Criteria
-
-- [x] `/ant:build` displays full pheromone table before spawning workers
-- [x] `/ant:status` shows pheromone counts and strongest/newest
-- [x] `/ant:pheromones` command exists for dedicated viewing
-- [x] `/ant:council` displays what was injected after session (already existed)
-- [x] All signal types (FOCUS/REDIRECT/FEEDBACK) visible
-- [x] Decay strength shown as percentage
-- [x] Age and expiry shown per signal

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

@@ -1,234 +0,0 @@
-<?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

@@ -1,47 +0,0 @@
-#!/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

@@ -1,79 +0,0 @@
-#!/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