aether-colony 1.1.0

package/.aether/docs/QUEEN-SYSTEM.md

@@ -0,0 +1,211 @@
+# QUEEN.md System
+
+The QUEEN.md system is Aether's wisdom feedback loop - a mechanism for capturing, validating, and propagating learnings across colonies.
+
+## Overview
+
+The Queen represents the accumulation of validated knowledge from all colonies. As colonies complete work, they promote significant patterns, decisions, and insights to QUEEN.md. Future colonies can then read this wisdom to benefit from previous experience.
+
+## File Location
+
+```
+.aether/docs/QUEEN.md
+```
+
+## Structure
+
+### 📜 Philosophies
+
+Core beliefs validated through repeated successful application across multiple colonies.
+
+**Threshold:** 5 successful validations required for promotion
+
+Example:
+```markdown
+- **colony-name** (2026-02-15T13:08:24Z): Test-driven development ensures quality
+```
+
+### 🧭 Patterns
+
+Validated approaches that consistently work. These represent discovered best practices.
+
+**Threshold:** 3 successful validations required for promotion
+
+Example:
+```markdown
+- **colony-name** (2026-02-15T13:08:28Z): Always validate inputs
+```
+
+### ⚠️ Redirects
+
+Anti-patterns to avoid. Approaches that have caused problems.
+
+**Threshold:** 2 failed validations required for promotion
+
+Example:
+```markdown
+- **colony-name** (2026-02-15T13:08:31Z): Never skip security checks
+```
+
+### 🔧 Stack Wisdom
+
+Technology-specific insights detected through codebase analysis.
+
+**Threshold:** 1 validation required for promotion
+
+Example:
+```markdown
+- **colony-name** (2026-02-15T13:08:36Z): Use jq for JSON in bash
+```
+
+### 🏛️ Decrees
+
+User-mandated rules that override other guidance.
+
+**Threshold:** 0 validations required (immediate promotion)
+
+Example:
+```markdown
+- **colony-name** (2026-02-15T13:08:40Z): All code must have tests
+```
+
+### 📊 Evolution Log
+
+Track how wisdom has evolved over time.
+
+## Commands
+
+### queen-init
+
+Initialize QUEEN.md from template if it doesn't exist.
+
+```bash
+bash .aether/aether-utils.sh queen-init
+```
+
+**Returns:**
+```json
+{"created": true, "path": ".aether/docs/QUEEN.md", "source": "~/.aether/system/templates/QUEEN.md.template"}
+```
+
+### queen-read
+
+Read QUEEN.md and return wisdom as JSON for worker priming.
+
+```bash
+bash .aether/aether-utils.sh queen-read
+```
+
+**Returns:**
+```json
+{
+  "metadata": {
+    "version": "1.0.0",
+    "last_evolved": "2026-02-15T13:08:40Z",
+    "colonies_contributed": ["colony-a"],
+    "promotion_thresholds": {...},
+    "stats": {...}
+  },
+  "wisdom": {
+    "philosophies": "...",
+    "patterns": "...",
+    "redirects": "...",
+    "stack_wisdom": "...",
+    "decrees": "..."
+  },
+  "priming": {
+    "has_philosophies": true,
+    "has_patterns": true,
+    ...
+  }
+}
+```
+
+### queen-promote
+
+Promote a learning to QUEEN.md wisdom.
+
+```bash
+bash .aether/aether-utils.sh queen-promote <type> <content> <colony_name>
+```
+
+**Types:** `philosophy`, `pattern`, `redirect`, `stack`, `decree`
+
+**Example:**
+```bash
+bash .aether/aether-utils.sh queen-promote pattern "Always validate inputs" "my-colony"
+```
+
+## Integration with Commands
+
+### init.md
+
+Calls `queen-init` after bootstrap to ensure QUEEN.md exists for the colony.
+
+### build.md
+
+Calls `queen-read` before spawning workers to inject wisdom into worker prompts.
+
+### continue.md
+
+After verification, promotes validated learnings to QUEEN.md using `queen-promote`.
+
+### seal.md
+
+Before archiving, promotes significant patterns and decisions to QUEEN.md.
+
+### entomb.md
+
+Before creating the chamber, promotes validated learnings to QUEEN.md.
+
+## Promotion Thresholds
+
+| Type | Threshold | Rationale |
+|------|-----------|-----------|
+| Philosophy | 5 | Core beliefs need strongest validation |
+| Pattern | 3 | Best practices need multiple confirmations |
+| Redirect | 2 | Anti-patterns need fewer failures to document |
+| Stack | 1 | Tech insights are domain-specific |
+| Decree | 0 | User mandates are immediate |
+
+## Metadata
+
+The QUEEN.md file includes a METADATA block at the end:
+
+```html
+<!-- METADATA
+{
+  "version": "1.0.0",
+  "last_evolved": "2026-02-15T13:08:40Z",
+  "colonies_contributed": ["colony-a"],
+  "promotion_thresholds": {
+    "philosophy": 5,
+    "pattern": 3,
+    "redirect": 2,
+    "stack": 1,
+    "decree": 0
+  },
+  "stats": {
+    "total_philosophies": 1,
+    "total_patterns": 1,
+    ...
+  }
+}
+-->
+```
+
+## Best Practices
+
+1. **Don't manually edit QUEEN.md** - Use `queen-promote` to ensure proper formatting
+2. **Validate before promoting** - Only promote learnings that have been tested
+3. **Use descriptive colony names** - Helps track wisdom origins
+4. **Read wisdom at build start** - Workers benefit from accumulated knowledge
+5. **Review periodically** - Some wisdom may become outdated as the system evolves
+
+## See Also
+
+- `/ant:init` - Initializes QUEEN.md for new colonies
+- `/ant:build` - Reads QUEEN.md wisdom for worker priming
+- `/ant:continue` - Promotes validated learnings
+- `/ant:seal` - Promotes final colony wisdom
+- `/ant:entomb` - Promotes wisdom before archiving

package/.aether/docs/README.md

@@ -0,0 +1,68 @@
+# Aether Documentation
+
+This directory contains actively maintained documentation for the Aether colony system. 8 files total plus `disciplines/` subdirectory.
+
+---
+
+## User-Facing Docs
+
+Distributed to target repos via `aether update` (update allowlist):
+
+| File | Purpose |
+|------|---------|
+| `pheromones.md` | Pheromone system guide (FOCUS/REDIRECT/FEEDBACK signals) |
+
+---
+
+## Colony System Docs
+
+Packaged in npm, available to all Aether installations:
+
+| File | Purpose |
+|------|---------|
+| `caste-system.md` | Worker caste definitions and emoji assignments |
+| `QUEEN-SYSTEM.md` | Queen wisdom promotion system |
+| `queen-commands.md` | Queen command documentation |
+| `QUEEN.md` | Generated Queen wisdom file (repo-specific, auto-updated) |
+| `error-codes.md` | Error code reference (E_* constants) |
+
+---
+
+## Development Docs
+
+Packaged in npm, documents active issues:
+
+| File | Purpose |
+|------|---------|
+| `known-issues.md` | Active known issues and workarounds |
+
+---
+
+## Worker Disciplines
+
+Training protocols that govern worker behavior (in `disciplines/` subdirectory):
+
+| File | Purpose |
+|------|---------|
+| `disciplines/DISCIPLINES.md` | Discipline index and overview |
+| `disciplines/verification.md` | No completion claims without evidence |
+| `disciplines/verification-loop.md` | 6-phase quality gate before advancement |
+| `disciplines/debugging.md` | Systematic root cause investigation |
+| `disciplines/tdd.md` | Test-first development |
+| `disciplines/learning.md` | Pattern detection with validation |
+| `disciplines/coding-standards.md` | Universal code quality rules |
+
+---
+
+## Archived Docs
+
+Historical documentation moved to `archive/` subdirectory:
+
+- `QUEEN_ANT_ARCHITECTURE.md` - superseded by agent files
+- `implementation-learnings.md` - historical findings
+- `constraints.md` - content now in agent definitions
+- `pathogen-schema.md` - specialized use case
+- `pathogen-schema-example.json` - example for schema
+- `progressive-disclosure.md` - design philosophy
+
+Archived docs remain available for reference but are not actively maintained.

package/.aether/docs/caste-system.md

@@ -0,0 +1,48 @@
+# Caste System Reference
+
+This is the **canonical source** for Aether caste emoji definitions.
+
+- All commands and documentation should reference this file
+- The `get_caste_emoji()` function in `aether-utils.sh` implements these mappings
+- To add a new caste: update this file AND the function
+
+## Display Format
+
+Workers are displayed as: `{caste_emoji} {worker_name}`
+Example: `🔨🐜 Hammer-42` (not "Hammer-42 (Builder)")
+
+## Caste Table
+
+| Caste | Emoji | Role | Name Patterns |
+|-------|-------|------|---------------|
+| queen | 👑🐜 | Colony coordinator | Queen, QUEEN, queen |
+| builder | 🔨🐜 | Implementation work | Builder, Bolt, Hammer, Forge, Mason, Brick, Anvil, Weld |
+| watcher | 👁️🐜 | Monitoring, observation | Watcher, Vigil, Sentinel, Guard, Keen, Sharp, Hawk, Alert |
+| scout | 🔍🐜 | Research, discovery | Scout, Swift, Dash, Ranger, Track, Seek, Path, Roam, Quest |
+| colonizer | 🗺️🐜 | New project setup | Colonizer, Pioneer, Map, Chart, Venture, Explore, Compass, Atlas, Trek |
+| surveyor | 📊🐜 | Measurement, assessment | Surveyor, Chart, Plot, Survey, Measure, Assess, Gauge, Sound, Fathom |
+| architect | 🏛️🐜 | Planning, design (merged into Keeper — no dedicated agent file) | Architect, Blueprint, Draft, Design, Plan, Schema, Frame, Sketch, Model |
+| chaos | 🎲🐜 | Edge case testing | Chaos, Probe, Stress, Shake, Twist, Snap, Breach, Surge, Jolt |
+| archaeologist | 🏺🐜 | Git history excavation | Archaeologist, Relic, Fossil, Dig, Shard, Epoch, Strata, Lore, Glyph |
+| oracle | 🔮🐜 | Deep research (RALF loop) | Oracle, Sage, Seer, Vision, Augur, Mystic, Sibyl, Delph, Pythia |
+| route_setter | 📋🐜 | Direction setting | Route, route |
+| ambassador | 🔌🐜 | Third-party API integration | Ambassador, Bridge, Connect, Link, Diplomat, Network, Protocol |
+| auditor | 👥🐜 | Code review, quality audits | Auditor, Review, Inspect, Examine, Scrutin, Critical, Verify |
+| chronicler | 📝🐜 | Documentation generation | Chronicler, Document, Record, Write, Chronicle, Archive, Scribe |
+| gatekeeper | 📦🐜 | Dependency management | Gatekeeper, Guard, Protect, Secure, Shield, Depend, Supply |
+| guardian | 🛡️🐜 | Security audits (merged into Auditor — no dedicated agent file) | Guardian, Defend, Patrol, Secure, Vigil, Watch, Safety, Security |
+| includer | ♿🐜 | Accessibility audits | Includer, Access, Inclusive, A11y, WCAG, Barrier, Universal |
+| keeper | 📚🐜 | Knowledge curation | Keeper, Archive, Store, Curate, Preserve, Knowledge, Wisdom, Pattern |
+| measurer | ⚡🐜 | Performance profiling | Measurer, Metric, Benchmark, Profile, Optimize, Performance, Speed |
+| probe | 🧪🐜 | Test generation | Probe, Test, Excavat, Uncover, Edge, Case, Mutant |
+| tracker | 🐛🐜 | Bug investigation | Tracker, Debug, Trace, Follow, Bug, Hunt, Root |
+| weaver | 🔄🐜 | Code refactoring | Weaver, Refactor, Restruct, Transform, Clean, Pattern, Weave |
+| dreamer | 💭🐜 | Creative ideation | Dreamer, Muse, Imagine, Wonder, Ponder, Reverie |
+
+## Notes
+
+- The global `get_caste_emoji()` function matches by **name pattern** (e.g., a worker named "Hammer-42" matches the builder caste)
+- Castes without dedicated patterns fall back to the generic ant emoji `🐜`
+- The `colonizer` canonical emoji is `🗺️🐜` — older references using `🌱🐜` should be updated
+- The `route_setter` canonical emoji is `📋🐜` — older references using `🧭🐜` should be updated
+- The `architect` and `guardian` castes are **merged**: their capabilities were absorbed by Keeper and Auditor respectively (Phase 25). The caste emoji rows remain because workers named after those patterns (e.g., "Blueprint-3", "Patrol-7") still resolve to the correct emojis via `get_caste_emoji()`. There are no longer dedicated agent files for these castes.

package/.aether/docs/disciplines/DISCIPLINES.md

@@ -0,0 +1,93 @@
+# Aether Colony Disciplines
+
+**Updated:** 2025-02-07
+
+## Overview
+
+The Aether ant colony system includes 8 integrated disciplines that govern worker behavior. These disciplines are infused directly into worker prompts and command execution.
+
+## Honest Execution Model
+
+**What the colony provides:**
+- Task organization and decomposition (real)
+- State persistence across sessions (real)
+- Parallel execution via Task tool (real, when explicitly used)
+- Structured verification gates (real)
+
+**What it does NOT provide:**
+- Automatic parallel execution (must be explicitly spawned)
+- Magic emergence (follows structured commands)
+- Guaranteed correctness (verification catches issues)
+
+## Discipline Reference
+
+### Core Disciplines (All Workers)
+
+| Discipline | File | Purpose |
+|-----------|------|---------|
+| Verification | `verification.md` | No completion claims without evidence |
+| Verification Loop | `verification-loop.md` | 6-phase quality gate before advancement |
+| Debugging | `debugging.md` | Systematic root cause investigation |
+| TDD | `tdd.md` | Test-first development |
+| Learning | `learning.md` | Pattern detection with validation |
+| Coding Standards | `coding-standards.md` | Universal code quality rules |
+
+### Role-Specific Disciplines
+
+| Discipline | File | Applies To |
+|-----------|------|------------|
+| Planning | `planning.md` | Route-Setter |
+
+## Learning Validation
+
+Learnings are NOT automatically trusted. They follow a validation lifecycle:
+
+```
+hypothesis → validated → (or) disproven
+```
+
+- **hypothesis**: Recorded but not yet tested (default)
+- **validated**: Tested and confirmed working
+- **disproven**: Found to be incorrect
+
+Instincts track success/failure counts and can be automatically disproven.
+
+## Verification Enforcement
+
+`/ant:continue` enforces verification:
+- Build must pass
+- Tests must pass
+- Success criteria must have evidence
+- **Phase will NOT advance without passing verification**
+
+No workarounds. Fix issues and re-run.
+
+## Command Integration
+
+| Command | Key Behaviors |
+|---------|---------------|
+| `/ant:build` | Real parallelism via Task tool, honest logging |
+| `/ant:continue` | Mandatory verification gate, learning extraction |
+| `/ant:plan` | Bite-sized task planning |
+| `/ant:status` | Colony state with instincts |
+
+## File Structure
+
+```
+.aether/
+├── workers.md               # Worker roles + honest execution model
+├── docs/disciplines/
+│   ├── verification.md      # Evidence before claims
+│   ├── verification-loop.md # 6-phase quality gate
+│   ├── debugging.md         # Systematic debugging
+│   ├── tdd.md               # Test-driven development
+│   ├── learning.md          # Colony learning system
+│   ├── coding-standards.md  # Code quality rules
+│   └── DISCIPLINES.md       # This file
+```
+
+## Reinstall After Updates
+
+```bash
+cd /Users/callumcowie/repos/Aether && npm run postinstall
+```

package/.aether/docs/disciplines/coding-standards.md

@@ -0,0 +1,197 @@
+# Coding Standards Discipline
+
+## Purpose
+
+Universal code quality rules that apply to all worker output. Code is read more than written - optimize for readability and maintainability.
+
+## Core Principles
+
+### 1. Readability First
+- Clear variable and function names
+- Self-documenting code preferred over comments
+- Consistent formatting
+
+### 2. KISS (Keep It Simple, Stupid)
+- Simplest solution that works
+- No premature optimization
+- Easy to understand > clever code
+
+### 3. DRY (Don't Repeat Yourself)
+- Extract common logic into functions
+- Create reusable components
+- No copy-paste programming
+
+### 4. YAGNI (You Aren't Gonna Need It)
+- Don't build features before needed
+- Add complexity only when required
+- Start simple, refactor when needed
+
+## Naming Conventions
+
+### Variables
+```
+✅ GOOD: Descriptive names
+const marketSearchQuery = 'election'
+const isUserAuthenticated = true
+
+❌ BAD: Unclear names
+const q = 'election'
+const flag = true
+```
+
+### Functions
+```
+✅ GOOD: Verb-noun pattern
+function fetchMarketData(marketId: string) { }
+function calculateSimilarity(a: number[], b: number[]) { }
+function isValidEmail(email: string): boolean { }
+
+❌ BAD: Unclear or noun-only
+function market(id: string) { }
+function similarity(a, b) { }
+```
+
+## Critical Patterns
+
+### Immutability (ALWAYS)
+```
+✅ ALWAYS use spread operator
+const updatedUser = { ...user, name: 'New Name' }
+const updatedArray = [...items, newItem]
+
+❌ NEVER mutate directly
+user.name = 'New Name'  // BAD
+items.push(newItem)     // BAD
+```
+
+### Error Handling
+```
+✅ GOOD: Comprehensive
+async function fetchData(url: string) {
+  try {
+    const response = await fetch(url)
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`)
+    }
+    return await response.json()
+  } catch (error) {
+    console.error('Fetch failed:', error)
+    throw new Error('Failed to fetch data')
+  }
+}
+
+❌ BAD: No error handling
+async function fetchData(url) {
+  const response = await fetch(url)
+  return response.json()
+}
+```
+
+### Async/Await
+```
+✅ GOOD: Parallel when possible
+const [users, markets] = await Promise.all([
+  fetchUsers(),
+  fetchMarkets()
+])
+
+❌ BAD: Sequential when unnecessary
+const users = await fetchUsers()
+const markets = await fetchMarkets()
+```
+
+### Type Safety
+```
+✅ GOOD: Proper types
+function getMarket(id: string): Promise<Market> { }
+
+❌ BAD: Using 'any'
+function getMarket(id: any): Promise<any> { }
+```
+
+## Code Smells to Avoid
+
+### Long Functions
+```
+❌ BAD: Function > 50 lines
+✅ GOOD: Split into smaller functions
+```
+
+### Deep Nesting
+```
+❌ BAD: 5+ levels of nesting
+✅ GOOD: Early returns
+if (!user) return
+if (!user.isAdmin) return
+// Do something
+```
+
+### Magic Numbers
+```
+❌ BAD: Unexplained numbers
+if (retryCount > 3) { }
+
+✅ GOOD: Named constants
+const MAX_RETRIES = 3
+if (retryCount > MAX_RETRIES) { }
+```
+
+## Comments
+
+### When to Comment
+```
+✅ GOOD: Explain WHY, not WHAT
+// Use exponential backoff to avoid overwhelming the API
+const delay = Math.min(1000 * Math.pow(2, retryCount), 30000)
+
+❌ BAD: Stating the obvious
+// Increment counter by 1
+count++
+```
+
+## Testing Standards
+
+### AAA Pattern
+```
+test('calculates similarity correctly', () => {
+  // Arrange
+  const vector1 = [1, 0, 0]
+  const vector2 = [0, 1, 0]
+
+  // Act
+  const similarity = calculateCosineSimilarity(vector1, vector2)
+
+  // Assert
+  expect(similarity).toBe(0)
+})
+```
+
+### Test Naming
+```
+✅ GOOD: Descriptive
+test('returns empty array when no markets match query', () => { })
+test('throws error when API key is missing', () => { })
+
+❌ BAD: Vague
+test('works', () => { })
+test('test search', () => { })
+```
+
+## Quick Checklist
+
+Before completing any code:
+- [ ] Names are clear and descriptive
+- [ ] No deep nesting (use early returns)
+- [ ] No magic numbers (use constants)
+- [ ] Error handling is comprehensive
+- [ ] Async operations parallelize where possible
+- [ ] No `any` types
+- [ ] Functions are < 50 lines
+- [ ] Comments explain WHY, not WHAT
+
+## Why This Matters
+
+- Clear code enables rapid development
+- Maintainable code enables confident refactoring
+- Quality code reduces debugging time
+- Standards enable team collaboration