karajan-code 2.7.4 → 2.9.0

package/src/review/diff-generator.js

@@ -1,5 +1,11 @@
 import { runCommand } from "../utils/process.js";
 import { generateSnapshotDiff } from "./snapshot-diff.js";
+import { getRunContext } from "../utils/run-context.js";
+
+// Module-scope back-compat state for callers outside a `withRunContext`
+// scope. When inside a pipeline, `getRunContext()` provides per-run
+// isolation (TSK-0338) — the module-level values below are only consulted
+// as a last resort.
 
 /** @type {((command: string, args?: string[], options?: object) => Promise<object>)|null} */
 let _runner = null;
@@ -10,35 +16,39 @@ let _snapshot = null;
 /** @type {string|null} — project directory scope for git diff (prevents leaking unrelated changes) */
 let _projectDir = null;
 
-/**
- * Set the project directory scope. When set, all diffs are scoped to this directory.
- * Call once at pipeline start when projectDir differs from repo root.
- * @param {string|null} dir
- */
+/** Retained for back-compat; pipelines should use `withRunContext({ projectDir })` for isolation. */
 export function setProjectDir(dir) {
   _projectDir = dir;
 }
 
-/**
- * Store a filesystem snapshot for git-free diff fallback.
- * Call before the coder runs. If git is available, this is unused.
- * @param {Map<string, string>} snapshot
- */
+/** Retained for back-compat; pipelines should use `withRunContext({ snapshot })` for isolation. */
 export function setSnapshot(snapshot) {
   _snapshot = snapshot;
 }
 
-/**
- * Inject an RTK-aware runner so all git operations in this module benefit from token savings.
- * Call once at pipeline start when RTK is available.
- * @param {(command: string, args?: string[], options?: object) => Promise<object>} runner
- */
+/** Retained for back-compat; pipelines should use `withRunContext({ runner })` for isolation. */
 export function setRunner(runner) {
   _runner = runner;
 }
 
+function resolveRunner() {
+  return getRunContext()?.runner || _runner || runCommand;
+}
+
+function resolveProjectDir() {
+  const ctx = getRunContext();
+  if (ctx && "projectDir" in ctx) return ctx.projectDir;
+  return _projectDir;
+}
+
+function resolveSnapshot() {
+  const ctx = getRunContext();
+  if (ctx && "snapshot" in ctx) return ctx.snapshot;
+  return _snapshot;
+}
+
 function run(command, args, ...rest) {
-  return (_runner || runCommand)(command, args, ...rest);
+  return resolveRunner()(command, args, ...rest);
 }
 
 export async function computeBaseRef({ baseBranch = "main", baseRef = null }) {
@@ -61,8 +71,9 @@ export async function computeBaseRef({ baseBranch = "main", baseRef = null }) {
 }
 
 export async function generateDiff({ baseRef, stageNewFiles = false, projectDir = null }) {
-  // Auto-resolve projectDir from config if not passed explicitly
-  const scopeDir = projectDir || _projectDir || null;
+  // Auto-resolve projectDir from run context (TSK-0338) or module fallback
+  const scopeDir = projectDir || resolveProjectDir() || null;
+  const snapshot = resolveSnapshot();
 
   // Try git diff first
   try {
@@ -80,14 +91,16 @@ export async function generateDiff({ baseRef, stageNewFiles = false, projectDir
   } catch { /* git not available or failed */ }
 
   // Fallback: snapshot-based diff (no git needed)
-  if (_snapshot) {
+  if (snapshot) {
     const dir = projectDir || process.cwd();
-    return generateSnapshotDiff(_snapshot, null, dir);
+    return generateSnapshotDiff(snapshot, null, dir);
   }
 
-  // No git and no snapshot — generate diff of all files as new
+  // No git and no snapshot — generate diff of all files as new.
+  // TSK-0340: dropped a stray `const { takeSnapshot } = await import(...)`
+  // that was never used in this branch (we synthesize an empty Map and
+  // let generateSnapshotDiff do the file walk itself).
   const dir = projectDir || process.cwd();
-  const { takeSnapshot } = await import("./snapshot-diff.js");
   const emptySnapshot = new Map();
   return generateSnapshotDiff(emptySnapshot, null, dir);
 }

package/src/review/snapshot-diff.js

@@ -67,7 +67,7 @@ export async function generateSnapshotDiff(before, after, rootDir) {
   const lines = [];
 
   // New files (in after but not before)
-  for (const [path, hash] of after) {
+  for (const [path, _hash] of after) {
     if (!before.has(path)) {
       const content = await safeRead(join(rootDir, path));
       if (content !== null) {

package/src/roles/audit-role.js

@@ -1,6 +1,11 @@
 import { AgentRole } from "./agent-role.js";
 import { buildAuditPrompt, parseAuditOutput, AUDIT_DIMENSIONS } from "../prompts/audit.js";
 import { measureBasalCost, loadPreviousAudit, saveAuditSnapshot, computeGrowthDelta } from "../audit/basal-cost.js";
+import { detectProjectStack } from "../utils/stack-detect.js";
+import { collectSonarFindings } from "../audit/sonar-findings.js";
+import { collectWebPerfInput } from "../audit/webperf-input.js";
+import { collectOsvFindings } from "../audit/osv-findings.js";
+import { collectSemgrepFindings } from "../audit/semgrep-findings.js";
 
 function parseDimensions(dimensionsStr) {
   if (!dimensionsStr || dimensionsStr === "all") return null;
@@ -26,37 +31,98 @@ export class AuditRole extends AgentRole {
     super({ ...opts, name: "audit" });
   }
 
-  async execute(input) {
-    const task = typeof input === "string" ? input : input?.task || this.context?.task || "";
-    const onOutput = typeof input === "string" ? null : input?.onOutput || null;
-    const rawDimensions = typeof input === "object" ? input?.dimensions || null : null;
-    const context = typeof input === "object" ? input?.context || null : null;
-    const dimensions = typeof rawDimensions === "string" ? parseDimensions(rawDimensions) : rawDimensions;
-
+  /**
+   * Run the deterministic side of an audit — basalCost, stack detection,
+   * Sonar issues, WebPerf input — without invoking the LLM. Cheap (no
+   * tokens, no API call). KJC-TSK-0364 splits the original execute() into
+   * this collector + executeWithDeterministic() so the CLI can show
+   * deterministic findings first and ask the user before paying for the
+   * LLM phase.
+   *
+   * @param {object|string} input - same shape execute() accepts
+   * @returns {Promise<object>} deterministic context (the same data
+   *   execute() would gather internally)
+   */
+  async collectDeterministic(input) {
+    const noSonar = typeof input === "object" ? Boolean(input?.noSonar) : false;
+    const noOsv = typeof input === "object" ? Boolean(input?.noOsv) : false;
+    const noSemgrep = typeof input === "object" ? Boolean(input?.noSemgrep) : false;
     const projectDir = this.config?.projectDir || process.cwd();
     let basalCost = null;
     let growthDelta = null;
+    let stack = null;
+    let sonarFindings = null;
+    let webperf = null;
+    let osvFindings = null;
+    let semgrepFindings = null;
     try {
       basalCost = await measureBasalCost(projectDir);
       const previous = await loadPreviousAudit(projectDir);
       growthDelta = computeGrowthDelta(basalCost, previous);
     } catch { /* basal cost is best-effort */ }
+    try {
+      stack = await detectProjectStack(projectDir);
+    } catch { /* stack detect is best-effort */ }
+    if (!noSonar) {
+      try {
+        sonarFindings = await collectSonarFindings(this.config, this.logger);
+      } catch { /* sonar fetch is best-effort */ }
+    }
+    try {
+      webperf = collectWebPerfInput(stack, this.config);
+    } catch { /* webperf input is best-effort */ }
+    // OSV vulnerabilities — KJC-TSK-0365. Best-effort: missing
+    // osv-scanner binary returns available:false and the audit
+    // continues without the section.
+    if (!noOsv) {
+      try {
+        osvFindings = await collectOsvFindings(projectDir, this.logger);
+      } catch { /* osv-scanner is best-effort */ }
+    }
+    // Semgrep SAST — KJC-TSK-0366. Best-effort: missing semgrep binary
+    // returns available:false and the audit continues without the section.
+    if (!noSemgrep) {
+      try {
+        semgrepFindings = await collectSemgrepFindings(projectDir, this.logger);
+      } catch { /* semgrep is best-effort */ }
+    }
+    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings };
+  }
+
+  /**
+   * Run the LLM phase of an audit using a pre-collected deterministic
+   * context. KJC-TSK-0364: separated from execute() so the CLI can run
+   * collectDeterministic() first, show findings, prompt, and only then
+   * call this if the user wants to spend tokens.
+   */
+  async executeWithDeterministic(input, deterministicCtx) {
+    const task = typeof input === "string" ? input : input?.task || this.context?.task || "";
+    const onOutput = typeof input === "string" ? null : input?.onOutput || null;
+    const rawDimensions = typeof input === "object" ? input?.dimensions || null : null;
+    const context = typeof input === "object" ? input?.context || null : null;
+    const dimensions = typeof rawDimensions === "string" ? parseDimensions(rawDimensions) : rawDimensions;
+
+    const { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings } = deterministicCtx;
 
     const provider = this.resolveProvider();
     const agent = this.createAgentInstance(provider);
-    const prompt = buildAuditPrompt({ task, instructions: this.instructions, dimensions, context, basalCost, growthDelta });
+    const prompt = buildAuditPrompt({ task, instructions: this.instructions, dimensions, context, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings });
     const runArgs = { prompt, role: "audit" };
     if (onOutput) runArgs.onOutput = onOutput;
+    const startedAt = Date.now();
     const result = await agent.runTask(runArgs);
+    const durationMs = Date.now() - startedAt;
+
+    const usage = extractUsage(result, { provider, durationMs });
 
     if (!result.ok) {
-      return { ok: false, result: { error: result.error || result.output || "Audit failed", provider }, summary: `Audit failed: ${result.error || "unknown error"}`, usage: result.usage };
+      return { ok: false, result: { error: result.error || result.output || "Audit failed", provider }, summary: `Audit failed: ${result.error || "unknown error"}`, usage };
     }
 
     try {
       const parsed = parseAuditOutput(result.output);
       if (!parsed) {
-        return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage: result.usage };
+        return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage };
       }
       if (basalCost) { try { await saveAuditSnapshot(projectDir, basalCost); } catch { /* best-effort */ } }
 
@@ -65,13 +131,59 @@ export class AuditRole extends AgentRole {
         result: {
           summary: parsed.summary, dimensions: parsed.dimensions,
           topRecommendations: parsed.topRecommendations,
-          basalCost: basalCost || undefined, growthDelta: growthDelta || undefined, provider
+          textSummary: parsed.textSummary || undefined,
+          basalCost: basalCost || undefined, growthDelta: growthDelta || undefined,
+          stack: stack || undefined,
+          sonarFindings: sonarFindings?.available ? sonarFindings : undefined,
+          webperf: webperf?.available ? webperf : undefined,
+          osvFindings: osvFindings?.available ? osvFindings : undefined,
+          semgrepFindings: semgrepFindings?.available ? semgrepFindings : undefined,
+          provider
         },
         summary: buildSummary(parsed),
-        usage: result.usage
+        usage
       };
     } catch {
-      return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage: result.usage };
+      return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage };
     }
   }
+
+  /**
+   * Convenience: run both phases in one call. Identical to the previous
+   * (single-phase) execute() so MCP and pipeline callers don't change.
+   */
+  async execute(input) {
+    const deterministicCtx = await this.collectDeterministic(input);
+    return this.executeWithDeterministic(input, deterministicCtx);
+  }
+}
+
+/**
+ * Consolidate the usage telemetry the agent spreads across its top-level
+ * result fields. Returns a single object so consumers (CLI formatter,
+ * report-file writer, MCP) don't need to know about the spread shape.
+ *
+ * @param {object} result - raw agent.runTask() return
+ * @param {{provider: string, durationMs: number}} ctx
+ * @returns {{available: boolean, provider: string, model?: string, tokens_in?: number, tokens_out?: number, total_tokens?: number, cost_usd?: number, durationMs: number, reason?: string}}
+ */
+function extractUsage(result, { provider, durationMs }) {
+  if (!result || typeof result !== "object") {
+    return { available: false, provider, durationMs, reason: "no agent result" };
+  }
+  const tokens_in = Number.isFinite(result.tokens_in) ? result.tokens_in : null;
+  const tokens_out = Number.isFinite(result.tokens_out) ? result.tokens_out : null;
+  if (tokens_in === null && tokens_out === null) {
+    return { available: false, provider, model: result.model, durationMs, reason: `provider "${provider}" did not report token usage` };
+  }
+  return {
+    available: true,
+    provider,
+    model: result.model,
+    tokens_in: tokens_in ?? 0,
+    tokens_out: tokens_out ?? 0,
+    total_tokens: (tokens_in ?? 0) + (tokens_out ?? 0),
+    cost_usd: typeof result.cost_usd === "number" ? result.cost_usd : null,
+    durationMs,
+  };
 }

package/src/roles/coder-role.js

@@ -22,19 +22,41 @@ export class CoderRole extends AgentRole {
   }
 
   extractInput(input) {
-    if (typeof input === "string") return { task: input, reviewerFeedback: null, sonarSummary: null, deferredContext: null, onOutput: null };
+    if (typeof input === "string") {
+      return {
+        task: input,
+        reviewerFeedback: null, sonarSummary: null, deferredContext: null,
+        acceptanceTests: null,
+        adrs: null, specSection: null, reviewerFindings: null, huId: null,
+        onOutput: null
+      };
+    }
     return {
       task: input?.task || this.context?.task || "",
       reviewerFeedback: input?.reviewerFeedback || null,
       sonarSummary: input?.sonarSummary || null,
       deferredContext: input?.deferredContext || null,
+      // Tests-first (v2.7.5): the coder reads these as the gate it
+      // must satisfy. Only the plan-backed HU path populates this;
+      // the standard single-task `kj run` flow leaves it null.
+      acceptanceTests: input?.acceptanceTests || null,
+      // PR F (v2.7.5): per-HU planning context. ADRs constrain HOW,
+      // specSection ties this HU to a SPEC heading, reviewerFindings
+      // are filtered to entries that mention this HU. All four are
+      // null for non-plan-backed runs, which keeps the legacy flow
+      // byte-for-byte identical.
+      adrs: Array.isArray(input?.adrs) ? input.adrs : null,
+      specSection: input?.specSection || null,
+      reviewerFindings: input?.reviewerFindings || null,
+      huId: input?.huId || null,
       onOutput: input?.onOutput || null
     };
   }
 
-  async buildPrompt({ task, reviewerFeedback, sonarSummary, deferredContext }) {
+  async buildPrompt({ task, reviewerFeedback, sonarSummary, deferredContext, acceptanceTests, adrs, specSection, reviewerFindings, huId }) {
     const prompt = await buildCoderPrompt({
-      task, reviewerFeedback, sonarSummary, deferredContext,
+      task, reviewerFeedback, sonarSummary, deferredContext, acceptanceTests,
+      adrs, specSection, reviewerFindings, huId,
       coderRules: this.instructions,
       methodology: this.config?.development?.methodology || "tdd",
       serenaEnabled: Boolean(this.config?.serena?.enabled),

package/src/roles/planner-role.js

@@ -65,7 +65,48 @@ export class PlannerRole extends AgentRole {
 
     const sections = [];
     if (this.instructions) sections.push(this.instructions, "");
-    sections.push("Create an implementation plan for this task.", "Return concise numbered steps focused on execution order and risk.", "");
+    // Tests-first planning (v2.7.5):
+    // The planner MUST emit structured acceptance tests for every step.
+    // These are the contract the coder is handed (phase 2 of the
+    // tests-first flow); the tester role later runs them as the
+    // pass/fail gate. Without them the coder has no executable spec.
+    sections.push(
+      "Create an implementation plan for this task as structured JSON.",
+      "",
+      "Output MUST be a JSON object with this exact shape:",
+      "",
+      "```json",
+      "{",
+      '  "approach": "<2-3 sentence high-level plan>",',
+      '  "risks": ["<risk 1>", "<risk 2>"],',
+      '  "outOfScope": ["<excluded item>"],',
+      '  "steps": [',
+      "    {",
+      '      "description": "<what this step achieves, one sentence>",',
+      '      "spec_section": "<short reference to the SPEC section this implements, e.g. \\"5.3\\" or \\"§5 Initial Scope\\". Optional but strongly preferred.>",',
+      '      "acceptance_tests": [',
+      '        { "type": "gherkin", "content": "Given <ctx>\\nWhen <action>\\nThen <outcome>" },',
+      '        { "type": "shell", "content": "<bash command that must exit 0>" }',
+      "      ]",
+      "    }",
+      "  ]",
+      "}",
+      "```",
+      "",
+      "Rules for acceptance_tests (CRITICAL — this is the contract the coder must satisfy):",
+      '- EVERY step MUST have at least one acceptance_test. No empty arrays.',
+      '- "gherkin" tests describe observable behaviour in natural language. Use them for end-to-end or user-facing assertions.',
+      '- "shell" tests are bash commands that exit 0 on success. Use them for concrete verifications (file exists, lint passes, specific exit code, HTTP status).',
+      '- Write tests BEFORE the step is implemented — they should fail until the step is done, pass afterwards.',
+      '- Prefer 2-4 tests per step: one happy-path, at least one edge case / failure path.',
+      '- Do NOT use the generic fallback "npx vitest run" (pre-v2.7.5 placeholder). Each test must assert something specific to the step.',
+      "",
+      "spec_section: when the task includes a structured SPEC (numbered headings like '## 5. Initial Scope'), every step MUST cite the section it implements. Becomes traceability metadata for the coder and reviewer.",
+      "",
+      "Steps must be ordered so that each depends only on previous steps (the first step has no prerequisites).",
+      "Return ONLY the JSON — no prose, no markdown fences around it.",
+      ""
+    );
     if (this.config?.productContext) sections.push("## Product Context", this.config.productContext, "");
     if (this.config?.domainContext) sections.push("## Domain Context", this.config.domainContext, "");
     appendDecompositionSection(sections, triageDecomposition);

package/src/roles/repairer-role.js

@@ -0,0 +1,181 @@
+/**
+ * RepairerRole — repairs broken acceptance tests at runtime.
+ *
+ * The Brain calls this when an HU's acceptance test has failed N
+ * consecutive iterations with the same error signature, signalling
+ * that the test ITSELF may be the bug (not the implementation).
+ * Originated from the 2026-04-29 incident where the planner emitted
+ * a syntactically-broken jq query in HU 002's acceptance_tests; the
+ * coder iterated 3× trying to make an irreparable test pass; HU 002
+ * → failed → 7 dependents blocked.
+ *
+ * The role takes the failing test + its error output + HU intent and
+ * returns either a corrected test (`verdict: "fixable"` with
+ * `fixed_test`) or an escalation (`verdict: "unfixable"` with reason).
+ *
+ * Behaviour notes:
+ *  - The role MUST NOT soften assertions to make them pass — the test
+ *    defines the contract; this role's job is to make the test ASK
+ *    its question correctly, not weakly.
+ *  - The role MUST NOT rewrite a test to pass against the current
+ *    code. Code is measured against the test, not the other way.
+ *  - One bug per repair. If the test is layered with problems, return
+ *    the most blocking fix first; subsequent invocations handle the
+ *    rest.
+ */
+
+import { AgentRole } from "./agent-role.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
+
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Do NOT use any MCP tools. Focus only on diagnosing and (if possible) repairing a single broken acceptance test.",
+].join(" ");
+
+export class RepairerRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "repairer" });
+  }
+
+  resolveProvider() {
+    // Default to the same provider family the coder uses — keeps
+    // the repair attempt cheap and consistent. Per-role override
+    // works as for every other role.
+    return this.config?.roles?.repairer?.provider
+      || this.config?.roles?.coder?.provider
+      || this.config?.coder
+      || "claude";
+  }
+
+  /**
+   * Inputs:
+   *   - failingTest: the test object (`{ type, content }` or string).
+   *   - errorOutput: stdout+stderr from the last test run (truncated to
+   *     ~2KB to keep the prompt small).
+   *   - huTitle, huScope: intent context.
+   *   - siblingTests: the HU's other acceptance_tests (for consistency).
+   *   - iteration: how many coder iterations have already failed on this.
+   */
+  extractInput(input) {
+    if (typeof input === "string") {
+      return {
+        failingTest: input, errorOutput: "", huTitle: "", huScope: "",
+        siblingTests: [], iteration: 0, onOutput: null,
+      };
+    }
+    return {
+      failingTest: input?.failingTest ?? null,
+      errorOutput: input?.errorOutput ?? "",
+      huTitle: input?.huTitle ?? "",
+      huScope: input?.huScope ?? "",
+      siblingTests: Array.isArray(input?.siblingTests) ? input.siblingTests : [],
+      iteration: Number.isFinite(input?.iteration) ? input.iteration : 0,
+      onOutput: input?.onOutput ?? null,
+    };
+  }
+
+  async buildPrompt({ failingTest, errorOutput, huTitle, huScope, siblingTests, iteration }) {
+    const sections = [SUBAGENT_PREAMBLE];
+    if (this.instructions) sections.push(this.instructions);
+
+    const testContent = (failingTest && typeof failingTest === "object")
+      ? failingTest.content
+      : String(failingTest || "");
+    const testType = (failingTest && typeof failingTest === "object" && failingTest.type)
+      ? failingTest.type
+      : "shell";
+
+    sections.push(
+      "You are repairing a broken acceptance test. The coder has failed to satisfy it across multiple iterations,",
+      "and the Brain suspects the test ITSELF is the bug — not the implementation.",
+      "",
+      "## HU intent",
+      `Title: ${huTitle || "(unknown)"}`,
+      `Scope: ${huScope || "(unknown)"}`,
+      "",
+      `## Failing test (type: ${testType}, after ${iteration} iteration(s))`,
+      "```",
+      testContent,
+      "```",
+      "",
+      "## Last error output",
+      "```",
+      String(errorOutput || "").slice(0, 2048),
+      "```",
+    );
+
+    if (siblingTests.length > 0) {
+      sections.push("## HU's other acceptance tests (for consistency — do NOT modify these)", "```");
+      for (const t of siblingTests) {
+        const c = typeof t === "object" ? t.content : t;
+        sections.push(`- ${c}`);
+      }
+      sections.push("```");
+    }
+
+    sections.push(
+      "",
+      "## Your job",
+      "Decide whether the failing test is **fixable** (you can correct a syntactic / structural bug)",
+      "or **unfixable** (test is fundamentally impossible, or the test is correct and the code must change).",
+      "",
+      "Return ONLY a single valid JSON object:",
+      '{"verdict":"fixable"|"unfixable","fixed_test":{"type":"shell"|"gherkin","content":string}|null,"reason":string,"diagnostics":[string]}',
+      "",
+      "- When verdict=fixable, fixed_test is REQUIRED and reason describes the bug class.",
+      "- When verdict=unfixable, fixed_test is null and reason explains why.",
+      "- NEVER soften an assertion. NEVER rewrite to pass against current code.",
+    );
+
+    const projectDir = this.config?.projectDir || process.cwd();
+    const skills = await loadAvailableSkills(projectDir);
+    const skillSection = buildSkillSection(skills, {
+      provider: this._resolvedProvider || (typeof this.resolveProvider === "function" ? this.resolveProvider() : null),
+      role: "repairer",
+    });
+    if (skillSection) sections.push(skillSection);
+
+    return { prompt: sections.join("\n\n") };
+  }
+
+  parseOutput(raw) { return extractFirstJson(raw); }
+
+  isSuccessful(parsed) {
+    if (!parsed || typeof parsed !== "object") return false;
+    if (parsed.verdict === "fixable") {
+      // Must produce a complete fixed_test object.
+      const ft = parsed.fixed_test;
+      return Boolean(ft && typeof ft === "object" && typeof ft.content === "string" && ft.content.trim());
+    }
+    if (parsed.verdict === "unfixable") {
+      // Unfixable is a valid OUTCOME (escalation), not a role failure.
+      return Boolean(parsed.reason && String(parsed.reason).trim());
+    }
+    return false;
+  }
+
+  buildSuccessResult(parsed, provider) {
+    return {
+      verdict: parsed.verdict,
+      fixed_test: parsed.fixed_test || null,
+      reason: parsed.reason || "",
+      diagnostics: Array.isArray(parsed.diagnostics) ? parsed.diagnostics : [],
+      provider,
+    };
+  }
+
+  buildSummary(parsed) {
+    if (!parsed) return "Repairer: no parseable output";
+    if (parsed.verdict === "fixable") {
+      const reason = (parsed.reason || "").slice(0, 120);
+      return `Repairer: fixable — ${reason}`;
+    }
+    if (parsed.verdict === "unfixable") {
+      const reason = (parsed.reason || "").slice(0, 120);
+      return `Repairer: unfixable — ${reason}`;
+    }
+    return `Repairer: unexpected verdict "${parsed.verdict}"`;
+  }
+}