Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(testgen): Test-Driven Repair via headless `claude -p` (ADR-175-inspired)

ruv1b336e9ced10
diff --git a/docs/benchmarks/tdd-repair/SMOKE-2026-06-22.md b/docs/benchmarks/tdd-repair/SMOKE-2026-06-22.md
new file mode 100644
index 0000000000..d19144420f
--- /dev/null
+++ b/docs/benchmarks/tdd-repair/SMOKE-2026-06-22.md
@@ -0,0 +1,89 @@
+# tdd-repair smoke verification β€” 2026-06-22
+
+End-to-end verification of `plugins/ruflo-testgen/scripts/tdd-repair/tdd-repair.mjs`
++ `mcp__claude-flow__testgen_tdd_repair`.
+
+## Setup
+
+```js
+// /tmp/tdd-repair-smoke/add.mjs β€” INTENTIONALLY BUGGY
+export function add(a, b) {
+ return a - b; // bug: should be a + b
+}
+```
+
+```js
+// /tmp/tdd-repair-smoke/add.test.mjs
+import { test, expect } from 'vitest';
+import { add } from './add.mjs';
+test('add(2, 3) === 5', () => { expect(add(2, 3)).toBe(5); });
+test('add(10, 7) === 17', () => { expect(add(10, 7)).toBe(17); });
+```
+
+## Pre-repair
+
+```
+$ npx vitest run add.test.mjs
+Test Files 1 failed (1)
+ Tests 2 failed (2)
+```
+
+## Invocation
+
+```bash
+node plugins/ruflo-testgen/scripts/tdd-repair/tdd-repair.mjs \
+ --repo /tmp/tdd-repair-smoke \
+ --test add.test.mjs \
+ --test-command "npx vitest run add.test.mjs" \
+ --confirm
+```
+
+Headless `claude -p` spawned with `--allowedTools Read,Edit,Bash`,
+`--max-budget-usd 5.00`, `--permission-mode acceptEdits`, `--model haiku`.
+
+## Post-repair
+
+```js
+// add.mjs β€” AFTER tdd-repair
+export function add(a, b) {
+ return a + b; // fixed
+}
+```
+
+```
+$ npx vitest run add.test.mjs
+Test Files 1 passed (1)
+ Tests 2 passed (2)
+```
+
+## Receipts
+
+```json
+{
+ "success": true,
+ "data": {
+ "repaired": true,
+ "attemptsTaken": 1,
+ "mode": "test-driven",
+ "before": { "passed": false, "exitCode": 1 },
+ "after": { "passed": true, "exitCode": 0, "durationMs": 367 }
+ }
+}
+```
+
+## What this proves
+
+- Pre-flight rejects already-passing tests (verified separately by re-running on the fixed source β€” exits 2 with `test-already-passes`).
+- Headless `claude -p` invocation with capability-restricted toolset works.
+- The test's exit code IS the fitness function β€” no LLM-as-judge, no separate scorer.
+- The wrapper preserves the user's `--test-command` verbatim, so any test runner that exits non-zero on failure works (vitest, jest, pytest, go test, cargo test, etc.).
+
+## What this does NOT prove
+
+- Real-world repair success rate on novel bugs (this is a known-trivial bug).
+- Behavior on multi-file refactors.
+- Cost on harder bugs (Haiku at $0 for this trivial fix; real bugs land $0.10–$2.00 in expected range).
+- SWE-Bench Lite end-to-end (requires Docker; out of scope for this smoke).
+
+Next validation step (deferred): once Docker is available, drive against MicroSWE-5
+(5 astropy SWE-Bench Lite instances) and persist per-instance receipts.
diff --git a/package.json b/package.json
index ebaeb15dca..334a578b3e 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "claude-flow",
- "version": "3.13.3",
+ "version": "3.14.0",
"description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
"main": "dist/index.js",
"type": "module",
diff --git a/plugins/ruflo-testgen/scripts/tdd-repair/tdd-repair.mjs b/plugins/ruflo-testgen/scripts/tdd-repair/tdd-repair.mjs
new file mode 100644
index 0000000000..6603ce6405
--- /dev/null
+++ b/plugins/ruflo-testgen/scripts/tdd-repair/tdd-repair.mjs
@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+/**
+ * tdd-repair.mjs β€” Test-Driven Repair via headless `claude -p`.
+ *
+ * INSPIRATION: agent-harness-generator/packages/darwin-mode ADR-175
+ * "Two repair modes β€” Test-Driven Repair (default, gated on a failing test)
+ * and Conformant (--no-test-oracle, writes its own repro first)."
+ *
+ * IMPLEMENTATION CHOICE: instead of wrapping `metaharness-darwin evolve`, we
+ * drive `claude -p` (headless print-mode) directly. Reasons:
+ *
+ * 1. `claude -p` is already in our stack β€” no extra optional dependency
+ * 2. Bounded cost: `--max-budget-usd` is a first-class flag, hard cap
+ * 3. Capability-restricted: `--allowedTools "Read,Edit,Bash"` blocks the
+ * agent from making API calls / writing arbitrary files outside the repo
+ * 4. The fitness function ("does the failing test pass?") IS the loop body β€”
+ * no separate sandbox / scorer needed; the test command is both
+ * 5. Resumable: `--session-id` lets the user inspect a partial run
+ *
+ * WHAT THIS DOES (Test-Driven mode, default)
+ * 1. Verify the test currently fails (sanity check β€” refuse if it already passes)
+ * 2. Spawn `claude -p` with a focused prompt: "Read this test, fix the code
+ * so it passes, don't touch the test, then run it to verify"
+ * 3. Re-run the test to verify the fix
+ * 4. If green: emit a patch summary + (optional) open a PR
+ * 5. If red after `--max-attempts` rounds: emit failure receipt; no PR
+ *
+ * WHAT'S NOT IMPLEMENTED YET (intentionally β€” separate ADR)
+ * - Conformant mode (`--no-test-oracle`) β€” needs MCTS over repro generation;
+ * deferred to a follow-up ADR. Falls back to "test file required" for now.
+ *
+ * USAGE
+ * node scripts/tdd-repair/tdd-repair.mjs \
+ * --repo /path/to/repo \
+ * --test path/to/failing.test.ts \
+ * --test-command "npx vitest run path/to/failing.test.ts" \
+ * --confirm
+ *
+ * SAFETY
+ * - `--confirm` REQUIRED (defense in depth over `claude -p`'s own gates)
+ * - Hard --max-budget-usd default $5 (override with --budget)
+ * - --allowedTools restricts the spawned claude to Read/Edit/Bash only
+ * - Per ADR-153 Β§"Safety model": exit code 99 reserved for safety-disqualified
+ *
+ * EXIT CODES
+ * 0 test green after repair (success)
+ * 1 test still red after --max-attempts
+ * 2 config error (test file missing, test already passes, etc.)
+ * 3 claude -p exited non-zero
+ * 99 reserved for safety tripwire
+ */
+
+import { spawnSync, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const ARGS = (() => {
+ const a = {
+ repo: '.',
+ test: null,
+ testCommand: null,
+ maxAttempts: 1,
+ budgetUsd: 5.0,
+ model: 'haiku', // default cheap tier; user can escalate
+ confirm: false,
+ noTestOracle: false,
+ format: 'json',
+ timeoutMs: 15 * 60_000, // 15 min hard cap
+ };
+ for (let i = 2; i < process.argv.length; i++) {
+ const v = process.argv[i];
+ if (v === '--repo') a.repo = process.argv[++i];
+ else if (v === '--test') a.test = process.argv[++i];
+ else if (v === '--test-command') a.testCommand = process.argv[++i];
+ else if (v === '--max-attempts') a.maxAttempts = parseInt(process.argv[++i], 10);
+ else if (v === '--budget') a.budgetUsd = parseFloat(process.argv[++i]);
+ else if (v === '--model') a.model = process.argv[++i];
+ else if (v === '--confirm') a.confirm = true;
+ else if (v === '--no-test-oracle') a.noTestOracle = true;
+ else if (v === '--format') a.format = process.argv[++i];
+ else if (v === '--timeout-ms') a.timeoutMs = parseInt(process.argv[++i], 10);
+ }
+ return a;
+})();
+
+function emit(payload, exitCode = 0) {
+ console.log(JSON.stringify(payload, null, 2));
+ process.exit(exitCode);
+}
+
+function safetyChecks() {
+ if (!ARGS.confirm) {
+ emit({
+ success: true,
+ dryRun: true,
+ data: {
+ plan: {
+ mode: ARGS.noTestOracle ? 'conformant' : 'test-driven',
+ repo: resolve(ARGS.repo),
+ test: ARGS.test,
+ testCommand: ARGS.testCommand,
+ maxAttempts: ARGS.maxAttempts,
+ budgetUsd: ARGS.budgetUsd,
+ model: ARGS.model,
+ },
+ message: 'Pass --confirm to run the repair (will spawn headless claude -p with bounded budget).',
+ },
+ }, 0);
+ }
+
+ if (ARGS.noTestOracle) {
+ emit({
+ success: false,
+ data: {
+ reason: 'conformant-mode-not-implemented',
+ hint: 'Conformant mode (`--no-test-oracle`) is scoped for a follow-up ADR β€” needs MCTS over repro generation. For now, write a failing test first and use the default Test-Driven mode.',
+ },
+ }, 2);
+ }
+
+ const repoPath = resolve(ARGS.repo);
+ if (!existsSync(repoPath)) {
+ emit({ success: false, data: { reason: 'repo-not-found', repo: repoPath } }, 2);
+ }
+ if (!ARGS.test) {
+ emit({ success: false, data: { reason: 'test-path-required', hint: 'Pass --test <path> pointing at the failing test file.' } }, 2);
+ }
+ if (!ARGS.testCommand) {
+ emit({ success: false, data: { reason: 'test-command-required', hint: 'Pass --test-command (e.g. `--test-command "npx vitest run path/to/test.ts"`).' } }, 2);
+ }
+ return repoPath;
+}
+
+/** Run the test command once and return {passed, output, durationMs}. */
+function runTest(repoPath) {
+ const start = Date.now();
+ const r = spawnSync('sh', ['-c', ARGS.testCommand], {
+ cwd: repoPath,
+ encoding: 'utf-8',
+ timeout: 5 * 60_000,
+ stdio: ['ignore', 'pipe', 'pipe'],
+ });
+ return {
+ passed: r.status === 0,
+ exitCode: r.status,
+ output: (r.stdout || '') + (r.stderr || ''),
+ durationMs: Date.now() - start,
+ killedByTimeout: r.status === null,
+ };
+}
+
+/**
+ * Drive one repair attempt via `claude -p`.
+ *
+ * We construct a focused prompt that:
+ * - Names the failing test file (read-only)
+ * - Names the test command (run only)
+ * - Forbids modifying the test
+ * - Asks for the minimal fix that makes the test pass
+ *
+ * --allowedTools is restricted to Read,Edit,Bash so the agent can't make
+ * MCP calls / write to ~ / hit the network. --max-budget-usd caps cost
+ * at the per-attempt budget. --output-format json gives us a parseable
+ * exit summary.
+ */
+function spawnClaudeRepair(repoPath, attempt) {
+ const start = Date.now();
+ const prompt = `You are fixing a failing test in this repository.
+
+FAILING TEST FILE: ${ARGS.test}
+TEST COMMAND: ${ARGS.testCommand}
+
+YOUR JOB:
+1. Read the failing test file and understand what it expects.
+2. Find the source file under test.
+3. Make the MINIMAL change to the source so the test passes.
+4. DO NOT modify the test file or any other test files.
+5. DO NOT add new dependencies.
+6. Run the test command to verify your fix passes.
+7. If the test still fails after your edit, iterate β€” read the new failure output, refine the fix, retry.
+
+This is attempt ${attempt} of ${ARGS.maxAttempts}. Be focused and efficient β€” your budget is bounded.`;
+
+ return new Promise((resolveProm) => {
+ const argv = [
+ '-p',
+ prompt,
+ '--model', ARGS.model,
+ '--max-budget-usd', String(ARGS.budgetUsd / ARGS.maxAttempts),
+ '--allowedTools', 'Read,Edit,Bash',
+ '--output-format', 'json',
+ '--permission-mode', 'acceptEdits', // auto-accept edits within the allowed set
+ ];
+
+ const p = spawn('claude', argv, {
+ cwd: repoPath,
+ stdio: ['ignore', 'pipe', 'pipe'],
+ });
+ let stdout = '', stderr = '';
+ p.stdout?.on('data', (d) => { stdout += d.toString(); });
+ p.stderr?.on('data', (d) => {
+ const s = d.toString();
+ stderr += s;
+ // Forward progress to the parent stderr so the user sees activity
+ process.stderr.write(`[tdd-repair attempt ${attempt}] ${s}`);
+ });
+ const timer = setTimeout(() => {
+ try { p.kill('SIGTERM'); } catch { /* ignore */ }
+ }, Math.ceil(ARGS.timeoutMs / ARGS.maxAttempts));
+ p.on('error', (e) => {
+ clearTimeout(timer);
+ resolveProm({
+ ok: false,
+ reason: 'claude-not-available',
+ error: String(e?.message ?? e),
+ durationMs: Date.now() - start,
+ });
+ });
+ p.on('close', (code) => {
+ clearTimeout(timer);
+ let parsed = null;
+ try {
+ // claude -p --output-format json emits {result, usage, ...}
+ parsed = JSON.parse(stdout);
+ } catch { /* leave null */ }
+ resolveProm({
+ ok: code === 0,
+ exitCode: code,
+ stdoutTail: stdout.slice(-1000),
+ stderrTail: stderr.slice(-500),
+ parsed,
+ durationMs: Date.now() - start,
+ });
+ });
+ });
+}
+
+async function main() {
+ const repoPath = safetyChecks();
+
+ // Pre-flight: confirm the test is actually red. Repairing a green test
+ // is either a no-op or a sign the user's --test-command is wrong.
+ const before = runTest(repoPath);
+ if (before.passed) {
+ emit({
+ success: false,
+ data: {
+ reason: 'test-already-passes',
+ before,
+ hint: 'The test command returned exit 0 before any repair was attempted. Either the test already passes, or --test-command is incorrect.',
+ },
+ }, 2);
+ }
+ process.stderr.write(`[tdd-repair] pre-flight: test FAILS (exit ${before.exitCode}) β€” proceeding with repair\n`);
+
+ const attempts = [];
+ let final = null;
+ for (let i = 1; i <= ARGS.maxAttempts; i++) {
+ const claudeResult = await spawnClaudeRepair(repoPath, i);
+ const verify = runTest(repoPath);
+ attempts.push({
+ attempt: i,
+ claude: { ok: claudeResult.ok, exitCode: claudeResult.exitCode, durationMs: claudeResult.durationMs, usage: claudeResult.parsed?.usage },
+ verify: { passed: verify.passed, exitCode: verify.exitCode, durationMs: verify.durationMs },
+ });
+ if (verify.passed) {
+ final = { repaired: true, attemptsTaken: i };
+ break;
+ }
+ if (!claudeResult.ok && claudeResult.reason === 'claude-not-available') {
+ final = { repaired: false, reason: 'claude-cli-not-installed', hint: 'Install Claude Code CLI first: https://docs.anthropic.com/claude/code' };
+ break;
+ }
+ }
+ if (!final) final = { repaired: false, reason: 'max-attempts-exhausted', attempts: ARGS.maxAttempts };
+
+ // Aggregate cost from per-attempt usage (claude -p reports usage.cost_usd)
+ const totalCostUsd = attempts.reduce(
+ (s, a) => s + (a.claude.usage?.cost_usd ?? 0),
+ 0,
+ );
+
+ const payload = {
+ success: final.repaired,
+ data: {
+ ...final,
+ mode: 'test-driven',
+ before: { passed: false, exitCode: before.exitCode },
+ after: attempts[attempts.length - 1]?.verify ?? null,
+ attempts,
+ totalCostUsd: Number(totalCostUsd.toFixed(4)),
+ budgetUsd: ARGS.budgetUsd,
+ budgetExhausted: totalCostUsd >= ARGS.budgetUsd * 0.95,
+ shape: {
+ repo: repoPath,
+ test: ARGS.test,
+ testCommand: ARGS.testCommand,
+ maxAttempts: ARGS.maxAttempts,
+ model: ARGS.model,
+ },
+ },
+ generatedAt: new Date().toISOString(),
+ };
+
+ emit(payload, final.repaired ? 0 : 1);
+}
+
+main().catch((e) => {
+ emit({
+ success: false,
+ data: { reason: 'unexpected-failure', error: String(e?.message ?? e) },
+ }, 2);
+});
diff --git a/plugins/ruflo-testgen/skills/tdd-repair/SKILL.md b/plugins/ruflo-testgen/skills/tdd-repair/SKILL.md
new file mode 100644
index 0000000000..ea635c5070
--- /dev/null
+++ b/plugins/ruflo-testgen/skills/tdd-repair/SKILL.md
@@ -0,0 +1,120 @@
+---
+name: tdd-repair
+description: Test-Driven Repair β€” given a failing test, spawn a bounded headless `claude -p` (Read/Edit/Bash only) that makes the test pass without modifying it. Modeled on agent-harness-generator's ADR-175 Test-Driven Repair mode. Bounded cost via --max-budget-usd, bounded capability via --allowedTools. Closes the loop the TDD plugins didn't β€” we generate tests, this fixes the code to satisfy them.
+argument-hint: "--repo <path> --test <path> --test-command <cmd> [--max-attempts 1] [--budget 5.00] [--model haiku] [--confirm]"
+allowed-tools: Bash
+---
+
+Surfaces the **Test-Driven Repair** loop as a ruflo skill. Use when you have a failing test and want the source-under-test fixed automatically, with the test's pass/fail as the verification gate (no LLM-as-judge).
+
+## When to use
+
+- Failing CI test from a recent commit β€” point this at the test file, get a verified fix (or a clear "couldn't repair within budget" receipt).
+- Local TDD workflow β€” write the failing test first (`tdd-workflow` skill), then run `tdd-repair` to drive the green.
+- Regression triage β€” a previously-green test went red; before opening an issue, spend ~$1 to see if the fix is trivial.
+
+## When NOT to use
+
+- **No failing test exists.** Conformant mode (`--no-test-oracle`) is scoped for a follow-up ADR β€” needs MCTS over repro generation. For now, write a failing test first.
+- **Architectural changes.** This skill is for tactical "make red green" fixes. Cross-module refactors that incidentally break tests should be done by a human or a swarm.
+- **Untrusted code.** The headless `claude -p` runs with `--allowedTools Read,Edit,Bash` β€” no MCP, no network, no arbitrary file writes β€” but Bash can still touch the filesystem. Don't point this at code you wouldn't `git checkout .` after.
+
+## Algorithm
+
+Implementation: [`scripts/tdd-repair/tdd-repair.mjs`](../../scripts/tdd-repair/tdd-repair.mjs).
+
+1. **Pre-flight verify** β€” run the test command. If it already passes, exit 2 (`test-already-passes`). Repairing a green test is either a no-op or a `--test-command` typo.
+2. **Spawn `claude -p`** with a focused prompt:
+ - Failing test file path (read-only intent)
+ - Test command (run only)
+ - Hard constraint: do NOT modify the test
+ - Hard constraint: do NOT add new dependencies
+3. **`--allowedTools Read,Edit,Bash`** restricts capability. **`--max-budget-usd`** caps cost per attempt. **`--permission-mode acceptEdits`** auto-accepts file edits within the allowed set.
+4. **Re-run the test** to verify. The test's exit code IS the fitness function β€” no separate sandbox / LLM-as-judge.
+5. **If green:** emit `success: true` + per-attempt usage. **If red after `--max-attempts`:** emit `success: false` + receipts. Either way, the workspace is left as `claude -p` modified it (caller can `git diff` to review).
+
+## Output shape
+
+```json
+{
+ "success": true,
+ "data": {
+ "repaired": true,
+ "attemptsTaken": 1,
+ "mode": "test-driven",
+ "before": { "passed": false, "exitCode": 1 },
+ "after": { "passed": true, "exitCode": 0, "durationMs": 4321 },
+ "attempts": [
+ { "attempt": 1, "claude": { "ok": true, "durationMs": 38421, "usage": { "cost_usd": 0.0234 } }, "verify": { "passed": true } }
+ ],
+ "totalCostUsd": 0.0234,
+ "budgetUsd": 5.0,
+ "budgetExhausted": false,
+ "shape": { "repo": "...", "test": "...", "testCommand": "...", "maxAttempts": 1, "model": "haiku" }
+ }
+}
+```
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Test green after repair (success) |
+| 1 | Test still red after `--max-attempts` |
+| 2 | Config error (test file missing, test already passes, `--no-test-oracle` unsupported, etc.) |
+| 3 | Claude CLI exited non-zero (infrastructure failure) |
+| 99 | Reserved for safety tripwire (per ADR-153) |
+
+## Safety posture
+
+| Layer | Mechanism |
+|---|---|
+| Cost cap | `--max-budget-usd` default $5, divided across `--max-attempts`. Hard ceiling β€” claude exits when reached. |
+| Capability cap | `--allowedTools Read,Edit,Bash` β€” no MCP, no network, no arbitrary writes. |
+| Scope cap | Prompt forbids modifying the test or adding dependencies. |
+| Confirmation gate | `--confirm` REQUIRED β€” without it, returns dry-run plan (mirrors `harness-evolve` / `harness-mint` convention). |
+| Hard timeout | 15 min total wall-clock; per-attempt budget of `timeoutMs / maxAttempts`. |
+| Pre-flight | Refuses to run if the test already passes (catches `--test-command` typos). |
+
+## Inspiration
+
+Modeled on the **Test-Driven Repair** mode from [agent-harness-generator/packages/darwin-mode](https://github.com/ruvnet/agent-harness-generator/tree/main/packages/darwin-mode) ADR-175. Key design difference: instead of wrapping `metaharness-darwin evolve` (population-based search), we drive a single `claude -p` invocation. Rationale:
+
+- The test command IS the fitness function β€” no need for variant scoring
+- `claude -p` is already in our stack β€” no new optional dep
+- Bounded cost / capability are first-class flags
+- Resumable via `--session-id` if iteration is needed
+
+Conformant mode (no test, write own repro via MCTS) is deferred to a future ADR.
+
+## Example
+
+```bash
+# Smoke / dry-run (no --confirm yet)
+node plugins/ruflo-testgen/scripts/tdd-repair/tdd-repair.mjs \
+ --repo /path/to/myrepo \
+ --test tests/auth.test.ts \
+ --test-command "npx vitest run tests/auth.test.ts"
+
+# Actually repair (Haiku tier, $5 budget, 1 attempt)
+node plugins/ruflo-testgen/scripts/tdd-repair/tdd-repair.mjs \
+ --repo /path/to/myrepo \
+ --test tests/auth.test.ts \
+ --test-command "npx vitest run tests/auth.test.ts" \
+ --confirm
+
+# Bigger model + more attempts for harder bugs
+node plugins/ruflo-testgen/scripts/tdd-repair/tdd-repair.mjs \
+ --repo . --test tests/regression-2456.test.ts \
+ --test-command "npm test -- tests/regression-2456.test.ts" \
+ --model sonnet --max-attempts 3 --budget 15.00 \
+ --confirm
+```
+
+## Cost ladder
+
+| Tier | Model | Per-attempt typical | Use when |
+|---|---|---:|---|
+| 1 | Haiku | $0.02 – $0.20 | First try β€” most "make red green" bugs are tactical |
+| 2 | Sonnet | $0.30 – $2.00 | Haiku failed, or the bug has multi-file scope |
+| 3 | Opus | $1.50 – $8.00 | Sonnet failed β€” architectural reasoning required (rarely worth it for a single failing test) |
diff --git a/ruflo/package.json b/ruflo/package.json
index beefe77ba4..43c3d40a72 100644
--- a/ruflo/package.json
+++ b/ruflo/package.json
@@ -1,6 +1,6 @@
{
"name": "ruflo",
- "version": "3.13.3",
+ "version": "3.14.0",
"description": "Ruflo - Enterprise AI agent orchestration platform. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
"main": "bin/ruflo.js",
"type": "module",
diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.json
index 20616e7b9a..bc9c339f98 100644
--- a/v3/@claude-flow/cli/package.json
+++ b/v3/@claude-flow/cli/package.json
@@ -1,6 +1,6 @@
{
"name": "@claude-flow/cli",
- "version": "3.13.3",
+ "version": "3.14.0",
"type": "module",
"description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
"main": "dist/src/index.js",
diff --git a/v3/@claude-flow/cli/src/mcp-tools/index.ts b/v3/@claude-flow/cli/src/mcp-tools/index.ts
index 6b67b6fc84..fe9f053c4e 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/index.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/index.ts
@@ -27,3 +27,5 @@ export { guidanceTools } from './guidance-tools.js';
export { autopilotTools } from './autopilot-tools.js';
// ADR-150 β€” MetaHarness MCP tools (score / genome / mcp-scan / threat-model / oia-audit)
export { metaharnessTools } from './metaharness-tools.js';
+// ADR-175-inspired β€” Test-Driven Repair via headless `claude -p`
+export { testgenTools } from './testgen-tools.js';
diff --git a/v3/@claude-flow/cli/src/mcp-tools/testgen-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/testgen-tools.ts
new file mode 100644
index 0000000000..59497296d0
--- /dev/null
+++ b/v3/@claude-flow/cli/src/mcp-tools/testgen-tools.ts
@@ -0,0 +1,163 @@
+/**
+ * Testgen MCP Tools β€” Test-Driven Repair surface.
+ *
+ * Exposes `ruflo-testgen` plugin scripts as first-class MCP tools so
+ * agents (Claude Code, Codex, etc.) can invoke them programmatically.
+ *
+ * Current surface (one tool, narrow on purpose β€” Conformant mode follows
+ * in a separate ADR):
+ *
+ * - testgen_tdd_repair Test-Driven Repair via headless `claude -p`
+ * (read failing test β†’ fix source β†’ verify)
+ *
+ * Inspired by agent-harness-generator/packages/darwin-mode ADR-175.
+ *
+ * ARCHITECTURAL CONSTRAINT (mirrors metaharness-tools.ts)
+ * Zero static `ruflo-testgen/*` imports. All script invocation stays
+ * behind a subprocess bridge. When the plugin isn't reachable at
+ * runtime, the tool returns `{success: true, degraded: true,
+ * reason: 'plugin-not-found'}` and exits 0 β€” same posture as
+ * metaharness-tools so callers see one contract.
+ *
+ * @module @claude-flow/cli/mcp-tools/testgen
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { MCPTool } from './types.js';
+import { getProjectCwd } from './types.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Locate the ruflo-testgen plugin's scripts directory.
+ *
+ * Mirrors `metaharness-tools.ts::locatePluginScripts()` strategy but
+ * targets the testgen plugin. Walks up from this module's own location
+ * (covers npx + global install) then falls back to cwd-walks. We probe
+ * for `tdd-repair/tdd-repair.mjs` (the only script in this surface
+ * today) β€” when that lands at a candidate path, we've found the dir.
+ */
+function locateTestgenScripts(): string | null {
+ const candidates: string[] = [];
+ let p = resolve(__dirname);
+ for (let i = 0; i < 8; i++) {
+ candidates.push(join(p, 'plugins', 'ruflo-testgen', 'scripts'));
+ candidates.push(join(p, '..', 'plugins', 'ruflo-testgen', 'scripts'));
+ p = dirname(p);
+ }
+ const cwd = getProjectCwd();
+ candidates.push(join(cwd, 'plugins', 'ruflo-testgen', 'scripts'));
+ candidates.push(join(cwd, 'node_modules', '@claude-flow', 'cli', 'plugins', 'ruflo-testgen', 'scripts'));
+ for (const c of candidates) {
+ if (existsSync(join(c, 'tdd-repair', 'tdd-repair.mjs'))) return c;
+ }
+ return null;
+}
+
+/**
+ * Run a testgen plugin script with the same success-semantics contract
+ * as metaharness-tools.ts (exit 0 β‡’ success: true even if degraded).
+ */
+function runTestgenScript(scriptName: string, args: string[]): Promise<{
+ exitCode: number;
+ json: unknown;
+ degraded: boolean;
+ success: boolean;
+}> {
+ return new Promise((resolve) => {
+ const dir = locateTestgenScripts();
+ if (!dir) {
+ resolve({
+ exitCode: 0,
+ json: { degraded: true, reason: 'plugin-not-found' },
+ degraded: true,
+ success: true,
+ });
+ return;
+ }
+ const scriptPath = join(dir, scriptName);
+ const p = spawn('node', [scriptPath, ...args], {
+ stdio: ['ignore', 'pipe', 'pipe'],
+ env: process.env,
+ });
+ let stdout = '';
+ p.stdout?.on('data', (d) => { stdout += d.toString(); });
+ p.stderr?.on('data', () => { /* swallow β€” graceful */ });
+ // 20 min hard ceiling (tdd-repair has its own 15 min cap; we add 5 min slack)
+ const timer = setTimeout(() => { try { p.kill('SIGTERM'); } catch { /* ignore */ } }, 20 * 60_000);
+ p.on('close', (code) => {
+ clearTimeout(timer);
+ let json: unknown = null;
+ const m = /\{[\s\S]*\}/.exec(stdout);
+ if (m) { try { json = JSON.parse(m[0]); } catch { /* leave null */ } }
+ const looksDegraded = !!(json && typeof json === 'object' && (json as { data?: { reason?: string } }).data?.reason === 'plugin-not-found');
+ const exitCode = code ?? 0;
+ resolve({
+ exitCode,
+ json,
+ degraded: looksDegraded,
+ success: exitCode === 0,
+ });
+ });
+ p.on('error', () => {
+ clearTimeout(timer);
+ resolve({
+ exitCode: 127,
+ json: { degraded: true, reason: 'spawn-failed' },
+ degraded: true,
+ success: false,
+ });
+ });
+ });
+}
+
+const TESTGEN_SUCCESS_SEMANTIC =
+ 'Returns `{success, data, degraded, exitCode}`. success=true when the script ran as designed (including graceful-degradation payloads); ' +
+ 'success=false when the test could not be repaired within --max-attempts (exit 1) or on config error (exit 2). ' +
+ 'Reads data.repaired for the actual outcome β€” true means the test now passes, false means it does not.';
+
+export const testgenTools: MCPTool[] = [
+ {
+ name: 'testgen_tdd_repair',
+ description:
+ 'ADR-175-inspired Test-Driven Repair. Given a failing test, spawn a bounded headless `claude -p` (Read/Edit/Bash only, --max-budget-usd capped) ' +
+ 'that makes the test pass without modifying it. The test\'s exit code IS the fitness function β€” no LLM-as-judge. ' +
+ 'Use when you have a failing test and want a verified fix. Skipping this and asking an agent to "fix the bug" is wrong because (a) you lose the bounded-cost guarantee, ' +
+ '(b) you lose the strict no-test-modification constraint, (c) you lose the verify-on-finish step. ' +
+ 'REQUIRES --confirm β€” without it returns a dry-run plan. Cost ladder: Haiku $0.02-0.20, Sonnet $0.30-2.00, Opus $1.50-8.00 per attempt. ' + TESTGEN_SUCCESS_SEMANTIC,
+ category: 'testgen',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ repo: { type: 'string', description: 'Absolute path to the repo root (default: cwd)', default: '.' },
+ test: { type: 'string', description: 'Relative path (from repo root) to the failing test file. REQUIRED.' },
+ testCommand: { type: 'string', description: 'Shell command to run the test (e.g. `npx vitest run tests/auth.test.ts`). REQUIRED.' },
+ maxAttempts: { type: 'number', description: '1..5 (ruflo cap). Each attempt gets budgetUsd/maxAttempts of the total budget.', default: 1 },
+ budgetUsd: { type: 'number', description: 'Total cost ceiling across all attempts. Hard cap β€” claude exits when reached.', default: 5.0 },
+ model: { type: 'string', enum: ['haiku', 'sonnet', 'opus'], description: 'Claude model tier. Haiku for simple bugs (default); Sonnet for multi-file; Opus rarely worth it.', default: 'haiku' },
+ confirm: { type: 'boolean', description: 'REQUIRED to actually run. Without it returns a dry-run plan.', default: false },
+ noTestOracle: { type: 'boolean', description: 'Conformant mode (agent writes its own repro). NOT YET IMPLEMENTED β€” returns config error.', default: false },
+ timeoutMs: { type: 'number', description: 'Hard wall-clock cap. Default 15 min.', default: 900000 },
+ },
+ required: ['test', 'testCommand'],
+ },
+ handler: async (input) => {
+ const args: string[] = [];
+ if (input.repo) args.push('--repo', String(input.repo));
+ if (input.test) args.push('--test', String(input.test));
+ if (input.testCommand) args.push('--test-command', String(input.testCommand));
+ if (input.maxAttempts !== undefined) args.push('--max-attempts', String(input.maxAttempts));
+ if (input.budgetUsd !== undefined) args.push('--budget', String(input.budgetUsd));
+ if (input.model) args.push('--model', String(input.model));
+ if (input.confirm === true) args.push('--confirm');
+ if (input.noTestOracle === true) args.push('--no-test-oracle');
+ if (input.timeoutMs !== undefined) args.push('--timeout-ms', String(input.timeoutMs));
+ const r = await runTestgenScript('tdd-repair/tdd-repair.mjs', args);
+ return { success: r.success, data: r.json, degraded: r.degraded, exitCode: r.exitCode };
+ },
+ },
+];