@karajan-family/code 4.66.0 → 4.67.0

package/package.json

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

package/src/commands/harden.js

@@ -44,7 +44,7 @@ const JS_TEST_CMD = {
  */
 export async function resolveCmds(projectDir, language) {
   const lang = language ?? detectStackRoots(projectDir)[0]?.language ?? null;
-  const cmds = { ...commandsForLanguage(lang) };
+  const cmds = commandsForLanguage(lang, projectDir);
   if (lang !== "javascript" && lang !== "typescript") return cmds;
 
   const pkgPath = join(projectDir, "package.json");

package/src/git/automation.js

@@ -4,6 +4,7 @@
  */
 
 import { addCheckpoint } from "../session/store.js";
+import { setGitPreexisting } from "../session/mutators.js";
 import { pipelineSonarBlock, stampStagedVerdict } from "../review/verdict-store.js";
 import { branchSize } from "../commands/pr-size.js";
 import { pushRemedy } from "./hu-automation.js";
@@ -80,7 +81,11 @@ function prefixForTaskType(taskType) {
 }
 
 export function commitMessageFromTask(task, taskType = null) {
-  const clean = String(task || "")
+  // KJC-BUG-0413 (#2565): the header comes from the first paragraph, without
+  // its leading Markdown marks; the whole task made "feat: # Roadmap ... Context: ...".
+  const firstParagraph = String(task || "").trim().split(/\n[ \t]*\r?\n/)[0];
+  const clean = firstParagraph
+    .replace(/^[#>*\-\s]+/, "")
     .replaceAll(/\s+/g, " ")
     .trim();
   const prefix = prefixForTaskType(taskType);
@@ -119,9 +124,22 @@ async function checkoutRunBranch(created) {
   }
 }
 
-export async function prepareGitAutomation({ config, task, logger, session }) {
+export async function prepareGitAutomation({ config, task, logger, session, preexisting: resumedBaseline = null }) {
   const enabled = config.git.auto_commit || config.git.auto_push || config.git.auto_pr;
-  if (!enabled) return { enabled: false };
+  if (!enabled) {
+    // KJC-TSK-1237: the format stage needs the baseline also when kj does not
+    // commit; outside git there is none, and that stage says so.
+    let baseline = resumedBaseline;
+    if (!baseline) {
+      try {
+        baseline = await listPendingPaths();
+      } catch {
+        baseline = null;
+      }
+    }
+    if (session && Array.isArray(baseline)) setGitPreexisting(session, baseline);
+    return { enabled: false };
+  }
 
   if (!(await ensureGitRepo())) {
     throw new Error("Git automation requested but current directory is not a git repository");
@@ -147,7 +165,10 @@ export async function prepareGitAutomation({ config, task, logger, session }) {
   // pipeline commits only what it changes. Both names of a pending rename are
   // kept. Fails closed: with no answer from git the run stops here rather than
   // commit the person's pending changes later.
-  const preexisting = await listPendingPaths();
+  // KJC-BUG-0412 (#2564): a resumed run keeps the baseline of the session it
+  // resumes; the tree now also holds that session's own work.
+  const preexisting = resumedBaseline ?? await listPendingPaths();
+  if (session) setGitPreexisting(session, preexisting);
   const repoHasCommits = await hasCommits();
 
   // New repo without commits: create branch directly (no fetch/sync possible)

package/src/harden/harness-hooks.js

@@ -50,15 +50,16 @@ export function guardCommand(guard, { blocking = false, viaKj = isSea() || !kjHo
   return `if command -v ${bin} >/dev/null 2>&1; then ${run}; else ${missing}${blocking ? "; exit 2" : ""}; fi`;
 }
 
-/** The wiring kj harden wrote before ADR 0030: node running the project's copy. */
-const withoutLegacy = (list, script) => {
-  const legacy = `node ${join(".karajan", "harness", script)}`;
-  return list.flatMap((e) => {
-    if (!Array.isArray(e?.hooks) || !e.hooks.some((h) => h?.command === legacy)) return [e];
-    const hooks = e.hooks.filter((h) => h?.command !== legacy);
-    return hooks.length ? [{ ...e, hooks }] : [];
-  });
-};
+/**
+ * Drop the commands that ran this guard some other way: node on the project's copy
+ * (before ADR 0030) or the other runner (KJC-BUG-0403: switching runner must not
+ * leave the guard wired twice).
+ */
+const withoutStale = (list, stale) => list.flatMap((e) => {
+  if (!Array.isArray(e?.hooks) || !e.hooks.some((h) => stale.includes(h?.command))) return [e];
+  const hooks = e.hooks.filter((h) => !stale.includes(h?.command));
+  return hooks.length ? [{ ...e, hooks }] : [];
+});
 
 /**
  * KJC-TSK-1206 (ADR 0030): the wiring is what decides which guard runs, so it is
@@ -98,7 +99,7 @@ export function wiringState({ projectDir, entries }) {
  * basename; an entry is present when that script already appears under the
  * same event (and matcher, when given).
  */
-export function mergeClaudeHooks({ projectDir, logger = console, entries }) {
+export function mergeClaudeHooks({ projectDir, logger = console, entries, viaKj = isSea() || !kjHookOnPath() }) {
   const settingsPath = join(projectDir, ".claude", "settings.json");
   let settings = {};
   if (existsSync(settingsPath)) {
@@ -116,10 +117,12 @@ export function mergeClaudeHooks({ projectDir, logger = console, entries }) {
       return { wired: false };
     }
   }
-  const viaKj = isSea() || !kjHookOnPath();
   for (const { event, matcher, script } of entries) {
-    const list = withoutLegacy(Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [], script);
-    const command = guardCommand(script.replace(/\.mjs$/, ""), { blocking: event === "PreToolUse", viaKj });
+    const guard = script.replace(/\.mjs$/, "");
+    const blocking = event === "PreToolUse";
+    const stale = [`node ${join(".karajan", "harness", script)}`, guardCommand(guard, { blocking, viaKj: !viaKj })];
+    const list = withoutStale(Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [], stale);
+    const command = guardCommand(guard, { blocking, viaKj });
     const present = list.some(
       (e) => (e?.hooks || []).some((h) => h?.command === command) && (matcher === undefined || e?.matcher === matcher),
     );

package/src/harden/hook-commands.js

@@ -8,6 +8,12 @@
  * commands depend on what the project defines). Unknown language ⇒ no commands,
  * leaving only the universal POSIX-shell checks.
  */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+// KJC-BUG-0411 (#2563): uv and poetry keep pytest and ruff in the project's
+// venv, where a bare command exits 127; their manager runs them.
+const PYTHON_RUNNERS = [["uv.lock", "uv run"], ["poetry.lock", "poetry run"]];
 
 export const COMMANDS_BY_LANGUAGE = {
   python: { lint: "ruff check .", format: "ruff format --check .", test: "pytest" },
@@ -19,7 +25,28 @@ export const COMMANDS_BY_LANGUAGE = {
   },
 };
 
-/** Native commands for a language, or {} when JS/TS or unknown. */
-export function commandsForLanguage(language) {
-  return COMMANDS_BY_LANGUAGE[language] ?? {};
+// KJC-TSK-1237 (#2565): the formatter in write mode, run on the files of a session.
+const FORMAT_WRITE_BY_LANGUAGE = {
+  python: { command: "ruff format", extensions: [".py", ".pyi"] },
+  go: { command: "gofmt -w", extensions: [".go"] },
+  php: { command: "vendor/bin/php-cs-fixer fix", extensions: [".php"] },
+};
+
+const runnerFor = (language, projectDir) => (language === "python" && projectDir
+  ? PYTHON_RUNNERS.find(([lock]) => existsSync(join(projectDir, lock)))?.[1] ?? null
+  : null);
+
+/** Native commands for a language, or {} when JS/TS or unknown; python ones through uv/poetry when the project uses them. */
+export function commandsForLanguage(language, projectDir = null) {
+  const cmds = { ...COMMANDS_BY_LANGUAGE[language] };
+  const runner = runnerFor(language, projectDir);
+  if (runner) for (const [step, command] of Object.entries(cmds)) cmds[step] = `${runner} ${command}`;
+  return cmds;
+}
+
+/** The write-mode formatter of a language and the extensions it takes, or null. */
+export function formatWriteFor(language, projectDir = null) {
+  const entry = FORMAT_WRITE_BY_LANGUAGE[language];
+  if (!entry) return null;
+  return { ...entry, command: [runnerFor(language, projectDir), entry.command].filter(Boolean).join(" ") };
 }

package/src/orchestrator/drivers/init-context.js

@@ -47,7 +47,7 @@ export function adoptPreLoopConfig(ctx, updatedConfig) {
   ctx.coderRoleInstance.config = updatedConfig;
 }
 
-export async function initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags }) {
+export async function initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags, preexisting = null }) {
   // Auto-init .karajan/ if missing (copies coder-rules, review-rules, role templates)
   const initProjectDir = config.projectDir || process.cwd();
   await autoInit(initProjectDir, logger);
@@ -229,7 +229,7 @@ export async function initFlowContext({ task, config, logger, emitter, askQuesti
     ctx.journalDecisions = [];
   }
 
-  ctx.gitCtx = await prepareGitAutomation({ config: ctx.config, task, logger, session: ctx.session });
+  ctx.gitCtx = await prepareGitAutomation({ config: ctx.config, task, logger, session: ctx.session, preexisting });
   const projectDir = ctx.config.projectDir || process.cwd();
   ctx.reviewRules = (await resolveReviewProfile({ mode: ctx.config.review_mode, projectDir })).rules;
   await ctx.coderRoleInstance.init();

package/src/orchestrator/drivers/iteration-phases/quality-gates.js

@@ -23,9 +23,13 @@ import { runPerfStage } from "../../stages/perf-stage.js";
 import { runTddDisciplineStage } from "../../stages/tdd-discipline-stage.js";
 import { runSuiteGreenStage, suiteGreenRequired } from "../../stages/suite-green-stage.js";
 import { runToolJudgeStage } from "../../stages/tool-judge-stage.js";
+import { runFormatStage } from "../../stages/format-stage.js";
 import { tryCiComment } from "../../ci-integration.js";
 
 export async function runQualityGateStages({ config, logger, emitter, eventBase, session, trackBudget, i, askQuestion, repeatDetector, budgetSummary, sonarState, task, stageResults, coderRole, pipelineFlags, brainCtx }) {
+  // KJC-TSK-1237 (#2565): the coder's files reach every gate formatted.
+  await runFormatStage({ config, logger, emitter, eventBase, session });
+
   const tddResult = await runTddCheckStage({ config, logger, emitter, eventBase, session, trackBudget, iteration: i, askQuestion, task, brainCtx });
   if (tddResult.action === "pause") return { action: "return", result: tddResult.result };
   if (tddResult.action === "continue") return { action: "continue" };

package/src/orchestrator/flow-runner.js

@@ -112,7 +112,7 @@ export async function runFlow(opts) {
   return withRunContext({}, () => _runFlowInner(opts));
 }
 
-async function _runFlowInner({ task, config, logger, flags = {}, emitter = null, askQuestion = null, pgTaskId = null, pgProject = null }) {
+async function _runFlowInner({ task, config, logger, flags = {}, emitter = null, askQuestion = null, pgTaskId = null, pgProject = null, preexisting = null }) {
   // Defensive test-harness resolution for callers that bypass loadConfig()
   // (orchestrator unit tests that build raw config objects). Production
   // callers go through src/config/loader.js → loadConfig which already
@@ -153,7 +153,7 @@ async function _runFlowInner({ task, config, logger, flags = {}, emitter = null,
 
   let ctx;
   try {
-    ctx = await initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags });
+    ctx = await initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags, preexisting });
   } catch (initError) {
     // Pre-loop / preflight failures are CONFIG problems, not pipeline
     // disputes. Pre-v2.7.5 we escalated them to Solomon, which:
@@ -356,7 +356,8 @@ export async function resumeFlow({ sessionId, answer, config, logger, flags = {}
 
   // Re-run the flow with the existing session context
   try {
-    return await runFlow({ task, config: sessionConfig, logger, flags, emitter, askQuestion });
+    // KJC-BUG-0412: what was pending is what was pending when THIS session started.
+    return await runFlow({ task, config: sessionConfig, logger, flags, emitter, askQuestion, preexisting: session.git_preexisting ?? null });
   } catch (err) {
     await markSessionStatus(session, "failed");
     throw err;

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

@@ -0,0 +1,61 @@
+/**
+ * KJC-TSK-1237 (#2565): no stage formatted the coder's files, so a pre-commit
+ * format check aborted the final commit after every gate was green, and a
+ * one-command fix reached Solomon. This stage runs the project's formatter in
+ * write mode (the one kj harden knows) on the files of this session only:
+ * pending now and not pending when the session started. It is not a gate: a
+ * failing or missing formatter is said and the next stages judge the files.
+ * Opt-out: `development.format_after_coder: false`.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { extname, join } from "node:path";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+import { runCommand } from "../../utils/process.js";
+import { listPendingPaths } from "../../utils/git.js";
+import { detectStackRoots } from "../../harden/stack-roots.js";
+import { formatWriteFor } from "../../harden/hook-commands.js";
+
+const TIMEOUT_MS = 2 * 60 * 1000;
+const primaryLanguage = (projectDir) => detectStackRoots(projectDir)[0]?.language ?? null;
+
+const expand = (projectDir, p) => (p.endsWith("/")
+  ? readdirSync(join(projectDir, p), { recursive: true }).map((f) => join(p, f))
+  : [p]);
+
+/** Files of the session the formatter takes; git names a new directory, so its files are listed. */
+function filesToFormat({ pending, preexisting, extensions, projectDir }) {
+  const before = new Set(preexisting);
+  return pending.filter((p) => !before.has(p) && existsSync(join(projectDir, p)))
+    .flatMap((p) => expand(projectDir, p))
+    .filter((p) => extensions.includes(extname(p)));
+}
+
+/** @returns {Promise<{ran: boolean, ok?: boolean, files?: string[]}>} */
+export async function runFormatStage({ config, logger, emitter, eventBase, session, detectLanguageImpl = primaryLanguage, listPendingImpl = (dir) => listPendingPaths(dir), runImpl = async (...args) => runCommand(...args) }) {
+  if (config?.development?.format_after_coder === false) return { ran: false };
+  const projectDir = config?.projectDir || process.cwd();
+  const formatter = formatWriteFor(detectLanguageImpl(projectDir), projectDir);
+  if (!formatter) return { ran: false };
+  const preexisting = session?.git_preexisting;
+  if (!Array.isArray(preexisting)) {
+    logger?.warn?.("format: no baseline of what was pending when the session started: nothing formatted");
+    return { ran: false };
+  }
+  let files;
+  try {
+    files = filesToFormat({ pending: await listPendingImpl(projectDir), preexisting, extensions: formatter.extensions, projectDir });
+  } catch (err) {
+    logger?.warn?.(`format: the session's files could not be listed (${err.message}): nothing formatted`);
+    return { ran: false };
+  }
+  if (files.length === 0) return { ran: false };
+  const [bin, ...args] = formatter.command.split(" ");
+  const res = await runImpl(bin, [...args, "--", ...files], { cwd: projectDir, timeout: TIMEOUT_MS }).catch(() => ({ exitCode: null }));
+  const ok = res.exitCode === 0;
+  const message = ok
+    ? `format: ${formatter.command} on ${files.length} file(s)`
+    : `format: ${formatter.command} failed (exit ${res.exitCode ?? "none"}); the next stages judge the files as they are`;
+  logger?.[ok ? "info" : "warn"]?.(message);
+  emitProgress(emitter, makeEvent("format:result", { ...eventBase, stage: "format" }, { status: ok ? "ok" : "warn", message, detail: { command: formatter.command, files } }));
+  return { ran: true, ok, files };
+}

package/src/review/pr-requirements.js

@@ -4,6 +4,8 @@
  * The rules are the own-work ones: the same budget, Conventional Commits and
  * attribution patterns, and tests-with-code.
  */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { AI_ATTRIBUTION, CONVENTIONAL_TYPES } from "../harden/hook-templates.js";
 import { loadPolicy } from "../policy/engine.js";
 import { runCommand } from "../utils/process.js";
@@ -59,12 +61,35 @@ export function commitChecks(commits) {
   ];
 }
 
-/** Source changed with no test changed (a delete-only change needs none). */
+// KJC-TSK-1238 (#2263): a convention the reviewed repo declares (commitlint, kj's commit-msg hook).
+const CONVENTION_FILES = [
+  "commitlint.config.js", "commitlint.config.cjs", "commitlint.config.mjs", "commitlint.config.ts",
+  ".commitlintrc", ".commitlintrc.json", ".commitlintrc.yml", ".commitlintrc.yaml", ".commitlintrc.js", ".commitlintrc.cjs",
+  ".karajan/hooks/commit-msg",
+];
+
+export function declaresCommitConvention(projectDir) {
+  if (CONVENTION_FILES.some((f) => existsSync(join(projectDir, f)))) return true;
+  try {
+    return Boolean(JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8")).commitlint);
+  } catch {
+    return false; // no package.json, or not JSON: it declares nothing
+  }
+}
+
+/**
+ * Source changed with no test changed (a delete-only change needs none). On
+ * someone else's PR test-first is kj's rule, not theirs (KJC-TSK-1238): a
+ * change with no business logic needs no test, so it is a question, not a failure.
+ */
 export function testsCheck({ config, numstat }) {
   const rows = rowsOf(numstat);
   const res = checkTestsWithCode({ config, stagedFiles: rows.map((r) => r.file), numstat: rows });
-  const ok = res.ok && res.mode !== "warn";
-  return { id: "tests", ok, detail: ok ? `tests: ${res.mode}` : res.reason || "source changed with no test changed" };
+  if (res.ok && res.mode !== "warn") return { id: "tests", ok: true, detail: `tests: ${res.mode}` };
+  return {
+    id: "tests", ok: null, detail: res.reason || "source changed with no test changed",
+    question: "No test changed: does the change touch business logic, behaviour a unit, integration or E2E test could observe? A plain index, configuration or infrastructure needs none.",
+  };
 }
 
 const git = async (projectDir, args) => {
@@ -83,5 +108,9 @@ export async function prRequirementChecks({ range, projectDir, config, run = git
     const [sha, subject = "", body = ""] = r.split("\x1f");
     return { sha, subject, body };
   });
-  return [sizeCheck({ numstat, limit: prSizeLimit({ projectDir, config }).limit }), ...commitChecks(commits), testsCheck({ config, numstat })];
+  const [conventional, attribution] = commitChecks(commits);
+  const commitFormat = declaresCommitConvention(projectDir)
+    ? conventional
+    : { id: "conventional-commits", ok: null, skipped: true, detail: "the repo declares no commit convention (no commitlint config, no kj commit-msg hook): not checked" };
+  return [sizeCheck({ numstat, limit: prSizeLimit({ projectDir, config }).limit }), commitFormat, attribution, testsCheck({ config, numstat })];
 }

package/src/session/mutators.js

@@ -227,6 +227,11 @@ export function setPgTaskId(session, id) {
   session.pg_task_id = id;
 }
 
+/** KJC-BUG-0412: what was pending in the tree when the session started. */
+export function setGitPreexisting(session, paths) {
+  session.git_preexisting = paths;
+}
+
 export function appendPgCommits(session, commits) {
   session.pg_commits = [...(session.pg_commits ?? []), ...commits];
 }