karajan-code 3.7.2 → 3.8.0

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/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 };
   }

package/src/start/assessment.js

@@ -0,0 +1,74 @@
+// KJC-TSK-0569 (Onboard B) — deterministic synthesis of the read-only sweep.
+//
+// Turns the sweep bundle (Onboard A, 0568) into one coherent digest: a
+// human-readable report plus a machine summary the decider (StartDecidorRole)
+// consumes to pick an intent. No LLM here — the costly call is the haiku
+// decider, not a redundant strong-model narration. Reuses the harden advisory
+// formatter so the improvements section reads exactly like `kj harden --report`.
+import { formatAdvisoryReport } from "../harden/advisory.js";
+
+const EMPTY_TALLY = { install: 0, update: 0, review: 0, keep: 0 };
+
+/** Tally harden advisory artifacts by recommendation. */
+function tallyImprovements(improvements) {
+  const tally = { ...EMPTY_TALLY };
+  for (const a of improvements?.artifacts ?? []) {
+    if (a?.recommendation in tally) tally[a.recommendation] += 1;
+  }
+  return tally;
+}
+
+/** Quality/maintenance gaps as short phrases, derived from signals + drift. */
+function collectGaps(signals = {}, drift) {
+  const gaps = [];
+  if (!signals.hasTests) gaps.push("no tests");
+  if (!signals.hasCI) gaps.push("no CI");
+  if (typeof signals.staleDays === "number" && signals.staleDays > 365) {
+    gaps.push(`last commit ${signals.staleDays}d old`);
+  }
+  if (drift && drift.ok === false) {
+    const failed = (drift.checks ?? []).filter((c) => c?.ok === false).length;
+    if (failed > 0) gaps.push(`${failed} harden check(s) drifting`);
+  }
+  return gaps;
+}
+
+/**
+ * @param {object} bundle output of runReadOnlySweep (0568)
+ * @returns {{text: string, summary: object}}
+ */
+export function buildAssessment(bundle) {
+  if (!bundle || typeof bundle !== "object") {
+    throw new TypeError("buildAssessment: bundle must be an object");
+  }
+  const { maturity = {}, signals = {}, drift, improvements, rag, qmd } = bundle;
+  const gaps = collectGaps(signals, drift);
+  const improvementCounts = tallyImprovements(improvements);
+
+  const summary = {
+    maturity: maturity.maturity ?? "unknown",
+    declared: Boolean(maturity.declared),
+    deepHealthRecommended: Boolean(maturity.deepHealthRecommended),
+    gaps,
+    driftOk: drift ? drift.ok !== false : null,
+    improvementCounts,
+    indexed: rag ? Boolean(rag.indexed) : null,
+    qmdAvailable: qmd ? Boolean(qmd.available) : null,
+  };
+
+  const lines = [
+    `Project maturity: ${summary.maturity}${summary.declared ? " (declared)" : " (inferred)"}`,
+    ...(maturity.reasons ?? []).map((r) => `  - ${r}`),
+    "",
+    `Tests: ${signals.hasTests ? "yes" : "no"} · CI: ${signals.hasCI ? "yes" : "no"} · commits: ${signals.commitCount ?? 0}`,
+    `Quality gaps: ${gaps.length ? gaps.join(", ") : "none detected"}`,
+    `Knowledge index: ${summary.indexed === null ? "n/a" : summary.indexed ? "present" : "missing"}` +
+      ` · qmd: ${summary.qmdAvailable === null ? "n/a" : summary.qmdAvailable ? "available" : "absent"}`,
+  ];
+
+  if (improvements) {
+    lines.push("", ...formatAdvisoryReport(improvements));
+  }
+
+  return { text: lines.join("\n"), summary };
+}

package/src/start/maturity.js

@@ -0,0 +1,73 @@
+// KJC-TSK-0568 (Onboard A) — maturity classifier for the Brain (`kj start`).
+//
+// Pure and deterministic: given a bundle of read-only signals it labels the
+// project new | existing | legacy. No LLM, no I/O — the sweep (sweep.js) does
+// the reading; this only decides. The label drives which read-only subset the
+// orchestrator runs and, downstream (0570), whether a deep health pass is worth
+// the cost. A user-declared maturity always wins over inference.
+//
+// Acceptance criteria (KJC-TSK-0568):
+//   - empty repo / scaffolding only       -> new
+//   - code + config + tests/CI            -> existing
+//   - code but missing tests/CI, or very stale -> legacy
+
+/** Last-commit age (days) beyond which a repo counts as stalled/neglected. */
+export const STALE_DAYS_THRESHOLD = 365;
+
+const VALID = new Set(["new", "existing", "legacy"]);
+
+/**
+ * @param {object} signals
+ * @param {("new"|"existing"|"legacy"|null)} [signals.declared] user override
+ * @param {boolean} signals.hasSourceCode  real source files present
+ * @param {boolean} signals.scaffoldingOnly only generator boilerplate, no real code
+ * @param {boolean} signals.hasTests        a test suite is present
+ * @param {boolean} signals.hasCI           CI workflows are present
+ * @param {number}  [signals.commitCount]   number of commits (capped upstream)
+ * @param {number|null} [signals.staleDays] age of the last commit in days
+ * @returns {{maturity: "new"|"existing"|"legacy", reasons: string[], deepHealthRecommended: boolean, declared: boolean}}
+ */
+export function classifyMaturity(signals) {
+  if (!signals || typeof signals !== "object") {
+    throw new TypeError("classifyMaturity: signals must be an object");
+  }
+
+  if (VALID.has(signals.declared)) {
+    const maturity = signals.declared;
+    return {
+      maturity,
+      reasons: [`maturity declared by user as "${maturity}"`],
+      deepHealthRecommended: maturity === "legacy",
+      declared: true,
+    };
+  }
+
+  const reasons = [];
+  let maturity;
+
+  if (!signals.hasSourceCode || signals.scaffoldingOnly) {
+    maturity = "new";
+    reasons.push(signals.scaffoldingOnly ? "only scaffolding present, no real code yet" : "no source code found");
+  } else {
+    const stalled = typeof signals.staleDays === "number" && signals.staleDays > STALE_DAYS_THRESHOLD;
+    const gaps = [];
+    if (!signals.hasTests) gaps.push("no tests");
+    if (!signals.hasCI) gaps.push("no CI");
+    if (stalled) gaps.push(`last commit ${signals.staleDays}d old (stalled)`);
+
+    if (gaps.length > 0) {
+      maturity = "legacy";
+      reasons.push(`code present but neglected: ${gaps.join(", ")}`);
+    } else {
+      maturity = "existing";
+      reasons.push("code with tests and CI, actively maintained");
+    }
+  }
+
+  return {
+    maturity,
+    reasons,
+    deepHealthRecommended: maturity === "legacy",
+    declared: false,
+  };
+}

package/src/start/start-decider-role.js

@@ -0,0 +1,79 @@
+// KJC-TSK-0569 (Onboard B) — the StartDecidor: the only LLM in the Brain's
+// onboarding. Reads the deterministic assessment + user goal, picks ONE intent
+// from a closed set, and never executes (0570 maps the intent to a safe command).
+// Provider falls back to the coder, model defaults to haiku. Unparseable/unknown
+// output degrades to ASK_USER so `kj start` always has a sane next step.
+import { AgentRole } from "../roles/agent-role.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+import { buildStartDecisionPrompt, INTENTS } from "../prompts/start-decision.js";
+
+const FALLBACK_QUESTION = "What would you like to do with this project?";
+
+export class StartDecidorRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "start" });
+  }
+
+  extractInput(input) {
+    const src = typeof input === "string" ? { userMessage: input } : input || {};
+    return {
+      userMessage: src.userMessage || "",
+      assessment: src.assessment || "",
+      onOutput: src.onOutput || null,
+      ...src,
+    };
+  }
+
+  async buildPrompt({ userMessage, assessment }) {
+    return {
+      prompt: buildStartDecisionPrompt({ userMessage, assessment, instructions: this.instructions }),
+    };
+  }
+
+  parseOutput(raw) {
+    return extractFirstJson(raw);
+  }
+
+  buildSuccessResult(parsed, provider) {
+    const intent = INTENTS.has(parsed.intent) ? parsed.intent : "ASK_USER";
+    const rationale = String(parsed.rationale || "").trim();
+    const questionToAsk = String(parsed.questionToAsk || "").trim();
+    const degraded = intent !== parsed.intent;
+    return {
+      intent,
+      rationale: rationale || (degraded ? "Unrecognized intent, asking the user." : "No rationale provided."),
+      questionToAsk: intent === "ASK_USER" ? questionToAsk || FALLBACK_QUESTION : "",
+      provider,
+    };
+  }
+
+  buildSummary(parsed) {
+    const intent = INTENTS.has(parsed.intent) ? parsed.intent : "ASK_USER";
+    return `Start decision: ${intent}`;
+  }
+
+  handleParseNull(agentResult, provider) {
+    return this.degradedDecision({ agentResult, provider, reason: "no JSON found" });
+  }
+
+  handleParseError(err, agentResult, provider) {
+    return this.degradedDecision({ agentResult, provider, reason: err?.message || "parse error" });
+  }
+
+  // Never block onboarding: garbage in → ask the user one open question.
+  degradedDecision({ agentResult, provider, reason }) {
+    this.logger?.warn?.(`[start] decider output unusable (${reason}) — asking the user.`);
+    return {
+      ok: true,
+      result: {
+        intent: "ASK_USER",
+        rationale: `Could not read a decision (${reason}).`,
+        questionToAsk: FALLBACK_QUESTION,
+        provider,
+        degraded: true,
+      },
+      summary: "Start decision: ASK_USER (fallback)",
+      usage: agentResult.usage,
+    };
+  }
+}