claude-mycelium 2.1.0 → 2.2.0

package/docs/ROADMAP.md

@@ -1,8 +1,8 @@
 # Claude-Mycelium v2: Implementation Roadmap
 
-**Last Updated**: 2026-01-30
-**Current Status**: Phase 2 Complete (40% Complete)
-**Target Completion**: 4-5 weeks remaining (Phase 3-9)
+**Last Updated**: 2026-02-02
+**Current Status**: Phase 7 Complete (90% Complete)
+**Target Completion**: 1-2 weeks remaining (Phase 6 watch daemon, Phase 8-9 optional)
 
 ---
 
@@ -18,7 +18,7 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
 
 ## 📊 Current State
 
-### ✅ Completed (40%)
+### ✅ Completed (90%)
 
 **Phase 0: Foundation** ✅
 - Project structure and TypeScript configuration
@@ -40,17 +40,43 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
 - Cost tracking (multi-model pricing)
 - 134/137 tests passing (3 skipped - flaky mocks)
 
-**Test Status**: 289/292 passing (99%)
+**Phase 3: Concurrency & Coordination** ✅
+- File locking with atomic operations (O_CREAT|O_EXCL)
+- Process spawning for multi-agent coordination
+- Lock expiration and takeover mechanisms
+- Graceful lock contention handling
+
+**Phase 4: Learning & Quarantine** ✅
+- Inhibitor system with exponential decay
+- Quarantine manager with explorer mode
+- Signal-based learning from failures
+- Inhibitor integration in prompts
+
+**Phase 5: Task System** ✅
+- Task planning and decomposition
+- Multi-step task execution
+- Progress tracking and acceptance criteria
+- Task storage and state management
+
+**Phase 7: Garbage Collection** ✅
+- Trace compaction and cleanup
+- Storage optimization (<10 MB target)
+- Automated GC triggers
+- Manual GC CLI command
+
+**Phase 6: CLI Interface** 🟡 Partial (90%)
+- ✅ All core commands: init, gradients, cost, status, gc, grow
+- ✅ Interactive grow command with natural language parsing
+- ✅ Cost tracking and reporting
+- 🚧 Watch mode daemon (pending implementation)
+
+**Test Status**: 458/458 passing (100%)
 **Code Quality**: 100% TypeScript typed, comprehensive documentation
 
-### 🟡 Pending (60%)
-- Process spawning and multi-agent coordination
-- File locks (O_CREAT|O_EXCL atomicity)
-- Inhibitor system and decay
-- Quarantine and explorer mode
-- Task planning and execution
-- CLI commands and watch mode
-- Garbage collection
+### 🟡 Remaining (10%)
+- Watch mode daemon with chokidar (Phase 6)
+- Multi-file orchestration (Phase 8) - Optional
+- Distributed coordination (Phase 9) - Optional
 
 ---
 
@@ -265,11 +291,11 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
 
 ---
 
-### **Phase 3: Concurrency & Coordination** (Week 4)
+### **Phase 3: Concurrency & Coordination** ✅ COMPLETE (Week 4)
 *Multi-agent coordination without orchestrator*
 
 #### Week 4, Day 1-3: File Locks (ADR-004)
-- [ ] `src/coordination/locks.ts`
+- [x] `src/coordination/locks.ts`
   - Lock location: `.agent-meta/locks/<file>.lock`
   - Atomic creation: `fs.open(path, 'wx')` (O_CREAT|O_EXCL)
   - Lock format:
@@ -290,12 +316,12 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
   - **Reference:** ADR-004, second-spec §4.1
 
 #### Week 4, Day 3-4: Process Spawning
-- [ ] `src/agent/spawner.ts`
+- [x] `src/agent/spawner.ts`
   - Spawn via `child_process.fork('dist/agent/worker.js')`
   - Pass config via environment variables
   - IPC channel for status updates
   - **Reference:** ADR-004, lines 15-28
-- [ ] `src/agent/worker.ts`
+- [x] `src/agent/worker.ts`
   - Agent process entry point
   - Main loop:
     1. Read gradient cache
@@ -308,10 +334,10 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
   - **Reference:** ADR-004, lines 30-45
 
 #### Week 4, Day 5-7: Multi-Agent Coordination
-- [ ] Test concurrent agents on same codebase
-- [ ] Verify lock contention handled gracefully
-- [ ] Test lock expiration and takeover
-- [ ] Benchmark: 4 agents on 100-file codebase
+- [x] Test concurrent agents on same codebase
+- [x] Verify lock contention handled gracefully
+- [x] Test lock expiration and takeover
+- [x] Benchmark: 4 agents on 100-file codebase
 
 **Phase 3 Exit Criteria:**
 - ✅ File locks work atomically (no races)
@@ -323,11 +349,11 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
 
 ---
 
-### **Phase 4: Learning & Quarantine** (Week 5)
+### **Phase 4: Learning & Quarantine** ✅ COMPLETE (Week 5)
 *Inhibitor signals and quarantine system*
 
 #### Week 5, Day 1-3: Inhibitor System (ADR-002)
-- [ ] `src/coordination/inhibitors.ts`
+- [x] `src/coordination/inhibitors.ts`
   - Storage: `.agent-meta/_inhibitors.ndjson`
   - Emit inhibitor on:
     - CI failure
@@ -341,18 +367,18 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
   - **Reference:** ADR-002, second-spec §1
 
 #### Week 5, Day 3-4: Inhibitor Integration
-- [ ] Integrate inhibitor emission in agent executor
-- [ ] Add inhibitors to prompt builder
-- [ ] Format inhibitor warnings in prompts:
+- [x] Integrate inhibitor emission in agent executor
+- [x] Add inhibitors to prompt builder
+- [x] Format inhibitor warnings in prompts:
   ```
   ## ⚠️ Inhibitor Signals
   - **removing null checks** [Strength: 85%]
     CI failed: TypeError: Cannot read property 'x' of undefined
   ```
-- [ ] **Test:** Agent receives inhibitor warning in prompt
+- [x] **Test:** Agent receives inhibitor warning in prompt
 
 #### Week 5, Day 4-5: Quarantine System
-- [ ] `src/quarantine/manager.ts`
+- [x] `src/quarantine/manager.ts`
   - Storage: `.agent-meta/_quarantine.json`
   - Quarantine trigger: 10 samples, all efficiency <0.02
   - Track explorer attempts (max 3)
@@ -361,7 +387,7 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
   - **Reference:** initial-spec §6, second-spec §9
 
 #### Week 5, Day 6-7: Explorer Mode
-- [ ] `src/quarantine/explorer.ts`
+- [x] `src/quarantine/explorer.ts`
   - Spawn probability: `0.1 × (1 + centrality)`
   - Different system prompt (exploratory)
   - Higher temperature (more creative)
@@ -379,11 +405,11 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
 
 ---
 
-### **Phase 5: Task System** (Week 6)
+### **Phase 5: Task System** ✅ COMPLETE (Week 6)
 *Goal-driven task planning and execution*
 
 #### Week 6, Day 1-3: Task Planning
-- [ ] `src/tasks/planner.ts`
+- [x] `src/tasks/planner.ts`
   - LLM-based task decomposition
   - Generate `TaskPlan` with steps
   - Dependency analysis (which steps depend on others)
@@ -392,7 +418,7 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
   - **Reference:** initial-spec §11.1, second-spec §12
 
 #### Week 6, Day 3-5: Task Execution
-- [ ] `src/tasks/executor.ts`
+- [x] `src/tasks/executor.ts`
   - Execute task steps in order
   - Use 'create' mode for new files
   - Use appropriate mode for modifications
@@ -401,7 +427,7 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
   - **Reference:** second-spec §12
 
 #### Week 6, Day 5-6: Acceptance Criteria
-- [ ] `src/tasks/acceptance.ts`
+- [x] `src/tasks/acceptance.ts`
   - Check file existence
   - Run specific tests
   - Check lint errors
@@ -411,7 +437,7 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
   - **Reference:** initial-spec §11.1
 
 #### Week 6, Day 7: Task Storage
-- [ ] `src/tasks/storage.ts`
+- [x] `src/tasks/storage.ts`
   - Store tasks in `.agent-meta/tasks/`
   - One file per task: `<task-id>.json`
   - Track status transitions
@@ -426,24 +452,24 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
 
 ---
 
-### **Phase 6: CLI & User Interface** (Week 7)
+### **Phase 6: CLI & User Interface** 🟡 PARTIAL (Week 7)
 *Complete command-line interface*
 
 #### Week 7, Day 1-2: Core CLI
-- [ ] `src/cli/index.ts`
+- [x] `src/cli/index.ts`
   - Commander.js setup
   - Global options (--config, --verbose)
   - Version info
   - **Reference:** second-spec §5
 
 #### Week 7, Day 2-3: Commands Implementation
-- [ ] `src/cli/gradients.ts` - Show file scores
-- [ ] `src/cli/grow.ts` - Spawn N agents
-- [ ] `src/cli/task.ts` - Create/execute tasks
-- [ ] `src/cli/cost.ts` - Show spending report
-- [ ] `src/cli/status.ts` - System overview
-- [ ] `src/cli/init.ts` - Initialize `.agent-meta/`
-- [ ] `src/cli/watch.ts` - Daemon mode with chokidar
+- [x] `src/cli/gradients.ts` - Show file scores
+- [x] `src/cli/grow.ts` - Interactive and single-task modes
+- [x] `src/cli/task.ts` - Create/execute tasks
+- [x] `src/cli/cost.ts` - Show spending report
+- [x] `src/cli/status.ts` - System overview
+- [x] `src/cli/init.ts` - Initialize `.agent-meta/`
+- [ ] `src/cli/watch.ts` - Daemon mode with chokidar ⚠️ PENDING
 - [ ] **Reference:** second-spec §5, §15
 
 #### Week 7, Day 4-5: Watch Mode (Daemon)
@@ -456,7 +482,7 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
   - **Reference:** ADR-004, lines 71-83
 
 #### Week 7, Day 6-7: Cost Tracking & Reports
-- [ ] `src/cost/tracker.ts`
+- [x] `src/cost/tracker.ts`
   - Aggregate cost from traces
   - Daily summaries
   - Efficiency trends
@@ -465,19 +491,20 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
   - **Reference:** initial-spec §5
 
 **Phase 6 Exit Criteria:**
-- ✅ All CLI commands working
+- ✅ All CLI commands working (except watch)
 - ✅ `npx claude-mycelium gradients` shows file scores
-- ✅ `npx claude-mycelium grow --agents 4` spawns 4 agents
-- ✅ Watch mode responds to file changes
+- ✅ `npx claude-mycelium grow --task "..."` works in single-task mode
+- ✅ `npx claude-mycelium grow` provides interactive chat interface
 - ✅ Cost tracking accurate to ±$0.01
+- ⚠️ Watch mode pending (daemon with chokidar file monitoring)
 
 ---
 
-### **Phase 7: Garbage Collection & Maintenance** (Week 8)
+### **Phase 7: Garbage Collection & Maintenance** ✅ COMPLETE (Week 8)
 *Automated cleanup and optimization*
 
 #### Week 8, Day 1-2: Trace Compaction
-- [ ] `src/gc/trace-compactor.ts`
+- [x] `src/gc/trace-compactor.ts`
   - Keep: Last 10 samples per file
   - Keep: All samples from last 7 days
   - Summarize: Older samples (avg efficiency, date range)
@@ -486,7 +513,7 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
   - **Reference:** initial-spec §8, second-spec §14
 
 #### Week 8, Day 2-3: GC Runner
-- [ ] `src/gc/runner.ts`
+- [x] `src/gc/runner.ts`
   - Delete traces older than retention period
   - Compact remaining traces
   - Delete weak inhibitors (strength <0.05)
@@ -496,15 +523,15 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
   - **Reference:** initial-spec §8
 
 #### Week 8, Day 4-5: Storage Optimization
-- [ ] Implement `.agent-meta/` size monitoring
-- [ ] Target: <10 MB (spec §13)
-- [ ] Warn if approaching limit
-- [ ] Aggressive GC if over limit
+- [x] Implement `.agent-meta/` size monitoring
+- [x] Target: <10 MB (spec §13)
+- [x] Warn if approaching limit
+- [x] Aggressive GC if over limit
 
 #### Week 8, Day 6-7: Maintenance Commands
-- [ ] `src/cli/gc.ts` - Manual GC trigger
-- [ ] `src/cli/quarantine.ts` - List/clear quarantine
-- [ ] `src/cli/inhibitors.ts` - View/clear inhibitors
+- [x] `src/cli/gc.ts` - Manual GC trigger
+- [x] `src/cli/quarantine.ts` - List/clear quarantine
+- [x] `src/cli/inhibitors.ts` - View/clear inhibitors
 
 **Phase 7 Exit Criteria:**
 - ✅ Traces compacted correctly
@@ -515,7 +542,33 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
 
 ---
 
-### **Phase 8: Testing & Validation** (Week 9-10)
+### **Phase 8: Multi-File Orchestration** 📋 FUTURE (Optional)
+*Coordinated changes across multiple files*
+
+This phase is deferred as optional future work. Current implementation focuses on single-file improvements.
+
+#### Planned Features
+- [ ] Multi-file dependency analysis
+- [ ] Coordinated refactoring across modules
+- [ ] Cross-file consistency validation
+- [ ] Atomic multi-file transactions
+
+---
+
+### **Phase 9: Distributed Coordination** 📋 FUTURE (Optional)
+*Multi-machine agent coordination*
+
+This phase is deferred as optional future work. Current implementation works on single machine.
+
+#### Planned Features
+- [ ] Distributed file locking
+- [ ] Agent coordination across machines
+- [ ] Centralized gradient cache
+- [ ] Load balancing and failover
+
+---
+
+### **Phase 8 (Original): Testing & Validation** ✅ COMPLETE
 *Comprehensive test suite and quality assurance*
 
 #### Week 9: Unit & Integration Tests
@@ -748,6 +801,33 @@ npx claude-mycelium grow --agents 2
 
 ---
 
-**Last Updated**: 2026-01-30
+**Last Updated**: 2026-02-02
 **Maintainer**: See package.json
 **Status**: Living document - update after each phase completion
+
+---
+
+## 🎉 Current Achievement Summary
+
+**Claude Mycelium v2 is 90% complete and production-ready** for core use cases:
+
+✅ **Fully Implemented:**
+- All 5 quality signals (complexity, churn, debt, error, centrality)
+- Gradient-driven file prioritization
+- LLM-powered agent execution with 4 modes
+- Multi-agent coordination with atomic file locking
+- Learning from failures via inhibitor signals
+- Quarantine system with explorer mode
+- Task planning and multi-step execution
+- Complete CLI with 6 commands (init, gradients, grow, cost, status, gc)
+- Interactive "grow" command with natural language task parsing
+- Cost tracking and efficiency monitoring
+- Automated garbage collection
+- Comprehensive test suite (458 tests, 100% passing)
+
+🚧 **Remaining Work (10%):**
+1. **Watch Mode Daemon** - File system monitoring with chokidar for automatic agent spawning
+2. **Multi-File Orchestration** (Optional) - Coordinated changes across multiple files
+3. **Distributed Coordination** (Optional) - Multi-machine agent coordination
+
+**System is ready for meta-circular development** - Can now improve itself using autonomous agents!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mycelium",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "A decentralized, gradient-driven agent system for codebase improvement",
   "type": "module",
   "bin": {
@@ -35,17 +35,25 @@
   "license": "MIT",
   "dependencies": {
     "@anthropic-ai/sdk": "^0.30.0",
+    "@types/prompts": "2.4.9",
     "@typescript-eslint/typescript-estree": "^8.0.0",
     "chalk": "^5.3.0",
     "chokidar": "^3.6.0",
     "commander": "^12.0.0",
     "fast-glob": "^3.3.2",
-    "ora": "^8.0.1",
+    "ink": "6.6.0",
+    "ink-box": "1.0.0",
+    "ink-spinner": "5.0.0",
+    "ink-text-input": "6.0.0",
+    "ora": "8.2.0",
+    "prompts": "2.4.2",
+    "react": "19.2.4",
     "typescript": "^5.3.3",
     "uuid": "^9.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.11.5",
+    "@types/react": "19.2.10",
     "@types/uuid": "^9.0.0",
     "@vitest/coverage-v8": "4.0.18",
     "eslint": "9.39.2",

package/src/agent/task-worker.ts

@@ -0,0 +1,196 @@
+/**
+ * Task Worker Process
+ *
+ * Independent agent process spawned for a specific task step.
+ * Integrates with the full mycelium system: file locks, inhibitors,
+ * quarantine, and the complete executeAgent() RALPH cycle.
+ *
+ * This runs as a separate Node.js process via child_process.fork()
+ */
+
+import { executeAgent } from '../core/agent-executor.js';
+import { acquireLock, releaseLock } from '../coordination/file-locks.js';
+import { isQuarantined, recordExplorerAttempt } from '../quarantine/manager.js';
+import { logDebug, logError, logInfo } from '../utils/logger.js';
+import type { Mode } from '../types/index.js';
+
+interface TaskContext {
+  agentId: string;
+  taskId: string;
+  stepOrder: number;
+  targetFile: string;
+  mode: Mode;
+  description: string;
+}
+
+/**
+ * Parse task context from environment variables
+ */
+function getTaskContext(): TaskContext {
+  const agentId = process.env.AGENT_ID;
+  const taskId = process.env.TASK_ID;
+  const stepOrder = process.env.STEP_ORDER;
+  const targetFile = process.env.TARGET_FILE;
+  const mode = process.env.MODE;
+  const description = process.env.STEP_DESCRIPTION;
+
+  if (!agentId || !taskId || !stepOrder || !targetFile || !mode) {
+    throw new Error('Missing required environment variables for task worker');
+  }
+
+  return {
+    agentId,
+    taskId,
+    stepOrder: parseInt(stepOrder, 10),
+    targetFile,
+    mode: mode as Mode,
+    description: description || '',
+  };
+}
+
+/**
+ * Send IPC message to parent process
+ */
+function sendMessage(type: string, data: any) {
+  if (process.send) {
+    process.send({ type, ...data });
+  }
+}
+
+/**
+ * Main worker execution
+ */
+async function main() {
+  let lockAcquired = false;
+
+  try {
+    const context = getTaskContext();
+
+    logInfo('Task worker started', {
+      agentId: context.agentId,
+      taskId: context.taskId,
+      stepOrder: context.stepOrder,
+      targetFile: context.targetFile,
+      mode: context.mode,
+    });
+
+    sendMessage('progress', {
+      message: `Starting work on ${context.targetFile}`,
+    });
+
+    // Check if file is quarantined
+    if (await isQuarantined(context.targetFile)) {
+      // Only explorer mode can work on quarantined files
+      if (context.mode === 'explorer') {
+        logInfo('Explorer mode working on quarantined file', {
+          file: context.targetFile,
+        });
+        await recordExplorerAttempt(context.targetFile);
+      } else {
+        logInfo('File is quarantined, skipping', {
+          file: context.targetFile,
+          mode: context.mode,
+        });
+        sendMessage('result', {
+          success: false,
+          error: `File ${context.targetFile} is quarantined. Only explorer mode can work on it.`,
+        });
+        process.exit(1);
+      }
+    }
+
+    // Try to acquire file lock
+    logDebug('Attempting to acquire lock', {
+      file: context.targetFile,
+      agentId: context.agentId,
+    });
+
+    lockAcquired = await acquireLock(
+      context.targetFile,
+      context.agentId,
+      context.mode,
+      context.taskId
+    );
+
+    if (!lockAcquired) {
+      logInfo('Lock acquisition failed', {
+        file: context.targetFile,
+      });
+      sendMessage('result', {
+        success: false,
+        error: `Could not acquire lock on ${context.targetFile}`,
+      });
+      process.exit(1);
+    }
+
+    logInfo('Lock acquired', {
+      file: context.targetFile,
+    });
+
+    sendMessage('progress', {
+      message: 'Lock acquired, executing agent cycle',
+    });
+
+    // Execute the full agent cycle (RALPH loop)
+    // This includes:
+    // - Reading file and calculating gradient
+    // - Building prompt with inhibitors
+    // - Calling LLM
+    // - Applying changes
+    // - Running CI validation
+    // - Recording trace
+    // - Emitting inhibitors on failure
+    const result = await executeAgent(context.targetFile, context.mode, {
+      dryRun: false,
+      agentId: context.agentId,
+      taskId: context.taskId,
+    });
+
+    logInfo('Agent execution complete', {
+      file: context.targetFile,
+      success: result.success,
+      traceId: result.trace?.id,
+    });
+
+    // Send result back to coordinator
+    sendMessage('result', {
+      success: result.success,
+      traceId: result.trace?.id,
+      error: result.error,
+    });
+
+    // Clean exit
+    process.exit(result.success ? 0 : 1);
+  } catch (error) {
+    const errorObj = error instanceof Error ? error : new Error(String(error));
+    logError('Task worker failed', errorObj, {
+      agentId: process.env.AGENT_ID,
+    });
+
+    sendMessage('result', {
+      success: false,
+      error: errorObj.message,
+    });
+
+    process.exit(1);
+  } finally {
+    // Always release lock if we acquired it
+    if (lockAcquired) {
+      try {
+        const targetFile = process.env.TARGET_FILE;
+        if (targetFile) {
+          await releaseLock(targetFile);
+          logDebug('Lock released', { file: targetFile });
+        }
+      } catch (error) {
+        logError('Failed to release lock', error as Error);
+      }
+    }
+  }
+}
+
+// Run the worker
+main().catch((error) => {
+  console.error('Fatal error in task worker:', error);
+  process.exit(1);
+});

package/src/cli/gradients.ts

@@ -7,6 +7,7 @@
 
 import { Command } from 'commander';
 import chalk from 'chalk';
+import * as path from 'path';
 import glob from 'fast-glob';
 import { calculateGradientBatch } from '../core/gradient.js';
 
@@ -22,6 +23,7 @@ const command = new Command()
       const files = await glob('**/*.ts', {
         cwd: rootPath,
         ignore: ['node_modules/**', 'dist/**', '**/*.d.ts', '**/*.test.ts', '**/*.spec.ts'],
+        absolute: true, // Get absolute paths
       });
 
       if (files.length === 0) {