karajan-code 4.66.1 → 4.68.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.66.1",
+  "version": "4.68.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

@@ -1119,7 +1119,8 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--no-config", "Skip lint/format/commit config files (hooks only)")
     .option("--no-ci", "Skip CI quality workflows")
     .option("--no-guidelines", "Skip AI-agent guideline files (AGENTS.md/CLAUDE.md)")
-    .option("--no-sandbox", "Leave the host Bash sandbox alone (by default it is turned on where it can start)")
+    .option("--sandbox", "Turn the host Bash sandbox on where it can start (off by default: it blocks gh, push and Sonar)")
+    .option("--no-sandbox", "Leave the host Bash sandbox alone (the default; kept for existing scripts)")
     .option("--mutation", "Also seed an opt-in nightly/manual mutation CI job (never a PR gate)")
     .option("--only <dirs...>", "Harden only these language roots (e.g. frontend backend)")
     .option("--exclude <globs...>", "Skip language roots matching these globs (e.g. wrappers)")
@@ -1137,7 +1138,7 @@ export function registerMeta(program, { pkgVersion }) {
           config: flags.config !== false,
           ci: flags.ci !== false,
           guidelines: flags.guidelines !== false,
-          sandbox: flags.sandbox !== false,
+          sandbox: flags.sandbox === true,
           mutation: Boolean(flags.mutation),
           only: flags.only ?? [],
           exclude: flags.exclude ?? [],

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");
@@ -92,7 +92,7 @@ export async function hardenCommand({
   only = [],
   exclude = [],
   commitSupervisor = false,
-  sandbox = true,
+  sandbox = false,
   kjVersion = null,
   // KJC-BUG-0289: the contract files already dirty before anything was generated
   // (kj init captures them before writing its own). What is dirty NOW is the person's.
@@ -162,7 +162,8 @@ export async function hardenCommand({
       // sin sello, que es como una sesión se dejaba sin herramientas.
       const sh = installSentinelHooks({ projectDir, logger, human: commitSupervisor });
       result.sentinelHooks = sh.wired ? "wired" : "script-only";
-      // KJC-TSK-1092: the host sandbox, on by default wherever it can start here.
+      // KJC-TSK-1092/1241: the host sandbox, only when asked (kj harden --sandbox):
+      // inside it kj run cannot push, open the PR or reach Sonar on localhost.
       if (sandbox) result.sandbox = installSandbox({ projectDir, logger }).state;
     }
   } catch (err) {

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/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, readFileSync } 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,46 @@ 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"] },
+};
+
+// KJC-TSK-1239: JS/TS takes the formatter the project declares, from its node_modules.
+// Declared both? The one its scripts call wins; else prettier, the more common.
+const JS_TS = [".js", ".mjs", ".cjs", ".jsx", ".ts", ".mts", ".cts", ".tsx"];
+const JS_FORMATTERS = [
+  { pkg: "prettier", bin: "prettier", inScripts: /\bprettier\b/, command: "node_modules/.bin/prettier --write" },
+  { pkg: "@biomejs/biome", bin: "biome", inScripts: /\bbiome\b/, command: "node_modules/.bin/biome format --write" },
+];
+function jsFormatWrite(projectDir) {
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8")); } catch { return null; }
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const scripts = Object.values(pkg.scripts ?? {}).join("\n");
+  const usable = JS_FORMATTERS.filter((f) => deps[f.pkg] && existsSync(join(projectDir, "node_modules", ".bin", f.bin)));
+  const chosen = usable.find((f) => f.inScripts.test(scripts)) ?? usable[0];
+  return chosen ? { command: chosen.command, extensions: JS_TS } : null;
+}
+
+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) {
+  if (language === "javascript" || language === "typescript") return projectDir ? jsFormatWrite(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];
 }