karajan-code 4.44.0 → 4.45.0

package/package.json

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

package/src/environment/contract-commit.js

@@ -40,6 +40,8 @@ const runner = (projectDir, env) => (args) => execFileSync("git", ["-C", project
 // or under a stack root (a fullstack monorepo is hardened on every side).
 const isContract = (file) =>
   CONTRACT_PATHS.some((p) => (p.endsWith("/") || p.endsWith("-") ? file.startsWith(p) : file === p)) || GENERATED_CONFIG_FILES.has(basename(file));
+/** The supervisor's files: the hooks and their provenance, sealed by the human (ADR 0009). */
+const isSupervisor = (file) => file.startsWith(".karajan/hooks/") || file === ".karajan/supervisor-provenance.json";
 
 /** The contract files git sees as changed, with their porcelain code (`??` untracked). */
 function contractStatus(git) {
@@ -70,9 +72,14 @@ const branchOf = (git) => { try { return git(["symbolic-ref", "--short", "HEAD"]
  */
 export function commitContract({ projectDir, before = new Set(), baseBranch = "main", env = process.env }) {
   const git = runner(projectDir, env);
-  const files = contractStatus(git).map(([file]) => file).filter((file) => !before.has(file)).sort();
-  if (files.length === 0) return { committed: false, reason: "nothing of the contract to commit" };
   const history = hasCommits(git);
+  // KJC-BUG-0302: a sealed supervisor regenerated (tracked hooks or provenance
+  // that changed) is the seal's, a human act (ADR 0009), never the contract
+  // commit's: regenerated together after a version bump, the gate refused the one
+  // and the seal the other, and the person had to unstage the hook by hand. The
+  // first install (untracked hooks) still rides in the contract commit.
+  const files = contractStatus(git).filter(([file, code]) => !before.has(file) && !(history && code !== "??" && isSupervisor(file))).map(([file]) => file).sort();
+  if (files.length === 0) return { committed: false, reason: "nothing of the contract to commit" };
   if (history && branchOf(git) === baseBranch) {
     // kj never commits on the base branch, and will not switch the person's branch
     // for them: the files are named so the commit can be made where it belongs.
@@ -83,7 +90,10 @@ export function commitContract({ projectDir, before = new Set(), baseBranch = "m
     // --only: these paths and nothing else. What the person had staged stays staged.
     git(["commit", "--only", "-m", history ? REGEN_MESSAGE : FRESH_MESSAGE, "--", ...files]);
   } catch (err) {
-    return { committed: false, files, reason: `git could not commit the contract: ${String(err.stderr || err.message).trim().split("\n")[0]}` };
+    // KJC-BUG-0302: the files stay staged, and the reason names the way to commit them.
+    const why = String(err.stderr || err.message).trim().split("\n")[0];
+    const quoted = files.map((f) => "'" + f.replaceAll("'", String.raw`'\''`) + "'").join(" ");
+    return { committed: false, files, reason: `git could not commit the contract: ${why}. Commit these generated files on a branch yourself: git add -- ${quoted} && kj review --staged && git commit -m "chore(kj): el contrato del método, generado por kj"` };
   }
   return { committed: true, files };
 }

package/src/orchestrator/drivers/post-loop.js

@@ -32,6 +32,8 @@ import {
 } from "../../session/mutators.js";
 import { emitProgress, makeEvent } from "../../utils/events.js";
 import { runTesterStage, runSecurityStage, runFinalAuditStage } from "../post-loop-stages.js";
+import { runAcceptanceCoverageStage } from "../stages/acceptance-coverage-stage.js";
+import { criteriaOfCard } from "../../roles/acceptance-coverage-role.js";
 import { invokeSolomon } from "../solomon-escalation.js";
 import { tryCiComment } from "../ci-integration.js";
 import { getIntegration } from "../integrations.js";
@@ -103,6 +105,23 @@ export async function handlePostLoopStages({ config, session, emitter, eventBase
     return { action: "continue" };
   }
 
+  // KJC-TSK-0987 (#1894): with a card, each acceptance criterion is read against
+  // the diff by a different AI before the run is approved. An uncovered one goes
+  // back to the coder; a judge with no verdict stops the approval, never grants it.
+  const coverage = await runAcceptanceCoverageStage({
+    config, logger, emitter, eventBase, trackBudget, iteration: i, task,
+    criteria: criteriaOfCard(session.pg_card), diff: postLoopDiff,
+  });
+  if (coverage.stageResult) stageResults.acceptanceCoverage = coverage.stageResult;
+  if (coverage.action === "retry") {
+    setReviewerFeedback(session, coverage.feedback);
+    await saveSession(session);
+    return { action: "continue" };
+  }
+  if (coverage.action === "fail") {
+    return { action: "return", result: { approved: false, sessionId: session.id, reason: "acceptance_coverage_unavailable", error: coverage.stageResult.summary } };
+  }
+
   return { action: "proceed" };
 }
 

package/src/orchestrator/drivers/run-hu-batch.js

@@ -32,6 +32,9 @@ import { runRepair } from "../repair/repair-runner.js";
 import { writeHistoryRecord } from "./post-loop.js";
 import { setReviewerFeedback } from "../../session/mutators.js";
 import { createHuSnapshot } from "../../git/hu-snapshot.js";
+import { generateDiff } from "../../review/diff-generator.js";
+import { runAcceptanceCoverageStage } from "../stages/acceptance-coverage-stage.js";
+import { criteriaOfCard } from "../../roles/acceptance-coverage-role.js";
 
 /**
  * @param {object} args
@@ -422,12 +425,28 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
   // the host reads, not only in a warn line of the log.
   const warnings = collectGitWarnings(subPipelineResult.results);
   for (const w of warnings) logger.warn(`git automation: ${w}`);
+  // KJC-TSK-0987 (#1894): the HUs approved themselves against their own stories;
+  // the card's criteria are read against the diff of the whole run before the
+  // run says approved. Uncovered: approved:false with the list, for the host.
+  let coverage = { action: "skip" };
+  if (subPipelineResult.approved) {
+    const diff = await generateDiff({ baseRef: ctx.session.head_at_start || ctx.session.session_start_sha });
+    coverage = await runAcceptanceCoverageStage({
+      config: ctx.config, logger, emitter, eventBase: ctx.eventBase, trackBudget: ctx.trackBudget,
+      iteration: 0, task, criteria: criteriaOfCard(ctx.session.pg_card), diff,
+    });
+    if (coverage.stageResult) ctx.stageResults.acceptanceCoverage = coverage.stageResult;
+  }
+  const uncovered = coverage.action === "retry" ? { reason: "acceptance_criteria_uncovered", uncovered: coverage.stageResult.uncovered } : {};
+  const unavailable = coverage.action === "fail" ? { reason: "acceptance_coverage_unavailable", error: coverage.stageResult.summary } : {};
   const finalResult = {
-    approved: subPipelineResult.approved,
+    approved: subPipelineResult.approved && coverage.action !== "retry" && coverage.action !== "fail",
     sessionId: ctx.session.id,
     huResults: subPipelineResult.results,
     blockedIds: subPipelineResult.blockedIds,
     planId: ctx.session._planRef?.planId || null,
+    ...uncovered,
+    ...unavailable,
     ...(warnings.length > 0 ? { warnings } : {})
   };
   await writeHistoryRecord({ sessionId: ctx.session.id, task, result: finalResult, logger });

package/src/orchestrator/stages/acceptance-coverage-stage.js

@@ -0,0 +1,47 @@
+// KJC-TSK-0987 (issue #1894): the acceptance-coverage stage. With a card whose
+// criteria the run was meant to implement, a different AI reads each criterion
+// against the diff before the run is approved. No card or no criteria: the
+// stage does not run and costs nothing. An unreadable verdict is the judge's
+// failure, never an approval.
+import { AcceptanceCoverageRole } from "../../roles/acceptance-coverage-role.js";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+
+const STAGE = "acceptance-coverage";
+
+/** The feedback the coder gets: the criteria with no evidence in the diff. */
+export const uncoveredFeedback = (uncovered) => {
+  const lines = uncovered.map((c) => "- [" + c.index + "] " + c.text + (c.evidence ? " (judge: " + c.evidence + ")" : ""));
+  return "Acceptance criteria NOT covered by the diff (implement them, with tests that exercise them):\n" + lines.join("\n");
+};
+
+/**
+ * @returns {Promise<{action: "skip"|"ok"|"retry"|"fail", stageResult?: object, feedback?: string}>}
+ */
+export async function runAcceptanceCoverageStage({ config, logger, emitter, eventBase, trackBudget, iteration, task, criteria, diff, RoleClass = AcceptanceCoverageRole }) {
+  if (!Array.isArray(criteria) || criteria.length === 0) return { action: "skip" };
+  logger.setContext?.({ iteration, stage: STAGE });
+  emitProgress(emitter, makeEvent(`${STAGE}:start`, { ...eventBase, stage: STAGE }, {
+    message: `Acceptance coverage: ${criteria.length} criteria against the diff`,
+    detail: { criteria: criteria.length, executorType: "agent" },
+  }));
+  const role = new RoleClass({ config, logger, emitter });
+  await role.init({ task, iteration });
+  const started = Date.now();
+  const output = await role.run({ task, criteria, diff });
+  const provider = output.result?.provider || role.resolveProvider();
+  trackBudget?.({ role: STAGE, provider, model: config?.roles?.[STAGE]?.model || null, result: output, duration_ms: Date.now() - started });
+
+  if (!output.ok) {
+    const stageResult = { ok: false, summary: output.summary || "acceptance-coverage: the judge gave no verdict", provider, error: output.result?.error || null };
+    emitProgress(emitter, makeEvent(`${STAGE}:end`, { ...eventBase, stage: STAGE }, { status: "fail", message: stageResult.summary, detail: stageResult }));
+    return { action: "fail", stageResult };
+  }
+  const { criteria: verdicts, uncovered } = output.result;
+  const stageResult = { ok: uncovered.length === 0, summary: output.summary, provider, criteria: verdicts, uncovered };
+  emitProgress(emitter, makeEvent(`${STAGE}:end`, { ...eventBase, stage: STAGE }, {
+    status: stageResult.ok ? "ok" : "fail", message: output.summary, detail: stageResult,
+  }));
+  if (stageResult.ok) return { action: "ok", stageResult };
+  logger.warn(`${output.summary} — sending them back to the coder`);
+  return { action: "retry", stageResult, feedback: uncoveredFeedback(uncovered) };
+}

package/src/prompts/acceptance-coverage.js

@@ -0,0 +1,32 @@
+// KJC-TSK-0987 (issue #1894): the prompt of the acceptance-coverage judge. A run
+// ended approved with none of the card's three criteria implemented; this judge
+// reads each criterion against the diff and says, one by one, whether it is
+// covered and where.
+
+const PREAMBLE = "IMPORTANT: You are running as a Karajan sub-agent. "
+  + "Do NOT use any MCP tools, do NOT mention Karajan. "
+  + "Your job is to judge whether a diff covers a card's acceptance criteria.";
+
+/**
+ * @param {{criteria: string[], diff: string, task?: string, instructions?: string|null}} opts
+ * @returns {string}
+ */
+export function buildAcceptanceCoveragePrompt({ criteria, diff, task = "", instructions = null }) {
+  const list = criteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
+  const body = [
+    "You are the AcceptanceCoverage judge for Karajan Code.",
+    "Input: (a) the acceptance criteria of the task's card, numbered, and (b) the diff the run produced.",
+    "For EACH criterion decide whether the diff implements it. Covered means the behavior the",
+    "criterion describes exists in the diff (code, config or tests that exercise it), not that",
+    "something related was touched. Point to the evidence: file and what it does. A criterion",
+    "with no evidence in the diff is NOT covered, whatever the task description says.",
+    "Return a single valid JSON object and nothing else.",
+    'Schema: {"criteria":[{"index":number,"covered":boolean,"evidence":string}]}',
+    "One entry per criterion, in order, index starting at 1. Do not add or drop criteria.",
+  ].join("\n");
+  const sections = [PREAMBLE];
+  if (instructions) sections.push(instructions);
+  if (task) sections.push(`## Task\n${task}`);
+  sections.push(body, `## Acceptance criteria (${criteria.length})\n${list}`, `## Diff\n${diff || "(empty diff)"}`);
+  return sections.join("\n\n");
+}

package/src/roles/acceptance-coverage-role.js

@@ -0,0 +1,78 @@
+// KJC-TSK-0987 (issue #1894): AcceptanceCoverageRole, the judge that reads each
+// acceptance criterion of the card against the diff before the run is approved.
+// Judged by a different AI than the coder (the reviewer's provider by default).
+// Role + helpers ship here; the stage wires it (same PR), the loops next.
+
+import { AgentRole } from "./agent-role.js";
+import { buildAcceptanceCoveragePrompt } from "../prompts/acceptance-coverage.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+
+/**
+ * The card's acceptance criteria as plain sentences, one per criterion.
+ * Structured Given/When/Then first; else the free text, one per line or bullet.
+ * @param {object|null} card
+ * @returns {string[]}
+ */
+export function criteriaOfCard(card) {
+  const structured = Array.isArray(card?.acceptanceCriteriaStructured) ? card.acceptanceCriteriaStructured : [];
+  const fromStructured = structured
+    .map((ac) => (ac?.given && ac?.when && ac?.then ? `Given ${ac.given}, when ${ac.when}, then ${ac.then}` : String(ac?.raw || "").trim()))
+    .filter(Boolean);
+  if (fromStructured.length > 0) return fromStructured;
+  return String(card?.acceptanceCriteria || "")
+    .split("\n")
+    .map((line) => line.replace(/^\s*(?:[-*•]|\d+[.)])\s*/, "").trim())
+    .filter(Boolean);
+}
+
+const normalizeVerdicts = (parsed, criteria) => criteria.map((text, i) => {
+  const v = Array.isArray(parsed?.criteria) ? parsed.criteria.find((c) => Number(c?.index) === i + 1) : null;
+  return {
+    index: i + 1,
+    text,
+    // No entry for a criterion is no evidence for it: not covered, never assumed.
+    covered: v ? Boolean(v.covered) : false,
+    evidence: typeof v?.evidence === "string" ? v.evidence.trim() : "",
+  };
+});
+
+export class AcceptanceCoverageRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "acceptance-coverage" });
+  }
+
+  // A different AI than the coder: the reviewer's, unless the role has its own.
+  resolveProvider() {
+    return this.config?.roles?.["acceptance-coverage"]?.provider
+      || this.config?.roles?.reviewer?.provider
+      || this.config?.reviewer
+      || "codex";
+  }
+
+  extractInput(input) {
+    return { ...super.extractInput(input), criteria: Array.isArray(input?.criteria) ? input.criteria : [], diff: String(input?.diff || "") };
+  }
+
+  async buildPrompt({ task, criteria, diff }) {
+    this._criteria = criteria;
+    return { prompt: buildAcceptanceCoveragePrompt({ criteria, diff, task, instructions: this.instructions }) };
+  }
+
+  parseOutput(raw) { return extractFirstJson(raw); }
+
+  // A verdict with no `criteria` array is not a verdict: the reviewer's failure.
+  isSuccessful(parsed) { return Array.isArray(parsed?.criteria); }
+
+  buildSuccessResult(parsed, provider) {
+    const criteria = normalizeVerdicts(parsed, this._criteria || []);
+    const uncovered = criteria.filter((c) => !c.covered);
+    return { criteria, uncovered, provider, error: Array.isArray(parsed?.criteria) ? undefined : "no criteria array in the verdict" };
+  }
+
+  buildSummary(parsed) {
+    if (!Array.isArray(parsed?.criteria)) return "acceptance-coverage: unreadable verdict (no criteria array)";
+    const total = (this._criteria || []).length;
+    const uncovered = normalizeVerdicts(parsed, this._criteria || []).filter((c) => !c.covered).length;
+    return uncovered === 0 ? `acceptance-coverage: ${total}/${total} criteria covered` : `acceptance-coverage: ${uncovered} of ${total} criteria NOT covered`;
+  }
+}

package/src/utils/update-check.js

@@ -3,8 +3,22 @@ import { readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { isSea } from "node:sea";
+import { fileURLToPath } from "node:url";
 import { getKarajanHome } from "./paths.js";
 
+// KJC-BUG-0301: `kj update` on a kj linked from a source tree (npm link) said
+// "Updating 4.44.0 → 4.43.0", installed the registry's older version globally
+// and replaced the development link. Two facts decide now, before any install.
+/** Whether this kj runs from a source tree (npm link), not from a node_modules install. */
+export const isSourceTree = (selfPath = fileURLToPath(import.meta.url)) => !selfPath.split(path.sep).includes("node_modules");
+const numeric = (v) => String(v).split(/[.-]/, 3).map((n) => Number.parseInt(n, 10) || 0);
+/** Whether version `a` is strictly newer than `b` (major.minor.patch; a prerelease tag is ignored). */
+export const isNewerVersion = (a, b) => {
+  const [x, y] = [numeric(a), numeric(b)];
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i];
+  return false;
+};
+
 const CACHE_FILE = "update-check.json";
 // KJC-TSK-0690: 6h — kj can ship several releases a day; a session should
 // not work a full day blind. KJ_NO_UPDATE_CHECK=1 opts out (CI).
@@ -183,7 +197,7 @@ export async function printUpdateNotice(currentVersion) {
  * @param {typeof fetch} [opts.fetchFn] - injectable fetch (registry lookup + installer download)
  * @returns {Promise<{ ok: boolean, alreadyLatest?: boolean, latest?: string, manual?: boolean }>}
  */
-export async function performSelfUpdate({ currentVersion, exec, logger = console, channel, fetchFn = fetch } = {}) {
+export async function performSelfUpdate({ currentVersion, exec, logger = console, channel, fetchFn = fetch, sourceTree = isSourceTree() } = {}) {
   const run = exec || (async (cmd, args) => (await import("execa")).execa(cmd, args));
   const ch = channel || detectInstallChannel();
   logger.log(`Current version: ${currentVersion}`);
@@ -207,6 +221,15 @@ export async function performSelfUpdate({ currentVersion, exec, logger = console
     logger.log(`Already on the latest version (${currentVersion}).`);
     return { ok: true, alreadyLatest: true, latest };
   }
+  // KJC-BUG-0301: never a downgrade, and never over a development link.
+  if (isNewerVersion(currentVersion, latest)) {
+    logger.log(`This kj (${currentVersion}) is newer than the registry's latest (${latest}): nothing to update.`);
+    return { ok: true, newerThanRegistry: true, latest };
+  }
+  if (ch === "npm" && sourceTree) {
+    logger.log(`Update available: ${currentVersion} → ${latest}, but this kj runs from a source tree (npm link) and kj update will not replace it. Pull or rebuild that tree, or unlink it first: npm unlink -g ${packageName()}`);
+    return { ok: true, latest, manual: true };
+  }
 
   if (ch === "sea" && process.platform === "win32") {
     // Executing a downloaded .ps1 from inside the binary is not supported