aether-colony 1.1.0

package/.aether/docs/disciplines/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/.aether/docs/disciplines/learning.md

@@ -0,0 +1,254 @@
+# Colony Learning Discipline
+
+## Overview
+
+The colony learns from every phase. Patterns observed during builds become **instincts** - atomic learned behaviors with confidence scoring that improve future work.
+
+## The Instinct Model
+
+An instinct is a small learned behavior:
+
+```yaml
+id: prefer-composition
+trigger: "when designing component architecture"
+confidence: 0.7
+domain: "architecture"
+source: "phase-3-observation"
+evidence:
+  - "Composition pattern succeeded in Phase 3"
+  - "User approved component structure"
+action: "Use composition over inheritance for component reuse"
+```
+
+**Properties:**
+- **Atomic** — one trigger, one action
+- **Confidence-weighted** — 0.3 = tentative, 0.9 = near certain
+- **Domain-tagged** — architecture, testing, code-style, debugging, workflow
+- **Evidence-backed** — tracks what observations created it
+
+## Confidence Scoring
+
+| Score | Meaning | Behavior |
+|-------|---------|----------|
+| 0.3 | Tentative | Suggested but not enforced |
+| 0.5 | Moderate | Applied when relevant |
+| 0.7 | Strong | Auto-applied in matching contexts |
+| 0.9 | Near-certain | Core colony behavior |
+
+**Confidence increases when:**
+- Pattern is repeatedly observed across phases
+- Pattern leads to successful outcomes
+- No corrections or rework needed
+
+**Confidence decreases when:**
+- Pattern leads to errors or rework
+- User provides negative feedback
+- Contradicting evidence appears
+
+## Pattern Detection
+
+During each phase, observe for:
+
+### 1. Success Patterns
+What worked well:
+- Approaches that completed without issues
+- Code structures that passed all tests
+- Workflows that were efficient
+
+### 2. Error Resolutions
+What was learned from debugging:
+- Root causes discovered
+- Fixes that worked
+- Architectural insights
+
+### 3. User Corrections
+What the user redirected:
+- Feedback via `/ant:feedback`
+- Redirects via `/ant:redirect`
+- Explicit corrections
+
+### 4. Tool Preferences
+What tools/patterns were effective:
+- Testing approaches that caught bugs
+- File organization that worked
+- Command sequences that succeeded
+
+## Instinct Structure
+
+Store in `memory.instincts`:
+
+```json
+{
+  "instincts": [
+    {
+      "id": "instinct_<timestamp>",
+      "trigger": "when X",
+      "action": "do Y",
+      "confidence": 0.5,
+      "domain": "testing",
+      "source": "phase-2",
+      "evidence": ["observation 1", "observation 2"],
+      "created_at": "<ISO-8601>",
+      "last_applied": null,
+      "applications": 0,
+      "successes": 0
+    }
+  ]
+}
+```
+
+## Instinct Lifecycle
+
+```
+Observation
+    │
+    ▼
+┌─────────────────────────────┐
+│     Pattern Detected        │
+│   (success/error/feedback)  │
+└─────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────┐
+│     Instinct Created        │
+│   (confidence: 0.3-0.5)     │
+└─────────────────────────────┘
+    │
+    │ Applied in future phases
+    ▼
+┌─────────────────────────────┐
+│   Confidence Adjusted       │
+│   (+0.1 success, -0.1 fail) │
+└─────────────────────────────┘
+    │
+    │ Reaches 0.9
+    ▼
+┌─────────────────────────────┐
+│     Core Behavior           │
+│   (always applied)          │
+└─────────────────────────────┘
+```
+
+## Extracting Instincts
+
+After each phase, the Prime Worker should identify:
+
+1. **What patterns led to success?**
+   - Approach taken
+   - Tools used effectively
+   - Code structures that worked
+
+2. **What was learned from errors?**
+   - Root causes found
+   - Fixes that worked
+   - What to avoid
+
+3. **What feedback was received?**
+   - User corrections
+   - Focus areas emphasized
+   - Patterns to avoid
+
+Format for extraction:
+
+```json
+"patterns_observed": [
+  {
+    "type": "success",
+    "trigger": "when implementing API endpoints",
+    "action": "use repository pattern with dependency injection",
+    "evidence": "All endpoint tests passed first try"
+  },
+  {
+    "type": "error_resolution",
+    "trigger": "when debugging async code",
+    "action": "check for missing await statements first",
+    "evidence": "Root cause was missing await in 3 cases"
+  },
+  {
+    "type": "user_feedback",
+    "trigger": "when structuring components",
+    "action": "prefer smaller, focused components",
+    "evidence": "User feedback: 'keep components small'"
+  }
+]
+```
+
+## Applying Instincts
+
+When starting a new phase, workers should:
+
+1. **Check relevant instincts** for the task domain
+2. **Apply high-confidence instincts** (≥0.7) automatically
+3. **Consider moderate instincts** (0.5-0.7) as suggestions
+4. **Log applications** for confidence tracking
+
+Format in worker prompt:
+
+```
+--- COLONY INSTINCTS ---
+Relevant learned patterns for this phase:
+
+[0.9] testing: Always run tests before claiming completion
+[0.7] architecture: Use composition over inheritance
+[0.5] code-style: Prefer functional patterns (tentative)
+```
+
+## Reporting Learned Patterns
+
+Prime Worker output should include:
+
+```json
+"learning": {
+  "patterns_observed": [
+    {
+      "type": "success|error_resolution|user_feedback",
+      "trigger": "when X",
+      "action": "do Y",
+      "evidence": "observation"
+    }
+  ],
+  "instincts_applied": ["instinct_id_1", "instinct_id_2"],
+  "instinct_outcomes": [
+    {"id": "instinct_id_1", "success": true},
+    {"id": "instinct_id_2", "success": false}
+  ]
+}
+```
+
+## Colony Memory Evolution
+
+Over time, instincts with high confidence become colony-wide behaviors:
+
+| Threshold | Evolution |
+|-----------|-----------|
+| 0.9+ with 5+ applications | Core behavior - always applied |
+| 3+ related instincts | Cluster into skill document |
+| Domain-specific cluster | Specialist worker enhancement |
+
+## Integration Points
+
+### /ant:build
+- Workers receive relevant instincts in prompt
+- Workers report patterns observed
+- Workers log instinct applications
+
+### /ant:continue
+- Extract patterns from build results
+- Create/update instincts
+- Adjust confidence based on outcomes
+
+### /ant:status
+- Show learned instincts with confidence
+- Show application statistics
+- Show recent pattern discoveries
+
+### /ant:feedback
+- Creates user_feedback instinct
+- High initial confidence (0.7)
+- Immediate application to current work
+
+## Privacy
+
+- Instincts stay local in `.aether/data/COLONY_STATE.json`
+- Only patterns extracted, not raw code
+- Export capability for sharing (future)

package/.aether/docs/disciplines/tdd.md

@@ -0,0 +1,257 @@
+# Test-Driven Development Discipline
+
+## The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+If you didn't watch the test fail, you don't know if it tests the right thing.
+
+Write code before the test? Delete it. Start over. No exceptions.
+
+## When to Use
+
+**Always:**
+- New features
+- Bug fixes
+- Refactoring
+- Behavior changes
+
+**The only exceptions (must be explicit):**
+- Throwaway prototypes (will be deleted)
+- Generated/config code
+- User explicitly opts out
+
+Thinking "skip TDD just this once"? Stop. That's rationalization.
+
+## Red-Green-Refactor Cycle
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                                                             │
+│   RED ────────► VERIFY RED ────────► GREEN                  │
+│   Write         (must fail           Write minimal          │
+│   failing       correctly)           code to pass           │
+│   test                                    │                 │
+│                                           ▼                 │
+│                                      VERIFY GREEN           │
+│                                      (must pass,            │
+│                                       all green)            │
+│                                           │                 │
+│   ◄───────────── REFACTOR ◄───────────────┘                 │
+│   Next test      Clean up                                   │
+│                  (stay green)                               │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### RED - Write Failing Test
+
+Write ONE minimal test showing desired behavior.
+
+```typescript
+// GOOD: Clear name, tests real behavior, one thing
+test('rejects empty email with error message', async () => {
+  const result = await submitForm({ email: '' });
+  expect(result.error).toBe('Email required');
+});
+
+// BAD: Vague name, tests mock not code
+test('validation works', async () => {
+  const mock = jest.fn();
+  // ...
+});
+```
+
+**Requirements:**
+- One behavior per test
+- Clear descriptive name
+- Real code (mocks only if unavoidable)
+
+### VERIFY RED - Watch It Fail (MANDATORY)
+
+```bash
+npm test path/to/test.test.ts
+```
+
+Confirm:
+- Test **fails** (not errors)
+- Failure message is expected
+- Fails because feature missing (not typos)
+
+**Test passes immediately?** You're testing existing behavior. Fix test.
+
+**Test errors?** Fix error, re-run until it fails correctly.
+
+### GREEN - Minimal Code
+
+Write **simplest** code to pass the test.
+
+```typescript
+// GOOD: Just enough to pass
+function validateEmail(email: string): string | null {
+  if (!email?.trim()) return 'Email required';
+  return null;
+}
+
+// BAD: Over-engineered (YAGNI)
+function validateEmail(
+  email: string,
+  options?: { customMessage?: string; allowEmpty?: boolean }
+): ValidationResult { /* ... */ }
+```
+
+Don't add features beyond the test. Don't refactor other code. Don't "improve."
+
+### VERIFY GREEN - Watch It Pass (MANDATORY)
+
+```bash
+npm test path/to/test.test.ts
+```
+
+Confirm:
+- Test passes
+- Other tests still pass
+- Output pristine (no errors, warnings)
+
+**Test fails?** Fix code, not test.
+**Other tests fail?** Fix now.
+
+### REFACTOR - Clean Up
+
+Only after green:
+- Remove duplication
+- Improve names
+- Extract helpers
+
+**Keep tests green. Don't add behavior.**
+
+### REPEAT
+
+Next failing test for next behavior.
+
+## Test Types
+
+### Unit Tests
+- Individual functions
+- Component logic
+- Pure functions
+- < 50ms each
+
+### Integration Tests
+- API endpoints
+- Database operations
+- Service interactions
+
+### E2E Tests
+- Critical user flows
+- Complete workflows
+- Browser automation
+
+## Coverage Requirements
+
+- Minimum 80% coverage target
+- All edge cases covered
+- Error scenarios tested
+- Boundary conditions verified
+
+Verify with:
+```bash
+npm run test:coverage
+```
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests passing immediately prove nothing. |
+| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
+| "Deleting X hours is wasteful" | Sunk cost fallacy. Unverified code is debt. |
+| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
+| "TDD will slow me down" | TDD faster than debugging. |
+| "Keep as reference" | You'll adapt it. That's testing after. Delete. |
+
+## Red Flags - STOP and Start Over
+
+If you catch yourself:
+- Writing code before test
+- Test passes immediately (didn't fail first)
+- Can't explain why test failed
+- Rationalizing "just this once"
+- "I already manually tested it"
+- "Keep as reference"
+- "This is different because..."
+
+**ALL mean: Delete code. Start over with TDD.**
+
+## Testing Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|--------------|---------|-----|
+| Testing implementation | Breaks on refactor | Test behavior/output |
+| Brittle selectors | `.css-class-xyz` | `[data-testid="x"]` |
+| Test interdependence | Tests depend on order | Each test sets up own data |
+| Mock everything | Tests mock, not code | Real code, inject deps |
+| One giant test | Can't isolate failure | One behavior per test |
+
+## TDD Report Format
+
+When reporting TDD work:
+
+```
+🧪 TDD Report
+=============
+
+Feature: {what was implemented}
+
+Cycle 1:
+  RED: test('rejects empty email')
+  Verified: ✓ Failed with "undefined is not 'Email required'"
+  GREEN: Added email validation
+  Verified: ✓ Passes
+
+Cycle 2:
+  RED: test('rejects invalid format')
+  Verified: ✓ Failed with expected message
+  GREEN: Added regex check
+  Verified: ✓ Passes
+
+Coverage: 87% (target: 80%)
+All tests: 47/47 passing
+```
+
+## Bug Fix with TDD
+
+1. Write failing test reproducing bug
+2. Verify it fails (proves bug exists)
+3. Fix bug
+4. Verify test passes
+5. Test now prevents regression
+
+**Never fix bugs without a test.**
+
+## Integration with Debugging
+
+When debugging reveals root cause:
+1. Write test that would have caught it
+2. Verify test fails
+3. Apply fix
+4. Verify test passes
+
+This ensures the bug never returns.
+
+## Verification Checklist
+
+Before marking work complete:
+
+- [ ] Every new function has a test
+- [ ] Watched each test fail before implementing
+- [ ] Each test failed for expected reason
+- [ ] Wrote minimal code to pass
+- [ ] All tests pass
+- [ ] Coverage meets threshold
+- [ ] No skipped/disabled tests
+
+Can't check all boxes? You skipped TDD. Start over.