@karajan-family/code 5.0.3 → 5.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karajan-family/code",
-  "version": "5.0.3",
+  "version": "5.1.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/audit/deterministic-summary.js

@@ -33,6 +33,7 @@ export function formatDeterministicSummary(ctx) {
   const lines = ["## Deterministic Findings", ""];
   lines.push("These are the rule-based findings (no LLM). They cost zero tokens and are always factually accurate. The interactive prompt below asks if you want to extend this with an LLM analysis (which will cost tokens).");
   lines.push("");
+  lines.push(...formatCoverageBlock(auditCoverage(ctx)));
 
   if (ctx.stack) lines.push(...formatStackBlock(ctx.stack));
   if (ctx.basalCost) lines.push(...formatBasalCostBlock(ctx.basalCost, ctx.growthDelta));
@@ -51,6 +52,31 @@ export function formatDeterministicSummary(ctx) {
   return lines.join("\n");
 }
 
+// KJC-TSK-1381 (#3208): a green audit that skipped half its checks must not read as complete.
+const CHECK_NAMES = {
+  sonarFindings: "Sonar", osvFindings: "osv-scanner", semgrepFindings: "semgrep",
+  injectionFindings: "prompt-injection", infraFindings: "checkov", npmSignatures: "npm signatures",
+  circularDeps: "madge", deadExports: "knip", aiSlop: "ai-slop", envKeys: "env keys", webperf: "webperf",
+};
+
+/** Checks attempted (a section skipped by a flag is null and does not count), and those that did not run. */
+export function auditCoverage(ctx) {
+  const attempted = Object.entries(CHECK_NAMES).filter(([key]) => ctx[key]);
+  const notRun = attempted.filter(([key]) => ctx[key].available === false)
+    .map(([key, name]) => ({ name, reason: ctx[key].reason || "did not run" }));
+  return { ran: attempted.length - notRun.length, total: attempted.length, notRun };
+}
+
+function formatCoverageBlock({ ran, total, notRun }) {
+  const lines = [`**Coverage:** ${ran} of ${total} checks ran.`];
+  for (const n of notRun) lines.push(`- not run, ${n.name}: ${n.reason}`);
+  if (notRun.some((n) => /not installed|not found/i.test(n.reason))) {
+    lines.push("- Install the missing tools with `kj install-tools`: until then this audit covers less than it can.");
+  }
+  lines.push("");
+  return lines;
+}
+
 const MAX_SAMPLE_ENV_KEYS = 8;
 
 // KJC-TSK-0845: the same key resolved with two rules in two modules, and a

package/src/cli/register-pipeline.js

@@ -87,6 +87,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--position <text>", "Why the brain disagrees with the reviewer")
     .option("--position-file <path>", "Read the position from a file (no quoting to get right)")
     .option("--range <range>", "Arbitrate a git range instead of the staged diff")
+    .option("--finding <id>", "Arbitrate only this finding of the verdict; the others keep blocking")
     .action(async (flags) => {
       await withConfig(pkgVersion, "solomon", flags, async ({ config, logger }) => {
         await solomonCommand({ config, logger, flags });

package/src/commands/review-gate.js

@@ -176,8 +176,11 @@ export async function solomonCommand({ config, logger = null, flags = {} }) {
     process.exitCode = 1;
     return { ruling: "reject", reasoning: "security-class policy denial — not arbitrable" };
   }
-  const res = await runSolomonArbitration({ diff, position, config, logger, projectDir });
-  if (res.ruling === "approve") {
+  const res = await runSolomonArbitration({ diff, position, config, logger, projectDir, findingId: flags.finding || null });
+  if (res.ruling === "approve" && res.remaining?.length > 0) {
+    // KJC-TSK-1379: one finding arbitrated; the rest still block the gate.
+    console.log(`⚖ Solomon (${res.solomon}) rules for the brain on ${flags.finding}; still blocking: ${res.remaining.join(", ")}.`);
+  } else if (res.ruling === "approve") {
     console.log(`⚖ Solomon (${res.solomon}) rules for the brain — verdict recorded, the gate is open.`);
   } else {
     const who = res.solomon ? ` (${res.solomon})` : "";

package/src/environment/briefs.js

@@ -74,6 +74,7 @@ const B = {
           ...(config?.method_gates?.mutation
             ? ["Green is not proof: run `kj mutate --since <base>` after the suite passes and BEFORE review — kill surviving mutants (weak asserts) first."]
             : []),
+          "Once green, simplify your change before `kj review --staged`: same behavior, no test weakened, within the line budget. The verdict binds to the exact diff, so a cleanup after it costs a second review.",
         ],
         "green suite + the list of new/changed tests and what each one pins.");
     },

package/src/environment/playbook.js

@@ -64,10 +64,10 @@ Invariants (the git gates enforce these — they are not suggestions):
   \`kj_rag_query\` tool: reach for it before grepping by hand. Questions about
   the project's docs, notes, ADRs or plans: ask qmd (its MCP) first.
 - ${trackingLine(stateBackend, boardName)}
-- Tests prove behavior: the failing test exists first (TDD), and the suite
-  is never left red. Green is not proof: with \`method_gates.mutation\`
-  declared, run \`kj mutate --since <base>\` after green and BEFORE the
-  review — a surviving mutant is a weak assert; kill it first.
+- Tests prove behavior: failing test first (TDD), suite never left red.
+  Green is not proof: with \`method_gates.mutation\` declared, run
+  \`kj mutate --since <base>\` and kill surviving mutants (weak asserts); then
+  simplify (same behavior, no test weakened). Both BEFORE the review.
 - Every diff is reviewed by a DIFFERENT AI before it is committed
   (\`kj review --staged\`): verdicts bind to the exact diff — change the code
   and it must be reviewed again. Disagree with a rejection? \`kj solomon\`.

package/src/prompts/reviewer.js

@@ -35,7 +35,7 @@ const SERENA_INSTRUCTIONS = [
  * on it; the per-review content (task context + git diff, up to 12 KB
  * and always different) goes last.
  */
-export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null, roleSkillBlock = null }) {
+export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null, roleSkillBlock = null, factsBlock = null }) {
   const { body: clippedDiff, note: clipNote } = clipDiff(diff);
   // KJC-BUG-0138: full diff on purpose — the moved-to side survives clipping.
   const splitSignal = buildSplitSignal(diff);
@@ -61,7 +61,9 @@ export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode,
     section("A claim that a tool, platform or API does not support something the diff uses is not a blocking issue on its own: your training data may predate the feature. Block only when the diff or the task context shows it fails; otherwise put it in non_blocking_suggestions.", 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","category":"security|correctness|performance|style|other","file":string,"line":number,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}', STABLE),
+    section('{"approved":boolean,"blocking_issues":[{"id":string,"severity":"critical|high|medium|low","category":"security|correctness|performance|style|other","file":string|null,"line":number|null,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}', STABLE),
+    // KJC-TSK-1379 (#3207): a finding that names no line is hard to apply and hard to arbitrate.
+    section("Every blocking issue names the file and the line of the diff it is about; use null only for a finding about the whole diff.", STABLE),
     section(serenaEnabled ? SERENA_INSTRUCTIONS : null, STABLE),
     section(rtkSnippet, STABLE),
     section(productContext ? `## Product Context\n${productContext}` : null, STABLE),
@@ -69,6 +71,8 @@ export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode,
     section(`Review rules:\n${reviewRules}`, STABLE),
     section(skillSection, STABLE),
     section(`Task context:\n${task}`, VOLATILE),
+    // KJC-TSK-1380 (#3207): facts computed without a model, before the diff they describe.
+    section(factsBlock || null, VOLATILE),
     section(`Git diff:\n${clippedDiff}`, VOLATILE),
     section(clipNote, VOLATILE),
     section(splitSignal, VOLATILE),

package/src/review/diff-facts.js

@@ -0,0 +1,110 @@
+/**
+ * KJC-TSK-1380 (#3207): facts about a diff computed without a model, each with its
+ * file:line where it has one. The reviewer starts from them and keeps the judgement;
+ * they inform, they never block on their own.
+ */
+import { scanText, loadPrivacyList } from "../privacy/scan.js";
+
+const MAX_SIZE_FACTS = 10;
+const TEST_FILE = /(^|\/)(tests?|__tests__|spec)\/|\.(test|spec)\.[cm]?[jt]sx?$/;
+const CODE_FILE = /\.([cm]?[jt]sx?|py|go|rb|java|rs|php|cs|kt|swift)$/;
+const DYNAMIC_IMPORT = /await\s+import\(\s*["'`]([^"'`]+)["'`]\s*\)/;
+const STATIC_IMPORT = /^\s*import\s[^;]*?from\s+["']([^"']+)["']/gm;
+const DEP_LINE = /^\s*"([^"]+)":\s*"([^"]*)"\s*,?\s*$/;
+const DEP_SECTIONS = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
+const NOT_DEPS = new Set(["name", "version", "description", "main", "module", "types", "license", "type", "node", "npm"]);
+
+/** Added lines (with their line in the new file) and removed counts, per file. */
+function parseDiff(diff) {
+  const files = new Map();
+  let current = null;
+  let line = 0;
+  let name;
+  for (const raw of String(diff).split("\n")) {
+    if (raw.startsWith("diff --git ")) {
+      name = / b\/(.+)$/.exec(raw)?.[1] ?? null;
+      current = name ? { added: [], removed: 0 } : null;
+      if (current) files.set(name, current);
+      line = 1;
+    } else if (raw.startsWith("+++ ")) {
+      continue; // file header, not an added line (the file was named by "diff --git")
+    } else if (raw.startsWith("@@")) {
+      line = Number(/\+(\d+)/.exec(raw)?.[1] ?? 1);
+    } else if (current && raw.startsWith("+")) {
+      current.added.push({ line, text: raw.slice(1) });
+      line += 1;
+    } else if (current && raw.startsWith("-") && !raw.startsWith("---")) {
+      current.removed += 1;
+    } else if (current && raw.startsWith(" ")) {
+      line += 1;
+    }
+  }
+  return files;
+}
+
+function declaredDeps(readFile, name) {
+  try {
+    const pkg = JSON.parse(readFile(name));
+    return new Set(DEP_SECTIONS.flatMap((s) => Object.keys(pkg[s] || {})));
+  } catch { return null; } // unreadable: fall back to the shape of the line
+}
+
+function dependencyFacts(name, added, readFile) {
+  if (!/(^|\/)package\.json$/.test(name)) return [];
+  const deps = readFile ? declaredDeps(readFile, name) : null;
+  return added.flatMap(({ line, text }) => {
+    const m = DEP_LINE.exec(text);
+    if (!m) return [];
+    const isDep = deps ? deps.has(m[1]) : !NOT_DEPS.has(m[1]) && /^[\^~<>=*\d]|^(npm|workspace|file|git)/.test(m[2]);
+    return isDep ? [{ kind: "new-dependency", file: name, line, text: `adds dependency ${m[1]}@${m[2]}` }] : [];
+  });
+}
+
+function dynamicImportFacts(name, added, readFile) {
+  if (!readFile) return [];
+  let content;
+  try { content = readFile(name); } catch { return []; }
+  const staticSpecs = new Set([...content.matchAll(STATIC_IMPORT)].map((m) => m[1]));
+  return added.flatMap(({ line, text }) => {
+    const spec = DYNAMIC_IMPORT.exec(text)?.[1];
+    return spec && staticSpecs.has(spec) ? [{ kind: "redundant-dynamic-import", file: name, line, text: `await import("${spec}") of a module this file already imports statically` }] : [];
+  });
+}
+
+function secretFacts(name, added, list) {
+  return added.flatMap(({ line, text }) => scanText(text, { list, source: name })
+    .filter((f) => f.severity === "block" || f.type === "secret-assignment")
+    .map((f) => ({ kind: "secret-shape", file: name, line, text: `${f.type}: ${f.masked}` })));
+}
+
+/**
+ * @param {string} diff unified diff
+ * @param {{ readFile?: (path: string) => string, list?: object }} [opts] readFile reads a file as it is after the diff
+ */
+export function diffFacts(diff, { readFile = null, list } = {}) {
+  const files = parseDiff(diff);
+  const names = [...files.keys()];
+  const privacy = list ?? loadPrivacyList(); // read once, not per added line
+  const facts = [...files]
+    .toSorted(([, a], [, b]) => (b.added.length + b.removed) - (a.added.length + a.removed))
+    .slice(0, MAX_SIZE_FACTS)
+    .map(([name, f]) => ({ kind: "size", file: name, text: `+${f.added.length} / -${f.removed}` }));
+  const code = names.filter((n) => CODE_FILE.test(n) && !TEST_FILE.test(n));
+  if (code.length > 0 && !names.some((n) => TEST_FILE.test(n))) {
+    facts.push({ kind: "no-tests", text: `code changes in ${code.length} file(s) and no test file is touched` });
+  }
+  for (const [name, f] of files) {
+    facts.push(...dependencyFacts(name, f.added, readFile), ...dynamicImportFacts(name, f.added, readFile),
+      ...secretFacts(name, f.added, privacy));
+  }
+  return facts;
+}
+
+/** The facts as a prompt block; empty when there are none. */
+export function formatDiffFacts(facts) {
+  if (!facts?.length) return "";
+  const where = (f) => (f.file ? `${f.file}${f.line ? `:${f.line}` : ""} ` : "");
+  return ["## Verified facts (computed without a model)",
+    "Checked mechanically on this diff. Start from them; judging what they mean is yours.",
+    ...facts.map((f) => `- ${where(f)}${f.text}`)].join("\n");
+}

package/src/review/one-shot-review.js

@@ -17,6 +17,9 @@ import { detectAvailableAgents, detectHostAgent } from "../utils/agent-detect.js
 import { accountLabel } from "../utils/agent-home.js";
 import { saveVerdict, diffHash } from "./verdict-store.js";
 import { summarizeGeneratedFiles } from "./prompt-diff.js";
+import { diffFacts, formatDiffFacts } from "./diff-facts.js";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { reportUnparseableVerdict } from "./unparseable-verdict.js";
 import { detectWorkspace } from "./workspace.js";
 import { branchOf } from "./correction-rounds.js";
@@ -107,11 +110,14 @@ export async function runOneShotReview({
   }
 
   const { rules } = await resolveReviewProfile({ mode: "standard", projectDir });
+  // KJC-TSK-1380 (#3207): facts computed without a model; the reviewer starts from them.
+  const facts = diffFacts(diff, { readFile: (p) => readFileSync(join(projectDir || process.cwd(), p), "utf8") });
   const attempt = async (who, cfg = config) => {
     const prompt = await buildReviewerPrompt({
       task: task || "Review the following diff for correctness, security and maintainability.",
       // KJC-BUG-0347: generated files summarized; the verdict still binds to the full diff.
       diff: summarizeGeneratedFiles(diff), reviewRules: rules, mode: "standard", provider: who, projectDir, roleSkillBlock: skills,
+      factsBlock: formatDiffFacts(facts),
     });
     // KJC-TSK-1344: with two subscriptions per CLI, say which account reviews.
     const account = accountLabel(who, { env });
@@ -139,6 +145,7 @@ export async function runOneShotReview({
   }
 
   const record = await verdictRecord(parsed, { reviewer: activeReviewer, hostAgent, projectDir, sonar, rag, ui });
+  if (facts.length > 0) record.facts = facts;
   return persist ? saveVerdict(projectDir, diff, record) : record;
 }
 

package/src/review/solomon-arbitration.js

@@ -43,7 +43,7 @@ export async function pickThirdParty({ config, hostAgent, reviewerAgent, detectA
 }
 
 export async function runSolomonArbitration({
-  diff, position, config, logger, projectDir,
+  diff, position, config, logger, projectDir, findingId = null,
   hostAgent = detectHostAgent(),
   createAgentFn = createAgent,
   detectAgents = detectAvailableAgents,
@@ -56,8 +56,15 @@ export async function runSolomonArbitration({
     throw new Error("nothing to arbitrate — there is no rejected verdict for the current diff (run `kj review --staged` first)");
   }
 
+  // KJC-TSK-1379 (#3207): with findingId only that finding is disputed; the rest keep blocking.
+  const allIssues = verdict.issues || [];
+  const disputed = findingId ? allIssues.filter((issue) => issue.id === findingId) : allIssues;
+  if (findingId && disputed.length === 0) {
+    throw new Error(`no finding "${findingId}" in the rejected verdict; its findings are: ${allIssues.map((i) => i.id).join(", ") || "none"}`);
+  }
+
   // ABSOLUTE RULE: security findings are never overridable.
-  const securityIssues = (verdict.issues || []).filter((issue) => securityReason(issue));
+  const securityIssues = disputed.filter((issue) => securityReason(issue));
   if (securityIssues.length > 0) {
     const named = securityIssues.map(describeSecurityIssue).join("; ");
     const record = await saveVerdict(projectDir, diff, {
@@ -79,8 +86,9 @@ export async function runSolomonArbitration({
     "The reviewer REJECTED a diff; the orchestrating brain DISAGREES. Decide who is right.",
     "Never approve to save time or effort — only if the reviewer's objections are genuinely wrong or immaterial for this diff.",
     'Return only one JSON object: {"ruling":"approve"|"reject","reasoning":string}. "approve" = the brain is right, the diff may ship as-is. "reject" = the reviewer is right, the brain must fix the issues.',
+    ...(findingId ? ["Rule on this one finding only: the reviewer's other findings are not in dispute."] : []),
     "", "## Reviewer's blocking issues",
-    JSON.stringify(verdict.issues || [], null, 2),
+    JSON.stringify(disputed, null, 2),
     "", "## Brain's position", position,
     // KJC-BUG-0347: generated files summarized; the ruling still binds to the full diff.
     "", "## The diff under dispute", summarizeGeneratedFiles(diff),
@@ -115,12 +123,17 @@ export async function runSolomonArbitration({
   // for this exact hash and travels with the overriding verdict — without it
   // `kj review --check` refuses every arbitrated diff.
   const evidence = { ...(verdict.sonar ? { sonar: verdict.sonar } : {}), ...(verdict.rag ? { rag: verdict.rag } : {}) };
-  const record = parsed.ruling === "approve"
-    ? await saveVerdict(projectDir, diff, {
+  if (findingId) arbitration.findingId = findingId;
+  const remaining = parsed.ruling === "approve" ? allIssues.filter((issue) => !disputed.includes(issue)) : allIssues;
+  let record;
+  if (parsed.ruling !== "approve") record = await saveVerdict(projectDir, diff, { ...verdict, arbitration });
+  else if (remaining.length > 0) record = await saveVerdict(projectDir, diff, { ...verdict, issues: remaining, arbitration });
+  else {
+    record = await saveVerdict(projectDir, diff, {
       verdict: "approved", reviewer: `solomon:${solomon}`, host: hostAgent || null,
       issues: [], summary: `Arbitration overrode ${verdict.reviewer}'s rejection: ${parsed.reasoning || ""}`.trim(), arbitration, ...evidence,
-    })
-    : await saveVerdict(projectDir, diff, { ...verdict, arbitration });
+    });
+  }
 
-  return { ruling: parsed.ruling, reasoning: parsed.reasoning || "", solomon, record };
+  return { ruling: parsed.ruling, reasoning: parsed.reasoning || "", solomon, record, remaining: remaining.map((issue) => issue.id) };
 }