aether-colony 3.1.17 → 5.0.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/QUEEN.md

@@ -0,0 +1,84 @@
+# QUEEN.md — Colony Wisdom
+
+> Last evolved: 2026-02-15T13:08:15Z
+> Colonies contributed: 0
+> Wisdom version: 1.0.0
+
+---
+
+## 📜 Philosophies
+
+Core beliefs that guide all colony work. These are validated through repeated successful application across multiple colonies.
+
+- **colony-a** (2026-02-15T13:08:24Z): Test-driven development ensures quality
+
+---
+
+## 🧭 Patterns
+
+Validated approaches that consistently work. These represent discovered best practices that have proven themselves in the field.
+
+- **colony-b** (2026-02-15T13:08:28Z): Always validate inputs
+
+---
+
+## ⚠️ Redirects
+
+Anti-patterns to avoid. These represent approaches that have caused problems and should be redirected away from.
+
+- **colony-c** (2026-02-15T13:08:31Z): Never skip security checks
+
+---
+
+## 🔧 Stack Wisdom
+
+Technology-specific insights and constraints detected through codebase analysis.
+
+- **colony-d** (2026-02-15T13:08:36Z): Use jq for JSON in bash
+
+---
+
+## 🏛️ Decrees
+
+User-mandated rules that override other guidance. These represent explicit directives from the Queen.
+
+- **colony-e** (2026-02-15T13:08:40Z): All code must have tests
+
+---
+
+## 📊 Evolution Log
+
+Track how wisdom has evolved over time.
+
+| Date | Colony | Change | Details |
+|------|--------|--------|---------|
+| 2026-02-15T13:08:40Z | colony-e | promoted_decree | Added: All code must have tests... |
+| 2026-02-15T13:08:36Z | colony-d | promoted_stack | Added: Use jq for JSON in bash... |
+| 2026-02-15T13:08:31Z | colony-c | promoted_redirect | Added: Never skip security checks... |
+| 2026-02-15T13:08:28Z | colony-b | promoted_pattern | Added: Always validate inputs... |
+| 2026-02-15T13:08:24Z | colony-a | promoted_philosophy | Added: Test-driven development ensures quality... |
+| 2026-02-15T13:08:15Z | system | initialized | QUEEN.md created from template |
+
+---
+
+<!-- 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,
+    "total_redirects": 1,
+    "total_stack_entries": 1,
+    "total_decrees": 1
+  }
+}
+-->

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/{runtime → .aether/docs/disciplines}/DISCIPLINES.md

@@ -76,14 +76,14 @@ No workarounds. Fix issues and re-run.
 ```
 .aether/
 ├── workers.md               # Worker roles + honest execution model
-├── 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
-├── planning.md              # Bite-sized task planning
-├── DISCIPLINES.md           # This file
+├── 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