aether-colony 2.0.0

package/runtime/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

package/runtime/debugging.md

@@ -0,0 +1,207 @@
+# Systematic Debugging Discipline
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes. Symptom fixes are failure.
+
+## When to Use
+
+Use for ANY technical issue encountered during colony work:
+- Test failures
+- Build errors
+- Unexpected behavior
+- Performance problems
+- Integration issues
+
+**Use ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+
+## The Four Phases
+
+Complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - If not reproducible → gather more data, don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+
+4. **Gather Evidence in Multi-Component Systems**
+   ```
+   For EACH component boundary:
+     - Log what data enters component
+     - Log what data exits component
+     - Verify environment/config propagation
+
+   Run once to gather evidence showing WHERE it breaks
+   THEN analyze to identify failing component
+   ```
+
+5. **Trace Data Flow (Root Cause Tracing)**
+
+   When error is deep in call stack:
+   - Where does bad value originate?
+   - What called this with bad value?
+   - Keep tracing UP until you find the source
+   - Fix at source, not at symptom
+
+   ```
+   Symptom → Immediate cause → What called this? → Keep tracing → Original trigger → FIX HERE
+   ```
+
+### Phase 2: Pattern Analysis
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - Read reference implementation COMPLETELY
+   - Don't skim - understand fully
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+
+### Phase 3: Hypothesis and Testing
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify Before Continuing**
+   - Did it work? → Phase 4
+   - Didn't work? → Form NEW hypothesis
+   - DON'T add more fixes on top
+
+### Phase 4: Implementation
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - MUST have before fixing
+
+2. **Implement Single Fix**
+   - Address root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+   - Issue actually resolved?
+
+4. **If Fix Doesn't Work**
+   - Count: How many fixes have you tried?
+   - If < 3: Return to Phase 1, re-analyze
+   - **If ≥ 3: STOP - question the architecture**
+
+## The 3-Fix Rule
+
+**If 3+ fixes have failed:**
+
+Pattern indicating architectural problem:
+- Each fix reveals new problem in different place
+- Fixes require "massive refactoring"
+- Each fix creates new symptoms elsewhere
+
+**STOP and question fundamentals:**
+- Is this pattern fundamentally sound?
+- Should we refactor architecture vs. continue fixing symptoms?
+
+Report to parent/Queen with architectural concern before attempting more fixes.
+
+## Red Flags - STOP and Follow Process
+
+If you catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "One more fix attempt" (when already tried 2+)
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too |
+| "Emergency, no time for process" | Systematic is FASTER than thrashing |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause |
+
+## Quick Reference
+
+| Phase | Key Activities | Exit Criteria |
+|-------|---------------|---------------|
+| **1. Root Cause** | Read errors, reproduce, trace data flow | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | Identify differences |
+| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+
+## Debugging Report Format
+
+When reporting debugging work:
+
+```
+🔍 Debug Report
+===============
+
+Issue: {what broke}
+
+Phase 1 - Root Cause:
+  Error: {exact error message}
+  Reproduced: {yes/no, steps}
+  Trace: {call chain to source}
+  Root cause: {the actual source}
+
+Phase 2 - Pattern:
+  Working example: {reference found}
+  Key difference: {what differs}
+
+Phase 3 - Hypothesis:
+  Theory: {X causes Y because Z}
+  Test: {minimal change made}
+  Result: {confirmed/refuted}
+
+Phase 4 - Fix:
+  Change: {what was changed}
+  Test: {failing test created}
+  Verified: {tests pass, issue resolved}
+
+Fix count: {N}/3 max
+```
+
+## Real-World Impact
+
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common

package/runtime/docs/pheromones.md

@@ -0,0 +1,213 @@
+# Pheromone Signals -- User Guide
+
+Pheromones are how you communicate with the colony. Instead of micromanaging individual ants, you emit chemical signals that influence their behavior based on each caste's sensitivity. Signals decay over time, so the colony naturally returns to neutral behavior.
+
+## How Pheromones Work
+
+- **You emit** signals using `/ant:focus`, `/ant:redirect`, `/ant:feedback`
+- **The colony also emits** signals automatically after builds (FEEDBACK after every phase, REDIRECT when error patterns recur)
+- **Signals decay** exponentially -- a FOCUS signal at strength 0.7 with a 1-hour half-life will be at ~0.35 after an hour
+- **Each caste responds differently** -- builders are highly sensitive to FOCUS (0.9), while architects barely notice it (0.4)
+
+Run `/ant:status` at any time to see all active pheromones and their current strength.
+
+## FOCUS -- Guide Attention
+
+**Command:** `/ant:focus "<area>"`
+**Strength:** 0.7 | **Half-life:** 1 hour | **Decays to noise in:** ~3-4 hours
+
+**What it does:** Tells the colony "pay extra attention here." Workers with high FOCUS sensitivity will prioritize this area in their next task.
+
+**Highest sensitivity:** Builder (0.9), Scout (0.9), Watcher (0.8)
+**Lowest sensitivity:** Architect (0.4), Route-setter (0.5)
+
+### When to use FOCUS
+
+**Scenario 1: Steering the next build phase**
+You're about to run `/ant:build 3` and Phase 3 has tasks touching both the API layer and the database layer. You know the database schema is fragile and needs careful attention:
+
+```
+/ant:focus "database schema -- handle migrations carefully"
+/ant:build 3
+```
+
+The builder-ant (sensitivity 0.9) will receive an effective signal of 0.63, crossing the PRIORITIZE threshold (>0.5). It will weight database-related tasks with extra care and thoroughness.
+
+**Scenario 2: Post-build quality concern**
+The watcher scored Phase 2 at 6/10 and flagged auth middleware issues. Before continuing to Phase 3:
+
+```
+/ant:focus "auth middleware correctness"
+/ant:continue
+```
+
+The next phase's watcher (sensitivity 0.8) will scrutinize auth middleware more carefully during verification.
+
+**Scenario 3: Directing colonization**
+You're colonizing a new project and want the colonizer to pay special attention to the testing infrastructure:
+
+```
+/ant:focus "test framework and coverage gaps"
+/ant:colonize
+```
+
+The colonizer (sensitivity 0.7) will weight test infrastructure discovery higher in its analysis.
+
+### When NOT to use FOCUS
+
+- Don't stack 5+ FOCUS signals -- the colony can't prioritize everything (that's prioritizing nothing)
+- Don't FOCUS on things the colony already handles (like "write good code") -- be specific
+- Don't FOCUS after a phase completes if you're about to `/clear` context -- the signal persists in pheromones.json, but emit it fresh before the next build for strongest effect
+
+---
+
+## REDIRECT -- Warn Away
+
+**Command:** `/ant:redirect "<pattern to avoid>"`
+**Strength:** 0.9 | **Half-life:** 24 hours | **Decays to noise in:** ~3-4 days
+
+**What it does:** Acts as a hard constraint. Workers with high REDIRECT sensitivity will actively avoid the specified pattern. This is the strongest, longest-lasting signal.
+
+**Highest sensitivity:** Builder (0.9), Route-setter (0.8)
+**Lowest sensitivity:** Architect (0.3), Colonizer (0.3)
+
+### When to use REDIRECT
+
+**Scenario 1: Preventing a known bad approach**
+Your project uses Next.js Edge Runtime, and you know `jsonwebtoken` doesn't work there (CommonJS issues). Before the colony builds auth:
+
+```
+/ant:redirect "Don't use jsonwebtoken -- use jose library instead (Edge Runtime compatible)"
+/ant:build 2
+```
+
+The builder (sensitivity 0.9) receives effective signal 0.81 -- deep in PRIORITIZE territory. It will actively avoid jsonwebtoken and use jose instead.
+
+**Scenario 2: Steering away from a previous failure**
+Phase 1 tried to use synchronous file reads and caused performance issues (you saw this in the watcher report). Before Phase 2:
+
+```
+/ant:redirect "No synchronous file I/O -- use async fs/promises"
+```
+
+The route-setter (sensitivity 0.8) will exclude synchronous patterns from the task plan. The builder will avoid them in implementation.
+
+**Scenario 3: Architectural constraint**
+You want the colony to avoid global mutable state because the project might need server-side rendering:
+
+```
+/ant:redirect "No global mutable state -- use request-scoped context"
+```
+
+This signal persists for 24 hours (half-life), covering multiple build phases without re-emission.
+
+### When NOT to use REDIRECT
+
+- Don't REDIRECT for preferences -- use it for hard constraints ("will break" not "I don't like")
+- Don't REDIRECT on vague patterns ("don't write bad code") -- be specific about the approach to avoid and why
+- Don't use REDIRECT when FOCUS would suffice -- if you want more attention on testing, FOCUS on testing rather than REDIRECT away from skipping tests
+
+---
+
+## FEEDBACK -- Adjust Course
+
+**Command:** `/ant:feedback "<observation>"`
+**Strength:** 0.5 | **Half-life:** 6 hours | **Decays to noise in:** ~20 hours
+
+**What it does:** Provides gentle course correction. Unlike FOCUS (attention) or REDIRECT (avoidance), FEEDBACK adjusts the colony's approach based on your observations. The watcher is most sensitive to this signal.
+
+**Highest sensitivity:** Watcher (0.9), Builder (0.7), Route-setter (0.7)
+**Lowest sensitivity:** Architect (0.6), Colonizer (0.5), Scout (0.5)
+
+### When to use FEEDBACK
+
+**Scenario 1: Mid-project course correction**
+After building Phase 2, you review the output and notice the code is over-engineered -- too many abstractions for a simple feature:
+
+```
+/ant:feedback "Code is too abstract -- prefer simple, direct implementations over clever abstractions"
+```
+
+The builder (0.7) and watcher (0.9) both pick this up. The builder simplifies its approach in Phase 3. The watcher (effective signal 0.45 -- NOTE range) factors simplicity into its quality assessment.
+
+**Scenario 2: Positive reinforcement**
+Phase 3 produced clean, well-tested code. You want more of the same:
+
+```
+/ant:feedback "Great test coverage in Phase 3 -- maintain this level of testing"
+```
+
+The colony records this as a positive signal. The builder continues the pattern; the watcher validates against it.
+
+**Scenario 3: Quality emphasis shift**
+The watcher is scoring phases highly but you're noticing the code lacks error handling:
+
+```
+/ant:feedback "Need more error handling -- happy path works but edge cases are unhandled"
+```
+
+The watcher (sensitivity 0.9, effective 0.45) will increase scrutiny on error handling in its next verification pass.
+
+### When NOT to use FEEDBACK
+
+- Don't use FEEDBACK for hard constraints -- that's REDIRECT's job
+- Don't use FEEDBACK before the colony has produced anything -- it responds to observations, not predictions
+- Don't emit multiple conflicting FEEDBACK signals ("more abstraction" + "keep it simple") -- the colony can't resolve contradictions
+
+---
+
+## Auto-Emitted Pheromones
+
+The colony emits pheromones automatically during builds. You don't need to manage these:
+
+- **FEEDBACK after every phase:** build.md (Step 7b) emits a FEEDBACK pheromone summarizing what worked and what failed. Source: `auto:build`
+- **REDIRECT on error patterns:** If errors.json has recurring flagged patterns, build.md and continue.md auto-emit REDIRECT signals to steer future phases away from the problematic pattern. Source: `auto:build` or `auto:continue`
+- **FEEDBACK from global learnings:** When colonizing a new project, colonize.md injects relevant global learnings as FEEDBACK pheromones. Source: `global:inject`
+
+Auto-emitted signals have `"auto": true` in pheromones.json and are visible in `/ant:status`.
+
+---
+
+## Signal Combinations
+
+Pheromones combine. Each worker's spec defines combination effects:
+
+| Combination | Effect |
+|-------------|--------|
+| FOCUS + FEEDBACK | Workers concentrate on the focused area and adjust approach based on feedback |
+| FOCUS + REDIRECT | Workers prioritize the focused area while avoiding the redirected pattern |
+| FEEDBACK + REDIRECT | Workers adjust approach (feedback) and avoid specific patterns (redirect) |
+| All three | Full steering: attention (FOCUS), avoidance (REDIRECT), and adjustment (FEEDBACK) |
+
+**Effective signal formula:** `caste_sensitivity x current_strength`
+
+Thresholds:
+- **> 0.5 PRIORITIZE** -- worker restructures behavior around this signal
+- **0.3-0.5 NOTE** -- worker is aware, factors into decisions
+- **< 0.3 IGNORE** -- signal too weak to act on
+
+---
+
+## Quick Reference
+
+| Signal | Command | Strength | Half-life | Use for |
+|--------|---------|----------|-----------|---------|
+| FOCUS | `/ant:focus "<area>"` | 0.7 | 1 hour | "Pay attention to this" |
+| REDIRECT | `/ant:redirect "<avoid>"` | 0.9 | 24 hours | "Don't do this" |
+| FEEDBACK | `/ant:feedback "<note>"` | 0.5 | 6 hours | "Adjust based on this" |
+
+| | FOCUS | REDIRECT | FEEDBACK |
+|---|---|---|---|
+| Builder | 0.9 | 0.9 | 0.7 |
+| Scout | 0.9 | 0.4 | 0.5 |
+| Watcher | 0.8 | 0.5 | 0.9 |
+| Colonizer | 0.7 | 0.3 | 0.5 |
+| Route-setter | 0.5 | 0.8 | 0.7 |
+| Architect | 0.4 | 0.3 | 0.6 |
+
+**Rule of thumb:**
+- Before a build: FOCUS + REDIRECT to steer
+- After a build: FEEDBACK to adjust
+- For hard constraints: REDIRECT (strongest signal, longest decay)
+- For gentle nudges: FEEDBACK (moderate signal, medium decay)
+- For attention: FOCUS (moderate signal, short decay -- re-emit if needed)