claude-mycelium 2.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (189) hide show
  1. package/.agent-meta/_inhibitors.ndjson +1287 -0
  2. package/.agent-meta/_quarantine.json +45 -0
  3. package/.agent-meta/config.json +9 -0
  4. package/.claude/memory.db +0 -0
  5. package/.claude/settings.local.json +4 -1
  6. package/README.md +81 -235
  7. package/SECURITY.md +145 -0
  8. package/dist/agent/worker.d.ts +8 -0
  9. package/dist/agent/worker.d.ts.map +1 -0
  10. package/dist/agent/worker.js +97 -0
  11. package/dist/agent/worker.js.map +1 -0
  12. package/dist/bin.d.ts +7 -0
  13. package/dist/bin.d.ts.map +1 -0
  14. package/dist/bin.js +11 -0
  15. package/dist/bin.js.map +1 -0
  16. package/dist/cli/cost.d.ts +10 -0
  17. package/dist/cli/cost.d.ts.map +1 -0
  18. package/dist/cli/cost.js +163 -0
  19. package/dist/cli/cost.js.map +1 -0
  20. package/dist/cli/gc.d.ts +10 -0
  21. package/dist/cli/gc.d.ts.map +1 -0
  22. package/dist/cli/gc.js +108 -0
  23. package/dist/cli/gc.js.map +1 -0
  24. package/dist/cli/gradients.d.ts +10 -0
  25. package/dist/cli/gradients.d.ts.map +1 -0
  26. package/dist/cli/gradients.js +69 -0
  27. package/dist/cli/gradients.js.map +1 -0
  28. package/dist/cli/index.d.ts +17 -0
  29. package/dist/cli/index.d.ts.map +1 -0
  30. package/dist/cli/index.js +72 -0
  31. package/dist/cli/index.js.map +1 -0
  32. package/dist/cli/init.d.ts +11 -0
  33. package/dist/cli/init.d.ts.map +1 -0
  34. package/dist/cli/init.js +97 -0
  35. package/dist/cli/init.js.map +1 -0
  36. package/dist/cli/status.d.ts +10 -0
  37. package/dist/cli/status.d.ts.map +1 -0
  38. package/dist/cli/status.js +191 -0
  39. package/dist/cli/status.js.map +1 -0
  40. package/dist/coordination/file-locks.d.ts +42 -0
  41. package/dist/coordination/file-locks.d.ts.map +1 -0
  42. package/dist/coordination/file-locks.js +269 -0
  43. package/dist/coordination/file-locks.js.map +1 -0
  44. package/dist/coordination/index.d.ts +4 -0
  45. package/dist/coordination/index.d.ts.map +1 -1
  46. package/dist/coordination/index.js +4 -0
  47. package/dist/coordination/index.js.map +1 -1
  48. package/dist/coordination/inhibitors.d.ts +84 -0
  49. package/dist/coordination/inhibitors.d.ts.map +1 -0
  50. package/dist/coordination/inhibitors.js +290 -0
  51. package/dist/coordination/inhibitors.js.map +1 -0
  52. package/dist/coordination/process-manager.d.ts +73 -0
  53. package/dist/coordination/process-manager.d.ts.map +1 -0
  54. package/dist/coordination/process-manager.js +144 -0
  55. package/dist/coordination/process-manager.js.map +1 -0
  56. package/dist/core/agent-executor.d.ts.map +1 -1
  57. package/dist/core/agent-executor.js +28 -10
  58. package/dist/core/agent-executor.js.map +1 -1
  59. package/dist/core/change-applier.d.ts +29 -5
  60. package/dist/core/change-applier.d.ts.map +1 -1
  61. package/dist/core/change-applier.js +254 -24
  62. package/dist/core/change-applier.js.map +1 -1
  63. package/dist/core/signals/churn.d.ts.map +1 -1
  64. package/dist/core/signals/churn.js +6 -4
  65. package/dist/core/signals/churn.js.map +1 -1
  66. package/dist/core/signals/debt.d.ts.map +1 -1
  67. package/dist/core/signals/debt.js +4 -3
  68. package/dist/core/signals/debt.js.map +1 -1
  69. package/dist/cost/cost-tracker.d.ts.map +1 -1
  70. package/dist/cost/cost-tracker.js +2 -0
  71. package/dist/cost/cost-tracker.js.map +1 -1
  72. package/dist/gc/index.d.ts +17 -0
  73. package/dist/gc/index.d.ts.map +1 -0
  74. package/dist/gc/index.js +17 -0
  75. package/dist/gc/index.js.map +1 -0
  76. package/dist/gc/runner.d.ts +39 -0
  77. package/dist/gc/runner.d.ts.map +1 -0
  78. package/dist/gc/runner.js +277 -0
  79. package/dist/gc/runner.js.map +1 -0
  80. package/dist/gc/trace-compactor.d.ts +31 -0
  81. package/dist/gc/trace-compactor.d.ts.map +1 -0
  82. package/dist/gc/trace-compactor.js +162 -0
  83. package/dist/gc/trace-compactor.js.map +1 -0
  84. package/dist/index.d.ts +5 -1
  85. package/dist/index.d.ts.map +1 -1
  86. package/dist/index.js +6 -1
  87. package/dist/index.js.map +1 -1
  88. package/dist/prompts/index.d.ts +2 -1
  89. package/dist/prompts/index.d.ts.map +1 -1
  90. package/dist/prompts/index.js.map +1 -1
  91. package/dist/quarantine/explorer.d.ts +65 -0
  92. package/dist/quarantine/explorer.d.ts.map +1 -0
  93. package/dist/quarantine/explorer.js +175 -0
  94. package/dist/quarantine/explorer.js.map +1 -0
  95. package/dist/quarantine/index.d.ts +7 -0
  96. package/dist/quarantine/index.d.ts.map +1 -0
  97. package/dist/quarantine/index.js +7 -0
  98. package/dist/quarantine/index.js.map +1 -0
  99. package/dist/quarantine/manager.d.ts +75 -0
  100. package/dist/quarantine/manager.d.ts.map +1 -0
  101. package/dist/quarantine/manager.js +275 -0
  102. package/dist/quarantine/manager.js.map +1 -0
  103. package/dist/task/acceptance.d.ts +29 -0
  104. package/dist/task/acceptance.d.ts.map +1 -0
  105. package/dist/task/acceptance.js +228 -0
  106. package/dist/task/acceptance.js.map +1 -0
  107. package/dist/task/executor.d.ts +30 -0
  108. package/dist/task/executor.d.ts.map +1 -0
  109. package/dist/task/executor.js +429 -0
  110. package/dist/task/executor.js.map +1 -0
  111. package/dist/task/index.d.ts +12 -0
  112. package/dist/task/index.d.ts.map +1 -0
  113. package/dist/task/index.js +12 -0
  114. package/dist/task/index.js.map +1 -0
  115. package/dist/task/planner.d.ts +21 -0
  116. package/dist/task/planner.d.ts.map +1 -0
  117. package/dist/task/planner.js +253 -0
  118. package/dist/task/planner.js.map +1 -0
  119. package/dist/task/storage.d.ts +46 -0
  120. package/dist/task/storage.d.ts.map +1 -0
  121. package/dist/task/storage.js +266 -0
  122. package/dist/task/storage.js.map +1 -0
  123. package/dist/trace/trace-event.d.ts +2 -18
  124. package/dist/trace/trace-event.d.ts.map +1 -1
  125. package/dist/trace/trace-event.js +6 -6
  126. package/dist/trace/trace-event.js.map +1 -1
  127. package/dist/utils/file-utils.d.ts.map +1 -1
  128. package/dist/utils/file-utils.js +54 -15
  129. package/dist/utils/file-utils.js.map +1 -1
  130. package/docs/PHASE5_IMPLEMENTATION.md +237 -0
  131. package/docs/PHASES-3-7-COMPLETE.md +177 -0
  132. package/docs/PHASE_4_COMPLETE.md +135 -0
  133. package/docs/PHASE_7_DELIVERABLES.md +295 -0
  134. package/docs/PHASE_7_IMPLEMENTATION.md +306 -0
  135. package/docs/PHASE_7_SUMMARY.txt +195 -0
  136. package/docs/RELEASE-NOTES-v2.1.md +213 -0
  137. package/docs/ROADMAP.md +64 -57
  138. package/docs/SECURITY-AUDIT.md +387 -0
  139. package/docs/SNAPSHOT.md +59 -32
  140. package/docs/implementation/phase3-summary.md +220 -0
  141. package/package.json +19 -11
  142. package/src/agent/worker.ts +111 -0
  143. package/src/bin.ts +13 -0
  144. package/src/cli/cost.ts +210 -0
  145. package/src/cli/gc.ts +138 -0
  146. package/src/cli/gradients.ts +95 -0
  147. package/src/cli/index.ts +79 -0
  148. package/src/cli/init.ts +139 -0
  149. package/src/cli/status.ts +218 -0
  150. package/src/coordination/file-locks.ts +300 -0
  151. package/src/coordination/index.ts +4 -0
  152. package/src/coordination/inhibitors.ts +345 -0
  153. package/src/coordination/process-manager.ts +199 -0
  154. package/src/core/agent-executor.ts +20 -4
  155. package/src/core/signals/churn.ts +8 -5
  156. package/src/core/signals/debt.ts +4 -3
  157. package/src/cost/cost-tracker.ts +2 -0
  158. package/src/gc/index.ts +17 -0
  159. package/src/gc/runner.ts +314 -0
  160. package/src/gc/trace-compactor.ts +187 -0
  161. package/src/index.ts +7 -1
  162. package/src/prompts/index.ts +2 -1
  163. package/src/quarantine/explorer.ts +234 -0
  164. package/src/quarantine/index.ts +7 -0
  165. package/src/quarantine/manager.ts +336 -0
  166. package/src/task/acceptance.ts +267 -0
  167. package/src/task/executor.ts +538 -0
  168. package/src/task/index.ts +38 -0
  169. package/src/task/planner.ts +294 -0
  170. package/src/task/storage.ts +332 -0
  171. package/src/trace/trace-event.ts +7 -26
  172. package/src/utils/file-utils.ts +61 -15
  173. package/tests/cli/gc.test.ts +206 -0
  174. package/tests/cli/init.test.ts +181 -0
  175. package/tests/cli/status.test.ts +282 -0
  176. package/tests/coordination/file-locks.test.ts +196 -0
  177. package/tests/coordination/inhibitors.test.ts +459 -0
  178. package/tests/coordination/integration.test.ts +195 -0
  179. package/tests/coordination/process-manager.test.ts +165 -0
  180. package/tests/gc/trace-compactor.test.ts +245 -0
  181. package/tests/integration/phase-7.test.ts +145 -0
  182. package/tests/quarantine/explorer.test.ts +381 -0
  183. package/tests/quarantine/manager.test.ts +399 -0
  184. package/tests/security/command-injection.test.ts +88 -0
  185. package/tests/security/path-traversal.test.ts +103 -0
  186. package/tests/task/acceptance.test.ts +411 -0
  187. package/tests/task/executor.test.ts +421 -0
  188. package/tests/task/planner.test.ts +359 -0
  189. package/tsconfig.json +2 -2
package/docs/ROADMAP.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # Claude-Mycelium v2: Implementation Roadmap
2
2
 
3
3
  **Last Updated**: 2026-01-30
4
- **Current Status**: 15% Complete (Foundation Phase)
5
- **Target Completion**: 5-6 weeks (full-time development)
4
+ **Current Status**: Phase 2 Complete (40% Complete)
5
+ **Target Completion**: 4-5 weeks remaining (Phase 3-9)
6
6
 
7
7
  ---
8
8
 
@@ -18,42 +18,49 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
18
18
 
19
19
  ## 📊 Current State
20
20
 
21
- ### ✅ Completed (15%)
22
- - Project structure and directories
23
- - TypeScript configuration
21
+ ### ✅ Completed (40%)
22
+
23
+ **Phase 0: Foundation** ✅
24
+ - Project structure and TypeScript configuration
24
25
  - 5 comprehensive ADRs documenting all design decisions
25
- - Type system (98% - missing Inhibitor type)
26
- - File utilities (complete)
27
- - Implementation tracking document
28
- - Gitignore configuration
29
-
30
- ### Critical Blockers (Must Fix Before Continuing)
31
- 1. **Wrong dependency** - Using `@typescript-eslint/parser` instead of `typescript-estree`
32
- 2. **Missing dependencies** - No `@anthropic-ai/sdk`, `chokidar`, `uuid`
33
- 3. **Inaccurate tracking** - 4 utility files marked done but not implemented
34
- 4. **Missing Inhibitor type** - Core interface from second-spec §1.3
35
-
36
- ### 🟡 Pending (85%)
37
- - All 5 signal computations
38
- - LLM client and agent execution
39
- - Process spawning and coordination
26
+ - Complete type system (all interfaces defined)
27
+ - File utilities, config, logger, error provider, CI provider
28
+
29
+ **Phase 1: Signal System** ✅
30
+ - All 5 signal computations (complexity, churn, centrality, debt, errors)
31
+ - Gradient calculation with caching
32
+ - Mode selection logic
33
+ - 155/155 tests passing
34
+
35
+ **Phase 2: Agent Execution**
36
+ - LLM Integration (Anthropic Claude API)
37
+ - Agent executor with 10-step orchestration loop
38
+ - Change applier with backup/rollback
39
+ - Trace system (JSONL storage)
40
+ - Cost tracking (multi-model pricing)
41
+ - 134/137 tests passing (3 skipped - flaky mocks)
42
+
43
+ **Test Status**: 289/292 passing (99%)
44
+ **Code Quality**: 100% TypeScript typed, comprehensive documentation
45
+
46
+ ### 🟡 Pending (60%)
47
+ - Process spawning and multi-agent coordination
40
48
  - File locks (O_CREAT|O_EXCL atomicity)
41
- - Gradient calculation and mode selection
42
- - Inhibitor system
49
+ - Inhibitor system and decay
43
50
  - Quarantine and explorer mode
44
51
  - Task planning and execution
45
- - CLI commands
46
- - Complete test suite
52
+ - CLI commands and watch mode
53
+ - Garbage collection
47
54
 
48
55
  ---
49
56
 
50
57
  ## 🚀 Implementation Phases
51
58
 
52
- ### **Phase 0: Foundation Fixes** (1-2 days)
59
+ ### **Phase 0: Foundation Fixes** ✅ COMPLETE (1-2 days)
53
60
  *Fix critical blockers before continuing*
54
61
 
55
62
  #### Week 0, Day 1: Dependency Fixes
56
- - [ ] Fix package.json dependencies:
63
+ - [x] Fix package.json dependencies:
57
64
  ```json
58
65
  {
59
66
  "dependencies": {
@@ -68,21 +75,21 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
68
75
  }
69
76
  }
70
77
  ```
71
- - [ ] Run `npm install` and verify all packages install correctly
72
- - [ ] Document choice of `fast-glob` over `glob` in IMPLEMENTATION-STATUS.md
73
- - [ ] Document addition of `ora` for CLI UX in IMPLEMENTATION-STATUS.md
78
+ - [x] Run `npm install` and verify all packages install correctly
79
+ - [x] Document choice of `fast-glob` over `glob` in IMPLEMENTATION-STATUS.md
80
+ - [x] Document addition of `ora` for CLI UX in IMPLEMENTATION-STATUS.md
74
81
 
75
82
  #### Week 0, Day 2: Type System Completion
76
- - [ ] Add `Inhibitor` interface to `src/types/index.ts`
77
- - [ ] Add `InhibitorState` interface for storage
78
- - [ ] Verify all types match specs (Appendix A + second-spec §1.3)
83
+ - [x] Add `Inhibitor` interface to `src/types/index.ts`
84
+ - [x] Add `InhibitorState` interface for storage
85
+ - [x] Verify all types match specs (Appendix A + second-spec §1.3)
79
86
 
80
87
  #### Week 0, Day 2: Utility Implementation Status
81
- - [ ] Create `src/utils/config.ts` - Config loading with defaults (spec §13)
82
- - [ ] Create `src/utils/logger.ts` - Structured logging
83
- - [ ] Create `src/utils/error-provider.ts` - File-based error tracking (spec §2.5)
84
- - [ ] Create `src/utils/ci-provider.ts` - npm test/lint execution
85
- - [ ] Update IMPLEMENTATION-STATUS.md to reflect actual completion
88
+ - [x] Create `src/utils/config.ts` - Config loading with defaults (spec §13)
89
+ - [x] Create `src/utils/logger.ts` - Structured logging
90
+ - [x] Create `src/utils/error-provider.ts` - File-based error tracking (spec §2.5)
91
+ - [x] Create `src/utils/ci-provider.ts` - npm test/lint execution
92
+ - [x] Update IMPLEMENTATION-STATUS.md to reflect actual completion
86
93
 
87
94
  **Phase 0 Exit Criteria:**
88
95
  - ✅ All dependencies installed and working
@@ -93,13 +100,13 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
93
100
 
94
101
  ---
95
102
 
96
- ### **Phase 1: Core Signal System** (Week 1-2)
103
+ ### **Phase 1: Core Signal System** ✅ COMPLETE (Week 1-2)
97
104
  *Implement gradient calculation foundation*
98
105
 
99
106
  #### Week 1: Signal Computation (ADR-001)
100
107
 
101
108
  **Day 1-2: Complexity Signal**
102
- - [ ] `src/core/signals/complexity.ts`
109
+ - [x] `src/core/signals/complexity.ts`
103
110
  - AST parsing with `@typescript-eslint/typescript-estree`
104
111
  - Cyclomatic complexity counting (if, for, while, switch, catch, &&, ||)
105
112
  - LOC counting (exclude blanks and comments)
@@ -108,7 +115,7 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
108
115
  - **Reference:** second-spec §2.1, lines 280-380
109
116
 
110
117
  **Day 3: Churn Signal**
111
- - [ ] `src/core/signals/churn.ts`
118
+ - [x] `src/core/signals/churn.ts`
112
119
  - Git shell-out: `git log --since="30 days" --name-only`
113
120
  - 5-minute TTL cache to avoid repeated calls
114
121
  - Normalization: commits_to_file / max(commits_to_any_file)
@@ -117,7 +124,7 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
117
124
  - **Reference:** second-spec §2.2, lines 380-480
118
125
 
119
126
  **Day 4: Centrality Signal**
120
- - [ ] `src/core/signals/centrality.ts`
127
+ - [x] `src/core/signals/centrality.ts`
121
128
  - Regex-based import extraction: `import.*from ['"](.*)['"]`
122
129
  - Build import graph: `{ imports: {}, importedBy: {} }`
123
130
  - Path resolution with extensions (.ts, .tsx, .js, .jsx, /index)
@@ -127,7 +134,7 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
127
134
  - **Reference:** second-spec §2.3, lines 480-620
128
135
 
129
136
  **Day 5: Debt Signal**
130
- - [ ] `src/core/signals/debt.ts`
137
+ - [x] `src/core/signals/debt.ts`
131
138
  - ESLint subprocess: `npx eslint <file> --format json`
132
139
  - Formula: `(errors × 3 + warnings) / LOC`
133
140
  - Normalization: divide by 0.5, cap at 1.0
@@ -136,18 +143,18 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
136
143
  - **Reference:** second-spec §2.4, lines 620-664
137
144
 
138
145
  **Day 6-7: Error Signal + Integration**
139
- - [ ] `src/core/signals/errors.ts`
146
+ - [x] `src/core/signals/errors.ts`
140
147
  - Read `.agent-meta/_errors.json` (file-based provider)
141
148
  - Formula: `(error_count / LOC) / 0.1` capped at 1.0
142
149
  - **Test:** File with errors scores higher
143
150
  - **Reference:** second-spec §2.5, lines 665-705
144
- - [ ] `src/core/signals/index.ts` - Export all signals
151
+ - [x] `src/core/signals/index.ts` - Export all signals
145
152
  - [ ] Integration tests for all 5 signals
146
153
 
147
154
  #### Week 2: Gradient Calculation
148
155
 
149
156
  **Day 1-2: Gradient Formula**
150
- - [ ] `src/core/gradient.ts`
157
+ - [x] `src/core/gradient.ts`
151
158
  - Implement base score calculation (spec §2):
152
159
  ```typescript
153
160
  baseScore = complexity * 0.25 + churn * 0.15 +
@@ -160,7 +167,7 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
160
167
  - **Reference:** initial-spec §2, lines 66-102
161
168
 
162
169
  **Day 3: Gradient Cache**
163
- - [ ] `src/coordination/gradient-cache.ts`
170
+ - [x] `src/coordination/gradient-cache.ts`
164
171
  - Cache location: `.agent-meta/_gradient_cache.json`
165
172
  - 5-minute TTL (configurable)
166
173
  - Lock-protected refresh (prevent thundering herd)
@@ -168,7 +175,7 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
168
175
  - **Reference:** initial-spec §9
169
176
 
170
177
  **Day 4: Mode Selection**
171
- - [ ] `src/core/mode-selector.ts`
178
+ - [x] `src/core/mode-selector.ts`
172
179
  - Identify dominant signal (max of complexity, churn, error_rate, debt)
173
180
  - Map to mode: error_rate→error_reducer, complexity→complexity_reducer, etc.
174
181
  - Explorer mode for quarantined files (see Phase 2)
@@ -176,9 +183,9 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
176
183
  - **Reference:** initial-spec §3, lines 103-165
177
184
 
178
185
  **Day 5-7: Integration & Testing**
179
- - [ ] End-to-end gradient calculation test
180
- - [ ] Benchmark performance (target: <100ms per file)
181
- - [ ] Generate sample gradient report
186
+ - [x] End-to-end gradient calculation test
187
+ - [x] Benchmark performance (target: <100ms per file)
188
+ - [x] Generate sample gradient report
182
189
 
183
190
  **Phase 1 Exit Criteria:**
184
191
  - ✅ All 5 signals compute correctly
@@ -190,11 +197,11 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
190
197
 
191
198
  ---
192
199
 
193
- ### **Phase 2: Agent Execution** (Week 3)
200
+ ### **Phase 2: Agent Execution** ✅ COMPLETE (Week 3)
194
201
  *Implement LLM-powered agent cycle*
195
202
 
196
203
  #### Week 3, Day 1-2: LLM Client (ADR-003)
197
- - [ ] `src/agent/llm-client.ts`
204
+ - [x] `src/agent/llm-client.ts`
198
205
  - Anthropic SDK initialization
199
206
  - Model: `claude-sonnet-4-20250514` (configurable)
200
207
  - Timeout: 5 minutes
@@ -204,7 +211,7 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
204
211
  - **Reference:** ADR-003, second-spec §3
205
212
 
206
213
  #### Week 3, Day 2-3: Prompt Building
207
- - [ ] `src/agent/prompt-builder.ts`
214
+ - [x] `src/agent/prompt-builder.ts`
208
215
  - System prompt with mode-specific rules (spec §4.2)
209
216
  - User prompt with file content + metrics + inhibitors
210
217
  - Format: Complete file output, not diffs
@@ -213,7 +220,7 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
213
220
  - **Reference:** ADR-003, second-spec §11
214
221
 
215
222
  #### Week 3, Day 3-4: Agent Executor
216
- - [ ] `src/agent/executor.ts`
223
+ - [x] `src/agent/executor.ts`
217
224
  - Complete agent cycle:
218
225
  1. Read file + compute gradient
219
226
  2. Build prompt with metrics
@@ -229,7 +236,7 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
229
236
  - **Reference:** second-spec §3.2, lines 115-273
230
237
 
231
238
  #### Week 3, Day 5: Response Parsing
232
- - [ ] `src/agent/response-parser.ts`
239
+ - [x] `src/agent/response-parser.ts`
233
240
  - Extract code from markdown fence: ` ```typescript...``` `
234
241
  - Reject unchanged content
235
242
  - Handle malformed responses
@@ -237,11 +244,11 @@ Build a decentralized, gradient-driven agent system that autonomously improves c
237
244
  - **Reference:** ADR-003
238
245
 
239
246
  #### Week 3, Day 6-7: Metabolic Cost & Traces
240
- - [ ] `src/agent/metabolic.ts`
247
+ - [x] `src/agent/metabolic.ts`
241
248
  - Formula: `time * 0.2 + lines * 0.3 + tokens * 0.5`
242
249
  - Normalize to 0.0-1.0 range
243
250
  - **Reference:** initial-spec §4.4, lines 235-245
244
- - [ ] `src/trace/storage.ts`
251
+ - [x] `src/trace/storage.ts`
245
252
  - Write traces to `.agent-meta/traces/<file>.ndjson`
246
253
  - Path conversion: `src/auth.ts` → `src__auth.ts.ndjson`
247
254
  - Append-only writes
@@ -0,0 +1,387 @@
1
+ # Security Audit Report - Claude Mycelium v2.1.0
2
+
3
+ **Date**: January 31, 2026
4
+ **Auditor**: Claude Sonnet 4.5
5
+ **Scope**: npm packages + implementation code
6
+
7
+ ---
8
+
9
+ ## Executive Summary
10
+
11
+ **Overall Risk**: 🟡 MODERATE
12
+
13
+ - **7 npm vulnerabilities** (all dev dependencies, moderate severity)
14
+ - **2 CRITICAL code vulnerabilities** (command injection)
15
+ - **3 HIGH code vulnerabilities** (path handling, input validation)
16
+ - **2 MEDIUM code vulnerabilities** (API key exposure, race conditions)
17
+
18
+ **Recommended Actions**: Fix critical command injection issues immediately before public release.
19
+
20
+ ---
21
+
22
+ ## 1. NPM Package Vulnerabilities
23
+
24
+ ### 1.1 Dev Dependencies (Moderate Risk)
25
+
26
+ | Package | Severity | CVE | Impact | Fix |
27
+ |---------|----------|-----|--------|-----|
28
+ | **esbuild** ≤0.24.2 | Moderate | GHSA-67mh-4wv8-2f99 | Dev server can read responses from any website | Upgrade to vitest@4.x |
29
+ | **eslint** <9.26.0 | Moderate | GHSA-p5wg-g6qr-c7cg | Stack overflow with circular references | Upgrade to eslint@9.x |
30
+ | **vitest** | Moderate | Via esbuild | Transitive vulnerability | Upgrade to @4.x |
31
+ | **@vitest/coverage-v8** | Moderate | Via vitest | Transitive vulnerability | Upgrade to @4.x |
32
+
33
+ **Risk Assessment**: LOW - All vulnerabilities are in dev dependencies only, not production runtime.
34
+
35
+ **Recommendation**:
36
+ ```bash
37
+ npm install --save-dev vitest@^4.0.0 @vitest/coverage-v8@^4.0.0 eslint@^9.0.0
38
+ ```
39
+
40
+ ### 1.2 Outdated Packages
41
+
42
+ | Package | Current | Latest | Breaking |
43
+ |---------|---------|--------|----------|
44
+ | @anthropic-ai/sdk | 0.30.1 | **0.72.1** | Yes |
45
+ | commander | 12.1.0 | 14.0.3 | Yes |
46
+ | chokidar | 3.6.0 | 4.0.3 | Yes |
47
+ | uuid | 9.0.1 | 13.0.0 | Yes |
48
+
49
+ **Recommendation**: Upgrade @anthropic-ai/sdk to latest for security patches and new features.
50
+
51
+ ---
52
+
53
+ ## 2. Code Security Vulnerabilities
54
+
55
+ ### 🔴 CRITICAL: Command Injection in Signal Calculators
56
+
57
+ **Location**: `src/core/signals/debt.ts:46` and `src/core/signals/churn.ts`
58
+
59
+ **Vulnerability**:
60
+ ```typescript
61
+ // UNSAFE: No shell escaping
62
+ const { stdout } = await execAsync(`npx eslint "${filePath}" --format json`);
63
+ ```
64
+
65
+ **Attack Vector**:
66
+ ```typescript
67
+ // Malicious filename: test"; rm -rf /; echo ".ts
68
+ calculateDebt('test"; rm -rf /; echo ".ts');
69
+ // Executes: npx eslint "test"; rm -rf /; echo "" --format json
70
+ ```
71
+
72
+ **Impact**:
73
+ - **Arbitrary command execution** on the system
74
+ - **Data loss** through file deletion
75
+ - **System compromise** through malicious code execution
76
+ - **Supply chain attack** if used in CI/CD
77
+
78
+ **CVSS Score**: 9.8 (Critical)
79
+ **CWE**: CWE-78 (OS Command Injection)
80
+
81
+ **Fix**:
82
+ ```typescript
83
+ import { execFile } from 'child_process';
84
+ import { promisify } from 'util';
85
+ const execFileAsync = promisify(execFile);
86
+
87
+ // SAFE: Use execFile with array arguments (no shell interpretation)
88
+ const { stdout } = await execFileAsync('npx', ['eslint', filePath, '--format', 'json'], {
89
+ maxBuffer: 1024 * 1024,
90
+ });
91
+ ```
92
+
93
+ **Files to Fix**:
94
+ - `src/core/signals/debt.ts` (line 46)
95
+ - `src/core/signals/churn.ts` (lines 115, 127, 157)
96
+
97
+ ---
98
+
99
+ ### 🔴 CRITICAL: Path Traversal in File Operations
100
+
101
+ **Location**: `src/utils/file-utils.ts` (all functions)
102
+
103
+ **Vulnerability**: No validation against directory traversal attacks.
104
+
105
+ **Attack Vector**:
106
+ ```typescript
107
+ // Attacker-controlled input
108
+ readFile('../../../../etc/passwd');
109
+ writeFile('../../../../root/.ssh/authorized_keys', maliciousKey);
110
+ ```
111
+
112
+ **Impact**:
113
+ - **Read sensitive files** outside project directory
114
+ - **Write to arbitrary locations** on filesystem
115
+ - **Privilege escalation** if run with elevated permissions
116
+
117
+ **CVSS Score**: 8.6 (High)
118
+ **CWE**: CWE-22 (Path Traversal)
119
+
120
+ **Current Protection**:
121
+ - ✅ `change-applier.ts` validates paths are within project directory
122
+ - ❌ `file-utils.ts` has NO validation
123
+
124
+ **Fix**:
125
+ ```typescript
126
+ import * as path from 'path';
127
+ import * as fs from 'fs';
128
+
129
+ const PROJECT_ROOT = process.cwd();
130
+
131
+ function validatePath(filePath: string): string {
132
+ const absolutePath = path.resolve(filePath);
133
+ const normalizedPath = path.normalize(absolutePath);
134
+
135
+ // Ensure path is within project directory
136
+ if (!normalizedPath.startsWith(PROJECT_ROOT)) {
137
+ throw new Error(`Path traversal detected: ${filePath}`);
138
+ }
139
+
140
+ // Reject paths to protected directories
141
+ const relativePath = path.relative(PROJECT_ROOT, normalizedPath);
142
+ const components = relativePath.split(path.sep);
143
+ if (components.includes('.git') || components.includes('node_modules')) {
144
+ throw new Error(`Access to protected directory denied: ${relativePath}`);
145
+ }
146
+
147
+ return normalizedPath;
148
+ }
149
+
150
+ export function readFile(filePath: string): string {
151
+ const safePath = validatePath(filePath);
152
+ return fs.readFileSync(safePath, 'utf-8');
153
+ }
154
+ ```
155
+
156
+ ---
157
+
158
+ ### 🟠 HIGH: Insufficient Input Validation
159
+
160
+ **Location**: Multiple files
161
+
162
+ **Issues**:
163
+ 1. **No file extension validation** - `file-utils.ts` accepts any file type
164
+ 2. **No content validation** - LLM responses not sanitized before file write
165
+ 3. **No size limits on user input** - CLI accepts unlimited input
166
+
167
+ **Attack Vector**:
168
+ ```typescript
169
+ // Write non-code files
170
+ applyChanges([{ file: 'malicious.sh', newContent: '#!/bin/bash\nrm -rf /', reason: 'test' }]);
171
+
172
+ // Write oversized content
173
+ applyChanges([{ file: 'bomb.ts', newContent: 'x'.repeat(1e9), reason: 'test' }]);
174
+ ```
175
+
176
+ **Fix**:
177
+ - Add file extension whitelist (`.ts`, `.tsx`, `.js`, `.jsx` only)
178
+ - Validate LLM output contains valid code syntax
179
+ - Add rate limiting to CLI commands
180
+ - Enforce size limits before processing
181
+
182
+ ---
183
+
184
+ ### 🟠 HIGH: Missing Dependency Pinning
185
+
186
+ **Location**: `package.json`
187
+
188
+ **Issue**: Using caret ranges (`^`) allows automatic minor/patch updates that may introduce vulnerabilities.
189
+
190
+ **Risk**:
191
+ - Transitive dependency vulnerabilities
192
+ - Breaking changes in patch versions
193
+ - Supply chain attacks through compromised updates
194
+
195
+ **Current**:
196
+ ```json
197
+ "@anthropic-ai/sdk": "^0.30.0"
198
+ ```
199
+
200
+ **Recommended**:
201
+ ```json
202
+ "@anthropic-ai/sdk": "0.72.1"
203
+ ```
204
+
205
+ And use `npm audit` + `npm outdated` in CI/CD to monitor updates.
206
+
207
+ ---
208
+
209
+ ### 🟡 MEDIUM: API Key Exposure Risk
210
+
211
+ **Location**: Multiple files
212
+
213
+ **Issues**:
214
+ 1. **API key in environment variable** - can be logged/exposed
215
+ 2. **No key rotation mechanism** - compromised keys stay valid indefinitely
216
+ 3. **No rate limiting** - API key can be abused for unlimited requests
217
+
218
+ **Recommendations**:
219
+ - Add `.env` file support with proper .gitignore
220
+ - Implement key rotation notifications
221
+ - Add rate limiting per API key
222
+ - Warn users to use restricted API keys (not account-level keys)
223
+
224
+ ---
225
+
226
+ ### 🟡 MEDIUM: Race Conditions in File Operations
227
+
228
+ **Location**: `src/coordination/file-locks.ts`
229
+
230
+ **Current Protection**: ✅ Atomic file locking with `O_CREAT|O_EXCL`
231
+
232
+ **Residual Risk**:
233
+ - Lock files not cleaned up on process crash
234
+ - No lock timeout enforcement (5-minute expiration not automatically enforced)
235
+ - PID liveness check vulnerable to PID reuse
236
+
237
+ **Recommendations**:
238
+ - Add lock cleanup on process startup
239
+ - Implement active lock timeout checking
240
+ - Use stronger lock identifiers (PID + random nonce)
241
+
242
+ ---
243
+
244
+ ## 3. LLM-Specific Security
245
+
246
+ ### 3.1 Prompt Injection Risk: LOW
247
+
248
+ **Location**: `src/prompts/*.ts`
249
+
250
+ **Current Protection**:
251
+ - ✅ Structured prompts with clear sections
252
+ - ✅ File content passed as separate context
253
+ - ✅ No user-controlled system prompts
254
+
255
+ **Residual Risk**:
256
+ - Malicious code in files could influence LLM to generate harmful changes
257
+ - No content filtering on LLM responses
258
+
259
+ **Recommendation**: Add response validation to detect and reject:
260
+ - Shell commands in code output
261
+ - Credential patterns (API keys, passwords)
262
+ - Suspicious imports (`child_process`, `fs`, `net` without context)
263
+
264
+ ---
265
+
266
+ ### 3.2 Cost Control: MEDIUM
267
+
268
+ **Location**: `src/llm/anthropic-client.ts`
269
+
270
+ **Current Protection**:
271
+ - ✅ Cost tracking and logging
272
+ - ❌ No hard spending limits
273
+ - ❌ No user-configurable budgets
274
+
275
+ **Recommendation**:
276
+ ```typescript
277
+ const MAX_DAILY_COST = parseFloat(process.env.MAX_DAILY_COST || '10.00');
278
+ const MAX_SINGLE_REQUEST_COST = parseFloat(process.env.MAX_SINGLE_REQUEST_COST || '1.00');
279
+
280
+ async function callLLM(request: LLMRequest): Promise<LLMResponse> {
281
+ // Check daily budget
282
+ const dailyCost = await getDailyCost();
283
+ if (dailyCost >= MAX_DAILY_COST) {
284
+ throw new Error(`Daily budget exceeded: $${dailyCost.toFixed(2)}`);
285
+ }
286
+
287
+ // Estimate request cost
288
+ const estimatedCost = estimateRequestCost(request);
289
+ if (estimatedCost >= MAX_SINGLE_REQUEST_COST) {
290
+ throw new Error(`Request too expensive: $${estimatedCost.toFixed(2)}`);
291
+ }
292
+
293
+ // ... proceed with request
294
+ }
295
+ ```
296
+
297
+ ---
298
+
299
+ ## 4. Recommended Security Enhancements
300
+
301
+ ### Priority 1 (Critical - Fix Before Release)
302
+
303
+ - [ ] **Fix command injection** in `debt.ts` and `churn.ts` (use `execFile`)
304
+ - [ ] **Add path validation** to all `file-utils.ts` functions
305
+ - [ ] **Upgrade @anthropic-ai/sdk** to 0.72.1
306
+
307
+ ### Priority 2 (High - Fix Within 1 Week)
308
+
309
+ - [ ] **Add input validation** (file extensions, content size)
310
+ - [ ] **Pin dependency versions** in package.json
311
+ - [ ] **Add security tests** for injection and traversal attacks
312
+ - [ ] **Upgrade dev dependencies** (vitest, eslint)
313
+
314
+ ### Priority 3 (Medium - Fix Within 1 Month)
315
+
316
+ - [ ] **Implement API key rotation** notifications
317
+ - [ ] **Add cost control** (daily budgets, request limits)
318
+ - [ ] **Add LLM response validation** (detect malicious patterns)
319
+ - [ ] **Improve lock file cleanup** on crashes
320
+
321
+ ### Priority 4 (Low - Nice to Have)
322
+
323
+ - [ ] **Add security.txt** for responsible disclosure
324
+ - [ ] **Set up automated security scanning** (Dependabot, Snyk)
325
+ - [ ] **Add OWASP ZAP integration** for security testing
326
+ - [ ] **Create security documentation** for users
327
+
328
+ ---
329
+
330
+ ## 5. Security Testing Checklist
331
+
332
+ ### Manual Tests
333
+
334
+ ```bash
335
+ # Test command injection protection
336
+ npm test -- tests/security/command-injection.test.ts
337
+
338
+ # Test path traversal protection
339
+ npm test -- tests/security/path-traversal.test.ts
340
+
341
+ # Test input validation
342
+ npm test -- tests/security/input-validation.test.ts
343
+ ```
344
+
345
+ ### Automated Scanning
346
+
347
+ ```bash
348
+ # Run npm audit
349
+ npm audit
350
+
351
+ # Run SAST (if configured)
352
+ npm run security:scan
353
+
354
+ # Check for hardcoded secrets
355
+ git secrets --scan
356
+ ```
357
+
358
+ ---
359
+
360
+ ## 6. Security Contact
361
+
362
+ For security issues, please email: security@camplight.net
363
+
364
+ **Do NOT open public GitHub issues for security vulnerabilities.**
365
+
366
+ ---
367
+
368
+ ## Appendix: OWASP Top 10 Compliance
369
+
370
+ | Risk | Status | Notes |
371
+ |------|--------|-------|
372
+ | A01: Broken Access Control | ⚠️ PARTIAL | Path validation in change-applier only |
373
+ | A02: Cryptographic Failures | ✅ OK | API keys via env vars |
374
+ | A03: Injection | ❌ VULNERABLE | Command injection in signals |
375
+ | A04: Insecure Design | ✅ OK | Good architecture patterns |
376
+ | A05: Security Misconfiguration | ⚠️ PARTIAL | No default security headers |
377
+ | A06: Vulnerable Components | ⚠️ PARTIAL | 7 outdated packages |
378
+ | A07: Auth Failures | N/A | No auth system |
379
+ | A08: Software/Data Integrity | ⚠️ PARTIAL | No subresource integrity |
380
+ | A09: Logging Failures | ✅ OK | Good logging system |
381
+ | A10: SSRF | ✅ OK | No server-side requests |
382
+
383
+ ---
384
+
385
+ **Report Generated**: 2026-01-31
386
+ **Tool**: Claude Code Security Audit
387
+ **Version**: 2.1.0