karajan-code 4.6.0 → 4.6.2

package/package.json

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

package/src/commands/review-gate.js

@@ -113,14 +113,26 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // single test change warn (block via method_gates.tests_with_code).
   const changedFiles = (await rawDiff(flags.range, ["--name-only"])).split("\n").map((f) => f.trim()).filter(Boolean);
 
-  // KJC-TSK-0688 (MG-C): oversized-diff nudge — informative only; the
-  // project's CI owns any hard budget. Sums additions from --numstat.
+  // KJC-TSK-0688 (MG-C) + KJC-TSK-0691 (MG-E): oversized-diff policy.
+  // Field case: a 522-line PR sailed past the warning with a
+  // rationalization — where the project wants teeth, pr_size: "block"
+  // rejects deterministically with a NAMED escape. Default stays warn.
   const sizeWarn = config?.method_gates?.pr_size_warn ?? 150;
   if (sizeWarn > 0) {
     const numstat = await rawDiff(flags.range, ["--numstat"]);
     const added = numstat.split("\n").reduce((acc, l) => acc + (Number(l.split("\t")[0]) || 0), 0);
     if (added > sizeWarn) {
-      console.log(`⚠ pr-size: ${added} lines added (guideline ~${sizeWarn}) — atomic PRs review better; consider splitting (method_gates.pr_size_warn to tune)`);
+      const sizePolicy = config?.method_gates?.pr_size || "warn";
+      if (process.env.KJ_ALLOW_LARGE_PR === "1") {
+        console.log(`⚠ pr-size exempt: ${added} lines added — KJ_ALLOW_LARGE_PR=1 (explicit escape hatch)`);
+      } else if (sizePolicy === "block") {
+        const reason = `${added} lines added exceeds the ${sizeWarn}-line budget (method_gates.pr_size: block) — partition the work, or get your user's explicit OK and re-run with KJ_ALLOW_LARGE_PR=1`;
+        console.log(`✗ pr-size gate: ${reason}`);
+        process.exitCode = 1;
+        return { verdict: "rejected", reviewer: "pr-size", issues: [{ severity: "high", description: reason }] };
+      } else {
+        console.log(`⚠ pr-size: ${added} lines added (guideline ~${sizeWarn}) — an oversized warning is not an opinion: partition, or ask your user (method_gates.pr_size: block to harden)`);
+      }
     }
   }
   const tests = checkTestsWithCode({ config, stagedFiles: changedFiles });

package/src/environment/playbook.js

@@ -66,6 +66,10 @@ Invariants (the git gates enforce these — they are not suggestions):
   and it must be reviewed again. Disagree with a rejection? \`kj solomon\`.
 - Security findings are never overridable — not even by arbitration. You
   absorb the security role: \`kj brief security\` states what must be true.
+- A design decision the card's AC don't cover belongs to the USER: record
+  it as a proposed ADR (\`kj adr add\`) and ask — never bury it in a PR
+  bullet. An oversized-diff warning is not an opinion either: partition,
+  or get an explicit OK.
 - Branch first: never commit on the base branch — every change reaches it
   through an atomic PR (~150 net lines, Conventional Commits). More than one
   task, or the base tree must stay untouched? \`kj worktree start <slug>\`
@@ -81,6 +85,8 @@ architect, tester, security, audit, board) · \`kj hu add|move|list\` ·
 
 Hit a kj bug or friction? Diagnose it and file it upstream with
 \`kj report-issue\` (sanitized; ask your user before \`--publish\`).
+kj announces a newer version? Tell your user what it brings and ask —
+never run \`kj update\` on your own.
 `;
 
 export function renderPlaybook({ stateBackend = "hu-board", boardName = null } = {}) {

package/src/harden/hook-templates.js

@@ -16,8 +16,8 @@ export const SHEBANG = "#!/usr/bin/env sh";
 /** Hooks enabled per profile. */
 export const PROFILE_HOOKS = {
   minimal: ["commit-msg"],
-  standard: ["pre-commit", "commit-msg", "pre-push", "post-merge"],
-  strict: ["pre-commit", "commit-msg", "pre-push", "post-merge"],
+  standard: ["pre-commit", "prepare-commit-msg", "commit-msg", "pre-push", "post-merge"],
+  strict: ["pre-commit", "prepare-commit-msg", "commit-msg", "pre-push", "post-merge"],
 };
 
 /** Build the managed body for a single hook. */
@@ -99,6 +99,37 @@ export function hookBody(hook, cmds = {}, { globalHooksDir = null, baseBranch =
       else lines.push("# (no test command detected for this stack)");
       return [...lines, ...chain].join("\n");
     }
+    case "prepare-commit-msg":
+      // KJC-TSK-0692 (MG-F): the branch already carries the card ref
+      // (validated by the card-first gate) — the subject inherits it
+      // automatically. A convention that enforces itself needs no adoption.
+      return [
+        'msg_file="$1"',
+        'branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")',
+        "# POSIX-safe extraction (no grep -o): the ref is the leading",
+        "# card-shaped token of the branch's last segment (feat/REF-desc).",
+        "seg=$(printf '%s' \"$branch\" | tr '[:upper:]' '[:lower:]'); seg=\"${seg##*/}\"",
+        "ref=$(printf '%s' \"$seg\" | sed -nE 's/^([a-z][a-z0-9]{1,9}(-[a-z][a-z0-9]{1,9})*-[0-9]{1,6})(-.*)?$/\\1/p')",
+        'header=$(head -n1 "$msg_file")',
+        'if [ -n "$ref" ] && [ -n "$header" ]; then',
+        '  case "$header" in',
+        "    Merge*|fixup!*|squash!*) ;;",
+        "    *)",
+        "      # Boundary match — a header mentioning KJW-TSK-00011 must not",
+        "      # suppress the KJW-TSK-0001 stamp. $ref is [a-z0-9-] only by",
+        "      # construction (sed extraction above), safe inside the ERE.",
+        '      if ! printf \'%s\' "$header" | grep -qiE "(^|[^a-zA-Z0-9-])$ref([^a-zA-Z0-9-]|$)"; then',
+        "        stamp=$(printf '%s' \"$ref\" | tr '[:lower:]' '[:upper:]')",
+        '        new_header="$header ($stamp)"',
+        '        if [ "${#new_header}" -le 100 ]; then',
+        "          { printf '%s\\n' \"$new_header\"; tail -n +2 \"$msg_file\"; } > \"$msg_file.kjtmp\" && mv \"$msg_file.kjtmp\" \"$msg_file\"",
+        "        fi",
+        "      fi",
+        "      ;;",
+        "  esac",
+        "fi",
+        ...chain,
+      ].join("\n");
     case "post-merge":
       return [
         "# Refresh the local RAG index so retrieval never serves stale code.",

package/src/utils/update-check.js

@@ -5,8 +5,38 @@ import { isSea } from "node:sea";
 import { getKarajanHome } from "./paths.js";
 
 const CACHE_FILE = "update-check.json";
-const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+// 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).
+const CACHE_TTL_MS = 6 * 60 * 60 * 1000;
 const PACKAGE_NAME = "karajan-code";
+const CHANGELOG_URL = "https://raw.githubusercontent.com/manufosela/karajan-code/main/CHANGELOG.md";
+const HIGHLIGHT_MAX = 160;
+
+/**
+ * First paragraph of a version's CHANGELOG section — the release headline
+ * ("Minor. **The method, enforced.** …"), bold stripped, truncated. Pure.
+ */
+export function parseChangelogHighlight(markdown, version) {
+  const section = String(markdown).split(new RegExp(`^## \\[${version.replaceAll(".", "\\.")}\\][^\\n]*$`, "m"))[1];
+  if (!section) return null;
+  const firstLine = section.split(/^##|^###/m)[0].split("\n").map((l) => l.trim()).find(Boolean);
+  if (!firstLine) return null;
+  const clean = firstLine.replaceAll("**", "");
+  return clean.length > HIGHLIGHT_MAX ? `${clean.slice(0, HIGHLIGHT_MAX - 1)}…` : clean;
+}
+
+async function fetchHighlight(version) {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+    const res = await fetch(CHANGELOG_URL, { signal: controller.signal });
+    clearTimeout(timeout);
+    if (!res.ok) return null;
+    return parseChangelogHighlight(await res.text(), version);
+  } catch {
+    return null;
+  }
+}
 
 const RAW_BASE = "https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts";
 export const INSTALL_SH_URL = `${RAW_BASE}/install-binary.sh`;
@@ -48,6 +78,7 @@ export function detectInstallChannel() {
  * Returns { updateAvailable, latest, current } or null if check fails/cached.
  */
 export async function checkForUpdate(currentVersion) {
+  if (process.env.KJ_NO_UPDATE_CHECK === "1") return null;
   try {
     const cachePath = path.join(getKarajanHome(), CACHE_FILE);
 
@@ -59,7 +90,7 @@ export async function checkForUpdate(currentVersion) {
         if (!cache.latest || cache.latest === currentVersion) return null;
         // Only show update if latest is actually NEWER than current
         if (compareVersions(cache.latest, currentVersion) > 0) {
-          return { updateAvailable: true, latest: cache.latest, current: currentVersion };
+          return { updateAvailable: true, latest: cache.latest, current: currentVersion, highlight: cache.highlight || null };
         }
         return null;
       }
@@ -78,14 +109,16 @@ export async function checkForUpdate(currentVersion) {
     const data = await res.json();
     const latest = data.version;
 
+    // KJC-TSK-0690: a NEWER version also fetches its headline once — the
+    // notice tells the user what it brings, not just that it exists.
+    const newer = latest !== currentVersion && compareVersions(latest, currentVersion) > 0;
+    const highlight = newer ? await fetchHighlight(latest) : null;
+
     // Save cache
     await fs.mkdir(getKarajanHome(), { recursive: true });
-    await fs.writeFile(cachePath, JSON.stringify({ latest, checkedAt: Date.now() }), "utf8");
+    await fs.writeFile(cachePath, JSON.stringify({ latest, checkedAt: Date.now(), highlight }), "utf8");
 
-    if (latest === currentVersion) return null;
-    if (compareVersions(latest, currentVersion) > 0) {
-      return { updateAvailable: true, latest, current: currentVersion };
-    }
+    if (newer) return { updateAvailable: true, latest, current: currentVersion, highlight };
     return null;
   } catch {
     return null; // Network error, offline, etc. Never block.
@@ -100,7 +133,9 @@ export async function printUpdateNotice(currentVersion) {
   if (result?.updateAvailable) {
     const channel = detectInstallChannel();
     console.log(`\n  Update available: v${result.current} → v${result.latest}`);
-    console.log(`  ${updateInstruction({ channel })}\n`);
+    if (result.highlight) console.log(`  What it brings: ${result.highlight}`);
+    console.log(`  ${updateInstruction({ channel })}`);
+    console.log("  Agent: tell your user and ask before updating — never update on your own.\n");
   }
 }