claude-mycelium 2.0.0

package/docs/SNAPSHOT.md

@@ -0,0 +1,376 @@
+# Claude-Mycelium v2: Current Snapshot
+
+**Date**: 2026-01-30 (Updated after Phase 1)
+**Status**: Signal & Gradient System Complete (40% Complete)
+**Phase Completed**: Phase 0 + Phase 1 ✅
+**Next Phase**: Phase 2 - Agent Execution System
+
+---
+
+## 🎯 What This Document Is
+
+This is a **point-in-time walkthrough** of the codebase as it exists right now:
+- What files exist and what they contain
+- What works and what doesn't
+- What you can run today
+- What's missing
+
+Think of this as a guided tour of the current state. For history, see the ADRs. For future plans, see ROADMAP.md.
+
+---
+
+## 📊 Quick Stats
+
+- **Total Files**: 25 files (production + tests)
+- **Lines of Code**: ~4,500 lines production, ~2,500 lines tests
+- **Tests**: 155 passing tests across 9 test suites
+- **Test Coverage**: ~90% for implemented modules (core/, utils/)
+- **Implementation Status**: Foundation + Signals + Gradient complete
+
+---
+
+## 📂 Directory Structure (What Exists Now)
+
+```
+claude-mycelium/
+├── docs/                           ✅ Complete
+│   ├── specs/                      ✅ Moved from root
+│   │   ├── initial-spec.md         ✅ Full system spec (2096 lines)
+│   │   └── second-spec.md          ✅ Implementation details (2690 lines)
+│   ├── adrs/                       ✅ 5 ADRs documented
+│   │   ├── ADR-001-signal-computation.md
+│   │   ├── ADR-002-inhibitor-signals.md
+│   │   ├── ADR-003-llm-integration.md
+│   │   ├── ADR-004-process-architecture.md
+│   │   └── ADR-005-testing-strategy.md
+│   ├── IMPLEMENTATION-STATUS.md    ✅ Progress tracking
+│   ├── ROADMAP.md                  ✅ 8-phase implementation plan
+│   ├── SNAPSHOT.md                 ✅ This file
+│   ├── PHASE-0-COMPLETE.md         ✅ Foundation completion report
+│   └── PHASE-1-COMPLETE.md         ✅ Signal/gradient completion report
+│
+├── src/                            🟢 40% Complete
+│   ├── types/                      ✅ Complete (100%)
+│   │   └── index.ts                ✅ 267 lines - All core types
+│   │
+│   ├── utils/                      ✅ Complete (100%)
+│   │   ├── index.ts                ✅ Centralized exports
+│   │   ├── file-utils.ts           ✅ 112 lines - File I/O, LOC counting
+│   │   ├── config.ts               ✅ 95 lines - Config + spawn tracking
+│   │   ├── logger.ts               ✅ 89 lines - Structured logging
+│   │   ├── error-provider.ts       ✅ 127 lines - Error data provider
+│   │   └── ci-provider.ts          ✅ 132 lines - npm test/lint
+│   │
+│   ├── core/                       🟢 Partial (60% complete)
+│   │   ├── signals/                ✅ Complete (100%)
+│   │   │   ├── index.ts            ✅ Signal exports
+│   │   │   ├── complexity.ts       ✅ 200 lines - AST cyclomatic complexity
+│   │   │   ├── churn.ts            ✅ 240 lines - Git commit frequency
+│   │   │   ├── centrality.ts       ✅ 326 lines - Import graph analysis
+│   │   │   ├── debt.ts             ✅ 150 lines - ESLint errors/warnings
+│   │   │   └── errors.ts           ✅ 94 lines - Runtime error tracking
+│   │   ├── gradient.ts             ✅ 280 lines - Gradient calculation
+│   │   └── mode-selector.ts        ✅ 220 lines - Mode selection logic
+│   │
+│   ├── coordination/               🟢 Partial (30% complete)
+│   │   ├── index.ts                ✅ Coordination exports
+│   │   └── gradient-cache.ts       ✅ 180 lines - 5-min caching
+│   │   # Missing: file-locks.ts, process-manager.ts (Phase 3)
+│   │
+│   ├── agent/                      ❌ Empty (Phase 2)
+│   ├── cli/                        ❌ Empty (Phase 6)
+│   ├── task/                       ❌ Empty (Phase 5)
+│   ├── trace/                      ❌ Empty (Phase 2)
+│   ├── quarantine/                 ❌ Empty (Phase 4)
+│   ├── cost/                       ❌ Empty (Phase 2)
+│   └── gc/                         ❌ Empty (Phase 7)
+│
+├── tests/                          🟢 155 tests passing
+│   ├── utils/                      ✅ Complete
+│   │   └── file-utils.test.ts      ✅ 18 tests
+│   ├── core/
+│   │   ├── signals/                ✅ Complete
+│   │   │   ├── complexity.test.ts  ✅ 12 tests
+│   │   │   ├── churn.test.ts       ✅ 15 tests
+│   │   │   ├── centrality.test.ts  ✅ 30 tests
+│   │   │   ├── debt.test.ts        ✅ 14 tests
+│   │   │   └── errors.test.ts      ✅ 13 tests
+│   │   ├── gradient.test.ts        ✅ 14 tests
+│   │   └── mode-selector.test.ts   ✅ 36 tests
+│   └── coordination/
+│       └── gradient-cache.test.ts  ✅ 21 tests
+│
+├── .agent-meta/                    ✅ Initialized
+│   ├── locks/                      ✅ Ready for file locks
+│   └── (runtime directories created as needed)
+│
+├── package.json                    ✅ Complete (all deps correct)
+├── tsconfig.json                   ✅ Complete
+├── vitest.config.ts                ✅ Complete (75% coverage target)
+└── .gitignore                      ✅ Complete
+```
+
+---
+
+## 🎯 What Works Right Now
+
+### You Can Run These Commands
+
+```bash
+# Run all 155 tests
+npm test
+
+# Check test coverage
+npm run test:coverage
+
+# Build TypeScript
+npm run build
+
+# Calculate gradient for a file
+node -e "
+const { calculateGradient } = require('./dist/core/gradient.js');
+calculateGradient('./src/core/gradient.ts').then(g => {
+  console.log('File:', g.file);
+  console.log('Gradient Score:', g.score.toFixed(3));
+  console.log('Dominant Signal:', g.dominantSignal.name);
+  console.log('Signals:', {
+    complexity: g.signals.complexity.toFixed(3),
+    churn: g.signals.churn.toFixed(3),
+    error_rate: g.signals.error_rate.toFixed(3),
+    debt: g.signals.debt.toFixed(3),
+    centrality: g.signals.centrality.toFixed(3)
+  });
+});
+"
+
+# Check mode selection
+node -e "
+const { calculateGradient, selectModeFromGradient } = require('./dist/core/gradient.js');
+calculateGradient('./src/core/signals/complexity.ts').then(g => {
+  const mode = selectModeFromGradient(g);
+  console.log('Recommended Mode:', mode);
+});
+"
+```
+
+### Working Features
+
+1. **All 5 Signals**
+   - ✅ Complexity (AST-based cyclomatic complexity)
+   - ✅ Churn (git log analysis with 30-day window)
+   - ✅ Centrality (import graph with fan-in/fan-out)
+   - ✅ Debt (ESLint errors/warnings)
+   - ✅ Error Rate (file-based error provider)
+
+2. **Gradient Calculation**
+   - ✅ Weighted combination of all signals
+   - ✅ Impact multiplier based on centrality
+   - ✅ Formula: `baseScore * impactMultiplier - efficiencyPenalty`
+   - ✅ Batch processing for multiple files
+
+3. **Caching System**
+   - ✅ 5-minute TTL for computed gradients
+   - ✅ Automatic expiration
+   - ✅ Manual invalidation
+   - ✅ Cache statistics
+
+4. **Mode Selection**
+   - ✅ 5 modes implemented (error_reducer, complexity_reducer, debt_payer, stabilizer, explorer)
+   - ✅ Automatic selection based on dominant signal
+   - ✅ Mode-specific instructions for agents
+   - ✅ Multi-mode suggestions
+
+5. **Utilities**
+   - ✅ File operations (read, write, LOC counting)
+   - ✅ Configuration management
+   - ✅ Structured logging
+   - ✅ Error tracking
+   - ✅ CI integration (npm test/lint)
+
+---
+
+## ❌ What's Missing (By Phase)
+
+### Phase 2: Agent Execution (Next)
+- ❌ Anthropic API client
+- ❌ LLM streaming
+- ❌ Mode-specific prompts
+- ❌ Agent executor main loop
+- ❌ Change applier
+- ❌ Trace event system
+
+### Phase 3: Concurrency & Safety
+- ❌ File locks
+- ❌ Process spawning
+- ❌ Max concurrent agents
+- ❌ Resource cleanup
+
+### Phase 4: Learning System
+- ❌ Inhibitors
+- ❌ Quarantine
+- ❌ Explorer mode logic
+- ❌ Efficiency tracking
+
+### Phase 5: Task Management
+- ❌ Task queue
+- ❌ Task selection
+- ❌ Priority ordering
+
+### Phase 6: CLI Interface
+- ❌ commander CLI
+- ❌ `grow` command
+- ❌ `gradients` command
+- ❌ `watch` daemon
+
+### Phase 7: Garbage Collection
+- ❌ Trace cleanup
+- ❌ Lock cleanup
+- ❌ Inhibitor decay
+
+### Phase 8: Testing & Polish
+- ❌ Integration tests
+- ❌ E2E tests
+- ❌ Documentation
+- ❌ Examples
+
+---
+
+## 🔍 Key Implementation Details
+
+### Signal Computation
+
+Each signal returns a normalized score (0.0 - 1.0):
+
+```typescript
+interface SignalResult {
+  // Raw metrics
+  [metric: string]: number;
+
+  // Normalized score (0.0 - 1.0)
+  normalized: number;
+}
+```
+
+**Normalization Strategies:**
+- **Complexity**: `(cyclomatic/LOC) / 0.5`, capped at 1.0
+- **Churn**: `commits_to_file / max(commits_to_any_file)`
+- **Centrality**: `(fanIn/maxFanIn)*0.67 + (fanOut/maxFanOut)*0.33`
+- **Debt**: `(errors*3 + warnings) / LOC / 0.5`, capped at 1.0
+- **Error Rate**: `(errors / LOC) / 0.1`, capped at 1.0
+
+### Gradient Formula
+
+```typescript
+// Weights from initial-spec §2
+const baseScore = (
+  complexity * 0.25 +
+  churn * 0.15 +
+  error_rate * 0.35 +
+  debt * 0.25
+);
+
+// Centrality boosts central files
+const impactMultiplier = 0.5 + (centrality * 0.5);  // 0.5-1.0
+
+// Efficiency penalty (Phase 2)
+const efficiencyPenalty = recentEfficiency !== null
+  ? Math.max(0, 0.3 - recentEfficiency)
+  : 0;
+
+const gradient = Math.max(0, baseScore * impactMultiplier - efficiencyPenalty);
+```
+
+### Mode Selection
+
+```typescript
+// Threshold: signals must exceed 0.3 to be "dominant"
+const DOMINANCE_THRESHOLD = 0.3;
+
+// Mode mapping
+const modeMap = {
+  'error_rate': 'error_reducer',    // Fix bugs
+  'complexity': 'complexity_reducer', // Simplify
+  'debt': 'debt_payer',              // Fix lint
+  'churn': 'stabilizer'              // Add tests
+};
+
+// Default to debt_payer if nothing dominant
+return mode || 'debt_payer';
+```
+
+---
+
+## 🧪 Test Status
+
+### All Tests Passing ✅
+
+```
+ Test Files  9 passed (9)
+      Tests  155 passed (155)
+   Duration  13.16s
+```
+
+### Coverage by Module
+
+| Module | Tests | Files | Coverage |
+|--------|-------|-------|----------|
+| utils/ | 18 | 1 | ~95% |
+| signals/ | 84 | 5 | ~90% |
+| gradient | 14 | 1 | ~95% |
+| mode-selector | 36 | 1 | ~95% |
+| gradient-cache | 21 | 1 | ~95% |
+| **Total** | **155** | **9** | **~92%** |
+
+---
+
+## 🚧 Known Issues
+
+### None! ✅
+
+Phase 0 and Phase 1 are complete with no known issues.
+
+---
+
+## 📈 Progress Tracking
+
+### Overall Completion: 40%
+
+| Phase | Status | Files | Tests | Notes |
+|-------|--------|-------|-------|-------|
+| Phase 0: Foundation | ✅ Complete | 6/6 | 18/18 | Dependencies, types, utils |
+| Phase 1: Signals | ✅ Complete | 9/9 | 137/137 | 5 signals + gradient + cache + mode |
+| Phase 2: Agent Execution | ⏳ Next | 0/7 | 0/~50 | LLM, prompts, executor |
+| Phase 3: Concurrency | ⏳ Pending | 0/3 | 0/~30 | Locks, spawning |
+| Phase 4: Learning | ⏳ Pending | 0/3 | 0/~40 | Inhibitors, quarantine |
+| Phase 5: Tasks | ⏳ Pending | 0/2 | 0/~20 | Queue, selection |
+| Phase 6: CLI | ⏳ Pending | 0/2 | 0/~15 | Commands, daemon |
+| Phase 7: GC | ⏳ Pending | 0/1 | 0/~10 | Cleanup |
+| Phase 8: Polish | ⏳ Pending | 0/? | 0/~20 | Integration tests, docs |
+
+### Files Implemented: 15/30+ (50% of core files)
+### Tests Passing: 155/~300 (52% of planned tests)
+
+---
+
+## 🎯 Next Steps
+
+Ready to start **Phase 2: Agent Execution System**
+
+**Implementation Strategy:**
+- Use 5-7 agent swarm for parallel implementation
+- 7 core files + test suites
+- Estimated: 2-3 days with swarm, 8-10 days sequential
+
+**Phase 2 Deliverables:**
+1. Anthropic API client with streaming
+2. 4 mode-specific prompts (fix, refactor, stabilizer, test)
+3. Agent executor main loop
+4. Change applier (safe code modifications)
+5. Trace event system (learning foundation)
+6. Cost tracking ($$ per agent run)
+7. Comprehensive test suite (~50 tests)
+
+---
+
+**Last Updated**: January 30, 2026 after Phase 1 completion
+**Next Update**: After Phase 2 completion

package/docs/adrs/ADR-001-signal-computation.md

@@ -0,0 +1,76 @@
+# ADR-001: Signal Computation Implementation
+
+## Status
+Accepted
+
+## Context
+The initial spec defined 5 signals (complexity, churn, error_rate, debt, centrality) but didn't specify HOW to compute them. We needed concrete implementations for:
+- AST parsing for cyclomatic complexity
+- Git history analysis for churn
+- Import graph extraction for centrality
+- ESLint integration for debt
+- Error provider mechanism
+
+## Decision
+
+### Complexity Signal
+- **Library**: `@typescript-eslint/typescript-estree` for TypeScript AST parsing
+- **Algorithm**: Manual cyclomatic complexity counting by walking AST and counting decision points (if, for, while, switch, catch, logical operators)
+- **Normalization**: `(cyclomatic / LOC) / 0.5` capped at 1.0 (heuristic: 0.5 complexity/LOC is very high)
+- **LOC counting**: Exclude blank lines and comments
+
+### Churn Signal
+- **Method**: Shell out to `git log --since="30 days" --name-only`
+- **No git library**: Simple exec for Phase 1, avoids dependency
+- **Caching**: 5-minute TTL cache to avoid repeated git calls
+- **Normalization**: commits_to_file / max(commits_to_any_file)
+
+### Import Graph (Centrality)
+- **Method**: Regex-based import extraction (fast, good enough)
+- **Pattern**: Matches `import ... from '...'`, `require('...')`, `import('...')`
+- **Resolution**: Try extensions `.ts`, `.tsx`, `.js`, `.jsx`, `/index.*`
+- **Fallback**: AST parsing for edge cases (future)
+
+### Debt Signal
+- **Method**: Run `npx eslint <file> --format json` as subprocess
+- **Formula**: `(errors × 3 + warnings) / LOC` per spec
+- **Normalization**: Divide by 0.5, cap at 1.0
+
+### Error Signal
+- **Phase 1**: File-based provider (`.agent-meta/_errors.json`)
+- **Population**: Manual, script hook, or external tool
+- **Phase 2+**: Sentry/Datadog integration (future)
+
+## Consequences
+
+### Positive
+- ✅ No heavy dependencies (escomplex, js-ast, etc.)
+- ✅ Fast: regex and git shell-out are quick
+- ✅ Extensible: Easy to add Sentry/Datadog later
+- ✅ Cross-platform: Works on any system with git
+
+### Negative
+- ⚠️ Regex may miss complex import patterns (dynamic imports)
+- ⚠️ Git must be available (fails gracefully if not)
+- ⚠️ ESLint must be configured (returns 0 if missing)
+- ⚠️ Error provider requires manual setup
+
+## Alternatives Considered
+
+### Complexity
+- **escomplex**: Rejected (abandoned, doesn't support TS well)
+- **SonarQube API**: Rejected (heavy, requires SonarQube server)
+
+### Churn
+- **nodegit/isomorphic-git**: Rejected (heavy dependencies, native compilation issues)
+- **simple-git**: Considered but shell-out is simpler
+
+### Import Graph
+- **typescript compiler API**: Rejected (slow, heavy)
+- **dependency-cruiser**: Rejected (overkill)
+
+## Implementation Notes
+- All signal calculations are in `src/core/signals/`
+- Each signal has its own file: `complexity.ts`, `churn.ts`, `debt.ts`, `errors.ts`, `centrality.ts`
+- Caching is used for expensive operations (git, import graph)
+- Graceful fallbacks when tools unavailable (git, eslint)

package/docs/adrs/ADR-002-inhibitor-signals.md

@@ -0,0 +1,108 @@
+# ADR-002: Inhibitor Signals (Learning from Failures)
+
+## Status
+Accepted
+
+## Context
+From RALPH research: Systems need "guardrails" to avoid repeating failed patterns. The initial spec had quarantine (file-level blocking), but lacked surgical, pattern-specific warnings.
+
+Inspired by mycelial inhibitors: chemical markers that repel growth from areas where nutrients were already depleted.
+
+## Decision
+
+### Concept
+**Inhibitor signals** are pattern-specific warnings emitted after failures. They:
+- Decay over time (30-60 day half-life)
+- Are included in agent prompts
+- Target specific file + mode + pattern combinations
+
+### When Inhibitors Are Emitted
+1. **CI Failed**: After test/lint failure
+2. **Regression**: When gradient increases (made things worse)
+3. **Loop Detected**: 3+ attempts, no progress (efficiency < 0.02 each)
+
+### Storage
+- **File**: `.agent-meta/_inhibitors.ndjson` (append-only)
+- **Schema**:
+```typescript
+interface Inhibitor {
+  id: string;
+  timestamp: string;
+  trigger: { file?: string; pattern?: string; mode?: Mode };
+  signal: string;  // Human-readable warning
+  origin: {
+    agent_id: string;
+    trace_id: string;
+    energy_wasted: number;  // Cost in USD
+    failure_type: 'ci_failed' | 'regression' | 'reverted' | 'loop_detected';
+  };
+  strength: number;  // 1.0 = fresh, decays toward 0
+  half_life_days: number;  // Default: 30
+}
+```
+
+### Decay Function
+```
+strength(t) = initial_strength × 0.5^(days / half_life)
+```
+
+Examples:
+- Day 0: 1.0
+- Day 30: 0.5 (one half-life)
+- Day 60: 0.25
+- Day 90: 0.125
+
+### Relevance Threshold
+- Inhibitors with strength < 0.2 are ignored
+- Inhibitors with strength < 0.05 are garbage collected
+
+### Agent Prompt Integration
+Relevant inhibitors (matching file/mode) are added to agent prompts:
+```
+## ⚠️ Inhibitor Signals
+- **removing null checks** [Strength: 85%]
+  CI failed: TypeError: Cannot read property 'x' of undefined
+  Failed: ci_failed by agent-abc, wasted $0.04
+```
+
+## Consequences
+
+### Positive
+- ✅ **Surgical avoidance**: Warns against specific patterns, not entire files
+- ✅ **Self-healing**: Decays naturally as code changes
+- ✅ **Cost-aware**: Tracks wasted money, prioritizes expensive failures
+- ✅ **Complements quarantine**: Different mechanisms for different severities
+
+### Negative
+- ⚠️ **Prompt bloat**: Too many inhibitors could exceed context window (mitigated by relevance filtering)
+- ⚠️ **Pattern extraction is heuristic**: CI output parsing is imperfect
+- ⚠️ **Requires storage**: Another file to manage
+
+## Comparison: Inhibitor vs Quarantine
+
+| Mechanism | Scope | Trigger | Reversibility | Purpose |
+|-----------|-------|---------|---------------|---------|
+| **Inhibitor** | file + mode + pattern | Single failure | Decays (30-60 days) | "Don't try X on Y" |
+| **Quarantine** | Entire file, all modes | 10 samples, no progress | Requires explorer success | "Stop all work on Y" |
+
+A file can have many inhibitors without being quarantined. Quarantine is full withdrawal; inhibitors are warnings.
+
+## Implementation
+
+### Files
+- `src/coordination/inhibitors.ts` - Emit, query, decay logic
+- Integration in `src/agent/executor.ts` - Check after each run
+- Integration in `src/agent/prompt-builder.ts` - Add to prompts
+- GC in `src/storage/gc.ts` - Remove decayed inhibitors
+
+### CLI Commands
+```bash
+npx claude-mycelium inhibitors list
+npx claude-mycelium inhibitors show <file>
+npx claude-mycelium inhibitors clear <id>
+```
+
+## Future Work
+- Machine learning to improve pattern extraction
+- Cluster similar inhibitors
+- Inhibitor strength boosting (multiple hits → stronger signal)