anvil-engineering-workbench 1.0.1 → 1.0.4

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 (53) hide show
  1. package/CHANGELOG.md +41 -0
  2. package/README.md +20 -11
  3. package/SECURITY.md +1 -1
  4. package/dist/cli.js +276 -183
  5. package/dist/cli.js.map +1 -1
  6. package/dist/core/agent-config-release.js +1 -1
  7. package/dist/core/agent-config-versioning.js +1 -1
  8. package/dist/core/agent-evaluation-intelligence.js +1 -1
  9. package/dist/core/agent-evolution.js +1 -1
  10. package/dist/core/agent-experiment-studio.js +2 -2
  11. package/dist/core/agent-optimization.js +1 -1
  12. package/dist/core/agent-security-audit.js +1 -1
  13. package/dist/core/architecture-map.js +181 -20
  14. package/dist/core/architecture-map.js.map +1 -1
  15. package/dist/core/benchmark-engine.js +1 -1
  16. package/dist/core/benchmark-matrix.js +1 -1
  17. package/dist/core/benchmark-regression.js +1 -1
  18. package/dist/core/change-intelligence.js +1 -1
  19. package/dist/core/code-intelligence.js +1 -1
  20. package/dist/core/code-review.js +1 -1
  21. package/dist/core/dashboard-server.js +48 -44
  22. package/dist/core/dashboard-server.js.map +1 -1
  23. package/dist/core/dependency-impact.js +1 -1
  24. package/dist/core/dependency-intelligence.js +1 -1
  25. package/dist/core/doctor.d.ts +6 -0
  26. package/dist/core/doctor.js +175 -19
  27. package/dist/core/doctor.js.map +1 -1
  28. package/dist/core/engineering-risk.js +1 -1
  29. package/dist/core/git-intelligence.js +1 -1
  30. package/dist/core/intelligence-timeline.js +1 -1
  31. package/dist/core/patch-validation.js +1 -1
  32. package/dist/core/project-cleaner.d.ts +78 -0
  33. package/dist/core/project-cleaner.js +847 -0
  34. package/dist/core/project-cleaner.js.map +1 -0
  35. package/dist/core/project-health.js +1 -1
  36. package/dist/core/project-inspector.js +2 -2
  37. package/dist/core/quality-audit.js +2 -2
  38. package/dist/core/regression-intelligence.js +1 -1
  39. package/dist/core/remediation-planner.js +4 -4
  40. package/dist/core/review-history.js +1 -1
  41. package/dist/core/sandbox-cleanup-audit.js +2 -2
  42. package/dist/core/sandbox-compliance.js +1 -1
  43. package/dist/core/sandbox-lifecycle.js +3 -3
  44. package/dist/core/sandbox-policy.js +1 -1
  45. package/dist/core/sandbox-runtime.js +1 -1
  46. package/dist/core/skill-registry.js +1 -1
  47. package/dist/core/verification.js +1 -1
  48. package/dist/index.d.ts +2 -1
  49. package/dist/index.js +2 -1
  50. package/dist/index.js.map +1 -1
  51. package/dist/mcp/server.js +38 -1
  52. package/dist/mcp/server.js.map +1 -1
  53. package/package.json +11 -3
package/dist/cli.js CHANGED
@@ -96,12 +96,12 @@ function runSandboxProbe(args) {
96
96
  });
97
97
  }
98
98
  function readAgentTokenBudgets() {
99
- const raw = process.env.FORGE_MAX_ESTIMATED_TOKENS_PER_AGENT;
99
+ const raw = process.env.ANVIL_MAX_ESTIMATED_TOKENS_PER_AGENT ?? process.env.FORGE_MAX_ESTIMATED_TOKENS_PER_AGENT;
100
100
  if (!raw)
101
101
  return undefined;
102
102
  const parsed = JSON.parse(raw);
103
103
  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
104
- throw new Error("FORGE_MAX_ESTIMATED_TOKENS_PER_AGENT must be a JSON object mapping agent IDs to token limits.");
104
+ throw new Error("ANVIL_MAX_ESTIMATED_TOKENS_PER_AGENT must be a JSON object mapping agent IDs to token limits.");
105
105
  const budgets = {};
106
106
  for (const [agent, value] of Object.entries(parsed)) {
107
107
  if (!agent.trim() || !Number.isSafeInteger(value) || value < 1)
@@ -111,12 +111,12 @@ function readAgentTokenBudgets() {
111
111
  return budgets;
112
112
  }
113
113
  function readAgentDurationBudgets() {
114
- const raw = process.env.FORGE_MAX_TASK_DURATION_MS_BY_AGENT;
114
+ const raw = process.env.ANVIL_MAX_TASK_DURATION_MS_BY_AGENT ?? process.env.FORGE_MAX_TASK_DURATION_MS_BY_AGENT;
115
115
  if (!raw)
116
116
  return undefined;
117
117
  const parsed = JSON.parse(raw);
118
118
  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
119
- throw new Error("FORGE_MAX_TASK_DURATION_MS_BY_AGENT must be a JSON object mapping agent IDs to milliseconds.");
119
+ throw new Error("ANVIL_MAX_TASK_DURATION_MS_BY_AGENT must be a JSON object mapping agent IDs to milliseconds.");
120
120
  const budgets = {};
121
121
  for (const [agent, value] of Object.entries(parsed)) {
122
122
  if (!agent.trim() || !Number.isSafeInteger(value) || value < 1)
@@ -125,97 +125,104 @@ function readAgentDurationBudgets() {
125
125
  }
126
126
  return budgets;
127
127
  }
128
- const VERSION = "1.0.0";
129
- const HELP = `
130
- ANVIL — The AI Engineering Workbench
131
-
132
- Usage:
133
- anvil <command> [options]
134
- forge <command> [options]
135
-
136
- Commands:
137
- init [path] Create a safe, local-first .forge starter workspace
138
- inspect [path] Analyze project languages, tooling, dependencies, and scripts
139
- evaluate RUNID Score a saved run against a local evaluation suite
140
- benchmark [RUN_ID] [--suite SUITE_ID] [--path PROJECT] Record or view benchmark results
141
- benchmark-matrix CONFIG.json --suite SUITE_ID --goal "..." [--path PROJECT] Run model comparisons
142
- benchmark-regression [MATRIX_ID] [--path PROJECT] Compare latest matrix with its baseline
143
- optimize-agents [--path PROJECT] Recommend evidence-based agent improvements
144
- agent-intelligence [--suite ID] [--candidate ID] [--limit N] [--json] [--path PROJECT] Score agent effectiveness across benchmark history
145
- agent-evolution MATRIX_ID [--path PROJECT] Evaluate a controlled baseline/treatment experiment
146
- experiment-studio <create|compare> [options] Scaffold a skill or multi-model experiment
147
- experiment-history [--suite ID] [--candidate ID] [--limit N] [--json] [--path PROJECT] Rank historical benchmark candidates
148
- agent-config <snapshot|list|show|diff|approve> [options] Version and review agent/skill configuration
149
- agent-release <prepare|list|show|approve|reject> [options] Gate agent configuration promotion
150
- experiment <capture|show|compare> [options] Capture and compare reproducible benchmark manifests
151
- quality [path] Generate an evidence-based static engineering quality report
152
- deps [path] Analyze npm dependencies, licenses, and imported security reports
153
- remediate [path] Advisory remediation plan for vulnerable and outdated dependencies
154
- snapshot [path] Capture a local engineering intelligence snapshot
155
- timeline [path] Compare the latest snapshot with its predecessor
156
- change-risk [path] Analyze changed-file risk, downstream impact, and test candidates
157
- risk [path] Rank engineering hotspots using dependency and quality signals
158
- health [path] Generate a unified engineering score, evidence coverage, and health snapshot
159
- deep [path] Analyze AST symbols, circular imports, and change impact
160
- git [path] Analyze changed files, impact, suggested tests, and risk
161
- impact [path] Analyze dependency change blast radius and undeclared imports
162
- search QUERY Symbol-aware source code search (use --limit N, --path PROJECT)
163
- review [path] Review changed source files; add --ai for provider-backed suggestions
164
- review-history [path] List saved review snapshots
165
- review-show ID Display one saved review snapshot
166
- review-compare A B Compare two saved reviews
167
- patch-check ID N Dry-run validate AI patch N from a saved review
168
- patch-approve REVIEW_ID N --reviewer NAME Formally record human approval for AI suggestion N
169
- patch-approval-check ID Verify cryptographic approval validity and expiration
170
- patch-stage APPROVAL_ID Stage approved patch in an isolated temporary workspace
171
- patch-review STAGE_ID Review staged patch diff against source without modifying project
172
- regression [path] Compare verification history with Git changes and impact
173
- verify --list Discover available npm scripts without running them
174
- verify SCRIPT Explicitly run one selected npm script and record its result
175
- patch-verify ID SCRIPT Verify an approved staged patch in a temporary workspace
176
- sandbox-status Inspect Docker availability and advertised security options
177
- sandbox-compliance [PROFILE] [IMAGE@sha256:DIGEST] Generate a sandbox compliance report
178
- sandbox-policy-check POLICY.json Validate a fail-closed sandbox policy file
179
- sandbox-profiles [NAME] List or inspect built-in sandbox security profiles
180
- sandbox-cleanup Review stopped FORGE containers; add --apply to remove them
181
- sandbox-cleanup-history [PATH] Show recorded cleanup activity
182
- verify-history List saved verification runs for a project
183
- map [path] Map source modules and import relationships
184
- agents [path] List built-in and workspace agent roles
185
- memory <action> Manage local project memory (add, list, remove, context)
186
- skills [path] List built-in and workspace skills
187
- hooks [path] List configured declarative lifecycle hooks
188
- agent-security [path] Audit agent instructions, skills, hooks, and permissions
189
- plan --goal TEXT Create and save a reviewable draft plan
190
- run --goal TEXT Run the plan using a configured AI provider
191
- runs [path] List locally saved run history (add --json for versioned JSON)
192
- evals [path] List local agent evaluation suites
193
- trace RUNID Show per-agent execution telemetry
194
- replay RUNID Create a new run from retryable failed tasks
195
- resume RUNID Continue pending or approved tasks in a saved run
196
- approve RUNID TASK_ID Approve a task awaiting human review
197
- show-run ID Display one saved run (use --path for project directory)
198
- doctor [path] Run environment health checks (Node, git, Docker, API keys)
199
- dashboard [path] Start the local read-only web dashboard
200
- version Print the installed version
201
- help Show this help message
202
-
203
- Options:
204
- --json Output machine-readable JSON
205
- --help Show command usage
206
-
207
- Examples:
208
- forge inspect .
209
- forge inspect ./my-app --json
210
- forge map .
211
- forge agents .
212
- forge plan --goal "Add authentication safely"
213
- forge run --goal "Review the API design"
214
- forge runs .
215
- forge replay forge-RUN-ID
216
- forge approve forge-RUN-ID TASK_ID
217
- forge resume forge-RUN-ID
218
- forge dashboard .
128
+ const VERSION = "1.0.3";
129
+ const HELP = `
130
+ ANVIL — The AI Engineering Workbench
131
+
132
+ Usage:
133
+ anvil <command> [options]
134
+
135
+ Commands:
136
+ init [path] Create a safe, local-first .anvil starter workspace
137
+ inspect [path] Analyze project languages, tooling, dependencies, and scripts
138
+ evaluate RUNID Score a saved run against a local evaluation suite
139
+ benchmark [RUN_ID] [--suite SUITE_ID] [--path PROJECT] Record or view benchmark results
140
+ benchmark-matrix CONFIG.json --suite SUITE_ID --goal "..." [--path PROJECT] Run model comparisons
141
+ benchmark-regression [MATRIX_ID] [--path PROJECT] Compare latest matrix with its baseline
142
+ optimize-agents [--path PROJECT] Recommend evidence-based agent improvements
143
+ agent-intelligence [--suite ID] [--candidate ID] [--limit N] [--json] [--path PROJECT] Score agent effectiveness across benchmark history
144
+ agent-evolution MATRIX_ID [--path PROJECT] Evaluate a controlled baseline/treatment experiment
145
+ experiment-studio <create|compare> [options] Scaffold a skill or multi-model experiment
146
+ experiment-history [--suite ID] [--candidate ID] [--limit N] [--json] [--path PROJECT] Rank historical benchmark candidates
147
+ agent-config <snapshot|list|show|diff|approve> [options] Version and review agent/skill configuration
148
+ agent-release <prepare|list|show|approve|reject> [options] Gate agent configuration promotion
149
+ experiment <capture|show|compare> [options] Capture and compare reproducible benchmark manifests
150
+ quality [path] Generate an evidence-based static engineering quality report
151
+ clean [path] Clean farzi/junk files and logs; use --apply to delete, --fix to repair code
152
+ fix [path] Auto-fix code issues, unused imports, and formatting
153
+ deps [path] Analyze npm dependencies, licenses, and imported security reports
154
+ remediate [path] Advisory remediation plan for vulnerable and outdated dependencies
155
+ snapshot [path] Capture a local engineering intelligence snapshot
156
+ timeline [path] Compare the latest snapshot with its predecessor
157
+ change-risk [path] Analyze changed-file risk, downstream impact, and test candidates
158
+ risk [path] Rank engineering hotspots using dependency and quality signals
159
+ health [path] Generate a unified engineering score, evidence coverage, and health snapshot
160
+ deep [path] Analyze AST symbols, circular imports, and change impact
161
+ git [path] Analyze changed files, impact, suggested tests, and risk
162
+ impact [path] Analyze dependency change blast radius and undeclared imports
163
+ search QUERY Symbol-aware source code search (use --limit N, --path PROJECT)
164
+ review [path] Review changed source files; add --ai for provider-backed suggestions
165
+ review-history [path] List saved review snapshots
166
+ review-show ID Display one saved review snapshot
167
+ review-compare A B Compare two saved reviews
168
+ patch-check ID N Dry-run validate AI patch N from a saved review
169
+ patch-approve REVIEW_ID N --reviewer NAME Formally record human approval for AI suggestion N
170
+ patch-approval-check ID Verify cryptographic approval validity and expiration
171
+ patch-stage APPROVAL_ID Stage approved patch in an isolated temporary workspace
172
+ patch-review STAGE_ID Review staged patch diff against source without modifying project
173
+ regression [path] Compare verification history with Git changes and impact
174
+ verify --list Discover available npm scripts without running them
175
+ verify SCRIPT Explicitly run one selected npm script and record its result
176
+ patch-verify ID SCRIPT Verify an approved staged patch in a temporary workspace
177
+ sandbox-status Inspect Docker availability and advertised security options
178
+ sandbox-compliance [PROFILE] [IMAGE@sha256:DIGEST] Generate a sandbox compliance report
179
+ sandbox-policy-check POLICY.json Validate a fail-closed sandbox policy file
180
+ sandbox-profiles [NAME] List or inspect built-in sandbox security profiles
181
+ sandbox-cleanup Review stopped ANVIL containers; add --apply to remove them
182
+ sandbox-cleanup-history [PATH] Show recorded cleanup activity
183
+ verify-history List saved verification runs for a project
184
+ map [path] Map source modules and import relationships
185
+ agents [path] List built-in and workspace agent roles
186
+ memory <action> Manage local project memory (add, list, remove, context)
187
+ skills [path] List built-in and workspace skills
188
+ hooks [path] List configured declarative lifecycle hooks
189
+ agent-security [path] Audit agent instructions, skills, hooks, and permissions
190
+ plan --goal TEXT Create and save a reviewable draft plan
191
+ run --goal TEXT Run the plan using a configured AI provider
192
+ runs [path] List locally saved run history (add --json for versioned JSON)
193
+ evals [path] List local agent evaluation suites
194
+ trace RUNID Show per-agent execution telemetry
195
+ replay RUNID Create a new run from retryable failed tasks
196
+ resume RUNID Continue pending or approved tasks in a saved run
197
+ approve RUNID TASK_ID Approve a task awaiting human review
198
+ show-run ID Display one saved run (use --path for project directory)
199
+ clean [path] Scan and delete junk, logs, temp downloads; add --apply and --fix
200
+ fix [path] Auto-repair code errors, trim whitespace & prune unused imports (add --verify)
201
+ undo [path] Rollback the last anvil clean/fix operation using saved snapshot backup
202
+ hook install Install ANVIL automated pre-commit hook into Git
203
+ doctor [path] Run environment health checks; add --fix to auto-scaffold config
204
+ dashboard [path] Start the local read-only web dashboard
205
+ version Print the installed version
206
+ help Show this help message
207
+
208
+ Options:
209
+ --json Output machine-readable JSON
210
+ --help Show command usage
211
+
212
+ Examples:
213
+ anvil inspect .
214
+ anvil clean .
215
+ anvil clean . --apply --fix
216
+ anvil inspect ./my-app --json
217
+ anvil map .
218
+ anvil agents .
219
+ anvil plan --goal "Add authentication safely"
220
+ anvil run --goal "Review the API design"
221
+ anvil runs .
222
+ anvil replay anvil-RUN-ID
223
+ anvil approve anvil-RUN-ID TASK_ID
224
+ anvil resume anvil-RUN-ID
225
+ anvil dashboard .
219
226
  `.trim();
220
227
  async function main(args) {
221
228
  const [command = "help", ...rest] = args;
@@ -228,13 +235,13 @@ async function main(args) {
228
235
  case "version":
229
236
  case "--version":
230
237
  case "-v":
231
- process.stdout.write(`forge ${VERSION}\n`);
238
+ process.stdout.write(`anvil ${VERSION}\n`);
232
239
  return;
233
240
  case "init": {
234
241
  const target = rest.find(arg => !arg.startsWith("--")) ?? ".";
235
242
  try {
236
243
  const result = await initializeProject(path.resolve(target));
237
- process.stdout.write(`FORGE initialized in ${path.resolve(target)}\n`);
244
+ process.stdout.write(`ANVIL initialized in ${path.resolve(target)}\n`);
238
245
  for (const file of result.created)
239
246
  process.stdout.write(` created ${file}\n`);
240
247
  for (const file of result.skipped)
@@ -242,7 +249,7 @@ async function main(args) {
242
249
  }
243
250
  catch (error) {
244
251
  const message = error instanceof Error ? error.message : String(error);
245
- process.stderr.write(`FORGE could not initialize this project: ${message}\n`);
252
+ process.stderr.write(`ANVIL could not initialize this project: ${message}\n`);
246
253
  process.exitCode = 1;
247
254
  }
248
255
  return;
@@ -270,7 +277,7 @@ async function main(args) {
270
277
  const [candidateVersionId, baselineVersionId] = args;
271
278
  const matrixId = option("--matrix");
272
279
  if (!candidateVersionId || !baselineVersionId || !matrixId)
273
- throw new Error("Usage: forge agent-release prepare CANDIDATE_CONFIG_ID BASELINE_CONFIG_ID --matrix MATRIX_ID --path PROJECT");
280
+ throw new Error("Usage: anvil agent-release prepare CANDIDATE_CONFIG_ID BASELINE_CONFIG_ID --matrix MATRIX_ID --path PROJECT");
274
281
  const regression = await loadBenchmarkRegression(target, matrixId);
275
282
  const release = await prepareAgentConfigRelease(target, { candidateVersionId, baselineVersionId, regression });
276
283
  process.stdout.write(formatAgentConfigRelease(release) + "\nHuman approval is still required. No live files were changed.\n");
@@ -282,7 +289,7 @@ async function main(args) {
282
289
  else if (action === "show") {
283
290
  const id = args[0];
284
291
  if (!id)
285
- throw new Error("Usage: forge agent-release show RELEASE_ID --path PROJECT");
292
+ throw new Error("Usage: anvil agent-release show RELEASE_ID --path PROJECT");
286
293
  const item = (await listAgentConfigReleases(target)).find(entry => entry.id === id);
287
294
  if (!item)
288
295
  throw new Error("Release not found: " + id);
@@ -291,7 +298,7 @@ async function main(args) {
291
298
  else if (action === "approve" || action === "reject") {
292
299
  const id = args[0];
293
300
  if (!id)
294
- throw new Error("Usage: forge agent-release approve|reject RELEASE_ID --reviewer NAME --path PROJECT");
301
+ throw new Error("Usage: anvil agent-release approve|reject RELEASE_ID --reviewer NAME --path PROJECT");
295
302
  const reviewer = option("--reviewer");
296
303
  if (!reviewer?.trim())
297
304
  throw new Error("A reviewer is required via --reviewer NAME.");
@@ -302,7 +309,7 @@ async function main(args) {
302
309
  throw new Error("Unknown action. Use prepare, list, show, approve or reject.");
303
310
  }
304
311
  catch (error) {
305
- process.stderr.write("FORGE agent release failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
312
+ process.stderr.write("ANVIL agent release failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
306
313
  process.exitCode = 1;
307
314
  }
308
315
  return;
@@ -325,12 +332,12 @@ async function main(args) {
325
332
  else if (action === "show") {
326
333
  const id = ids[0];
327
334
  if (!id)
328
- throw new Error("Usage: forge agent-config show CONFIG_ID --path PROJECT");
335
+ throw new Error("Usage: anvil agent-config show CONFIG_ID --path PROJECT");
329
336
  process.stdout.write(formatAgentConfigVersion(await loadAgentConfigVersion(target, id)) + "\n");
330
337
  }
331
338
  else if (action === "diff") {
332
339
  if (ids.length < 2)
333
- throw new Error("Usage: forge agent-config diff BEFORE_ID AFTER_ID --path PROJECT");
340
+ throw new Error("Usage: anvil agent-config diff BEFORE_ID AFTER_ID --path PROJECT");
334
341
  const [before, after] = await Promise.all([loadAgentConfigVersion(target, ids[0]), loadAgentConfigVersion(target, ids[1])]);
335
342
  const diff = compareAgentConfigVersions(before, after);
336
343
  process.stdout.write(["Agent configuration diff", "Added: " + (diff.added.join(", ") || "none"), "Changed: " + (diff.changed.join(", ") || "none"), "Removed: " + (diff.removed.join(", ") || "none"), "Unchanged: " + diff.unchanged.length].join("\n") + "\n");
@@ -342,7 +349,7 @@ async function main(args) {
342
349
  throw new Error("Unknown action. Use snapshot, list, show or diff.");
343
350
  }
344
351
  catch (error) {
345
- process.stderr.write("FORGE agent configuration command failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
352
+ process.stderr.write("ANVIL agent configuration command failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
346
353
  process.exitCode = 1;
347
354
  }
348
355
  return;
@@ -354,7 +361,7 @@ async function main(args) {
354
361
  const rawLimit = option("--limit");
355
362
  const limit = rawLimit === undefined ? undefined : Number(rawLimit);
356
363
  if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)) {
357
- process.stderr.write("FORGE experiment history: --limit must be an integer from 1 to 100.\n");
364
+ process.stderr.write("ANVIL experiment history: --limit must be an integer from 1 to 100.\n");
358
365
  process.exitCode = 1;
359
366
  return;
360
367
  }
@@ -366,7 +373,7 @@ async function main(args) {
366
373
  process.stdout.write(rest.includes("--json") ? JSON.stringify(history, null, 2) + "\n" : formatExperimentHistory(history) + "\n");
367
374
  }
368
375
  catch (error) {
369
- process.stderr.write("FORGE experiment history failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
376
+ process.stderr.write("ANVIL experiment history failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
370
377
  process.exitCode = 1;
371
378
  }
372
379
  return;
@@ -375,7 +382,7 @@ async function main(args) {
375
382
  const action = rest[0] ?? "create";
376
383
  const option = (name) => { const index = rest.indexOf(name); return index >= 0 ? rest[index + 1] : undefined; };
377
384
  if (action !== "create" && action !== "compare") {
378
- process.stderr.write("Usage: forge experiment-studio compare --id ID --name NAME --candidates id:provider:model,id:provider:model [--config-versions id=cfg-id,id=cfg-id] [--repeats 2] [--path PROJECT]\n");
385
+ process.stderr.write("Usage: anvil experiment-studio compare --id ID --name NAME --candidates id:provider:model,id:provider:model [--config-versions id=cfg-id,id=cfg-id] [--repeats 2] [--path PROJECT]\n");
379
386
  process.stderr.write(" or: forge experiment-studio create --id ID --name NAME --provider PROVIDER --model MODEL --skills skill-a,skill-b [--repeats 2] [--path PROJECT]\n");
380
387
  process.exitCode = 1;
381
388
  return;
@@ -388,7 +395,7 @@ async function main(args) {
388
395
  const pathIndex = rest.indexOf("--path");
389
396
  const target = path.resolve(pathIndex >= 0 ? rest[pathIndex + 1] ?? "." : ".");
390
397
  if (!id || !name || !rawCandidates) {
391
- process.stderr.write("Usage: forge experiment-studio compare --id ID --name NAME --candidates id:provider:model,id:provider:model [--repeats 2] [--path PROJECT]\n");
398
+ process.stderr.write("Usage: anvil experiment-studio compare --id ID --name NAME --candidates id:provider:model,id:provider:model [--repeats 2] [--path PROJECT]\n");
392
399
  process.exitCode = 1;
393
400
  return;
394
401
  }
@@ -423,7 +430,7 @@ async function main(args) {
423
430
  process.stdout.write(formatModelComparisonMatrix(matrix) + "\nSaved: " + path.relative(target, destination) + "\n");
424
431
  }
425
432
  catch (error) {
426
- process.stderr.write("FORGE model comparison failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
433
+ process.stderr.write("ANVIL model comparison failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
427
434
  process.exitCode = 1;
428
435
  }
429
436
  return;
@@ -435,7 +442,7 @@ async function main(args) {
435
442
  const pathIndex = rest.indexOf("--path");
436
443
  const target = path.resolve(pathIndex >= 0 ? rest[pathIndex + 1] ?? "." : ".");
437
444
  if (!id || !name || !model || !skills) {
438
- process.stderr.write("Usage: forge experiment-studio create --id ID --name NAME --provider openai|claude-code --model MODEL --skills skill-a,skill-b [--repeats 2] [--path PROJECT]\n");
445
+ process.stderr.write("Usage: anvil experiment-studio create --id ID --name NAME --provider openai|claude-code --model MODEL --skills skill-a,skill-b [--repeats 2] [--path PROJECT]\n");
439
446
  process.exitCode = 1;
440
447
  return;
441
448
  }
@@ -458,7 +465,7 @@ async function main(args) {
458
465
  process.stdout.write(formatSkillExperimentMatrix(matrix) + "\nSaved: " + path.relative(target, destination) + "\n");
459
466
  }
460
467
  catch (error) {
461
- process.stderr.write("FORGE experiment studio failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
468
+ process.stderr.write("ANVIL experiment studio failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
462
469
  process.exitCode = 1;
463
470
  }
464
471
  return;
@@ -468,7 +475,7 @@ async function main(args) {
468
475
  const pathIndex = rest.indexOf("--path");
469
476
  const target = path.resolve(pathIndex >= 0 ? rest[pathIndex + 1] ?? "." : ".");
470
477
  if (!matrixId || matrixId.startsWith("--")) {
471
- process.stderr.write("Usage: forge agent-evolution MATRIX_ID --path PROJECT\n");
478
+ process.stderr.write("Usage: anvil agent-evolution MATRIX_ID --path PROJECT\n");
472
479
  process.exitCode = 1;
473
480
  return;
474
481
  }
@@ -483,21 +490,21 @@ async function main(args) {
483
490
  process.exitCode = assessment.status === "insufficient-evidence" ? 2 : 1;
484
491
  }
485
492
  catch (error) {
486
- process.stderr.write("FORGE agent evolution failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
493
+ process.stderr.write("ANVIL agent evolution failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
487
494
  process.exitCode = 1;
488
495
  }
489
496
  return;
490
497
  }
491
498
  case "agent-intelligence": {
492
499
  if (rest.includes("--help")) {
493
- process.stdout.write("Usage: forge agent-intelligence [--suite ID] [--candidate ID] [--limit N] [--json] [--path PROJECT]\n" +
500
+ process.stdout.write("Usage: anvil agent-intelligence [--suite ID] [--candidate ID] [--limit N] [--json] [--path PROJECT]\n" +
494
501
  "Score agent effectiveness across benchmark history.\n\n" +
495
502
  "Options:\n" +
496
503
  " --suite ID Filter to a specific evaluation suite ID.\n" +
497
504
  " --candidate ID Filter to a specific candidate ID.\n" +
498
505
  " --limit N Number of historical runs to analyze (2–50, default 10).\n" +
499
506
  " --json Output the full intelligence report as machine-readable JSON.\n" +
500
- " --path PROJECT Path to the FORGE project directory (defaults to cwd).\n\n" +
507
+ " --path PROJECT Path to the ANVIL project directory (defaults to cwd).\n\n" +
501
508
  "Exit codes:\n" +
502
509
  " 0 Ready: at least one scorecard was produced.\n" +
503
510
  " 1 Error: an unexpected failure occurred.\n" +
@@ -516,7 +523,7 @@ async function main(args) {
516
523
  const rawLimit = option("--limit");
517
524
  const limit = rawLimit === undefined ? undefined : Number(rawLimit);
518
525
  if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 2 || limit > 50)) {
519
- process.stderr.write("FORGE agent intelligence: --limit must be an integer from 2 to 50.\n");
526
+ process.stderr.write("ANVIL agent intelligence: --limit must be an integer from 2 to 50.\n");
520
527
  process.exitCode = 1;
521
528
  return;
522
529
  }
@@ -536,7 +543,7 @@ async function main(args) {
536
543
  process.exitCode = 2;
537
544
  }
538
545
  catch (error) {
539
- process.stderr.write("FORGE agent intelligence failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
546
+ process.stderr.write("ANVIL agent intelligence failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
540
547
  process.exitCode = 1;
541
548
  }
542
549
  return;
@@ -552,7 +559,7 @@ async function main(args) {
552
559
  process.exitCode = 2;
553
560
  }
554
561
  catch (error) {
555
- process.stderr.write("FORGE adaptive agent optimization failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
562
+ process.stderr.write("ANVIL adaptive agent optimization failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
556
563
  process.exitCode = 1;
557
564
  }
558
565
  return;
@@ -568,7 +575,7 @@ async function main(args) {
568
575
  process.exitCode = 2;
569
576
  }
570
577
  catch (error) {
571
- process.stderr.write("FORGE benchmark regression failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
578
+ process.stderr.write("ANVIL benchmark regression failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
572
579
  process.exitCode = 1;
573
580
  }
574
581
  return;
@@ -586,7 +593,7 @@ async function main(args) {
586
593
  const provider = option("--provider") ?? process.env.FORGE_AI_PROVIDER ?? "openai";
587
594
  const model = option("--model") ?? process.env.FORGE_AI_MODEL ?? process.env.FORGE_MODEL ?? "gpt-4.1";
588
595
  if (!matrixFile || !suiteId || !matrixId)
589
- throw new Error("Usage: forge experiment capture --matrix-file CONFIG.json --matrix-id ID --suite SUITE_ID [--provider ID] [--model NAME] [--path PROJECT]");
596
+ throw new Error("Usage: anvil experiment capture --matrix-file CONFIG.json --matrix-id ID --suite SUITE_ID [--provider ID] [--model NAME] [--path PROJECT]");
590
597
  const matrix = await loadBenchmarkMatrix(path.resolve(matrixFile));
591
598
  const suites = await loadEvaluationSuites(target);
592
599
  const suite = suites.find(item => item.id === suiteId);
@@ -606,13 +613,13 @@ async function main(args) {
606
613
  else if (action === "show") {
607
614
  const id = rest[1];
608
615
  if (!id)
609
- throw new Error("Usage: forge experiment show EXPERIMENT_ID --path PROJECT");
616
+ throw new Error("Usage: anvil experiment show EXPERIMENT_ID --path PROJECT");
610
617
  process.stdout.write(formatExperimentManifest(await loadExperimentManifest(target, id)) + "\n");
611
618
  }
612
619
  else if (action === "compare") {
613
620
  const ids = rest.slice(1).filter((arg, index, all) => !arg.startsWith("--") && all[index - 1] !== "--path");
614
621
  if (ids.length !== 2)
615
- throw new Error("Usage: forge experiment compare EXPERIMENT_A EXPERIMENT_B --path PROJECT");
622
+ throw new Error("Usage: anvil experiment compare EXPERIMENT_A EXPERIMENT_B --path PROJECT");
616
623
  const [a, b] = await Promise.all([loadExperimentManifest(target, ids[0]), loadExperimentManifest(target, ids[1])]);
617
624
  const comparison = compareExperimentManifests(a, b);
618
625
  process.stdout.write("Experiment reproducibility: " + (comparison.compatible ? "COMPATIBLE" : "NOT COMPARABLE") + "\n" + (comparison.differences.length ? comparison.differences.map(item => " - " + item).join("\n") : " Critical manifest fields match.") + "\n");
@@ -623,7 +630,7 @@ async function main(args) {
623
630
  throw new Error("Unknown action. Use capture, show or compare.");
624
631
  }
625
632
  catch (error) {
626
- process.stderr.write("FORGE experiment command failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
633
+ process.stderr.write("ANVIL experiment command failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
627
634
  process.exitCode = 1;
628
635
  }
629
636
  return;
@@ -636,7 +643,7 @@ async function main(args) {
636
643
  const goalEnd = goalIndex >= 0 ? rest.findIndex((arg, index) => index > goalIndex && arg.startsWith("--")) : -1;
637
644
  const goal = goalIndex >= 0 ? rest.slice(goalIndex + 1, goalEnd >= 0 ? goalEnd : rest.length).join(" ").trim() : "";
638
645
  if (!configFile || !suiteId || !goal) {
639
- process.stderr.write("Usage: forge benchmark-matrix CONFIG.json --suite SUITE_ID --goal \"engineering task\" [--path PROJECT]\n");
646
+ process.stderr.write("Usage: anvil benchmark-matrix CONFIG.json --suite SUITE_ID --goal \"engineering task\" [--path PROJECT]\n");
640
647
  process.exitCode = 1;
641
648
  return;
642
649
  }
@@ -772,7 +779,7 @@ async function main(args) {
772
779
  const target = path.resolve(pathIndex >= 0 ? rest[pathIndex + 1] ?? "." : ".");
773
780
  const suiteId = suiteIndex >= 0 ? rest[suiteIndex + 1] : undefined;
774
781
  if (!runId) {
775
- process.stderr.write("Usage: forge evaluate RUNID [--suite SUITE_ID] [--path PROJECT]\n");
782
+ process.stderr.write("Usage: anvil evaluate RUNID [--suite SUITE_ID] [--path PROJECT]\n");
776
783
  process.exitCode = 1;
777
784
  return;
778
785
  }
@@ -824,7 +831,7 @@ async function main(args) {
824
831
  }
825
832
  catch (error) {
826
833
  const message = error instanceof Error ? error.message : String(error);
827
- process.stderr.write(`FORGE could not load agents: ${message}\n`);
834
+ process.stderr.write(`ANVIL could not load agents: ${message}\n`);
828
835
  process.exitCode = 1;
829
836
  }
830
837
  return;
@@ -879,7 +886,23 @@ async function main(args) {
879
886
  }
880
887
  return;
881
888
  }
889
+ case "hook":
882
890
  case "hooks": {
891
+ if (rest[0] === "install" || rest.includes("--install")) {
892
+ const target = path.resolve(rest.find(arg => !arg.startsWith("--") && arg !== "install" && arg !== "pre-commit") ?? ".");
893
+ try {
894
+ const { installPrecommitHook } = await import("./core/project-cleaner.js");
895
+ const result = await installPrecommitHook(target);
896
+ process.stdout.write(`${result.detail}\n`);
897
+ if (!result.success)
898
+ process.exitCode = 1;
899
+ }
900
+ catch (error) {
901
+ process.stderr.write("Could not install hook: " + (error instanceof Error ? error.message : String(error)) + "\n");
902
+ process.exitCode = 1;
903
+ }
904
+ return;
905
+ }
883
906
  const target = path.resolve(rest.find(arg => !arg.startsWith("--")) ?? ".");
884
907
  try {
885
908
  const hooks = await loadHooks(target);
@@ -906,7 +929,7 @@ async function main(args) {
906
929
  const content = option("--content");
907
930
  const allowed = ["decision", "architecture", "constraint", "preference", "fact"];
908
931
  if (!kind || !allowed.includes(kind) || !content)
909
- throw new Error("Usage: forge memory add [path] --kind decision|architecture|constraint|preference|fact --content TEXT [--tags a,b]");
932
+ throw new Error("Usage: anvil memory add [path] --kind decision|architecture|constraint|preference|fact --content TEXT [--tags a,b]");
910
933
  const tags = option("--tags")?.split(",") ?? [];
911
934
  const entry = await addProjectMemory(target, { kind, content, tags });
912
935
  process.stdout.write(`Saved ${entry.id} to .forge/memory.json\n`);
@@ -914,7 +937,7 @@ async function main(args) {
914
937
  else if (action === "remove") {
915
938
  const id = memoryArgs.find(arg => arg.startsWith("mem-"));
916
939
  if (!id)
917
- throw new Error("Usage: forge memory remove [path] mem-ID");
940
+ throw new Error("Usage: anvil memory remove [path] mem-ID");
918
941
  const removed = await removeProjectMemory(target, id);
919
942
  process.stdout.write(removed ? `Removed ${id}.\n` : `Memory entry ${id} was not found.\n`);
920
943
  }
@@ -947,7 +970,7 @@ async function main(args) {
947
970
  }
948
971
  catch (error) {
949
972
  const message = error instanceof Error ? error.message : String(error);
950
- process.stderr.write(`FORGE could not create a plan: ${message}\n`);
973
+ process.stderr.write(`ANVIL could not create a plan: ${message}\n`);
951
974
  process.exitCode = 1;
952
975
  }
953
976
  return;
@@ -958,7 +981,7 @@ async function main(args) {
958
981
  const target = path.resolve(pathIndex >= 0 ? rest[pathIndex + 1] ?? "." : ".");
959
982
  try {
960
983
  if (!runId)
961
- throw new Error("Usage: forge replay RUN_ID [--path PROJECT]");
984
+ throw new Error("Usage: anvil replay RUN_ID [--path PROJECT]");
962
985
  const source = await loadRun(target, runId);
963
986
  const replay = createReplayRun(source);
964
987
  const saved = await saveRun(target, replay);
@@ -981,7 +1004,7 @@ async function main(args) {
981
1004
  const reasonIndex = rest.indexOf("--reason");
982
1005
  try {
983
1006
  if (!runId || !taskId)
984
- throw new Error("Usage: forge approve RUN_ID TASK_ID [--reviewer NAME] [--reason TEXT] [--path PROJECT]");
1007
+ throw new Error("Usage: anvil approve RUN_ID TASK_ID [--reviewer NAME] [--reason TEXT] [--path PROJECT]");
985
1008
  const updated = await decideTaskApproval(target, runId, taskId, "approved", reviewerIndex >= 0 ? rest[reviewerIndex + 1] ?? "local-user" : "local-user", reasonIndex >= 0 ? rest.slice(reasonIndex + 1, pathIndex >= 0 ? pathIndex : rest.length).join(" ") : undefined);
986
1009
  process.stdout.write("Approved " + taskId + " in " + runId + ". Resume explicitly with `forge resume " + runId + "`.\n");
987
1010
  process.stdout.write("Run status: " + updated.status + "\n");
@@ -998,7 +1021,7 @@ async function main(args) {
998
1021
  const target = path.resolve(pathIndex >= 0 ? rest[pathIndex + 1] ?? "." : ".");
999
1022
  try {
1000
1023
  if (!runId)
1001
- throw new Error("Usage: forge resume RUN_ID [--path PROJECT]");
1024
+ throw new Error("Usage: anvil resume RUN_ID [--path PROJECT]");
1002
1025
  const permissions = await loadPermissionPolicy(target);
1003
1026
  const providerChoice = (process.env.FORGE_AI_PROVIDER ?? "openai").toLowerCase();
1004
1027
  assertSupportedAgentPolicy(permissions, providerChoice, "FORGE resume");
@@ -1081,7 +1104,7 @@ async function main(args) {
1081
1104
  const pathIndex = rest.indexOf("--path");
1082
1105
  const target = path.resolve(pathIndex >= 0 ? rest[pathIndex + 1] ?? "." : ".");
1083
1106
  if (!runId) {
1084
- process.stderr.write("Usage: forge trace RUNID [--path PROJECT]\n");
1107
+ process.stderr.write("Usage: anvil trace RUNID [--path PROJECT]\n");
1085
1108
  process.exitCode = 1;
1086
1109
  return;
1087
1110
  }
@@ -1103,7 +1126,7 @@ async function main(args) {
1103
1126
  }
1104
1127
  case "runs": {
1105
1128
  if (rest.includes("--help")) {
1106
- process.stdout.write("Usage: forge runs [path] [--json] [--limit N] [--status STATUS]\nLists valid saved run records. Use --json for the versioned machine-readable summary, --limit N for the newest N runs, and --status to filter by run state.\n");
1129
+ process.stdout.write("Usage: anvil runs [path] [--json] [--limit N] [--status STATUS]\nLists valid saved run records. Use --json for the versioned machine-readable summary, --limit N for the newest N runs, and --status to filter by run state.\n");
1107
1130
  return;
1108
1131
  }
1109
1132
  const limitIndex = rest.indexOf("--limit");
@@ -1117,7 +1140,7 @@ async function main(args) {
1117
1140
  const target = positionalPaths[0] ?? ".";
1118
1141
  try {
1119
1142
  if (positionalPaths.length > 1) {
1120
- throw new Error("Usage: forge runs [path] [--json] [--limit N] [--status STATUS]");
1143
+ throw new Error("Usage: anvil runs [path] [--json] [--limit N] [--status STATUS]");
1121
1144
  }
1122
1145
  for (const option of ["--json", "--limit", "--status"]) {
1123
1146
  if (rest.filter(arg => arg === option).length > 1) {
@@ -1154,7 +1177,7 @@ async function main(args) {
1154
1177
  }
1155
1178
  case "show-run": {
1156
1179
  if (rest.includes("--help")) {
1157
- process.stdout.write("Usage: forge show-run RUN_ID [--path PROJECT]\nDisplays one validated saved run record.\n");
1180
+ process.stdout.write("Usage: anvil show-run RUN_ID [--path PROJECT]\nDisplays one validated saved run record.\n");
1158
1181
  return;
1159
1182
  }
1160
1183
  const pathIndices = rest.flatMap((arg, index) => arg === "--path" ? [index] : []);
@@ -1172,7 +1195,7 @@ async function main(args) {
1172
1195
  throw new Error("--path requires a project directory.");
1173
1196
  }
1174
1197
  if (positional.length !== 1)
1175
- throw new Error("Usage: forge show-run RUN_ID [--path PROJECT]");
1198
+ throw new Error("Usage: anvil show-run RUN_ID [--path PROJECT]");
1176
1199
  const id = positional[0];
1177
1200
  const run = await loadRun(path.resolve(target), id);
1178
1201
  process.stdout.write(`${JSON.stringify(run, null, 2)}\n`);
@@ -1261,7 +1284,7 @@ async function main(args) {
1261
1284
  }
1262
1285
  case "deps": {
1263
1286
  if (rest.includes("--help")) {
1264
- process.stdout.write("Usage: forge deps [path] [--audit-report FILE] [--outdated-report FILE] [--json]\n");
1287
+ process.stdout.write("Usage: anvil deps [path] [--audit-report FILE] [--outdated-report FILE] [--json]\n");
1265
1288
  return;
1266
1289
  }
1267
1290
  const option = (name) => { const index = rest.indexOf(name); return index >= 0 ? rest[index + 1] : undefined; };
@@ -1360,7 +1383,7 @@ async function main(args) {
1360
1383
  process.stdout.write(JSON.stringify(report, null, 2) + "\n");
1361
1384
  }
1362
1385
  catch (error) {
1363
- process.stderr.write("FORGE code search failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1386
+ process.stderr.write("ANVIL code search failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1364
1387
  process.exitCode = 1;
1365
1388
  }
1366
1389
  return;
@@ -1378,7 +1401,7 @@ async function main(args) {
1378
1401
  const dashboard = await startDashboard({ projectPath: target, port: portValue });
1379
1402
  const address = dashboard.server.address();
1380
1403
  const actualPort = address && typeof address !== "string" ? address.port : portValue;
1381
- process.stdout.write(`FORGE dashboard: http://127.0.0.1:${actualPort}\nProject: ${target}\nPress Ctrl+C to stop.\n`);
1404
+ process.stdout.write(`ANVIL dashboard: http://127.0.0.1:${actualPort}\nProject: ${target}\nPress Ctrl+C to stop.\n`);
1382
1405
  const shutdown = () => dashboard.server.close(() => process.exit(0));
1383
1406
  process.once("SIGINT", shutdown);
1384
1407
  process.once("SIGTERM", shutdown);
@@ -1402,7 +1425,7 @@ async function main(args) {
1402
1425
  return;
1403
1426
  }
1404
1427
  if (!script)
1405
- throw new Error("Choose one script explicitly. Usage: forge verify SCRIPT [--path PROJECT], or use --list to discover scripts.");
1428
+ throw new Error("Choose one script explicitly. Usage: anvil verify SCRIPT [--path PROJECT], or use --list to discover scripts.");
1406
1429
  const result = await runVerification(target, script);
1407
1430
  const comparison = await compareVerification(target, result);
1408
1431
  await saveVerification(target, result);
@@ -1413,7 +1436,7 @@ async function main(args) {
1413
1436
  }
1414
1437
  catch (error) {
1415
1438
  const message = error instanceof Error ? error.message : String(error);
1416
- process.stderr.write(`FORGE verification failed: ${message}\n`);
1439
+ process.stderr.write(`ANVIL verification failed: ${message}\n`);
1417
1440
  process.exitCode = 1;
1418
1441
  }
1419
1442
  return;
@@ -1436,7 +1459,7 @@ async function main(args) {
1436
1459
  }
1437
1460
  }
1438
1461
  catch (error) {
1439
- process.stderr.write("FORGE sandbox profiles failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1462
+ process.stderr.write("ANVIL sandbox profiles failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1440
1463
  process.exitCode = 1;
1441
1464
  }
1442
1465
  return;
@@ -1447,7 +1470,7 @@ async function main(args) {
1447
1470
  process.stdout.write(formatSandboxCleanupHistory(await readSandboxCleanupAudit(target)) + "\n");
1448
1471
  }
1449
1472
  catch (error) {
1450
- process.stderr.write("FORGE sandbox cleanup history failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1473
+ process.stderr.write("ANVIL sandbox cleanup history failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1451
1474
  process.exitCode = 1;
1452
1475
  }
1453
1476
  return;
@@ -1457,7 +1480,7 @@ async function main(args) {
1457
1480
  const unknown = rest.filter(arg => arg !== "--apply");
1458
1481
  try {
1459
1482
  if (unknown.length)
1460
- throw new Error("Usage: forge sandbox-cleanup [--apply]. Cleanup is dry-run unless --apply is explicit.");
1483
+ throw new Error("Usage: anvil sandbox-cleanup [--apply]. Cleanup is dry-run unless --apply is explicit.");
1461
1484
  const output = await runSandboxProbe([
1462
1485
  "ps", "-a", "--filter", "label=com.forge.managed=true",
1463
1486
  "--format", "{{.ID}}\\t{{.Status}}\\t{{.Names}}",
@@ -1481,7 +1504,7 @@ async function main(args) {
1481
1504
  process.stdout.write(formatSandboxCleanupReport(candidates, removed, apply) + "\n");
1482
1505
  }
1483
1506
  catch (error) {
1484
- process.stderr.write("FORGE sandbox cleanup failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1507
+ process.stderr.write("ANVIL sandbox cleanup failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1485
1508
  process.exitCode = 1;
1486
1509
  }
1487
1510
  return;
@@ -1489,7 +1512,7 @@ async function main(args) {
1489
1512
  case "sandbox-policy-check": {
1490
1513
  const policyPath = rest[0];
1491
1514
  if (!policyPath) {
1492
- process.stderr.write("Usage: forge sandbox-policy-check POLICY.json\n");
1515
+ process.stderr.write("Usage: anvil sandbox-policy-check POLICY.json\n");
1493
1516
  process.exitCode = 1;
1494
1517
  return;
1495
1518
  }
@@ -1528,7 +1551,7 @@ async function main(args) {
1528
1551
  process.exitCode = 1;
1529
1552
  }
1530
1553
  catch (error) {
1531
- process.stderr.write("FORGE sandbox compliance failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1554
+ process.stderr.write("ANVIL sandbox compliance failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1532
1555
  process.exitCode = 1;
1533
1556
  }
1534
1557
  return;
@@ -1567,7 +1590,7 @@ async function main(args) {
1567
1590
  const script = argsWithoutPath.find((arg, index) => !arg.startsWith("--") && index > 0);
1568
1591
  try {
1569
1592
  if (!stageId || !script)
1570
- throw new Error("Usage: forge patch-verify PATCH_STAGE_ID SCRIPT [--install-dependencies] [--sandbox-image IMAGE@sha256:DIGEST] [--require-rootless] [--profile balanced|hardened|rootless-required] [--policy POLICY.json] [--path PROJECT]");
1593
+ throw new Error("Usage: anvil patch-verify PATCH_STAGE_ID SCRIPT [--install-dependencies] [--sandbox-image IMAGE@sha256:DIGEST] [--require-rootless] [--profile balanced|hardened|rootless-required] [--policy POLICY.json] [--path PROJECT]");
1571
1594
  if (sandboxImageIndex >= 0 && !sandboxImage)
1572
1595
  throw new Error("--sandbox-image requires an image pinned by sha256 digest.");
1573
1596
  if (requireRootless && !sandboxImage)
@@ -1589,7 +1612,7 @@ async function main(args) {
1589
1612
  ...(securityProfile ? { securityProfile: securityProfile } : {}),
1590
1613
  ...(sandboxPolicyPath ? { sandboxPolicyPath } : {}),
1591
1614
  });
1592
- process.stdout.write("# FORGE Staged Patch Verification\n\n" +
1615
+ process.stdout.write("# ANVIL Staged Patch Verification\n\n" +
1593
1616
  "- **Stage:** `" + result.stageId + "`\n" +
1594
1617
  "- **Patch file:** `" + result.file + "`\n" +
1595
1618
  "- **Staged SHA-256:** `" + result.stagedSha256 + "`\n" +
@@ -1606,7 +1629,7 @@ async function main(args) {
1606
1629
  }
1607
1630
  catch (error) {
1608
1631
  const message = error instanceof Error ? error.message : String(error);
1609
- process.stderr.write("FORGE staged verification failed: " + message + "\n");
1632
+ process.stderr.write("ANVIL staged verification failed: " + message + "\n");
1610
1633
  process.exitCode = 1;
1611
1634
  }
1612
1635
  return;
@@ -1651,7 +1674,7 @@ async function main(args) {
1651
1674
  }
1652
1675
  catch (error) {
1653
1676
  const message = error instanceof Error ? error.message : String(error);
1654
- process.stderr.write(`FORGE code review failed: ${message}\n`);
1677
+ process.stderr.write(`ANVIL code review failed: ${message}\n`);
1655
1678
  process.exitCode = 1;
1656
1679
  }
1657
1680
  return;
@@ -1663,7 +1686,7 @@ async function main(args) {
1663
1686
  process.stdout.write(records.length ? records.map(r => r.id + " " + r.createdAt + " " + r.report.findings.length + " static findings").join("\n") + "\n" : "No saved reviews found.\n");
1664
1687
  }
1665
1688
  catch (error) {
1666
- process.stderr.write("FORGE review history failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1689
+ process.stderr.write("ANVIL review history failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1667
1690
  process.exitCode = 1;
1668
1691
  }
1669
1692
  return;
@@ -1677,7 +1700,7 @@ async function main(args) {
1677
1700
  process.stdout.write(formatReviewRecord(record) + "\n");
1678
1701
  }
1679
1702
  catch (error) {
1680
- process.stderr.write("FORGE could not load review: " + (error instanceof Error ? error.message : String(error)) + "\n");
1703
+ process.stderr.write("ANVIL could not load review: " + (error instanceof Error ? error.message : String(error)) + "\n");
1681
1704
  process.exitCode = 1;
1682
1705
  }
1683
1706
  return;
@@ -1688,13 +1711,13 @@ async function main(args) {
1688
1711
  const target = path.resolve(pathIndex >= 0 ? rest[pathIndex + 1] ?? "." : ".");
1689
1712
  try {
1690
1713
  if (ids.length < 2)
1691
- throw new Error("Usage: forge review-compare REVIEW_ID_A REVIEW_ID_B --path PROJECT");
1714
+ throw new Error("Usage: anvil review-compare REVIEW_ID_A REVIEW_ID_B --path PROJECT");
1692
1715
  const [a, b] = await Promise.all([loadReview(target, ids[0]), loadReview(target, ids[1])]);
1693
1716
  const diff = compareReviews(a, b);
1694
1717
  process.stdout.write(["Review comparison", "Added (" + diff.added.length + ")", ...diff.added.map(x => "+ " + x), "Resolved (" + diff.resolved.length + ")", ...diff.resolved.map(x => "- " + x), "Persistent (" + diff.persistent.length + ")", ...diff.persistent.map(x => "= " + x)].join("\n") + "\n");
1695
1718
  }
1696
1719
  catch (error) {
1697
- process.stderr.write("FORGE review comparison failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1720
+ process.stderr.write("ANVIL review comparison failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1698
1721
  process.exitCode = 1;
1699
1722
  }
1700
1723
  return;
@@ -1712,7 +1735,7 @@ async function main(args) {
1712
1735
  process.exitCode = 1;
1713
1736
  }
1714
1737
  catch (error) {
1715
- process.stderr.write("FORGE regression analysis failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1738
+ process.stderr.write("ANVIL regression analysis failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1716
1739
  process.exitCode = 1;
1717
1740
  }
1718
1741
  return;
@@ -1723,12 +1746,12 @@ async function main(args) {
1723
1746
  const stageId = rest.find((arg, index) => !arg.startsWith("--") && rest[index - 1] !== "--path") ?? "";
1724
1747
  try {
1725
1748
  if (!stageId)
1726
- throw new Error("Usage: forge patch-review STAGE_ID --path PROJECT");
1749
+ throw new Error("Usage: anvil patch-review STAGE_ID --path PROJECT");
1727
1750
  const review = await reviewStagedPatch(target, stageId);
1728
- process.stdout.write(["# FORGE Staged Patch Review", "- Stage: " + review.stageId, "- File: " + review.file, "- Source SHA-256: " + review.sourceSha256, "- Staged SHA-256: " + review.stagedSha256, "- Source unchanged: " + review.unchanged, "", review.diff].join("\n") + "\n");
1751
+ process.stdout.write(["# ANVIL Staged Patch Review", "- Stage: " + review.stageId, "- File: " + review.file, "- Source SHA-256: " + review.sourceSha256, "- Staged SHA-256: " + review.stagedSha256, "- Source unchanged: " + review.unchanged, "", review.diff].join("\n") + "\n");
1729
1752
  }
1730
1753
  catch (error) {
1731
- process.stderr.write("FORGE staged patch review failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1754
+ process.stderr.write("ANVIL staged patch review failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1732
1755
  process.exitCode = 1;
1733
1756
  }
1734
1757
  return;
@@ -1739,12 +1762,12 @@ async function main(args) {
1739
1762
  const approvalId = rest.find((arg, index) => !arg.startsWith("--") && rest[index - 1] !== "--path") ?? "";
1740
1763
  try {
1741
1764
  if (!approvalId)
1742
- throw new Error("Usage: forge patch-stage APPROVAL_ID --path PROJECT");
1765
+ throw new Error("Usage: anvil patch-stage APPROVAL_ID --path PROJECT");
1743
1766
  const staged = await stageApprovedPatch(target, approvalId);
1744
- process.stdout.write(["# FORGE Isolated Patch Stage", "- Stage: " + staged.id, "- Approval: " + staged.approvalId, "- File: " + staged.file, "- Staged copy: " + staged.stagedFile, "- SHA-256: " + staged.stagedSha256, "", "The original project file was not modified.", "No tests or commands were executed."].join("\n") + "\n");
1767
+ process.stdout.write(["# ANVIL Isolated Patch Stage", "- Stage: " + staged.id, "- Approval: " + staged.approvalId, "- File: " + staged.file, "- Staged copy: " + staged.stagedFile, "- SHA-256: " + staged.stagedSha256, "", "The original project file was not modified.", "No tests or commands were executed."].join("\n") + "\n");
1745
1768
  }
1746
1769
  catch (error) {
1747
- process.stderr.write("FORGE patch staging failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1770
+ process.stderr.write("ANVIL patch staging failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1748
1771
  process.exitCode = 1;
1749
1772
  }
1750
1773
  return;
@@ -1761,13 +1784,13 @@ async function main(args) {
1761
1784
  const reason = reasonIndex >= 0 ? rest[reasonIndex + 1] : undefined;
1762
1785
  try {
1763
1786
  if (!reviewId || !Number.isInteger(suggestionNumber) || suggestionNumber < 1 || !reviewer.trim()) {
1764
- throw new Error("Usage: forge patch-approve REVIEW_ID SUGGESTION_NUMBER --reviewer NAME [--reason TEXT] --path PROJECT");
1787
+ throw new Error("Usage: anvil patch-approve REVIEW_ID SUGGESTION_NUMBER --reviewer NAME [--reason TEXT] --path PROJECT");
1765
1788
  }
1766
1789
  const approval = await approveReviewPatch(target, reviewId, suggestionNumber, reviewer, reason);
1767
- process.stdout.write(["# FORGE Patch Approval", "- Approval ID: " + approval.id, "- Review: " + approval.reviewId, "- Suggestion: " + approval.suggestionNumber, "- File: " + approval.file, "- Reviewer: " + approval.reviewer, "- Approved: " + approval.approvedAt, "- Expires: " + approval.expiresAt, "- Patch SHA-256: " + approval.patchSha256, "- Source SHA-256: " + approval.sourceSha256, "", "No source files were modified."].join("\n") + "\n");
1790
+ process.stdout.write(["# ANVIL Patch Approval", "- Approval ID: " + approval.id, "- Review: " + approval.reviewId, "- Suggestion: " + approval.suggestionNumber, "- File: " + approval.file, "- Reviewer: " + approval.reviewer, "- Approved: " + approval.approvedAt, "- Expires: " + approval.expiresAt, "- Patch SHA-256: " + approval.patchSha256, "- Source SHA-256: " + approval.sourceSha256, "", "No source files were modified."].join("\n") + "\n");
1768
1791
  }
1769
1792
  catch (error) {
1770
- process.stderr.write("FORGE patch approval failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1793
+ process.stderr.write("ANVIL patch approval failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1771
1794
  process.exitCode = 1;
1772
1795
  }
1773
1796
  return;
@@ -1778,7 +1801,7 @@ async function main(args) {
1778
1801
  const target = path.resolve(pathIndex >= 0 ? rest[pathIndex + 1] ?? "." : ".");
1779
1802
  try {
1780
1803
  if (!id)
1781
- throw new Error("Usage: forge patch-approval-check APPROVAL_ID --path PROJECT");
1804
+ throw new Error("Usage: anvil patch-approval-check APPROVAL_ID --path PROJECT");
1782
1805
  const result = await verifyPatchApproval(target, id);
1783
1806
  process.stdout.write((result.valid ? "VALID: " : "INVALID: ") + result.reason + "\n");
1784
1807
  if (!result.valid)
@@ -1797,7 +1820,7 @@ async function main(args) {
1797
1820
  const numberArg = rest.find((arg, index) => index > 0 && !arg.startsWith("--") && rest[index - 1] !== id && rest[index - 1] !== "--path");
1798
1821
  try {
1799
1822
  if (!id || !numberArg)
1800
- throw new Error("Usage: forge patch-check REVIEW_ID SUGGESTION_NUMBER --path PROJECT");
1823
+ throw new Error("Usage: anvil patch-check REVIEW_ID SUGGESTION_NUMBER --path PROJECT");
1801
1824
  const record = await loadReview(target, id);
1802
1825
  const result = await validateReviewPatch(target, record, Number(numberArg));
1803
1826
  process.stdout.write(formatPatchValidation(result) + "\n");
@@ -1805,7 +1828,7 @@ async function main(args) {
1805
1828
  process.exitCode = 1;
1806
1829
  }
1807
1830
  catch (error) {
1808
- process.stderr.write("FORGE patch validation failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1831
+ process.stderr.write("ANVIL patch validation failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1809
1832
  process.exitCode = 1;
1810
1833
  }
1811
1834
  return;
@@ -1822,7 +1845,7 @@ async function main(args) {
1822
1845
  }
1823
1846
  catch (error) {
1824
1847
  const message = error instanceof Error ? error.message : String(error);
1825
- process.stderr.write(`FORGE Git analysis failed: ${message}\n`);
1848
+ process.stderr.write(`ANVIL Git analysis failed: ${message}\n`);
1826
1849
  process.exitCode = 1;
1827
1850
  }
1828
1851
  return;
@@ -1836,14 +1859,14 @@ async function main(args) {
1836
1859
  }
1837
1860
  catch (error) {
1838
1861
  const message = error instanceof Error ? error.message : String(error);
1839
- process.stderr.write(`FORGE deep analysis failed: ${message}\n`);
1862
+ process.stderr.write(`ANVIL deep analysis failed: ${message}\n`);
1840
1863
  process.exitCode = 1;
1841
1864
  }
1842
1865
  return;
1843
1866
  }
1844
1867
  case "remediate": {
1845
1868
  if (rest.includes("--help")) {
1846
- process.stdout.write("Usage: forge remediate [path] [--audit-report FILE] [--outdated-report FILE] [--json]\n");
1869
+ process.stdout.write("Usage: anvil remediate [path] [--audit-report FILE] [--outdated-report FILE] [--json]\n");
1847
1870
  return;
1848
1871
  }
1849
1872
  const option = (name) => { const index = rest.indexOf(name); return index >= 0 ? rest[index + 1] : undefined; };
@@ -1854,7 +1877,7 @@ async function main(args) {
1854
1877
  process.stdout.write(rest.includes("--json") ? JSON.stringify(plan, null, 2) + "\n" : formatRemediationPlan(plan) + "\n");
1855
1878
  }
1856
1879
  catch (error) {
1857
- process.stderr.write("FORGE remediation planning failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1880
+ process.stderr.write("ANVIL remediation planning failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1858
1881
  process.exitCode = 1;
1859
1882
  }
1860
1883
  return;
@@ -1868,14 +1891,61 @@ async function main(args) {
1868
1891
  }
1869
1892
  catch (error) {
1870
1893
  const message = error instanceof Error ? error.message : String(error);
1871
- process.stderr.write(`FORGE health report failed: ${message}\n`);
1894
+ process.stderr.write(`ANVIL health report failed: ${message}\n`);
1895
+ process.exitCode = 1;
1896
+ }
1897
+ return;
1898
+ }
1899
+ case "clean":
1900
+ case "fix": {
1901
+ if (rest.includes("--help")) {
1902
+ process.stdout.write(`Usage: anvil ${command} [path] [--apply] [--fix] [--json]\n Clean farzi/junk files, downloads, logs, and auto-repair code issues.\n`);
1903
+ return;
1904
+ }
1905
+ const json = rest.includes("--json");
1906
+ const isFix = command === "fix";
1907
+ const apply = isFix || rest.includes("--apply");
1908
+ const fix = isFix || rest.includes("--fix");
1909
+ const verify = rest.includes("--verify");
1910
+ const checkOrphans = !rest.includes("--no-orphans");
1911
+ const target = rest.find(arg => !arg.startsWith("--")) ?? ".";
1912
+ try {
1913
+ const { cleanProject, formatCleanReport } = await import("./core/project-cleaner.js");
1914
+ const report = await cleanProject(path.resolve(target), { apply, fix, checkOrphans, verify });
1915
+ process.stdout.write(json ? `${JSON.stringify(report, null, 2)}\n` : `${formatCleanReport(report)}\n`);
1916
+ }
1917
+ catch (error) {
1918
+ const message = error instanceof Error ? error.message : String(error);
1919
+ process.stderr.write(`ANVIL ${command} failed: ${message}\n`);
1920
+ process.exitCode = 1;
1921
+ }
1922
+ return;
1923
+ }
1924
+ case "undo": {
1925
+ if (rest.includes("--help")) {
1926
+ process.stdout.write("Usage: anvil undo [path] [--json]\n Rollback the last anvil clean or fix operation using saved snapshot backup.\n");
1927
+ return;
1928
+ }
1929
+ const json = rest.includes("--json");
1930
+ const target = rest.find(arg => !arg.startsWith("--")) ?? ".";
1931
+ try {
1932
+ const { undoLastClean, formatUndoReport } = await import("./core/project-cleaner.js");
1933
+ const report = await undoLastClean(path.resolve(target));
1934
+ process.stdout.write(json ? `${JSON.stringify(report, null, 2)}\n` : `${formatUndoReport(report)}\n`);
1935
+ if (report.errors.length > 0) {
1936
+ process.exitCode = 1;
1937
+ }
1938
+ }
1939
+ catch (error) {
1940
+ const message = error instanceof Error ? error.message : String(error);
1941
+ process.stderr.write(`ANVIL undo failed: ${message}\n`);
1872
1942
  process.exitCode = 1;
1873
1943
  }
1874
1944
  return;
1875
1945
  }
1876
1946
  case "quality": {
1877
1947
  if (rest.includes("--help")) {
1878
- process.stdout.write("Usage: forge quality [path] [--json]\n");
1948
+ process.stdout.write("Usage: anvil quality [path] [--json]\n");
1879
1949
  return;
1880
1950
  }
1881
1951
  const json = rest.includes("--json");
@@ -1886,7 +1956,7 @@ async function main(args) {
1886
1956
  }
1887
1957
  catch (error) {
1888
1958
  const message = error instanceof Error ? error.message : String(error);
1889
- process.stderr.write(`FORGE quality audit failed: ${message}\n`);
1959
+ process.stderr.write(`ANVIL quality audit failed: ${message}\n`);
1890
1960
  process.exitCode = 1;
1891
1961
  }
1892
1962
  return;
@@ -1894,7 +1964,7 @@ async function main(args) {
1894
1964
  case "inspect":
1895
1965
  case "map": {
1896
1966
  if (rest.includes("--help")) {
1897
- process.stdout.write(`Usage: forge ${command} [path] [--json]\n`);
1967
+ process.stdout.write(`Usage: anvil ${command} [path] [--json]\n`);
1898
1968
  return;
1899
1969
  }
1900
1970
  const json = rest.includes("--json");
@@ -1911,33 +1981,56 @@ async function main(args) {
1911
1981
  }
1912
1982
  catch (error) {
1913
1983
  const message = error instanceof Error ? error.message : String(error);
1914
- process.stderr.write(`FORGE could not ${command} this project: ${message}\n`);
1984
+ process.stderr.write(`ANVIL could not ${command} this project: ${message}\n`);
1915
1985
  process.exitCode = 1;
1916
1986
  }
1917
1987
  return;
1918
1988
  }
1919
1989
  case "doctor": {
1920
1990
  if (rest.includes("--help")) {
1921
- process.stdout.write("Usage: forge doctor [path] [--json]\n Run environment health checks.\n");
1991
+ process.stdout.write("Usage: anvil doctor [path] [--fix] [--json]\n" +
1992
+ " Run environment health checks.\n" +
1993
+ " Add --fix to auto-scaffold missing .anvil config directories, .gitignore, and .env.example.\n");
1922
1994
  return;
1923
1995
  }
1924
1996
  const json = rest.includes("--json");
1997
+ const doFix = rest.includes("--fix");
1925
1998
  const target = rest.find(arg => !arg.startsWith("--"));
1926
1999
  try {
1927
- const { runDoctorChecks, formatDoctorReport } = await import("./core/doctor.js");
2000
+ const { runDoctorChecks, fixDoctorIssues, formatDoctorReport } = await import("./core/doctor.js");
2001
+ if (doFix) {
2002
+ const fixResult = await fixDoctorIssues(target ? path.resolve(target) : undefined);
2003
+ if (!json) {
2004
+ process.stdout.write("# ANVIL Doctor Auto-Fix\n\n");
2005
+ if (fixResult.repaired.length > 0) {
2006
+ for (const item of fixResult.repaired) {
2007
+ process.stdout.write(`✓ ${item}\n`);
2008
+ }
2009
+ }
2010
+ else {
2011
+ process.stdout.write("✓ Environment and configuration are already properly set up.\n");
2012
+ }
2013
+ if (fixResult.warnings.length > 0) {
2014
+ for (const warn of fixResult.warnings) {
2015
+ process.stdout.write(`! Warning: ${warn}\n`);
2016
+ }
2017
+ }
2018
+ process.stdout.write("\nRunning health checks after fix...\n\n");
2019
+ }
2020
+ }
1928
2021
  const report = await runDoctorChecks(target ? path.resolve(target) : undefined);
1929
2022
  process.stdout.write(json ? JSON.stringify(report, null, 2) + "\n" : formatDoctorReport(report) + "\n");
1930
2023
  if (report.overallStatus === "critical")
1931
2024
  process.exitCode = 1;
1932
2025
  }
1933
2026
  catch (error) {
1934
- process.stderr.write("FORGE doctor failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
2027
+ process.stderr.write("ANVIL doctor failed: " + (error instanceof Error ? error.message : String(error)) + "\n");
1935
2028
  process.exitCode = 1;
1936
2029
  }
1937
2030
  return;
1938
2031
  }
1939
2032
  default:
1940
- process.stderr.write(`Unknown command: ${command}\nRun "forge help" to see available commands.\n`);
2033
+ process.stderr.write(`Unknown command: ${command}\nRun "anvil help" to see available commands.\n`);
1941
2034
  process.exitCode = 1;
1942
2035
  }
1943
2036
  }