karajan-code 4.1.10 → 4.2.0

package/package.json

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

package/src/cli/register-meta.js

@@ -403,10 +403,14 @@ export function registerMeta(program, { pkgVersion }) {
     .description("Resume a paused session")
     .argument("<sessionId>")
     .option("--answer <text>", "Answer to the question that caused the pause")
+    .option("--non-interactive", "Agents/CI: auto-answer prompts with their safe defaults; stop when there is none. Also enabled by KJ_NON_INTERACTIVE=1.")
     .option("--json", "Output JSON only")
     .action(async (sessionId, flags) => {
       await withConfig(pkgVersion, "resume", flags, async ({ config, logger }) => {
-        await resumeCommand({ sessionId, answer: flags.answer, config, logger, flags });
+        const res = await resumeCommand({ sessionId, answer: flags.answer, config, logger, flags });
+        // KJC-TSK-0674 (issue #1289): same contract as kj run — an aborted
+        // resume must be observable by CI.
+        if (res?.aborted) process.exitCode = 1;
       });
     });
 

package/src/cli/register-pipeline.js

@@ -54,6 +54,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md). Alternative to the positional task argument.")
     .option("-y, --yes", "Skip the cwd confirmation prompt (CI / scripted runs).")
+    .option("--non-interactive", "Agents/CI: auto-answer prompts with their safe defaults (warn → continue) and stop with exit code 1 when there is none (fail). Also enabled by KJ_NON_INTERACTIVE=1.")
     .option("--planner <name>")
     .option("--coder <name>")
     .option("--reviewer <name>")
@@ -145,7 +146,10 @@ export function registerPipeline(program, { pkgVersion }) {
         }
         const { resolveTaskInput } = await import("../utils/task-file.js");
         const resolvedTask = await resolveTaskInput({ task: effectiveTask, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
-        await runCommandHandler({ task: resolvedTask, config, logger, flags });
+        const res = await runCommandHandler({ task: resolvedTask, config, logger, flags });
+        // KJC-TSK-0674 (issue #1289): an aborted run (spec-review cancel,
+        // unanswerable non-interactive gate) must be observable by CI.
+        if (res?.aborted) process.exitCode = 1;
       });
     });
 
@@ -207,6 +211,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--check", "Verify the recorded verdict matches the staged diff (exit 0/1, hook-friendly)")
     .option("--range <range>", "Review a git range (e.g. main..HEAD) instead of the staged diff")
     .option("--install-gate", "Enable the pre-commit review gate for this project (creates .karajan/review-gate)")
+    .option("--no-sonar", "Skip the deterministic Sonar pre-gate that runs before the cross-AI verdict")
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "review", flags, async ({ config, logger }) => {
         // ENV-B1 (KJC-TSK-0637): the gate mode records a verdict tied to

package/src/commands/hu.js

@@ -20,6 +20,29 @@ export function creatorLabel() {
 export const HU_STATUSES = ["pending", "running", "done", "failed", "skipped"];
 const BACKLOG_NAME = "brain-backlog";
 
+// KJC-TSK-0675 (issue #1288): agents that skip `kj hu list` created twins of
+// existing work — sometimes in a DIFFERENT plan. Titles are compared
+// normalized (case/punctuation-insensitive) across every live HU of every
+// plan: identical → refuse; mostly-overlapping tokens → warn with candidates.
+const normTitle = (t) => String(t || "").toLowerCase().replaceAll(/[^\p{L}\p{N}]+/gu, " ").trim();
+const titleTokens = (t) => new Set(normTitle(t).split(" ").filter((w) => w.length > 2));
+
+export function findTitleMatches(title, allHus) {
+  const norm = normTitle(title);
+  const toks = titleTokens(title);
+  const identical = [];
+  const similar = [];
+  for (const h of allHus) {
+    if (h.status === "skipped") continue; // discarded cards don't reserve titles
+    if (normTitle(h.title) === norm) { identical.push(h); continue; }
+    const other = titleTokens(h.title);
+    const shared = [...toks].filter((w) => other.has(w)).length;
+    const smaller = Math.min(toks.size, other.size);
+    if (smaller > 0 && shared / smaller >= 0.8) similar.push(h);
+  }
+  return { identical, similar };
+}
+
 async function backlogPlan(projectDir) {
   const plans = await listPlans(projectDir);
   const existing = plans.find((p) => p.alias === BACKLOG_NAME || p.name === BACKLOG_NAME);
@@ -65,6 +88,26 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
   if (action === "add") {
     const title = args[0];
     if (!title || !title.trim()) throw new Error("kj hu add requires a title: kj hu add \"<story>\"");
+    // Cross-plan title dedup (KJC-TSK-0675) — check BEFORE creating anything.
+    const allHus = [];
+    for (const meta of await listPlans(projectDir)) {
+      const p = await loadPlan(projectDir, meta.planId);
+      for (const h of p.hus || []) allHus.push({ ...h, plan: p.alias || p.name || p.planId });
+    }
+    const { identical, similar } = findTitleMatches(title, allHus);
+    if (identical.length > 0) {
+      const ref = identical[0];
+      throw new Error(
+        `An HU with this title already exists: ${ref.short_id || ref.id} (status: ${ref.status}, plan: ${ref.plan}). `
+        + `HUs are never duplicated — work that card, move it with: kj hu move ${ref.short_id || ref.id} <status>, `
+        + `or run kj hu list before adding.`
+      );
+    }
+    if (similar.length > 0) {
+      const plural = similar.length === 1 ? "" : "s";
+      const candidates = similar.map((h) => `  · ${h.short_id || h.id} (${h.status}, plan: ${h.plan}) "${h.title}"`).join("\n");
+      console.warn(`⚠ possible duplicate${plural} — check before working it:\n${candidates}`);
+    }
     const plan = await backlogPlan(projectDir);
     // KJC-TSK-0669 (absolute rule): cards are permanent. The delete-and-
     // recreate "fix" an agent improvises loses history and duplicates ids —

package/src/commands/review-gate.js

@@ -10,10 +10,11 @@ import { checkVerdict } from "../review/verdict-store.js";
 import { runOneShotReview } from "../review/one-shot-review.js";
 import { runSolomonArbitration } from "../review/solomon-arbitration.js";
 import { ensureGateTrackable } from "../review/gate-gitignore.js";
+import { runSonarPregate, formatSonarFinding } from "../review/sonar-pregate.js";
 
 // Raw git always — never a wrapped/compressing runner (KJC-BUG-0115).
-async function rawDiff(range) {
-  const args = range ? ["diff", range] : ["diff", "--cached"];
+async function rawDiff(range, extraArgs = []) {
+  const args = range ? ["diff", range, ...extraArgs] : ["diff", "--cached", ...extraArgs];
   const res = await runCommand("git", args);
   if (res.exitCode !== 0) {
     throw new Error(res.stderr?.trim() || `git ${args.join(" ")} failed`);
@@ -29,7 +30,11 @@ function printVerdict(record) {
   }
   console.log(`✗ REJECTED by ${record.reviewer} — ${record.issues.length} blocking issue(s):`);
   for (const issue of record.issues) {
-    const where = issue.file ? ` [${issue.file}${issue.line ? `:${issue.line}` : ""}]` : "";
+    let where = "";
+    if (issue.file) {
+      const line = issue.line ? `:${issue.line}` : "";
+      where = ` [${issue.file}${line}]`;
+    }
     console.log(`  - (${issue.severity || "high"})${where} ${issue.description || issue.id}`);
     if (issue.suggested_fix) console.log(`    fix: ${issue.suggested_fix}`);
   }
@@ -48,7 +53,8 @@ export async function solomonCommand({ config, logger = null, flags = {} }) {
   if (res.ruling === "approve") {
     console.log(`⚖ Solomon (${res.solomon}) rules for the brain — verdict recorded, the gate is open.`);
   } else {
-    console.log(`⚖ Solomon${res.solomon ? ` (${res.solomon})` : ""} rules for the reviewer — obey and fix:`);
+    const who = res.solomon ? ` (${res.solomon})` : "";
+    console.log(`⚖ Solomon${who} rules for the reviewer — obey and fix:`);
   }
   if (res.reasoning) console.log(`  ${res.reasoning}`);
   process.exitCode = res.ruling === "approve" ? 0 : 1;
@@ -89,7 +95,39 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     return res;
   }
 
-  const record = await runOneShotReview({ diff, task: flags.task, config, logger, projectDir });
+  // KJC-TSK-0676: deterministic pre-gate — sonar findings on the changed
+  // files come back BEFORE any AI opinion. Blocking severities reject
+  // without spending reviewer tokens; the rest travel with the task so
+  // the cross-AI reviewer weighs them. Unavailable sonar degrades loudly.
+  let task = flags.task;
+  if (flags.sonar !== false) {
+    const files = (await rawDiff(flags.range, ["--name-only"])).split("\n").map((f) => f.trim()).filter(Boolean);
+    const pre = await runSonarPregate({ config, stagedFiles: files, logger });
+    if (!pre.available) {
+      console.log(`⚠ sonar pre-gate skipped: ${pre.reason}`);
+    } else {
+      const found = [...pre.blocking, ...pre.advisory];
+      if (found.length > 0) {
+        console.log(`Sonar on the changed files — ${pre.blocking.length} blocking, ${pre.advisory.length} advisory (project total: ${pre.totalProject}):`);
+        for (const f of found) console.log(`  - ${formatSonarFinding(f)}`);
+      }
+      if (pre.blocking.length > 0) {
+        console.log("✗ REJECTED by sonar (deterministic) — fix the blocking findings; the cross-AI reviewer was not invoked.");
+        process.exitCode = 1;
+        return {
+          verdict: "rejected", reviewer: "sonar",
+          issues: pre.blocking.map((i) => ({ severity: i.severity, file: undefined, description: formatSonarFinding(i) })),
+        };
+      }
+      if (pre.advisory.length > 0) {
+        task = `${task || "Review the following diff for correctness, security and maintainability."}\n\n`
+          + `Deterministic Sonar findings on these files (fold them into your review):\n`
+          + pre.advisory.map((f) => `- ${formatSonarFinding(f)}`).join("\n");
+      }
+    }
+  }
+
+  const record = await runOneShotReview({ diff, task, config, logger, projectDir });
   printVerdict(record);
   process.exitCode = record.verdict === "approved" ? 0 : 1;
   return record;

package/src/environment/briefs.js

@@ -87,9 +87,10 @@ const B = {
     render: () => brief("Board",
       "the HU Board is the permanent record of work: every card traces to who created it and what happened to it — a dashboard warning is fixed with the command it names, never by rebuilding the board.",
       [
+        "Before `kj hu add`, ALWAYS run `kj hu list`: if a card already covers the work (same scope, any plan), work THAT card instead of creating a twin.",
         "Cards are NEVER deleted or recreated — not to fix warnings, not to tidy up. Discard = `kj hu move <id> skipped` (archived, history kept).",
         "States move only via `kj hu move <id> <pending|running|done|failed|skipped>`.",
-        "A duplicate short_id means the card already exists: update that card, never add a twin.",
+        "A duplicate short_id or title means the card already exists: update that card, never add a twin.",
         "A warning is information, not damage: run the command it names; if it looks like a kj bug, `kj report-issue` — never work around it by destroying state.",
       ],
       "the board reflects reality: the same cards before and after your action, with truthful states and provenance intact."),

package/src/environment/playbook.js

@@ -29,7 +29,7 @@ const TARGET_FILES = {
 // ENV-D1 (KJC-TSK-0642): the tracking invariant names the CHOSEN state
 // backend — a playbook that says "board or PG" makes the host guess.
 const BACKEND_TRACKING = {
-  "hu-board": "Every piece of work has a tracked story/bug in the HU Board (`kj hu add` / `kj board`) before it starts. Cards are permanent — never delete or recreate one; discard with `kj hu move <id> skipped`. `kj brief board` explains the board.",
+  "hu-board": "Every piece of work has a tracked story/bug in the HU Board (`kj hu add` / `kj board`) before it starts — and `kj hu list` BEFORE `kj hu add`: reuse the existing card if one covers the work. Cards are permanent — never delete or recreate one; discard with `kj hu move <id> skipped`. `kj brief board` explains the board.",
   "planning-game": "Every piece of work has a tracked card in the Planning Game MCP before it starts (In Progress while you work it).",
 };
 

package/src/review/sonar-pregate.js

@@ -0,0 +1,63 @@
+/**
+ * Sonar pre-gate for `kj review --staged` (KJC-TSK-0676, user request
+ * 2026-07-23). With the brain outside the core (v4), skipping sonar is one
+ * decision away — proven the day the brain itself shipped 3 sonar issues in
+ * new code. Hung off the review gate, it becomes a gate, not discipline:
+ * deterministic findings on the STAGED files come back before any AI
+ * verdict, and BLOCKER/CRITICAL ones reject without spending reviewer
+ * tokens. Unavailable sonar degrades loudly ({available:false, reason}) —
+ * a laptop without Docker still commits.
+ */
+
+import { runSonarScan } from "../sonar/scanner.js";
+import { getOpenIssues } from "../sonar/api.js";
+import { acquireToolLock } from "../utils/tool-governor.js";
+
+const BLOCKING_SEVERITIES = new Set(["BLOCKER", "CRITICAL"]);
+
+/** Repo-relative path of a sonar issue (component is "<projectKey>:<path>"). */
+export function issueFile(issue) {
+  const component = String(issue?.component || "");
+  const idx = component.indexOf(":");
+  return idx === -1 ? component : component.slice(idx + 1);
+}
+
+/** One printable line per finding: (SEVERITY) [file:line] rule — message. */
+export function formatSonarFinding(issue) {
+  const line = issue.line ? `:${issue.line}` : "";
+  return `(${issue.severity}) [${issueFile(issue)}${line}] ${issue.rule} — ${issue.message}`;
+}
+
+/**
+ * Scan the project (single-flight via the tool governor) and return the
+ * open issues that live on the staged files, split by blocking severity.
+ * Every failure path degrades to {available:false, reason} — the pre-gate
+ * never breaks the review, it only refuses to stay silent.
+ */
+export async function runSonarPregate({ config, stagedFiles = [], logger = null }) {
+  if (config?.review_gate?.sonar === false) {
+    return { available: false, reason: "disabled in config (review_gate.sonar: false)" };
+  }
+  let lock = null;
+  try {
+    lock = await acquireToolLock("sonar-scanner", { timeoutMs: 300_000 });
+    const scan = await runSonarScan(config);
+    if (!scan.ok) {
+      return { available: false, reason: (scan.stderr || scan.stdout || "sonar scan failed").trim() };
+    }
+    const res = await getOpenIssues(config, scan.projectKey);
+    const staged = new Set(stagedFiles);
+    const onStaged = (res.issues || []).filter((i) => staged.has(issueFile(i)));
+    return {
+      available: true,
+      blocking: onStaged.filter((i) => BLOCKING_SEVERITIES.has(String(i.severity).toUpperCase())),
+      advisory: onStaged.filter((i) => !BLOCKING_SEVERITIES.has(String(i.severity).toUpperCase())),
+      totalProject: res.total ?? (res.issues || []).length,
+    };
+  } catch (err) {
+    logger?.warn?.(`[sonar-pregate] ${err.message}`);
+    return { available: false, reason: err.message };
+  } finally {
+    lock?.release?.();
+  }
+}

package/src/spec-review/run-spec-review.js

@@ -78,17 +78,24 @@ export async function runSpecReview({ spec, config, logger, askQuestion, flags =
       action = await decideGateAutonomously(resolve, { severity, findings });
     } else {
       if (!askQuestion) return { proceed: true, severity, findings, finalSpec: currentSpec };
+      // KJC-TSK-0674 (issue #1289): at severity FAIL the default flips to
+      // cancel — continuing past fails requires an explicit answer, both
+      // interactively (Enter cancels) and unattended (no declared default,
+      // so --yes / KJ_NON_INTERACTIVE stops with exit ≠ 0). warn/info keep
+      // the KJC-BUG-0109 contract: --yes presses Enter → continue.
+      const fallback = severity === "fail" ? "cancel" : "continue";
       const answer = await askQuestion(
-        `Spec review: ${findings.length} finding${findings.length === 1 ? "" : "s"} at severity ${severity}. [c]ontinue / [r]efine / [x]cancel? (default: continue)`,
+        `Spec review: ${findings.length} finding${findings.length === 1 ? "" : "s"} at severity ${severity}. [c]ontinue / [r]efine / [x]cancel? (default: ${fallback})`,
         {
           detail: { severity, findingCount: findings.length, categories: [...new Set(findings.map((f) => f.category))], iteration: iter + 1, findings: findingsForPrompt(findings) },
-          // KJC-BUG-0109: mirrors the interactive default — --yes presses Enter.
-          defaultAnswer: "continue",
+          defaultAnswer: severity === "fail" ? undefined : "continue",
         },
       );
       if (answer === null) return { proceed: false, cancelled: true, severity, findings };
-      const n = String(answer).trim().toLowerCase();
-      action = n.startsWith("x") || n === "cancel" ? "cancel" : n.startsWith("r") || n === "refine" ? "refine" : "continue";
+      const n = String(answer).trim().toLowerCase() || fallback;
+      if (n.startsWith("x") || n === "cancel") action = "cancel";
+      else if (n.startsWith("r") || n === "refine") action = "refine";
+      else action = "continue";
     }
     if (action === "cancel") return { proceed: false, cancelled: true, severity, findings };
     if (action === "refine") {

package/src/utils/cli-ask-question.js

@@ -28,22 +28,28 @@ export function createCliAskQuestion(opts = {}) {
   return async (question, context) => {
     const stdinReadable = process.stdin && process.stdin.readable !== false;
     const isInteractive = Boolean(process.stdin?.isTTY) && stdinReadable;
-    if (!isInteractive) {
-      if (flags?.yes) {
+    // KJC-TSK-0674 (issue #1289): agents and CI enable the same contract
+    // as --yes explicitly, via --non-interactive or KJ_NON_INTERACTIVE=1,
+    // instead of blocking forever on a board modal nobody is watching.
+    // Explicit mode wins even when a (pseudo-)TTY is attached.
+    const forcedNonInteractive = flags?.nonInteractive || process.env.KJ_NON_INTERACTIVE === "1";
+    if (!isInteractive || forcedNonInteractive) {
+      const nonInteractive = forcedNonInteractive || flags?.yes;
+      if (nonInteractive) {
         // KJC-BUG-0109: a question that declares a safe default is answered
         // with it — --yes means "press Enter for me", not "abort on any
         // gate". Questions without a declared default keep failing loud.
         const fallback = typeof context?.defaultAnswer === "string" && context.defaultAnswer.trim()
           ? context.defaultAnswer.trim() : null;
         if (fallback) {
-          process.stderr.write(`\n[non-interactive --yes] Auto-answering with declared default "${fallback}": ${question}\n`);
+          process.stderr.write(`\n[non-interactive] Auto-answering with declared default "${fallback}": ${question}\n`);
           return fallback;
         }
         process.stderr.write(
-          `\n[non-interactive --yes] Pipeline asked a question that cannot be auto-answered:\n`
+          `\n[non-interactive] Pipeline asked a question that cannot be auto-answered:\n`
           + `  ❓ ${question}\n`
           + (context?.detail ? `  Context: ${JSON.stringify(context.detail)}\n` : "")
-          + `  Stopping the session. Re-run without --yes (TTY or HU Board) to answer it,\n`
+          + `  Stopping the session. Re-run interactively (TTY or HU Board) to answer it,\n`
           + `  or pass --skip-spec-review / a more complete spec so the question never appears.\n`
         );
         return null;
@@ -56,7 +62,9 @@ export function createCliAskQuestion(opts = {}) {
       console.log(
         "\n[non-interactive] Routing the prompt to the HU Board.\n"
         + "  Open http://localhost:4000 — a modal will appear asking for your answer.\n"
-        + "  This process is now waiting; closing the board does NOT cancel the run."
+        + "  This process is now waiting; closing the board does NOT cancel the run.\n"
+        + "  Running from an agent or CI with nobody watching the board? Re-run with\n"
+        + "  --non-interactive (or KJ_NON_INTERACTIVE=1) to auto-answer safe defaults instead."
       );
       try {
         return await askThroughBoard({ sessionId, question, context });