@karajan-family/code 4.21.0

package/src/mcp/tools.js

@@ -0,0 +1,432 @@
+export const tools = [
+  {
+    name: "kj_init",
+    description: "Initialize karajan-code config, review rules, and SonarQube",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kjHome: { type: "string", description: "Optional KJ_HOME directory" },
+        timeoutMs: { type: "number", description: "Optional command timeout in ms" }
+      }
+    }
+  },
+  {
+    name: "kj_doctor",
+    description: "Check system dependencies, agent CLIs, ports, tokens and MCP health — auto-remediates when possible",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kjHome: { type: "string" },
+        timeoutMs: { type: "number" },
+        checkOnly: { type: "boolean", description: "Detect only, do not apply fixes" },
+        yes: { type: "boolean", description: "Auto-confirm prompts for invasive remediations" },
+        json: { type: "boolean", description: "Emit machine-readable JSON output" },
+        verbose: { type: "boolean", description: "Include fix hints and timing per check" }
+      }
+    }
+  },
+  {
+    name: "kj_config",
+    description: "Show kj configuration",
+    inputSchema: {
+      type: "object",
+      properties: {
+        json: { type: "boolean" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_scan",
+    description: "Run SonarQube scan for current project",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kjHome: { type: "string" },
+        sonarToken: { type: "string" },
+        timeoutMs: { type: "number" }
+      }
+    }
+  },
+  {
+    name: "kj_run",
+    description:
+      "Run the full Karajan pipeline. IMPORTANT: Pass the user's task description exactly as they wrote it. Do NOT group, split, reorder, or modify tasks yourself. Karajan handles decomposition, role activation, iteration, and quality gates internally. Do NOT override pipeline parameters (enableHuReviewer, mode, methodology) unless the user explicitly requested it. If you have observations about the task, use kj_suggest instead.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "Task description for the coder (can include a Planning Game card ID like KJC-TSK-0042). Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md (or any text file) whose contents become the task description. Relative paths resolve against projectDir." },
+        plan: { type: "string", description: "Plan ID from kj_plan. Loads persisted plan context and skips researcher/architect/planner stages." },
+        projectDir: { type: "string", description: "Absolute path to the project directory. Required when KJ MCP server runs from a different directory than the target project." },
+        pgTask: { type: "string", description: "Planning Game card ID (e.g., KJC-TSK-0042). If provided, fetches full card details as task context and updates card status on completion." },
+        pgProject: { type: "string", description: "Planning Game project ID (e.g., 'Karajan Code'). Required when pgTask is used." },
+        planner: { type: "string" },
+        coder: { type: "string" },
+        reviewer: { type: "string" },
+        refactorer: { type: "string" },
+        plannerModel: { type: "string" },
+        coderModel: { type: "string" },
+        reviewerModel: { type: "string" },
+        refactorerModel: { type: "string" },
+        enablePlanner: { type: "boolean" },
+        enableReviewer: { type: "boolean" },
+        enableRefactorer: { type: "boolean" },
+        enableResearcher: { type: "boolean" },
+        enableTester: { type: "boolean" },
+        enableSecurity: { type: "boolean" },
+        enableImpeccable: { type: "boolean" },
+        enablePerf: { type: "boolean" },
+        enableTriage: { type: "boolean" },
+        enableDiscover: { type: "boolean" },
+        enableArchitect: { type: "boolean" },
+        enableHuReviewer: { type: "boolean" },
+        architectModel: { type: "string" },
+        huFile: { type: "string", description: "Path to YAML file with HU stories to certify before coding" },
+        enableSerena: { type: "boolean" },
+        enableCi: { type: "boolean", description: "Enable Karajan CI (early PR + dispatch comments/reviews)" },
+        reviewerFallback: { type: "string" },
+        reviewerRetries: { type: "number" },
+        mode: { type: "string" },
+        maxIterations: { type: "number" },
+        maxIterationMinutes: { type: "number" },
+        maxTotalMinutes: { type: "number" },
+        baseBranch: { type: "string" },
+        baseRef: { type: "string" },
+        methodology: { type: "string", enum: ["tdd", "standard"] },
+        autoCommit: { type: "boolean" },
+        autoPush: { type: "boolean" },
+        autoPr: { type: "boolean" },
+        autoRebase: { type: "boolean" },
+        branchPrefix: { type: "string" },
+        autoSimplify: { type: "boolean", description: "Auto-simplify pipeline for simple tasks (level trivial/simple). Disable with false to force full pipeline." },
+        smartModels: { type: "boolean", description: "Enable/disable smart model selection based on triage complexity" },
+        checkpointInterval: { type: "number", description: "Minutes between interactive checkpoints (default: 5). Set 0 to disable." },
+        taskType: { type: "string", enum: ["sw", "infra", "doc", "add-tests", "refactor"], description: "Explicit task type for policy resolution. Overrides triage classification." },
+        quiet: { type: "boolean", description: "Suppress raw agent output lines, show only stage status (default: true). Set false for verbose output." },
+        noSonar: { type: "boolean" },
+        design: { type: "boolean", description: "Activate design refactoring mode. Impeccable role applies design changes instead of just auditing." },
+        enableSonarcloud: { type: "boolean", description: "Enable SonarCloud scan (complementary to SonarQube)" },
+        kjHome: { type: "string" },
+        sonarToken: { type: "string" },
+        timeoutMs: { type: "number" },
+        domain: { type: "string", description: "Domain knowledge: inline text describing the project domain, or absolute path to a .md file. Auto-saved to .karajan/domains/ for the curator." },
+        brain: { type: "string", enum: ["on", "off"], description: "Brain decisor: on|off. Controls whether intent-driven routing overrides pipeline flags." },
+        forceRole: { type: "array", items: { type: "string" }, description: "Force roles ON regardless of triage (e.g. [\"security\"])" },
+        skipRole: { type: "array", items: { type: "string" }, description: "Force roles OFF regardless of triage (e.g. [\"tester\"])" },
+        specReviewMode: { type: "string", enum: ["auto", "skip"], description: "Pre-pipeline spec-reviewer behaviour (KJC-PCS-0048). `auto` (default): the role runs, findings stream to the client via progress events; the pipeline continues regardless. `skip`: bypass the reviewer entirely (mirrors the --skip-spec-review CLI flag)." }
+      }
+    }
+  },
+  {
+    name: "kj_resume",
+    description:
+      "Resume a paused, stopped, or failed session by ID. For paused sessions, provide an answer. For stopped/failed sessions, re-runs the flow from scratch. Sends real-time progress notifications via MCP logging.",
+    inputSchema: {
+      type: "object",
+      required: ["sessionId"],
+      properties: {
+        sessionId: { type: "string", description: "Session ID to resume" },
+        answer: { type: "string", description: "Answer to the question that caused the pause" },
+        projectDir: { type: "string", description: "Absolute path to the project directory" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_report",
+    description: "Read latest or list session reports. Use trace=true for chronological stage-by-stage breakdown with timing and token usage.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        list: { type: "boolean" },
+        sessionId: { type: "string" },
+        format: { type: "string", enum: ["text", "json"] },
+        trace: { type: "boolean", description: "Show chronological trace of all pipeline stages" },
+        currency: { type: "string", enum: ["usd", "eur"], description: "Display costs in this currency" },
+        pgTask: { type: "string", description: "Filter reports by Planning Game card ID (e.g., KJC-TSK-0042)" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_roles",
+    description: "List pipeline roles or show the template instructions for a specific role. Use action='list' to see all roles with their provider and status. Use action='show' with roleName to read the .md template.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["list", "show"], description: "Action: list all roles or show a specific role template" },
+        roleName: { type: "string", description: "Role name to show (e.g. coder, reviewer, triage, reviewer-paranoid)" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_agents",
+    description: "List or change which AI agent (provider) is assigned to each pipeline role. Use action='list' to see current assignments. Use action='set' with role and provider to change it persistently (writes to kj.config.yml, no restart needed).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["list", "set"], description: "Action: list current agents or set a role's provider" },
+        role: { type: "string", description: "Role to change (e.g. coder, reviewer, planner, triage)" },
+        provider: { type: "string", description: "New provider to assign (e.g. claude, codex, gemini, aider)" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_preflight",
+    description: "Confirm or adjust agent configuration before first kj_run/kj_code. REQUIRED before running any task via MCP. Show the config to the human, get their confirmation or adjustments, then call this tool with their response.",
+    inputSchema: {
+      type: "object",
+      required: ["humanResponse"],
+      properties: {
+        humanResponse: { type: "string", description: "The human's response: 'ok' to confirm defaults, or specific changes like 'use gemini as coder'" },
+        coder: { type: "string", description: "Override coder for this session" },
+        reviewer: { type: "string", description: "Override reviewer for this session" },
+        tester: { type: "string", description: "Override tester for this session" },
+        security: { type: "string", description: "Override security for this session" },
+        solomon: { type: "string", description: "Override solomon for this session" },
+        enableTester: { type: "boolean", description: "Enable/disable tester for this session" },
+        enableSecurity: { type: "boolean", description: "Enable/disable security for this session" }
+      }
+    }
+  },
+  {
+    name: "kj_code",
+    description: "Run coder-only mode. Pass the user's task exactly as described. Do NOT split or reinterpret the task.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "Task description. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
+        coder: { type: "string" },
+        coderModel: { type: "string" },
+        projectDir: { type: "string", description: "Absolute path to the project directory" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_review",
+    description: "Run reviewer-only mode against current diff. Do NOT filter or pre-process the diff before passing it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "Task description. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
+        reviewer: { type: "string" },
+        reviewerModel: { type: "string" },
+        baseRef: { type: "string" },
+        projectDir: { type: "string", description: "Absolute path to the project directory" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_status",
+    description: "Show real-time status and log of the current or last Karajan run. Returns a parsed status (current stage, agent, iteration, errors) plus recent log lines. Use this to monitor progress while kj_run/kj_plan/kj_code is executing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lines: { type: "number", description: "Number of log lines to show (default 50)" }
+      }
+    }
+  },
+  {
+    name: "kj_plan",
+    description: "Generate implementation plan for a task. Pass the task as the user described it. Karajan's planner decides the approach.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "Task description. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
+        planner: { type: "string" },
+        plannerModel: { type: "string" },
+        coder: { type: "string", description: "Legacy alias for planner" },
+        coderModel: { type: "string", description: "Legacy alias for plannerModel" },
+        projectDir: { type: "string", description: "Absolute path to the project directory" },
+        kjHome: { type: "string" },
+        specReviewMode: { type: "string", enum: ["auto", "skip"], description: "Pre-planner spec-reviewer behaviour (KJC-PCS-0048). `auto` (default): runs the reviewer, findings stream as progress, planner continues. `skip`: bypass entirely." }
+      }
+    }
+  },
+  {
+    name: "kj_discover",
+    description: "Analyze a task for gaps, ambiguities, and missing information before execution. Returns a verdict (ready/needs_validation) with structured gap list. Can read task details from Planning Game if pgTask is provided.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "Task description to analyze for gaps. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
+        mode: { type: "string", enum: ["gaps", "momtest", "wendel", "classify", "jtbd"], description: "Discovery mode: gaps (default), momtest (Mom Test questions), wendel (behavior change checklist), classify (START/STOP/DIFFERENT), or jtbd (Jobs-to-be-Done)" },
+        context: { type: "string", description: "Additional context for the analysis (e.g., research output)" },
+        pgTask: { type: "string", description: "Planning Game card ID (e.g., KJC-TSK-0042). If provided, fetches full card details as additional context." },
+        pgProject: { type: "string", description: "Planning Game project ID. Required when pgTask is used." },
+        projectDir: { type: "string", description: "Absolute path to the project directory" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_triage",
+    description: "Classify task complexity and recommend which pipeline roles to activate. Returns level (trivial/simple/medium/complex), taskType, recommended roles, and optional decomposition.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "Task description to classify. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
+        projectDir: { type: "string", description: "Absolute path to the project directory" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_researcher",
+    description: "Research the codebase for a task. Identifies affected files, patterns, constraints, prior decisions, risks, and test coverage.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "Task description to research. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
+        projectDir: { type: "string", description: "Absolute path to the project directory" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_architect",
+    description: "Design solution architecture for a task. Returns layers, patterns, data model, API contracts, tradeoffs, and a verdict (ready/needs_clarification).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "Task description to architect. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
+        context: { type: "string", description: "Additional context (e.g., researcher output)" },
+        projectDir: { type: "string", description: "Absolute path to the project directory" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_audit",
+    description: "Analyze codebase health without modifying files. Returns findings across security, code quality, performance, architecture, and testing dimensions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "Optional focus for the audit. If absent (and no taskFile), defaults to a full-codebase analysis." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file with the audit focus." },
+        projectDir: { type: "string", description: "Absolute path to the project to audit" },
+        dimensions: { type: "string", description: "Comma-separated dimensions to analyze: security,codeQuality,performance,architecture,testing (default: all)" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_board",
+    description: "Start, stop, or check status of the HU Board dashboard",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["start", "stop", "status"], description: "Action to perform (default: status)" },
+        port: { type: "number", description: "Port (default: 4000)" }
+      }
+    }
+  },
+  {
+    name: "kj_hu",
+    description: "Manage user stories (HUs) in the local board",
+    inputSchema: {
+      type: "object",
+      required: ["action"],
+      properties: {
+        action: { type: "string", enum: ["create", "update", "list", "get"], description: "Action to perform" },
+        title: { type: "string", description: "HU title (required for create)" },
+        description: { type: "string", description: "HU description" },
+        acceptanceCriteria: { type: "string", description: "Acceptance criteria" },
+        huId: { type: "string", description: "HU ID (required for update/get)" },
+        status: { type: "string", description: "HU status (for create/update)", enum: ["pending", "coding", "reviewing", "done", "failed", "blocked"] },
+        projectDir: { type: "string", description: "Project directory (defaults to cwd)" }
+      }
+    }
+  },
+  {
+    name: "kj_suggest",
+    description: "Propose an observation or suggestion to Karajan's Solomon engine. Solomon will evaluate it and decide whether to accept, reject, or ask the human. You CANNOT override pipeline decisions through this tool, only propose.",
+    inputSchema: {
+      type: "object",
+      required: ["suggestion"],
+      properties: {
+        suggestion: { type: "string", description: "What you observed or want to propose" },
+        context: { type: "string", description: "Additional context (current HU, iteration, etc.)" },
+        projectDir: { type: "string", description: "Project directory" }
+      }
+    }
+  },
+  {
+    name: "kj_skills",
+    description: "Manage OpenSkills for domain-specific agent knowledge. Install skills from the marketplace or GitHub repos to give coders domain expertise.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["install", "remove", "list", "read"], description: "Action to perform" },
+        source: { type: "string", description: "Skill source: marketplace name, GitHub URL, or local path (for install)" },
+        name: { type: "string", description: "Skill name (for remove/read)" },
+        global: { type: "boolean", description: "Install globally (~/.agent/skills/) instead of project-local" },
+        projectDir: { type: "string", description: "Project directory" }
+      },
+      required: ["action"]
+    }
+  },
+  {
+    name: "kj_undo",
+    description: "Revert the last pipeline run by resetting to the pre-pipeline commit. Default: soft reset (keeps changes staged). Use hard=true to discard all changes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        hard: { type: "boolean", description: "If true, discard all changes (git reset --hard). Default: false (soft reset, keeps changes staged)." },
+        projectDir: { type: "string", description: "Absolute path to the project directory" }
+      }
+    }
+  },
+  {
+    name: "kj_clean",
+    description: "Garbage-collect stale Karajan state: orphan plans (project dir no longer exists), finalised plans/sessions past their retention window, and HU story batches. Dry-run by default; pass yes=true to actually delete. Use nuke=true to wipe everything (retention=0 on every bucket + drop the HU board SQLite DB).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        yes: { type: "boolean", description: "If true, actually delete. Default false (dry-run: returns the list of items that would be removed without touching disk)." },
+        nuke: { type: "boolean", description: "If true, retention=0 on every bucket + wipe the HU board DB (stops the board first if running). The \"I want it all gone right now\" button." },
+        planDays: { type: "number", description: "Keep finalised plans (approved/rejected/executed) for this many days. Default: 30." },
+        draftDays: { type: "number", description: "Keep draft plans for this many days. Default: 60." },
+        sessionDays: { type: "number", description: "Keep finalised sessions for this many days. Default: 7." },
+        huDays: { type: "number", description: "Keep HU story batches for this many days. Default: 14." }
+      }
+    }
+  },
+  {
+    name: "kj_rag_query",
+    description: "Run a semantic search across the indexed Karajan plans, onboarding briefs and (optionally) project source code. Returns the top-K nearest chunks with their metadata so the agent can quote prior decisions, locate where a concept was last implemented, or pull architectural context without re-walking the repo. The store is empty until `kj_rag_index` (or `kj rag index` CLI) has been run at least once on this project; in that case the response carries `empty: true`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "The natural-language query." },
+        topK: { type: "number", description: "Max number of hits to return. Default: 5." },
+        scope: { type: "string", description: "Filter by chunk kind: 'plans' | 'code' | 'onboarding' | 'all' (default)." },
+        projectDir: { type: "string", description: "Absolute path to the project directory" }
+      },
+      required: ["text"]
+    }
+  },
+  {
+    name: "kj_rag_index",
+    description: "(Re)index this project's Karajan-managed assets — every plan-*.json under ~/.karajan/plans/<slug>/ plus the onboarding brief at ~/.karajan/onboarding/<slug>.md — into the local vector store. Idempotent: a re-run replaces the chunks for each source, never appends duplicates. Pass `withSources: true` to also index the project's JS/TS files (skips node_modules / .git / dist / etc.). Required as a one-time bootstrap before kj_rag_query returns anything; safe to re-run after every `kj plan generate`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        withSources: { type: "boolean", description: "Also index .js/.ts files under projectDir. Default false." },
+        projectDir: { type: "string", description: "Absolute path to the project directory" }
+      }
+    }
+  }
+];

package/src/mutate/diff-scope.js

@@ -0,0 +1,105 @@
+/**
+ * Diff-scoping for mutation testing. Translates a git range (`--since <ref>`)
+ * into changed source files + line ranges, then into the scope flags of the
+ * tool resolved by the registry (`src/mutate/tool-registry.js`). Mutating only
+ * what the coder just touched is what makes mutation testing cheap and useful.
+ * The git call is injectable so the pure logic is testable without a repo.
+ */
+
+import { runCommand } from "../utils/process.js";
+import { getMutationTool } from "./tool-registry.js";
+
+const SOURCE_EXTENSIONS = {
+  javascript: [".js", ".mjs", ".cjs", ".jsx"],
+  typescript: [".ts", ".tsx"],
+  python: [".py"],
+  php: [".php"],
+  go: [".go"],
+  java: [".java"],
+};
+
+const HUNK = /^@@ -\S+ \+(\d+)(?:,(\d+))?/;
+
+/**
+ * Parse `git diff --unified=0` into new-side line ranges per file. Deleted
+ * files (`+++ /dev/null`) are omitted — there is nothing to mutate.
+ * @returns {Record<string, Array<[number, number]>>}
+ */
+export function parseUnifiedDiff(diffText) {
+  const ranges = {};
+  let current = null;
+  for (const line of String(diffText || "").split("\n")) {
+    if (line.startsWith("+++ ")) {
+      const target = line.slice(4).trim();
+      current = target === "/dev/null" ? null : target.replace(/^b\//, "");
+      if (current) ranges[current] ??= [];
+      continue;
+    }
+    if (!current) continue;
+    const match = HUNK.exec(line);
+    if (!match) continue;
+    const start = Number(match[1]);
+    const count = match[2] === undefined ? 1 : Number(match[2]);
+    if (count > 0) ranges[current].push([start, start + count - 1]);
+  }
+  return ranges;
+}
+
+/** @returns {string[]} source extensions for a language ([] if unsupported) */
+export function sourceExtensions(language) {
+  return SOURCE_EXTENSIONS[language] ?? [];
+}
+
+/** Keep only files whose extension belongs to the language's source set. */
+export function filterSourceFiles(files, language) {
+  const exts = sourceExtensions(language);
+  if (exts.length === 0) return [];
+  return files.filter((file) => exts.some((ext) => file.endsWith(ext)));
+}
+
+/**
+ * Build the tool's scope arguments for the changed source files. `ranges`
+ * (per-file changed line ranges) is only consumed by Stryker (`path:start-end`).
+ * @param {{language: string, files: string[], ranges?: Record<string, Array<[number, number]>>}} params
+ */
+export function buildScope({ language, files, ranges }) {
+  const tool = getMutationTool(language);
+  if (!tool.supported) {
+    return { supported: false, reason: tool.reason, empty: true, args: [] };
+  }
+  const source = filterSourceFiles(files ?? [], language);
+  if (source.length === 0) {
+    return { supported: true, tool: tool.id, empty: true, targets: [], args: [] };
+  }
+  const targets =
+    tool.id === "stryker" && ranges
+      ? source.flatMap((file) =>
+          (ranges[file] ?? [[undefined, undefined]]).map(([start, end]) =>
+            start === undefined ? file : `${file}:${start}-${end}`,
+          ),
+        )
+      : source;
+  const value = targets.join(tool.scope.separator);
+  const args = tool.scope.flag ? [tool.scope.flag, value] : [value];
+  return { supported: true, tool: tool.id, empty: false, targets, args };
+}
+
+/**
+ * Fetch the diff for `since..toRef` and compute the mutation scope. `run` is
+ * the injectable git runner (defaults to `runCommand`).
+ * @param {{since: string, language: string, toRef?: string, run?: Function}} params
+ */
+export async function getDiffScope({ since, language, toRef = "HEAD", staged = false, run = runCommand }) {
+  // MUT-A (KJC-TSK-0716): staged=true scopea al ÍNDICE (git diff --cached) —
+  // lo que el review gate evalúa. since..HEAD con since=HEAD sería un diff
+  // VACÍO y el pre-gate no mutaría nada (catch de codex, agravado).
+  const args = staged ? ["diff", "--unified=0", "--cached"] : ["diff", "--unified=0", `${since}..${toRef}`];
+  const result = await run("git", args).catch(
+    () => null,
+  );
+  if (!result || result.exitCode !== 0) {
+    return { supported: true, empty: true, targets: [], args: [] };
+  }
+  const ranges = parseUnifiedDiff(result.stdout);
+  return buildScope({ language, files: Object.keys(ranges), ranges });
+}

package/src/mutate/reviewer-signal.js

@@ -0,0 +1,76 @@
+/**
+ * Reviewer opt-in mutation signal (KJC-TSK-0588). OFF by default: only when
+ * `KJ_REVIEW_MUTATION` is set does the reviewer run `kj mutate` scoped to the
+ * diff and fold surviving mutants into its verdict as a weak-test signal.
+ * A null return means "add nothing" → the default-off prompt stays identical.
+ */
+
+import { mutateCommand } from "../commands/mutate.js";
+
+const DEFAULT_SINCE = "HEAD~1";
+const ENABLED = /^(1|true|yes|on)$/i;
+
+/** True when the reviewer mutation opt-in is switched on via env. */
+export function isMutationReviewEnabled(env = process.env) {
+  return ENABLED.test(String(env?.KJ_REVIEW_MUTATION ?? "").trim());
+}
+
+// Drives `kj mutate --json` over the diff, capturing its output instead of
+// printing it, and returns {code, result} where result is the normalized JSON.
+async function defaultRun({ since, projectDir }) {
+  const lines = [];
+  const code = await mutateCommand({
+    since,
+    projectDir,
+    json: true,
+    maxSurvivors: Number.POSITIVE_INFINITY,
+    logger: { info: (m) => lines.push(String(m)) },
+  });
+  const jsonLine = [...lines].reverse().find((l) => l.trim().startsWith("{"));
+  return { code, result: jsonLine ? JSON.parse(jsonLine) : null };
+}
+
+function unavailableNote() {
+  return [
+    "## Mutation testing (advisory)",
+    "Mutation testing was requested but could not run on this diff (unsupported",
+    "stack or tool unavailable). Treat it as unavailable — do not infer test",
+    "quality from its absence.",
+  ].join("\n");
+}
+
+function survivorSection(survivors) {
+  const lines = survivors.map((s) => `- ${s.file}:${s.line ?? "?"} (${s.mutator ?? s.status})`);
+  return [
+    "## Mutation testing (advisory signal)",
+    "The following mutants survived over the changed lines — the tests did not",
+    "catch these deliberate defects, so the covering tests are weak. Weigh this",
+    "as a signal about test quality, not as a hard blocker on its own:",
+    ...lines,
+  ].join("\n");
+}
+
+/**
+ * Build the reviewer's mutation-signal prompt section, or null to add nothing.
+ * `run` ({since, projectDir}) → {code, result} is injectable for tests.
+ * @returns {Promise<string|null>}
+ */
+export async function buildReviewerMutationSignal({
+  enabled,
+  since = DEFAULT_SINCE,
+  projectDir = process.cwd(),
+  run = defaultRun,
+} = {}) {
+  if (!enabled) return null;
+  let outcome;
+  try {
+    outcome = await run({ since, projectDir });
+  } catch {
+    return unavailableNote();
+  }
+  const { code, result } = outcome ?? {};
+  if (code === 1 || code === 2) return unavailableNote();
+  const survivors = result?.survived ?? [];
+  if (survivors.length === 0) return null;
+  return survivorSection(survivors);
+}