aether-colony 3.1.4 → 3.1.15

package/CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to the Aether Colony project will be documented in this file
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.5] - 2026-02-15
+
+### Fixed
+- **Agent Type Correction** — Changed all occurrences of `subagent_type="general"` to `subagent_type="general-purpose"` across all command files. The error "Agent type 'general' not found" was occurring because the correct agent type name is `general-purpose`. Fixed in: build.md, plan.md, organize.md, and workers.md (both Claude and OpenCode versions, plus runtime copy). (`.claude/commands/ant/build.md`, `.claude/commands/ant/plan.md`, `.claude/commands/ant/organize.md`, `.opencode/commands/ant/build.md`, `.opencode/commands/ant/plan.md`, `.opencode/commands/ant/organize.md`, `.aether/workers.md`, `runtime/workers.md`)
+
 ## [3.1.4] - 2026-02-15
 
 ### Fixed
@@ -36,6 +41,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Session Freshness Detection System** — Global system to prevent stale session files from silently breaking Aether workflows. Implements `session-verify-fresh` and `session-clear` commands with support for 7 commands (survey, oracle, watch, swarm, init, seal, entomb). Features cross-platform timestamp detection (macOS/Linux), environment variable overrides for testing, and protected operations (init/seal/entomb never auto-clear). Backward compatibility maintained with `survey-verify-fresh` and `survey-clear` wrappers. Added comprehensive test suite (`tests/bash/test-session-freshness.sh`) and API documentation (`docs/session-freshness-api.md`). (`.aether/aether-utils.sh`, `tests/bash/test-session-freshness.sh`, `docs/session-freshness-api.md`)
+  - `/ant:colonize` — Added `--force-resurvey` flag, stale survey detection, and verification
+  - `/ant:oracle` — Added `--force` flag, stale session detection with user options
+  - `/ant:watch` — Added session timestamp capture and stale file handling
+  - `/ant:swarm` — Added auto-clear for stale findings with verification
+  - `/ant:init` — Added freshness check with protected state (no auto-clear)
+  - `/ant:seal` — Added incomplete archive detection and integrity verification
+  - `/ant:entomb` — Added incomplete chamber detection and integrity verification
+
+### Fixed
+- **Architecture Cleanup: Source of Truth Flipped** — Complete review and cleanup of the flipped source-of-truth architecture. `.aether/` is now the source of truth for system files, with `runtime/` auto-populated by `bin/sync-to-runtime.sh` during npm install. Fixed 6 stale documentation files, updated 5 planning files, expanded allowlist from 20 to 36 files, handled 4 orphan files, and verified zero drift between directories. (`.aether/recover.sh`, `.aether/RECOVERY-PLAN.md`, `.planning/codebase/STRUCTURE.md`, `.planning/codebase/ARCHITECTURE.md`, `.planning/codebase/CONVENTIONS.md`, `TO-DOS.md`, `bin/sync-to-runtime.sh`, `bin/lib/update-transaction.js`)
+
+### Changed
+- **Phase 4: UX Improvements to Lay-Eggs** — Enhanced lay-eggs.md with visual lifecycle diagrams (🟢 ACTIVE COLONY → 🏺 SEAL/ENTOMB → 🥚 LAY EGGS) in error messages to clarify workflow progression. Updated success output to explicitly distinguish between sealing vs laying eggs for new projects, preserving wisdom across colony lifecycles. (`.claude/commands/ant/lay-eggs.md`)
+
 ### Fixed
 - **Phase 2: Fix Blocker Severity and Auto-Resolve Logic** — Made auto_resolve_on conditional by flag source: chaos-sourced blockers require manual resolution (auto_resolve_on: null), verification blockers auto-resolve on build pass. Reordered continue.md Flags Gate to run auto-resolve before blocker count check. Added advisory blocker warning (Step 1.5) to build.md so builders see active blockers before execution. (`.aether/aether-utils.sh`, `runtime/aether-utils.sh`, `.claude/commands/ant/continue.md`, `.opencode/commands/ant/continue.md`, `.claude/commands/ant/build.md`, `.opencode/commands/ant/build.md`)
 - **Phase 1: Fix Chaos Ant Duplicate Flagging** — Eliminated duplicate flag creation during build-rebuild cycles by removing redundant chaos flagging from build.md Step 5.5 (Step 5.4.2 already handles it), injected existing flag titles into Chaos Ant spawn prompt to prevent re-investigating known issues, and added flag persistence to standalone /ant:chaos for critical/high findings using source 'chaos-standalone'. (`.claude/commands/ant/build.md`, `.opencode/commands/ant/build.md`, `.claude/commands/ant/chaos.md`, `.opencode/commands/ant/chaos.md`)

package/README.md

@@ -18,7 +18,7 @@
   [![npm version](https://img.shields.io/npm/v/aether-colony.svg)](https://www.npmjs.com/package/aether-colony)
   [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-  **v1.1.0** — Production ready with model routing
+  **v3.1.14** — Production ready with model routing
 </div>
 
 ---
@@ -43,9 +43,9 @@ Aether brings **ant colony intelligence** to Claude Code. Instead of one agent d
    ├── 🔍 Scouts — research docs
    ├── 🗺️ Colonizers — explore codebases
    ├── 📋 Route-setters — plan phases
-   ├── 🏛️ Architects — extract patterns
+   ├── 🏗️ Architects — extract patterns
    ├── 🏺 Archaeologists — excavate git history
-   ├── 🔮 Oracles — deep research
+   ├── 🔮 Oracles — deep research (RALF pattern)
    └── 🎲 Chaos Ants — resilience testing
 ```
 
@@ -59,6 +59,8 @@ When a Builder hits something complex, it spawns a Scout to research. When code
 - **6-Phase Verification** — Build, types, lint, tests, security, diff before advancing
 - **Colony Memory** — Learnings and instincts persist across sessions
 - **Pause/Resume** — Full state serialization for context breaks
+- **Oracle Deep Research** — 50+ iteration autonomous research loop (RALF pattern)
+- **Multi-Agent Surveys** — 4 parallel scouts for codebase analysis
 
 ---
 
@@ -96,74 +98,101 @@ That's it. The colony takes over from there.
 
 ---
 
-## Commands
+## Complete Command Reference (33 Commands)
 
-Aether has **33 slash commands** organized into categories.
+### 🌱 Core Lifecycle Commands
 
-### Core Lifecycle
+| Command | Emoji | Description |
+|---------|-------|-------------|
+| `/ant:init "goal"` | 🌱 | Initialize colony with mission |
+| `/ant:plan` | 📝 | Generate phased roadmap (50-iteration research loop) |
+| `/ant:build N` | 🔨 | Execute phase N with worker waves |
+| `/ant:continue` | ➡️ | 6-phase verification, then advance to next phase |
+| `/ant:pause-colony` | 💾 | Save state for context break |
+| `/ant:resume-colony` | ▶️ | Restore from pause |
+| `/ant:lay-eggs "new goal"` | 🥚 | Start fresh colony (preserves instincts) |
+| `/ant:seal` | 🏺 | Complete and archive colony |
+| `/ant:entomb` | ⚰️ | Create chamber from completed colony |
 
-| Command | Purpose |
-|---------|---------|
-| `/ant:init "goal"` | Initialize colony with mission |
-| `/ant:plan` | Generate phased roadmap (50-iteration research loop) |
-| `/ant:build N` | Execute phase N with worker waves |
-| `/ant:continue` | 6-phase verification, then advance |
-| `/ant:status` | Colony overview |
-| `/ant:pause-colony` | Save state for context break |
-| `/ant:resume-colony` | Restore from pause |
-
-### Pheromone Signals
-
-| Command | Purpose |
-|---------|---------|
-| `/ant:focus "area"` | Guide colony attention |
-| `/ant:redirect "pattern"` | Warn away from approaches |
-| `/ant:feedback "msg"` | Teach preferences |
-
-### Power Commands
-
-| Command | Purpose |
-|---------|---------|
-| `/ant:swarm "problem"` | Deploy 4 parallel scouts for stubborn bugs |
-| `/ant:council` | Clarify intent via multi-choice questions |
-| `/ant:oracle` | Deep research with 50+ iterations |
-
-### Research & Analysis
-
-| Command | Purpose |
-|---------|---------|
-| `/ant:colonize` | Analyze existing codebase |
-| `/ant:archaeology <path>` | Excavate git history |
-| `/ant:chaos <target>` | Resilience testing |
-| `/ant:organize` | Codebase hygiene report |
-| `/ant:dream` | Philosophical codebase wanderer |
-| `/ant:interpret` | Ground dreams in reality |
-
-### Issue Tracking
-
-| Command | Purpose |
-|---------|---------|
-| `/ant:flag "issue"` | Create blocker/issue/note |
-| `/ant:flags` | List and manage flags |
-
-### Visibility
-
-| Command | Purpose |
-|---------|---------|
-| `/ant:watch` | Live tmux monitoring |
-| `/ant:phase N` | View phase details |
-| `/ant:history` | Recent colony activity |
-| `/ant:help` | Full command reference |
-
-### System
+**Core Lifecycle Flow:**
+```
+/ant:init → /ant:plan → /ant:build 1 → /ant:continue → /ant:build 2 → ... → /ant:seal → /ant:entomb
+```
 
-| Command | Purpose |
-|---------|---------|
-| `/ant:update` | Sync system files from hub |
-| `/ant:migrate-state` | Upgrade old state format |
-| `/ant:verify-castes` | Check model routing |
-| `/ant:seal` | Complete and archive colony |
-| `/ant:entomb` | Create chamber from completed colony |
+### 📊 Research & Analysis Commands
+
+| Command | Emoji | Description |
+|---------|-------|-------------|
+| `/ant:colonize` | 🗺️ | **Multi-agent territory survey** — 4 parallel scouts analyze your codebase and produce: `STRUCTURE.md`, `INTEGRATIONS.md`, `CONVENTIONS.md`, `ARCHITECTURE.md`, `CONCERNS.md` |
+| `/ant:archaeology <path>` | 🏺 | Excavate git history for any file/directory — traces why code exists, surfaces tribal knowledge, identifies "don't touch" areas |
+| `/ant:oracle ["topic"]` | 🔮 | **Deep research with RALF pattern** — 50+ iteration autonomous research loop. Use `stop` or `status` as arguments |
+| `/ant:chaos <target>` | 🎲 | Resilience testing — probes edge cases, boundary conditions, finds cracks before they break |
+| `/ant:swarm ["problem"]` | 🔥 | Deploy 4 parallel scouts for stubborn bugs OR view real-time swarm display |
+| `/ant:dream` | 💭 | The Dreamer — philosophical codebase wanderer that observes and imagines |
+| `/ant:interpret` | 🔍 | Ground dreams in reality — validates observations against actual code |
+| `/ant:organize` | 🧹 | Codebase hygiene report — scans for stale files, dead code, orphaned configs |
+
+**Research Command Details:**
+
+#### `/ant:colonize` — Territory Survey
+Dispatches 4 parallel Scout agents to analyze your codebase:
+- **Scout 1**: Maps directory structure, identifies entry points, dependencies
+- **Scout 2**: Maps integrations (databases, APIs, third-party services)
+- **Scout 3**: Documents conventions (naming, patterns, architecture decisions)
+- **Scout 4**: Identifies concerns (tech debt, risks, areas needing attention)
+
+Produces 5 documentation files in `.aether/docs/`.
+
+#### `/ant:oracle` — Deep Research (RALF Pattern)
+The Oracle runs autonomously in a separate process using the Recursive Agent Loop Framework:
+1. Configure research topic via interactive wizard
+2. Oracle iterates 50+ times, accumulating knowledge
+3. Each iteration reads previous progress, researches gaps
+4. Produces comprehensive findings in `.aether/oracle/discoveries/`
+
+Non-invasive: Never touches colony state, only writes to `.aether/oracle/`.
+
+### 🧭 Planning & Coordination Commands
+
+| Command | Emoji | Description |
+|---------|-------|-------------|
+| `/ant:council` | 🏛️ | Clarify intent via multi-choice questions |
+| `/ant:focus "area"` | 🔦 | Emit FOCUS signal — guide colony attention |
+| `/ant:redirect "pattern"` | ⚠️ | Emit REDIRECT signal — warn away from approaches |
+| `/ant:feedback "msg"` | 💬 | Emit FEEDBACK signal — teach preferences |
+
+**Pheromone Signals:**
+- **FOCUS** (normal priority): "Pay attention here"
+- **REDIRECT** (high priority): "Don't do this" (hard constraint)
+- **FEEDBACK** (low priority): "Adjust based on this"
+
+### 📋 Visibility & Status Commands
+
+| Command | Emoji | Description |
+|---------|-------|-------------|
+| `/ant:status` | 📈 | Colony overview — current phase, progress, active workers |
+| `/ant:phase N` | 📝 | View phase details — tasks, status, assignments |
+| `/ant:history` | 📜 | Recent colony activity log |
+| `/ant:maturity` | 👑 | View colony maturity journey with ASCII art anthill |
+| `/ant:watch` | 👁️ | Set up tmux session to watch ants working in real-time |
+| `/ant:tunnels [ch1] [ch2]` | 🕳️ | Explore tunnels — browse archived colonies, compare chambers |
+| `/ant:flags` | 🚩 | List and manage flags (blockers, issues, notes) |
+| `/ant:help` | 📖 | Full command reference |
+
+### 🚩 Issue Tracking Commands
+
+| Command | Emoji | Description |
+|---------|-------|-------------|
+| `/ant:flag "issue"` | 🚩 | Create blocker/issue/note |
+| `/ant:flags` | 📋 | List and manage flags |
+
+### ⚙️ System Commands
+
+| Command | Emoji | Description |
+|---------|-------|-------------|
+| `/ant:update` | 🔄 | Sync system files from global hub |
+| `/ant:verify-castes` | ✓ | Check caste model assignments and system status |
+| `/ant:migrate-state` | 🚚 | One-time state migration from v1 to v2.0 format |
 
 ---
 
@@ -175,20 +204,36 @@ The `aether` CLI provides additional utilities:
 # View version and status
 aether version
 
+# Update all registered repos
+aether update --all
+aether update --all --force  # Force even with dirty repos
+
 # Manage model routing
 aether caste-models list
 aether caste-models set builder=kimi-k2.5
+aether caste-models reset builder
 
-# Checkpoints
+# Checkpoints (safe snapshots)
 aether checkpoint create "before refactor"
 aether checkpoint list
 aether checkpoint restore <id>
+aether checkpoint verify <id>
 
 # View telemetry
 aether telemetry
+aether telemetry model kimi-k2.5
+aether telemetry performance
 
 # Sync state with planning docs
 aether sync-state
+
+# Context
+aether context        # Show auto-loaded context including nestmates
+aether nestmates      # List sibling colonies
+aether spawn-tree     # Display worker spawn tree
+
+# Initialize in current repo
+aether init --goal "My project"
 ```
 
 ---
@@ -226,18 +271,18 @@ Set `LITELLM_AUTH_TOKEN` environment variable for custom auth.
 
 ## The Castes
 
-| Caste | Role | Model |
-|-------|------|-------|
-| 👑 **Queen** | Orchestrates, spawns workers, synthesizes | glm-5 |
-| 🔨 **Builder** | Writes code, TDD-first | kimi-k2.5 |
-| 👁️ **Watcher** | Tests, validates, quality gates | kimi-k2.5 |
-| 🔍 **Scout** | Researches docs, finds answers | minimax-2.5 |
-| 🗺️ **Colonizer** | Explores codebases, maps structure | minimax-2.5 |
-| 🏛️ **Architect** | Synthesizes patterns, coordinates docs | glm-5 |
-| 📋 **Route-Setter** | Plans phases, breaks down goals | kimi-k2.5 |
-| 🏺 **Archaeologist** | Excavates git history | glm-5 |
-| 🔮 **Oracle** | Deep research, architecture analysis | minimax-2.5 |
-| 🎲 **Chaos** | Resilience testing, adversarial probing | kimi-k2.5 |
+| Caste | Emoji | Role | Model |
+|-------|-------|------|-------|
+| 👑 **Queen** | — | Orchestrates, spawns workers, synthesizes | glm-5 |
+| 🔨 **Builder** | 🛠️ | Writes code, TDD-first | kimi-k2.5 |
+| 👁️ **Watcher** | 👀 | Tests, validates, quality gates | kimi-k2.5 |
+| 🔍 **Scout** | 🗺️ | Researches docs, finds answers | minimax-2.5 |
+| 🗺️ **Colonizer** | 📊 | Explores codebases, maps structure | minimax-2.5 |
+| 🏗️ **Architect** | 🏛️ | Synthesizes patterns, coordinates docs | glm-5 |
+| 📋 **Route-Setter** | 🧭 | Plans phases, breaks down goals | kimi-k2.5 |
+| 🏺 **Archaeologist** | 📜 | Excavates git history | glm-5 |
+| 🔮 **Oracle** | 🔮 | Deep research, architecture analysis | minimax-2.5 |
+| 🎲 **Chaos** | 🎲 | Resilience testing, adversarial probing | kimi-k2.5 |
 
 ---
 
@@ -328,8 +373,33 @@ Detected automatically via `milestone-detect` utility.
     ├── aether-utils.sh           # Utility layer (50+ subcommands)
     ├── model-profiles.yaml       # Caste-to-model routing
     ├── verification-loop.md      # 6-phase verification reference
+    ├── QUEEN_ANT_ARCHITECTURE.md # Complete system architecture
+    ├── coding-standards.md       # Coding standards reference
+    ├── debugging.md              # Debugging discipline
+    ├── tdd.md                    # TDD discipline
+    │
+    ├── docs/                     # Documentation
+    │   ├── known-issues.md       # Known bugs and workarounds
+    │   ├── implementation-learnings.md  # Workflow patterns
+    │   ├── codebase-review.md    # Command inventory
+    │   ├── planning-discipline.md # Planning guidelines
+    │   └── ...
     │
-    ├── data/                     # Per-project state
+    ├── utils/                    # Utility scripts
+    │   ├── atomic-write.sh
+    │   ├── colorize-log.sh
+    │   ├── file-lock.sh
+    │   ├── spawn-tree.sh
+    │   └── ...
+    │
+    ├── oracle/                   # Oracle research infrastructure
+    │   ├── oracle.sh             # RALF loop script
+    │   ├── oracle.md             # Oracle agent prompt
+    │   ├── research.json         # Active research config
+    │   ├── progress.md           # Research progress
+    │   └── discoveries/          # Research findings
+    │
+    ├── data/                     # Per-project state (NEVER synced)
     │   ├── COLONY_STATE.json     # Goal, plan, memory, instincts
     │   ├── flags.json            # Blockers, issues, notes
     │   ├── constraints.json      # Focus areas and redirects
@@ -338,7 +408,8 @@ Detected automatically via `milestone-detect` utility.
     │   ├── telemetry.json        # Model performance data
     │   └── completion-report.md  # End-of-project summary
     │
-    ├── dreams/                   # Dream session files
+    ├── dreams/                   # Dream session files (NEVER synced)
+    ├── checkpoints/              # Update rollback data (NEVER synced)
     └── chambers/                 # Entombed (archived) colonies
 
 bin/                              # CLI
@@ -354,7 +425,9 @@ bin/                              # CLI
 
 ---
 
-## Typical Workflow
+## Typical Workflows
+
+### Starting a New Project
 
 ```
 1. /ant:init "Build feature X"     # Set the goal
@@ -367,6 +440,26 @@ bin/                              # CLI
 8. /ant:seal                        # Complete and archive
 ```
 
+### Deep Research Workflow
+
+```
+/ant:oracle "research topic"    # Configure and launch Oracle
+# Oracle runs autonomously for 50+ iterations
+/ant:oracle status              # Check progress
+/ant:oracle stop                # Stop if needed
+# Read findings in .aether/oracle/discoveries/
+```
+
+### Codebase Analysis Workflow
+
+```
+/ant:colonize                   # 4 scouts survey territory
+# Read generated docs in .aether/docs/
+/ant:archaeology src/legacy/    # Excavate git history
+/ant:organize                   # Hygiene report
+/ant:chaos "auth module"        # Resilience test
+```
+
 ### Between Sessions
 
 ```bash
@@ -390,7 +483,7 @@ bin/                              # CLI
 
 ## OpenCode Agents
 
-Aether includes 4 specialized OpenCode agents:
+Aether includes specialized OpenCode agents:
 
 | Agent | Purpose | Temperature |
 |-------|---------|-------------|
@@ -424,15 +517,30 @@ Aether includes 4 specialized OpenCode agents:
 └─────────────────────────────────────────────────────────────┘
 ```
 
+### Three-Tier Distribution
+
+```
+Aether Repo (.aether/)  →  Hub (~/.aether/)  →  Target Repos (.aether/)
+         │                        │                        │
+         │   npm install -g .     │    aether update       │
+         └───────────────────────→┴───────────────────────→┘
+                              (excluding user data)
+```
+
+**User data directories are NEVER synced:** `data/`, `dreams/`, `checkpoints/`, `locks/`, `temp/`
+
 ---
 
 ## Safety Features
 
-- **File Locking** — Prevents concurrent modification of state
+- **File Locking** — Prevents concurrent modification of state with configurable stale lock detection
 - **Atomic Writes** — Temp file + rename pattern
 - **Update Transactions** — Two-phase commit with rollback
+- **State Validation** — Schema validation before any state modifications
+- **Event Pruning** — Automatic cleanup prevents unbounded event history
 - **Git Checkpoints** — Automatic commits before phases
 - **Ant Graveyards** — Failed files marked for future caution
+- **Checkpoint System** — Safe snapshots before updates with `aether checkpoint`
 
 ---
 
@@ -459,11 +567,16 @@ npm install -g aether-colony
 # Verify install
 aether version
 ls ~/.claude/commands/ant/
+ls ~/.aether/  # Check hub structure
 
 # Verify runtime (from inside any repo)
 ls .aether/
 
-# Update
+# Update system files in all registered repos
+aether update --all
+aether update --all --force  # Force even with dirty repos
+
+# Update npm package
 npm update -g aether-colony
 
 # Uninstall (preserves project state)