claude-mycelium 2.0.0 → 2.2.0

package/.claude/settings.local.json

@@ -4,7 +4,10 @@
       "Bash(npm run build:*)",
       "Bash(npm test:*)",
       "Bash(find:*)",
-      "Bash(npx @claude-flow/cli@latest swarm init:*)"
+      "Bash(npx @claude-flow/cli@latest swarm init:*)",
+      "Bash(npx @claude-flow/cli@latest hooks session-start:*)",
+      "Bash(npm run cli:*)",
+      "Bash(node:*)"
     ]
   },
   "enableAllProjectMcpServers": true,

package/README.md

@@ -2,280 +2,139 @@
 
 [![npm version](https://img.shields.io/npm/v/claude-mycelium.svg)](https://www.npmjs.com/package/claude-mycelium)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Tests](https://img.shields.io/badge/tests-289%2F292-brightgreen.svg)](https://github.com/ruvnet/claude-mycelium)
+[![Tests](https://img.shields.io/badge/tests-458%20passing-brightgreen.svg)](https://github.com/camplight/claude-mycelium)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
 
-> **Self-Learning AI Code Evolution System** - Automated code quality improvement through intelligent gradient-based optimization and autonomous agent orchestration.
+> **Autonomous AI agents that improve your codebase** - Multi-agent swarm intelligence for continuous code evolution.
 
-Claude Mycelium is an autonomous AI agent system that continuously learns and improves your codebase using gradient-based signals, inhibitor-based learning, and LLM-powered code transformations. Like a mycelium network, it spreads intelligence throughout your codebase, connecting patterns and optimizing quality.
-
-## ✨ Features
-
-### 🎯 Intelligent Signal System
-- **Complexity Signal** - Detects cyclomatic complexity hotspots
-- **Churn Signal** - Identifies frequently modified files
-- **Centrality Signal** - Maps dependency relationships
-- **Technical Debt Signal** - Tracks code quality issues
-- **Error Signal** - Monitors runtime error patterns
-
-### 🤖 Autonomous Agent System
-- **4 Agent Modes** - Error Reducer, Complexity Reducer, Debt Payer, Stabilizer
-- **Gradient-Based Optimization** - Mathematical gradient descent for code quality
-- **Inhibitor-Based Learning** - Learns from failures through mycelium-inspired signals
-- **Automatic Rollback** - Reverts changes if tests fail
-- **Cost Tracking** - Monitors LLM API usage and efficiency
-
-### 🔬 Phase 2 Complete
-- ✅ **LLM Integration** - Anthropic Claude with streaming support
-- ✅ **Agent Execution** - 10-step orchestration loop
-- ✅ **Change Application** - Safe code modification with backup/rollback
-- ✅ **Trace System** - JSONL-based learning foundation
-- ✅ **Cost Tracking** - Multi-model pricing and budget monitoring
+Claude Mycelium coordinates autonomous AI agents to improve code quality through gradient-based optimization. Like a mycelium network, agents communicate through signals, learn from failures, and self-organize to reduce complexity, fix bugs, and pay down technical debt.
 
 ## 🚀 Quick Start
 
 ### Installation
 
 ```bash
-npm install claude-mycelium
+npm install -g claude-mycelium
 ```
 
-### Prerequisites
+### Setup
 
-- Node.js 20+
-- TypeScript 5.0+
-- Anthropic API Key
+```bash
+# Initialize in your project
+npx claude-mycelium init
 
-### Basic Usage
+# Set your Anthropic API key
+export ANTHROPIC_API_KEY=sk-ant-...
+```
 
-```typescript
-import { executeAgent } from 'claude-mycelium';
+### CLI Commands
 
-// Set your API key
-process.env.ANTHROPIC_API_KEY = 'sk-ant-...';
+```bash
+# Interactive mode - chat with mycelium to spawn agents
+npx claude-mycelium grow
 
-// Run the agent on a file
-const result = await executeAgent(
-  'src/my-file.ts',
-  'error_reducer',
-  { dryRun: false }
-);
+# Check code quality scores
+npx claude-mycelium gradients ./src
 
-console.log(`Changes: ${result.changes}`);
-console.log(`Cost: $${result.cost.toFixed(4)}`);
-console.log(`Efficiency: ${result.trace.metabolic_efficiency.toFixed(3)}`);
-```
+# View system status
+npx claude-mycelium status
 
-### Calculate Gradient Scores
+# Check API costs
+npx claude-mycelium cost
 
-```typescript
-import { calculateGradient } from 'claude-mycelium';
+# Run garbage collection
+npx claude-mycelium gc
 
-const gradient = await calculateGradient('src/my-file.ts');
-console.log(`Overall Score: ${gradient.score.toFixed(2)}`);
-console.log(`Complexity: ${gradient.signals.complexity.value}`);
-console.log(`Technical Debt: ${gradient.signals.debt.value}`);
+# Single task mode
+npx claude-mycelium grow --task "fix bugs in src/api.ts"
 ```
 
-### Agent Modes
-
-```typescript
-// Error Reducer - Adds error handling and validation
-await executeAgent('src/api.ts', 'error_reducer');
+## ✨ Features
 
-// Complexity Reducer - Simplifies complex functions
-await executeAgent('src/utils.ts', 'complexity_reducer');
+- **5 Quality Signals** - Complexity, churn, technical debt, error rate, centrality
+- **4 Agent Modes** - Error Reducer, Complexity Reducer, Debt Payer, Stabilizer
+- **Swarm Coordination** - Multi-agent parallel execution with file locking
+- **Learning System** - Inhibitors and quarantine prevent repeated failures
+- **Automatic Rollback** - Reverts changes if tests fail
+- **Cost Tracking** - Monitor LLM API usage and efficiency
 
-// Debt Payer - Fixes linting issues and code smells
-await executeAgent('src/legacy.ts', 'debt_payer');
+## 🎯 How It Works
 
-// Stabilizer - Reduces file churn and improves stability
-await executeAgent('src/volatile.ts', 'stabilizer');
-```
+Claude Mycelium treats code improvement as gradient descent:
 
-## 📊 Architecture
+1. **Measure** - Calculate quality gradients (complexity, debt, errors)
+2. **Prioritize** - Find files with highest improvement potential
+3. **Execute** - Spawn agents to make improvements in parallel
+4. **Validate** - Run tests and check for regressions
+5. **Learn** - Record outcomes to improve future decisions
 
-```
-┌─────────────────────────────────────────────────────────┐
-│  Claude Mycelium - Self-Learning Code Evolution        │
-└─────────────────────────────────────────────────────────┘
-                         │
-        ┌────────────────┼────────────────┐
-        │                │                │
-   [Signals]        [Gradient]       [Agents]
-        │                │                │
-   5 dimensions    Mathematical      4 modes
-   of quality      optimization      of action
-        │                │                │
-        └────────────────┼────────────────┘
-                         │
-              ┌──────────┴──────────┐
-              │                     │
-         [LLM Layer]          [Learning Layer]
-              │                     │
-      Anthropic Claude        Trace System
-      Cost Tracking          Efficiency Metrics
-      Retry Logic           Pattern Recognition
-```
+Agents coordinate through **inhibitor signals** - files with repeated failures get quarantined, preventing wasted resources.
 
 ## 🛠️ Configuration
 
 ### Environment Variables
 
 ```bash
-# Required
-ANTHROPIC_API_KEY=sk-ant-...
-
-# Optional
-LOG_LEVEL=info              # debug, info, warn, error
-MAX_RETRIES=3               # LLM retry attempts
-DRY_RUN=false              # Simulate without changes
+ANTHROPIC_API_KEY=sk-ant-...    # Required
+LOG_LEVEL=info                  # Optional: debug, info, warn, error
 ```
 
-### API Options
+### Project Config
 
-```typescript
-interface ExecuteOptions {
-  dryRun?: boolean;         // Validate without applying
-  maxRetries?: number;      // LLM retry attempts
-  createBackup?: boolean;   // Backup before changes
+Create `.agent-meta/config.json`:
+
+```json
+{
+  "weights": {
+    "complexity": 0.3,
+    "churn": 0.2,
+    "debt": 0.3,
+    "error": 0.1,
+    "centrality": 0.1
+  }
 }
 ```
 
-## 📈 How It Works
+## 📊 Current Status
 
-### The 10-Step Execution Loop
+- **Phase 1** ✅ - Signal system and gradient calculation
+- **Phase 2** ✅ - LLM integration and agent execution
+- **Phase 3** ✅ - Concurrency and file locking
+- **Phase 4** ✅ - Inhibitors and quarantine system
+- **Phase 5** ✅ - Task planning and execution
+- **Phase 7** ✅ - CLI and garbage collection
+- **Phase 6** 🚧 - Watch mode (coming soon)
+- **Phase 8** 📋 - Multi-file orchestration
+- **Phase 9** 📋 - Distributed coordination
 
-1. **Calculate Gradient** - Measure current code quality
-2. **Select Mode** - Choose optimal agent strategy
-3. **Generate Prompt** - Create context-aware instructions
-4. **Call LLM** - Request code improvements
-5. **Parse Response** - Extract code changes
-6. **Validate** - Check TypeScript syntax
-7. **Apply Changes** - Safely modify files
-8. **Run Tests** - Verify correctness
-9. **Calculate New Gradient** - Measure improvement
-10. **Record Trace** - Learn from outcome
+**90% Complete** - Meta-circular development ready (system can improve itself)
 
-### Gradient-Based Optimization
-
-Claude Mycelium treats code quality as a mathematical optimization problem:
+## 🔒 Safety Features
 
-```
-Gradient = Σ(weight_i × signal_i)
-
-Where:
-- signal_complexity: Cyclomatic complexity
-- signal_churn: File modification frequency
-- signal_debt: Technical debt indicators
-- signal_error: Error rate patterns
-- signal_centrality: Dependency coupling
-```
+- **Atomic File Locks** - Prevents concurrent modifications
+- **Backup System** - Automatic backups before changes
+- **Test Validation** - Automatic rollback on test failures
+- **Quarantine** - Isolates problematic files after repeated failures
+- **Path Safety** - Protects .git/ and node_modules/
 
-## 🎓 Advanced Usage
+## 📦 Programmatic API
 
-### Custom Signal Weights
+For advanced use cases, you can use the TypeScript API:
 
 ```typescript
-import { calculateGradient } from 'claude-mycelium';
-
-const gradient = await calculateGradient('src/app.ts', {
-  weights: {
-    complexity: 0.3,
-    churn: 0.2,
-    debt: 0.3,
-    error: 0.1,
-    centrality: 0.1,
-  }
-});
-```
+import { executeAgent, calculateGradient } from 'claude-mycelium';
 
-### Batch Processing
+// Calculate quality gradient
+const gradient = await calculateGradient('src/app.ts');
+console.log(`Score: ${gradient.score}`);
 
-```typescript
-import { executeAgent } from 'claude-mycelium';
-import { glob } from 'glob';
-
-const files = await glob('src/**/*.ts');
-
-for (const file of files) {
-  const gradient = await calculateGradient(file);
-
-  if (gradient.score > 0.7) {
-    // High complexity - needs improvement
-    await executeAgent(file, 'complexity_reducer');
-  }
-}
-```
-
-### Learning from Traces
-
-```typescript
-import { getRecentEfficiency } from 'claude-mycelium';
-
-// Get efficiency of last 10 changes
-const efficiency = await getRecentEfficiency('src/app.ts', 10);
-console.log(`Historical efficiency: ${efficiency}`);
+// Execute agent
+const result = await executeAgent('src/app.ts', 'complexity_reducer', {
+  dryRun: false
+});
 ```
 
-## 📦 What's Included
-
-- `src/core/` - Agent execution and orchestration
-- `src/signals/` - 5 quality measurement systems
-- `src/gradient/` - Mathematical optimization
-- `src/llm/` - Anthropic Claude integration
-- `src/trace/` - Learning and efficiency tracking
-- `src/cost/` - Budget monitoring and reporting
-
-## 🔒 Safety Features
-
-- **Backup System** - Creates backups before any changes
-- **Automatic Rollback** - Reverts on test failures
-- **TypeScript Validation** - Syntax checking before apply
-- **Path Safety** - Prevents modification of .git/ and node_modules/
-- **File Size Limits** - Protects against large file issues
-- **Dry Run Mode** - Test without applying changes
-
-## 📊 Performance
-
-- **Test Coverage**: 289/292 tests passing (99%)
-- **LLM Models**: Claude Sonnet 4.5, Opus 4.5, Haiku 3.5
-- **Retry Logic**: Exponential backoff for rate limits
-- **Cost Tracking**: Per-file and aggregate metrics
-- **Efficiency**: Gradient improvement per dollar spent
-
-## 🗺️ Roadmap
-
-### Phase 1 ✅ Complete
-- Signal system (5 dimensions)
-- Gradient calculation
-- Mode selection
-- Caching and optimization
-
-### Phase 2 ✅ Complete
-- LLM integration (Anthropic Claude)
-- Agent execution loop
-- Change application with rollback
-- Trace system and learning foundation
-- Cost tracking and efficiency metrics
-
-### Phase 3 🔄 Next
-- Concurrency & coordination
-- File locks (atomic operations)
-- Process spawning and IPC
-- Multi-agent coordination
-
-### Phase 4 📋 Planned
-- Inhibitor signals (ADR-002)
-- Quarantine system
-- Explorer mode
-- Learning from failures
-
-### Phase 5-9 📋 Future
-- Multi-file orchestration
-- Task planning and execution
-- CLI and watch mode
-- Distributed swarm coordination
+See [API Documentation](docs/API.md) for details.
 
 ## 🤝 Contributing
 
@@ -283,19 +142,12 @@ We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guid
 
 ## 📄 License
 
-MIT License - see [LICENSE](LICENSE) for details
-
-## 🙏 Acknowledgments
-
-- Built with [Anthropic Claude](https://www.anthropic.com/claude)
-- Inspired by gradient descent optimization
-- Named after mycelium networks in nature
+MIT License - see [LICENSE](LICENSE) for details.
 
 ## 📞 Support
 
-- **Issues**: [GitHub Issues](https://github.com/ruvnet/claude-mycelium/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/ruvnet/claude-mycelium/discussions)
-- **Email**: support@claude-mycelium.dev
+- **Issues**: [GitHub Issues](https://github.com/camplight/claude-mycelium/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/camplight/claude-mycelium/discussions)
 
 ---
 

package/SECURITY.md

@@ -0,0 +1,145 @@
+# Security Policy
+
+## Reporting Security Vulnerabilities
+
+If you discover a security vulnerability in Claude Mycelium, please email:
+
+**security@camplight.net**
+
+**Please do not open public GitHub issues for security vulnerabilities.**
+
+### What to Include
+
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if available)
+
+We will respond within 48 hours and work with you to address the issue.
+
+---
+
+## Security Audit Status
+
+**Last Audit**: 2026-01-31
+**Status**: 🟡 MODERATE RISK - Critical fixes needed before v2.1.0 release
+
+See [docs/SECURITY-AUDIT.md](docs/SECURITY-AUDIT.md) for full audit report.
+
+### Critical Issues (Must Fix Before Release)
+
+1. **Command Injection** in `src/core/signals/debt.ts` and `churn.ts`
+   - Use `execFile()` instead of `exec()` with shell interpolation
+   - CVSS: 9.8 (Critical)
+
+2. **Path Traversal** in `src/utils/file-utils.ts`
+   - Add path validation to all file operations
+   - CVSS: 8.6 (High)
+
+---
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 2.1.x   | :white_check_mark: |
+| 2.0.x   | :white_check_mark: |
+| < 2.0   | :x:                |
+
+---
+
+## Security Best Practices for Users
+
+### 1. API Key Security
+
+- **Never commit** API keys to git
+- Use `.env` files with `.gitignore`
+- Use restricted API keys (not account-level keys)
+- Rotate keys regularly
+
+### 2. File System Permissions
+
+- Run with **minimal permissions** (not root/admin)
+- Review file changes before applying
+- Keep backups of important code
+
+### 3. Cost Control
+
+- Set `MAX_DAILY_COST` environment variable
+- Monitor API usage regularly
+- Review changes before they're applied
+
+### 4. Network Security
+
+- Review LLM prompts for sensitive data
+- Don't include credentials in code comments
+- Use firewall rules to restrict outbound connections
+
+---
+
+## Known Security Limitations
+
+### 1. LLM Prompt Injection
+
+Claude Mycelium uses LLM-generated code. While we have safeguards:
+- File content could influence LLM output
+- Always review changes before applying
+- Run in sandboxed environments for untrusted codebases
+
+### 2. Dependency Vulnerabilities
+
+We actively monitor dependencies but:
+- Use `npm audit` to check your installation
+- Some dev dependencies have moderate vulnerabilities
+- Production dependencies are secure
+
+### 3. File System Access
+
+The system requires broad file system access:
+- Runs with your user's permissions
+- Can modify any file in the project
+- Use `.gitignore` to protect sensitive files
+
+---
+
+## Security Checklist for Contributors
+
+Before submitting code:
+
+- [ ] Run security tests: `npm test tests/security/`
+- [ ] Check for secrets: `git secrets --scan`
+- [ ] Validate all user inputs
+- [ ] Use `execFile()` not `exec()` for commands
+- [ ] Validate file paths before operations
+- [ ] Add security tests for new features
+- [ ] Update this document if needed
+
+---
+
+## Security Tools
+
+```bash
+# Run security audit
+npm audit
+
+# Run security tests
+npm test tests/security/
+
+# Check for outdated packages
+npm outdated
+
+# Scan for secrets (if git-secrets installed)
+git secrets --scan
+```
+
+---
+
+## Contact
+
+- **Security Issues**: security@camplight.net
+- **General Issues**: https://github.com/camplight/claude-mycelium/issues
+- **Discussions**: https://github.com/camplight/claude-mycelium/discussions
+
+---
+
+**Last Updated**: 2026-01-31

package/dist/agent/task-worker.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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()
+ */
+export {};
+//# sourceMappingURL=task-worker.d.ts.map

package/dist/agent/task-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-worker.d.ts","sourceRoot":"","sources":["../../src/agent/task-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}