@karajan-family/code 4.21.0

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}"`;
+  }
+}

package/src/roles/researcher-role.js

@@ -0,0 +1,70 @@
+import { AgentRole } from "./agent-role.js";
+import { extractFirstJson } from "../utils/json-extract.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 researching the codebase."
+].join(" ");
+
+const EMPTY_RESEARCH = {
+  affected_files: [], patterns: [], constraints: [],
+  prior_decisions: [], risks: [], test_coverage: ""
+};
+
+export class ResearcherRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "researcher" });
+  }
+
+  async buildPrompt({ task }) {
+    const sections = [SUBAGENT_PREAMBLE];
+    if (this.instructions) sections.push(this.instructions);
+    sections.push(
+      "Investigate the codebase for the following task.",
+      "Identify affected files, patterns, constraints, prior decisions, risks, and test coverage.",
+      "Return a single valid JSON object with your findings and nothing else.",
+      '{"affected_files":[string],"patterns":[string],"constraints":[string],"prior_decisions":[string],"risks":[string],"test_coverage":string}',
+      `## Task\n${task}`
+    );
+    return { prompt: sections.join("\n\n") };
+  }
+
+  parseOutput(raw) { return extractFirstJson(raw); }
+
+  buildSuccessResult(parsed, provider) {
+    return {
+      affected_files: parsed.affected_files || [],
+      patterns: parsed.patterns || [],
+      constraints: parsed.constraints || [],
+      prior_decisions: parsed.prior_decisions || [],
+      risks: parsed.risks || [],
+      test_coverage: parsed.test_coverage || "",
+      provider
+    };
+  }
+
+  buildSummary(parsed) {
+    const files = parsed.affected_files?.length || 0;
+    const risks = parsed.risks?.length || 0;
+    const patterns = parsed.patterns?.length || 0;
+    const parts = [];
+    if (files) parts.push(`${files} file${files === 1 ? "" : "s"}`);
+    if (risks) parts.push(`${risks} risk${risks === 1 ? "" : "s"}`);
+    if (patterns) parts.push(`${patterns} pattern${patterns === 1 ? "" : "s"}`);
+    return parts.length ? `Research complete: ${parts.join(", ")} identified` : "Research complete";
+  }
+
+  handleParseNull(agentResult, provider) {
+    return {
+      ok: true,
+      result: { ...EMPTY_RESEARCH, raw: agentResult.output, provider },
+      summary: "Research complete (unstructured output)",
+      usage: agentResult.usage
+    };
+  }
+
+  handleParseError(_err, agentResult, provider) {
+    return this.handleParseNull(agentResult, provider);
+  }
+}

package/src/roles/reviewer-role.js

@@ -0,0 +1,104 @@
+import { AgentRole } from "./agent-role.js";
+import { buildRtkInstructions } from "../prompts/rtk-snippet.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "../prompts/prompt-layout.js";
+import { clipDiff } from "../prompts/diff-clip.js";
+import { buildSplitSignal } from "../prompts/split-signal.js";
+import { isMutationReviewEnabled, buildReviewerMutationSignal } from "../mutate/reviewer-signal.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 reviewing the code."
+].join(" ");
+
+export class ReviewerRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "reviewer" });
+  }
+
+  get agentMethod() { return "reviewTask"; }
+
+  extractInput(input) {
+    if (typeof input === "string") return { task: input, diff: "", reviewRules: null, onOutput: null };
+    return {
+      task: input?.task || this.context?.task || "",
+      diff: input?.diff || "",
+      reviewRules: input?.reviewRules || null,
+      onOutput: input?.onOutput || null
+    };
+  }
+
+  // Φ1-E (KJC-PCS-0057): stable block (preamble, instructions, mode,
+  // schema, contexts, rtk, review rules) first; task + diff — different
+  // on every review — last. The buckets ride along so ClaudeAgent can
+  // ship the stable block via --append-system-prompt (Φ1-D).
+  async buildPrompt({ task, diff, reviewRules }) {
+    // Opt-in (KJ_REVIEW_MUTATION): null when off/clean → prompt stays identical.
+    const mutationSignal = await buildReviewerMutationSignal({
+      enabled: isMutationReviewEnabled(),
+      projectDir: this.config?.projectDir,
+    });
+    // KJC-BUG-0134: a clip is declared as kj's own, outside the diff body.
+    const { body: clippedDiff, note: clipNote } = clipDiff(diff || "");
+    // KJC-BUG-0138: moved-lines correlation, computed on the FULL diff.
+    const splitSignal = buildSplitSignal(diff || "");
+    const layout = buildPromptLayout([
+      section(SUBAGENT_PREAMBLE, STABLE),
+      section(this.instructions, STABLE),
+      section(`You are a code reviewer in ${this.config?.review_mode || "standard"} mode.`, STABLE),
+      section("Return only one valid JSON object and nothing else.", STABLE),
+      section("JSON schema:", STABLE),
+      section('{"approved":boolean,"blocking_issues":[{"id":string,"severity":"critical|high|medium|low","file":string,"line":number,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}', STABLE),
+      section(this.config?.productContext ? `## Product Context\n${this.config.productContext}` : null, STABLE),
+      section(this.config?.domainContext ? `## Domain Context\n${this.config.domainContext}` : null, STABLE),
+      section(buildRtkInstructions({ rtkAvailable: Boolean(this.config?.rtk?.available) }), STABLE),
+      section(reviewRules ? `Review rules:\n${reviewRules}` : null, STABLE),
+      section(`Task context:\n${task}`, VOLATILE),
+      section(`Git diff:\n${clippedDiff}`, VOLATILE),
+      section(clipNote, VOLATILE),
+      section(splitSignal, VOLATILE),
+      section(mutationSignal, VOLATILE),
+    ]);
+    return { prompt: joinLayout(layout), stablePrompt: layout.stable, volatilePrompt: layout.volatile };
+  }
+
+  parseOutput(raw) {
+    const parsed = extractFirstJson(raw);
+    if (!parsed) throw new Error("Failed to parse reviewer output: no JSON found");
+    return parsed;
+  }
+
+  buildSuccessResult(parsed, provider, agentResult) {
+    return {
+      ...agentResult,
+      approved: parsed.approved,
+      blocking_issues: parsed.blocking_issues || [],
+      non_blocking_suggestions: parsed.non_blocking_suggestions || [],
+      confidence: parsed.confidence ?? null,
+      raw_summary: parsed.summary || ""
+    };
+  }
+
+  buildSummary(parsed) {
+    const blockingIssues = parsed.blocking_issues || [];
+    return parsed.approved
+      ? `Approved: ${parsed.summary || "no issues found"}`
+      : `Rejected: ${blockingIssues.length} blocking issue(s) — ${parsed.summary || ""}`;
+  }
+
+  handleParseError(err, agentResult, _provider) {
+    return {
+      ok: true,
+      result: {
+        ...agentResult,
+        approved: false,
+        blocking_issues: [{ id: "PARSE_ERROR", severity: "high", description: `Reviewer output could not be parsed: ${err.message}` }],
+        non_blocking_suggestions: [],
+        confidence: 0,
+        raw_summary: `Parse error: ${err.message}`
+      },
+      summary: `Reviewer output parse error: ${err.message}`
+    };
+  }
+}

package/src/roles/security-role.js

@@ -0,0 +1,73 @@
+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 auditing code for security vulnerabilities."
+].join(" ");
+
+export class SecurityRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "security" });
+  }
+
+  async buildPrompt({ task, diff }) {
+    const sections = [SUBAGENT_PREAMBLE];
+    if (this.instructions) sections.push(this.instructions);
+    sections.push(
+      "You are a security auditor. Analyze the code changes for vulnerabilities.",
+      "Check for: OWASP top 10, exposed secrets/API keys, hardcoded credentials, command injection, XSS, SQL injection, path traversal, prototype pollution, insecure dependencies.",
+      "Return a single valid JSON object with your findings and nothing else.",
+      '{"vulnerabilities":[{"severity":"critical|high|medium|low","category":string,"file":string,"line":number,"description":string,"fix_suggestion":string}],"verdict":"pass"|"fail"}',
+      `## Task\n${task}`
+    );
+    if (diff) sections.push(`## Git diff to audit\n${diff}`);
+
+    // Inject security-relevant skills (owasp-*, security-*, sast-*) filtered
+    // by role=security.
+    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: "security",
+    });
+    if (skillSection) sections.push(skillSection);
+
+    return { prompt: sections.join("\n\n") };
+  }
+
+  extractInput(input) {
+    if (typeof input === "string") return { task: input, diff: null };
+    return { task: input?.task || this.context?.task || "", diff: input?.diff || null, onOutput: input?.onOutput || null };
+  }
+
+  parseOutput(raw) { return extractFirstJson(raw); }
+
+  isSuccessful(parsed) {
+    const verdict = parsed.verdict || (parsed.vulnerabilities?.length ? "fail" : "pass");
+    return verdict === "pass";
+  }
+
+  buildSuccessResult(parsed, provider) {
+    const verdict = parsed.verdict || (parsed.vulnerabilities?.length ? "fail" : "pass");
+    return { vulnerabilities: parsed.vulnerabilities || [], verdict, provider };
+  }
+
+  buildSummary(parsed) {
+    const verdict = parsed.verdict || (parsed.vulnerabilities?.length ? "fail" : "pass");
+    const vulns = parsed.vulnerabilities || [];
+    if (!vulns.length) return `Verdict: ${verdict}; No vulnerabilities found`;
+
+    const bySeverity = {};
+    for (const v of vulns) bySeverity[v.severity || "unknown"] = (bySeverity[v.severity || "unknown"] || 0) + 1;
+
+    const order = { critical: 0, high: 1, medium: 2, low: 3 };
+    const parts = Object.entries(bySeverity)
+      .sort(([a], [b]) => (order[a] ?? 4) - (order[b] ?? 4))
+      .map(([sev, count]) => `${count} ${sev}`);
+
+    return `Verdict: ${verdict}; ${parts.join(", ")}`;
+  }
+}