karajan-code 3.7.1 → 3.8.0

package/src/config/defaults.js

@@ -27,7 +27,8 @@ const DEFAULTS = {
     triage: { provider: null, model: null },
     discover: { provider: null, model: null },
     architect: { provider: null, model: null },
-    hu_reviewer: { provider: null, model: null }
+    hu_reviewer: { provider: null, model: null },
+    start: { provider: null, model: "haiku" }
   },
   pipeline: {
     planner: { enabled: false },

package/src/config/schema.js

@@ -90,6 +90,7 @@ const RolesMap = v.optional(v.looseObject({
   discover: v.optional(RoleEntry),
   architect: v.optional(RoleEntry),
   hu_reviewer: v.optional(RoleEntry),
+  start: v.optional(RoleEntry),
 }));
 
 const PipelineEntry = v.looseObject({

package/src/guards/secret-redactor.js

@@ -0,0 +1,71 @@
+// KJC-TSK-0583 — Inbound secret redaction for the review boundary.
+//
+// The outbound boundary (output-guard.js) already blocks committing secrets.
+// This closes the *inbound* gap: a hardcoded credential in the working tree
+// would otherwise reach the (possibly cloud) reviewer model verbatim inside the
+// diff. `redactSecrets` masks each credential before the model sees it, reusing
+// the SAME catalog as output-guard — no new patterns, no AI cost, deterministic.
+import { CREDENTIAL_PATTERNS } from "./output-guard.js";
+
+// Families whose match begins with a fixed, identifiable literal prefix. The
+// placeholder keeps that prefix so the reviewer can still tell WHAT kind of
+// secret was redacted (and say "move it to .env") without seeing the value.
+const STABLE_PREFIX_BY_ID = {
+  "aws-key": "AKIA",
+  "npm-token": "npm_",
+  "openai-key": "sk-",
+  "anthropic-key": "sk-ant-",
+  "stripe-key": "sk_live_",
+  "stripe-test": "sk_test_",
+  "google-api-key": "AIza",
+};
+
+// Families with a dynamic prefix: keep the real match up to and including the
+// first separator (ghp_/gho_/…, xoxb-/xoxp-/…), then mask the rest.
+const DYNAMIC_SEPARATOR_BY_ID = {
+  "github-token": "_",
+  "slack-token": "-",
+};
+
+const GENERIC = "***REDACTED-SECRET***";
+const SUFFIX = "***REDACTED***";
+
+function placeholderFor(id, match) {
+  const stable = STABLE_PREFIX_BY_ID[id];
+  if (stable) return `${stable}${SUFFIX}`;
+  const sep = DYNAMIC_SEPARATOR_BY_ID[id];
+  if (sep) {
+    const idx = match.indexOf(sep);
+    return idx >= 0 ? `${match.slice(0, idx + 1)}${SUFFIX}` : GENERIC;
+  }
+  return GENERIC;
+}
+
+// Apply the most specific prefixes first so `sk-ant-` wins over `sk-`; families
+// without a stable prefix keep their catalog order (stable sort) and run last.
+function orderedPatterns() {
+  return [...CREDENTIAL_PATTERNS].sort(
+    (a, b) => (STABLE_PREFIX_BY_ID[b.id]?.length ?? 0) - (STABLE_PREFIX_BY_ID[a.id]?.length ?? 0)
+  );
+}
+
+/**
+ * Mask every credential in `text`, preserving line structure. Pure and
+ * deterministic: clean text is returned untouched (no-op, no cost).
+ * @param {string} text
+ * @returns {string}
+ */
+export function redactSecrets(text) {
+  if (typeof text !== "string" || text.length === 0) return text;
+  let out = text;
+  for (const { id, pattern } of orderedPatterns()) {
+    const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
+    out = out.replace(new RegExp(pattern.source, flags), (match) =>
+      // Idempotent: a broad pattern (generic-secret, hardcoded-key-assignment)
+      // can span an already-masked value; leave the more specific placeholder
+      // in place instead of clobbering it with the generic one.
+      match.includes("REDACTED") ? match : placeholderFor(id, match)
+    );
+  }
+  return out;
+}

package/src/harden/workflow-engine.js

@@ -10,7 +10,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { upsertManagedBlock } from "../utils/managed-markers.js";
-import { extraWorkflowsFor, qualityWorkflowFor, WORKFLOWS } from "./workflow-templates.js";
+import { extraWorkflowsFor, mutationWorkflowFor, qualityWorkflowFor, WORKFLOWS } from "./workflow-templates.js";
 
 const BLOCK_VERSION = 1;
 const WORKFLOWS_DIR = join(".github", "workflows");
@@ -31,12 +31,14 @@ export function installWorkflows({
   projectDir = process.cwd(),
   language = null,
   profile = "standard",
+  mutation = false,
   dryRun = false,
 } = {}) {
   const dir = join(projectDir, WORKFLOWS_DIR);
   const quality = qualityWorkflowFor(language);
   const extras = extraWorkflowsFor({ profile, publishable: isPublishableNpm(projectDir) });
-  const all = [...WORKFLOWS, ...(quality ? [quality] : []), ...extras];
+  const mut = mutation ? mutationWorkflowFor(language) : null;
+  const all = [...WORKFLOWS, ...(quality ? [quality] : []), ...extras, ...(mut ? [mut] : [])];
   const results = [];
   for (const wf of all) {
     const target = join(dir, wf.file);

package/src/harden/workflow-templates.js

@@ -147,6 +147,58 @@ export const PACK_SMOKE_WORKFLOW = [
   '          echo "Tarball installs clean: $tgz"',
 ].join("\n");
 
+// Opt-in nightly/manual mutation audit (KJC-TSK-0589). NEVER a PR gate: it runs
+// on a weekly schedule + manual dispatch, and the mutate step is non-blocking
+// (continue-on-error) so a red run never nags. Only stacks whose `kj mutate`
+// yields a JSON report (stryker/mutmut/infection) get a workflow — no silent
+// scaffold for tools that can't report yet.
+const MUTATION_TOOLCHAIN = {
+  javascript: ["      - run: npm ci"],
+  python: [
+    "      - uses: actions/setup-python@v5",
+    "        with:",
+    "          python-version: '3.12'",
+    "      - run: pip install mutmut pytest",
+  ],
+  php: [
+    "      - uses: shivammathur/setup-php@v2",
+    "        with:",
+    "          php-version: '8.3'",
+    "      - run: composer install --no-interaction --no-progress",
+  ],
+};
+MUTATION_TOOLCHAIN.typescript = MUTATION_TOOLCHAIN.javascript;
+
+/** Opt-in mutation workflow entry, or null for a stack without a JSON report. */
+export function mutationWorkflowFor(language) {
+  const toolchain = MUTATION_TOOLCHAIN[language];
+  if (!toolchain) return null;
+  const body = [
+    "name: Mutation (nightly)",
+    "on:",
+    "  schedule:",
+    "    - cron: '0 4 * * 1'",
+    "  workflow_dispatch:",
+    "permissions:",
+    "  contents: read",
+    "jobs:",
+    "  mutation:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    "      - uses: actions/checkout@v4",
+    "        with:",
+    "          fetch-depth: 0",
+    "      - uses: actions/setup-node@v4",
+    "        with:",
+    "          node-version: 22",
+    ...toolchain,
+    "      - name: Mutation testing (advisory, never blocks a PR)",
+    "        continue-on-error: true",
+    "        run: npx --yes --package karajan-code kj mutate --since HEAD~1",
+  ].join("\n");
+  return { file: "kj-mutation.yml", blockId: "wf-mutation", body };
+}
+
 /** Conditional workflows: shrink-budget on strict, pack-smoke when publishable. */
 export function extraWorkflowsFor({ profile = "standard", publishable = false } = {}) {
   const extras = [];

package/src/mutate/diff-scope.js

@@ -0,0 +1,101 @@
+/**
+ * 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", run = runCommand }) {
+  const result = await run("git", ["diff", "--unified=0", `${since}..${toRef}`]).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);
+}

package/src/mutate/runner.js

@@ -0,0 +1,72 @@
+/**
+ * Mutation runner + report normalizer. Executes a mutation tool and parses its
+ * report (the shared mutation-testing-report-schema, `files[].mutants[]`) into a
+ * tool-agnostic result the CLI, reviewer and CI can all consume the same way.
+ * `exec` and `readReport` are injectable so the logic is testable without a
+ * real mutation tool installed.
+ */
+
+import { runCommand } from "../utils/process.js";
+
+// A mutant the test suite detected (killed or forced to time out).
+const KILLED = new Set(["Killed", "Timeout"]);
+// A real survivor: the mutation went undetected (or no test covered it).
+const SURVIVED = new Set(["Survived", "NoCoverage"]);
+// Not a real result: equivalent, config-ignored, or uncompilable mutants.
+const EXCLUDED = new Set(["Ignored", "CompileError", "RuntimeError"]);
+
+/**
+ * Normalize a standard-schema report into `{score, killed, survived, total, excluded}`.
+ * `score` is the covered mutation score `killed / (killed + survived) * 100`, or
+ * null when there is nothing to mutate. Excluded mutants never count as survivors.
+ * @param {{files?: Record<string, {mutants?: Array<object>}>}} report
+ */
+export function parseStandardReport(report) {
+  const files = report?.files ?? {};
+  let killed = 0;
+  let excluded = 0;
+  const survived = [];
+  for (const [file, entry] of Object.entries(files)) {
+    for (const mutant of entry?.mutants ?? []) {
+      const { status } = mutant;
+      if (EXCLUDED.has(status)) {
+        excluded += 1;
+      } else if (KILLED.has(status)) {
+        killed += 1;
+      } else if (SURVIVED.has(status)) {
+        survived.push({
+          file,
+          line: mutant.location?.start?.line ?? null,
+          mutator: mutant.mutatorName ?? null,
+          status,
+        });
+      }
+    }
+  }
+  const total = killed + survived.length;
+  const score = total === 0 ? null : Number(((killed / total) * 100).toFixed(2));
+  return { score, killed, survived, total, excluded };
+}
+
+/**
+ * Run a mutation tool and normalize the report it produced.
+ * @param {object} params
+ * @param {string} params.binary
+ * @param {string[]} [params.args]
+ * @param {string} [params.cwd]
+ * @param {Function} [params.exec] - injectable command runner (default runCommand)
+ * @param {() => Promise<object>} [params.readReport] - reads/parses the tool's report file
+ */
+export async function runMutation({ binary, args = [], cwd, exec = runCommand, readReport }) {
+  const run = await exec(binary, args, { cwd }).catch((err) => ({
+    exitCode: 1,
+    stdout: "",
+    stderr: String(err?.message ?? err),
+  }));
+  let result = null;
+  if (readReport) {
+    const report = await readReport().catch(() => null);
+    if (report) result = parseStandardReport(report);
+  }
+  return { exitCode: run.exitCode, result, stdout: run.stdout, stderr: run.stderr };
+}

package/src/mutate/tool-registry.js

@@ -0,0 +1,90 @@
+/**
+ * Mutation-tool registry.
+ *
+ * Maps a detected stack language (see `src/harden/stack-roots.js`) to the
+ * mutation-testing runner Karajan drives for it. Unknown or native-mobile
+ * languages resolve to an explicit `{ supported: false, reason }` object —
+ * never a silent fallback to another tool.
+ *
+ * `scope` describes how the runner limits mutation to a subset of files, so
+ * diff-scoped runs (`kj mutate --since <ref>`) can pass only the changed paths:
+ *   - flag:      the CLI flag that accepts the file list
+ *   - separator: how multiple paths are joined for that flag
+ */
+
+const TOOLS_BY_LANGUAGE = {
+  javascript: {
+    id: "stryker",
+    binary: "stryker",
+    installHint: "npm install --save-dev @stryker-mutator/core",
+    scope: { flag: "--mutate", separator: "," },
+    reportFormat: "json",
+  },
+  typescript: {
+    id: "stryker",
+    binary: "stryker",
+    installHint: "npm install --save-dev @stryker-mutator/core",
+    scope: { flag: "--mutate", separator: "," },
+    reportFormat: "json",
+  },
+  python: {
+    id: "mutmut",
+    binary: "mutmut",
+    installHint: "pip install mutmut",
+    scope: { flag: "--paths-to-mutate", separator: "," },
+    reportFormat: "json",
+  },
+  php: {
+    id: "infection",
+    binary: "infection",
+    installHint: "composer require --dev infection/infection",
+    scope: { flag: "--filter", separator: "," },
+    reportFormat: "json",
+  },
+  go: {
+    id: "go-mutesting",
+    binary: "go-mutesting",
+    installHint: "go install github.com/avito-tech/go-mutesting/cmd/go-mutesting@latest",
+    scope: { flag: "", separator: " " },
+    reportFormat: "json",
+  },
+  java: {
+    id: "pitest",
+    binary: "pitest",
+    installHint: "add org.pitest:pitest-maven (Maven) or gradle-pitest-plugin",
+    scope: { flag: "targetClasses", separator: "," },
+    reportFormat: "json",
+  },
+};
+
+const UNSUPPORTED_REASONS = {
+  swift: "Swift (iOS) has no mutation runner wired into Karajan",
+  kotlin: "Kotlin (Android) has no mutation runner wired into Karajan",
+};
+
+function normalize(language) {
+  if (typeof language !== "string") return "";
+  return language.trim().toLowerCase();
+}
+
+/**
+ * @param {string} language - language id from `detectStackRoots`
+ * @returns {{supported: true, id, binary, language, installHint, scope, reportFormat}
+ *          | {supported: false, language, reason: string}}
+ */
+export function getMutationTool(language) {
+  const key = normalize(language);
+  const tool = TOOLS_BY_LANGUAGE[key];
+  if (tool) {
+    return { supported: true, language: key, ...tool };
+  }
+  const reason =
+    UNSUPPORTED_REASONS[key] ??
+    `no mutation-testing tool is registered for language "${key || "(none)"}"`;
+  return { supported: false, language: key, reason };
+}
+
+/** @returns {string[]} languages with a registered mutation tool */
+export function listSupportedLanguages() {
+  return Object.keys(TOOLS_BY_LANGUAGE);
+}

package/src/orchestrator/drivers/post-loop.js

@@ -347,8 +347,8 @@ export async function tryAutoStartBoard(config, logger, emitter, eventBase) {
   try {
     const { startBoard, renderBoardBanner } = await import("../../commands/board.js");
     const boardPort = config.hu_board.port || 4000;
-    // Scope the board URL to the current run's project (`/p/<slug>`) so
-    // the user lands on a filtered view, not the global dashboard.
+    // Scope the board URL to the current run's project (`#board/<slug>`)
+    // so the user lands on a filtered view, not the global dashboard.
     const slug = config.projectDir ? slugFor(config.projectDir) : null;
     const boardResult = await startBoard(boardPort, { projectSlug: slug });
     const status = boardResult.alreadyRunning ? "already running" : "started";

package/src/orchestrator/stages/reviewer-stage.js

@@ -6,6 +6,7 @@
 import { addCheckpoint, markSessionStatus, saveSession } from "../../session/store.js";
 import { setReviewerFeedback, setDeferredIssues } from "../../session/mutators.js";
 import { generateDiff } from "../../review/diff-generator.js";
+import { redactSecrets } from "../../guards/secret-redactor.js";
 import { validateReviewResult } from "../../review/schema.js";
 import { filterReviewScope } from "../../review/scope-filter.js";
 import { emitProgress, makeEvent, emitAgentOutput } from "../../utils/events.js";
@@ -194,13 +195,18 @@ async function handleReviewerRejection({ review, repeatDetector, config, logger,
 }
 
 export async function fetchReviewDiff(session, logger) {
+  let diff;
   if (session.ci_pr_number) {
     const { getPrDiff } = await import("../../ci/pr-diff.js");
-    const diff = await getPrDiff(session.ci_pr_number);
+    diff = await getPrDiff(session.ci_pr_number);
     logger.info(`Reviewer reading PR diff #${session.ci_pr_number}`);
-    return diff;
+  } else {
+    diff = await generateDiff({ baseRef: session.session_start_sha, stageNewFiles: true });
   }
-  return generateDiff({ baseRef: session.session_start_sha, stageNewFiles: true });
+  // Inbound boundary: mask hardcoded secrets before the diff reaches the
+  // (possibly cloud) reviewer model. Runs BEFORE the injection guard below so
+  // that guard still sees the real prompt-injection phrasing (KJC-TSK-0583).
+  return redactSecrets(diff);
 }
 
 export async function runReviewerStage({ reviewerRole, config, logger, emitter, eventBase, session, trackBudget, iteration, reviewRules, task, repeatDetector, budgetSummary, askQuestion, brainCtx }) {

package/src/prompts/start-decision.js

@@ -0,0 +1,52 @@
+// KJC-TSK-0569 (Onboard B) — prompt + intent schema for the StartDecidor.
+//
+// The decider only DECIDES (one intent from a closed set); the safe HOW is
+// deterministic (0570 maps the intent to a saved command). Keep this prompt
+// tight: it routes, it never executes.
+const PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent (the `kj start` decider).",
+  "Do NOT mention Karajan, do NOT use MCP tools, do NOT execute anything.",
+  "Your only job: read the project assessment and pick ONE next-step intent.",
+].join(" ");
+
+/** Closed set of intents. Anything else degrades to ASK_USER. */
+export const INTENTS = new Set([
+  "ASSESS_ONLY",
+  "RECOMMEND_HARDEN",
+  "RECOMMEND_INDEX",
+  "START_TASK",
+  "PROPOSE_PLAN",
+  "ASK_USER",
+]);
+
+const INTENT_GUIDE = [
+  "- ASSESS_ONLY: the project is healthy and the user gave no goal — just report.",
+  "- RECOMMEND_HARDEN: quality gaps exist (no tests/CI, drifting checks, missing config).",
+  "- RECOMMEND_INDEX: the codebase has no knowledge index yet.",
+  "- START_TASK: the user stated a concrete thing to build or fix.",
+  "- PROPOSE_PLAN: legacy/large project, or a goal that needs a modernization/feature plan.",
+  "- ASK_USER: intent is unclear — ask ONE open question to disambiguate.",
+].join("\n");
+
+/**
+ * @param {{userMessage?: string, assessment?: string, instructions?: string}} input
+ * @returns {string}
+ */
+export function buildStartDecisionPrompt({ userMessage = "", assessment = "", instructions } = {}) {
+  const sections = [PREAMBLE];
+  if (instructions) sections.push(instructions);
+  sections.push(
+    "You route the next step for a project the user just opened with `kj start`.",
+    "## Project assessment (read-only signals)",
+    assessment || "(no assessment available)",
+    "## User goal",
+    userMessage.trim() || "(none given)",
+    "## Intents",
+    INTENT_GUIDE,
+    "Pick the single best intent. Prefer a concrete next step over ASK_USER when the assessment is clear.",
+    "If you pick ASK_USER, put the open question in questionToAsk.",
+    "Return a single valid JSON object and nothing else.",
+    'JSON schema: {"intent":"ASSESS_ONLY|RECOMMEND_HARDEN|RECOMMEND_INDEX|START_TASK|PROPOSE_PLAN|ASK_USER","rationale":string,"questionToAsk":string}',
+  );
+  return sections.join("\n\n");
+}

package/src/roles/reviewer-role.js

@@ -2,6 +2,7 @@ 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 { isMutationReviewEnabled, buildReviewerMutationSignal } from "../mutate/reviewer-signal.js";
 
 const MAX_DIFF_LENGTH = 12000;
 
@@ -38,6 +39,11 @@ export class ReviewerRole extends AgentRole {
   // 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,
+    });
     const layout = buildPromptLayout([
       section(SUBAGENT_PREAMBLE, STABLE),
       section(this.instructions, STABLE),
@@ -51,6 +57,7 @@ export class ReviewerRole extends AgentRole {
       section(reviewRules ? `Review rules:\n${reviewRules}` : null, STABLE),
       section(`Task context:\n${task}`, VOLATILE),
       section(`Git diff:\n${truncateDiff(diff)}`, VOLATILE),
+      section(mutationSignal, VOLATILE),
     ]);
     return { prompt: joinLayout(layout), stablePrompt: layout.stable, volatilePrompt: layout.volatile };
   }