karajan-code 2.10.2 → 2.12.0

package/src/skills/addyosmani-catalog.js

@@ -146,7 +146,7 @@ export async function ensureCatalog(opts = {}) {
  * ensureCatalog().
  *
  * @param {{ refreshMs?: number, repoUrl?: string, force?: boolean, logger?: object }} [opts]
- * @returns {Promise<{ok: boolean, action: "cloned"|"pulled"|"fresh"|"skipped", error?: string}>}
+ * @returns {Promise<{ok: boolean, action: "cloned"|"pulled"|"reset"|"fresh"|"skipped", error?: string}>}
  */
 export async function refreshIfStale(opts = {}) {
   const { refreshMs = DEFAULT_REFRESH_MS, repoUrl = REPO_URL, force = false, logger } = opts;
@@ -171,16 +171,38 @@ export async function refreshIfStale(opts = {}) {
     return { ok: true, action: "skipped" };
   }
 
-  const result = await runCommand(
+  const pullResult = await runCommand(
     "git",
     ["-C", root, "pull", "--ff-only", "--depth", "1"],
     { timeout: 60_000 }
   );
 
-  if (result.exitCode !== 0) {
-    const stderr = (result.stderr || "").trim();
-    logger?.warn?.(`addyosmani-catalog: git pull failed — ${stderr} (keeping stale cache)`);
-    return { ok: false, action: "skipped", error: stderr };
+  let action = "pulled";
+  if (pullResult.exitCode !== 0) {
+    // The cached catalog is read-only (we never commit to it), so a
+    // non-fast-forward result is virtually always upstream rewriting
+    // history with `git push --force` — see KJC-BUG-0033 / N3-2 (the
+    // user hit this on 2026-05-07 when addyosmani force-pushed his
+    // skills repo). Recover by fetching shallow and hard-resetting to
+    // FETCH_HEAD: there's nothing local to lose.
+    const fetchResult = await runCommand(
+      "git",
+      ["-C", root, "fetch", "--depth", "1", "origin", "HEAD"],
+      { timeout: 60_000 }
+    );
+    const resetResult = fetchResult.exitCode === 0
+      ? await runCommand("git", ["-C", root, "reset", "--hard", "FETCH_HEAD"], { timeout: 30_000 })
+      : { exitCode: fetchResult.exitCode, stderr: fetchResult.stderr };
+
+    if (resetResult.exitCode !== 0) {
+      const pullErr = (pullResult.stderr || "").trim();
+      const recoveryErr = (resetResult.stderr || "").trim();
+      const combined = recoveryErr ? `${pullErr} | recovery: ${recoveryErr}` : pullErr;
+      logger?.warn?.(`addyosmani-catalog: git pull failed — ${combined} (keeping stale cache)`);
+      return { ok: false, action: "skipped", error: combined };
+    }
+    action = "reset";
+    logger?.info?.("addyosmani-catalog: ff-only failed, recovered via fetch+reset (upstream force-pushed)");
   }
 
   await writeMeta({
@@ -189,7 +211,7 @@ export async function refreshIfStale(opts = {}) {
     lastPullAt: new Date().toISOString(),
   });
 
-  return { ok: true, action: "pulled" };
+  return { ok: true, action };
 }
 
 /**

package/src/sonar/project-key.js

@@ -81,3 +81,40 @@ export async function resolveSonarProjectKey(config, options = {}) {
   const repo = slug(repoId.split("/").pop());
   return normalizeProjectKey(`kj-${repo}-${digest(repoId)}`);
 }
+
+/**
+ * Non-throwing predicate: can a Sonar project key be resolved for `config`?
+ *
+ * Used by callers (audit collector, run-loop SonarStage) that want to skip
+ * the Sonar work cleanly instead of letting `resolveSonarProjectKey` throw
+ * "Missing git remote.origin.url" deep inside the scanner. The scanner's
+ * thrown error is fine for an explicit `kj sonar` call (the user asked
+ * for it), but for implicit pipeline gates it produces a noisy "Sonar
+ * scan failed" loop in fresh /tmp/... repos.
+ *
+ * Returns true when EITHER:
+ *   - an explicit `project_key` is set (env var, config, or per-call option),
+ *   - OR `git config --get remote.origin.url` succeeds with a non-empty value.
+ *
+ * Side-effect-free apart from the git probe.
+ *
+ * @param {object} config
+ * @param {object} [options]
+ * @param {string} [options.projectKey]
+ * @returns {Promise<boolean>}
+ */
+export async function canResolveSonarProjectKey(config, options = {}) {
+  const explicit = String(
+    options.projectKey || process.env.KJ_SONAR_PROJECT_KEY || config?.sonarqube?.project_key || ""
+  ).trim();
+  if (explicit) return true;
+  // try/catch (instead of `.catch(...)`) tolerates two legitimate test
+  // realities: a runCommand mock that returns undefined, and a real
+  // promise rejection from a missing git binary. Either way we treat
+  // it as "no remote available" and let the caller skip Sonar cleanly.
+  let remote;
+  try { remote = await runCommand("git", ["config", "--get", "remote.origin.url"]); }
+  catch { return false; }
+  if (!remote) return false;
+  return remote.exitCode === 0 && String(remote.stdout || "").trim().length > 0;
+}

package/src/types/session.js

@@ -64,7 +64,8 @@
  * @property {string[]} [skillsRecommended]               - wouldHaveUsed when openskills missing
  * @property {string[]} [autoInstalledSkills]
  * @property {RtkSavings} [rtk_savings]
- * @property {string} [session_start_sha]
+ * @property {string} [session_start_sha]                 - baseline for `git diff`; may be the empty-tree SHA when no prior commits exist
+ * @property {string} [head_at_start]                     - actual HEAD when the run started; used by the post-loop journal to enumerate commits produced BY the run. Falls back to session_start_sha in zero-commits repos. (2026-05-07 dogfooding fix.)
  * @property {string} [_journalDir]                       - runtime journal path
  * @property {string[]} [_journalIterations]              - rendered iteration markdown
  * @property {string[]} [_journalFiles]

package/src/utils/display/session-summary.js

@@ -26,9 +26,19 @@ function printSessionPlanner(planner) {
   }
 }
 
-function printSessionSonar(sonar) {
+export function printSessionSonar(sonar) {
   if (!sonar) return;
-  const gateLabel = sonar.gateStatus === "OK" ? ANSI.green : ANSI.red;
+  // Three buckets so the banner reads correctly:
+  //   - OK                                 \u2192 green (real pass).
+  //   - SKIPPED / PENDING                  \u2192 gray (informational; sonar
+  //     wasn't gated against, this is NOT a fail). Pre-2026-05-07 N4
+  //     dogfooding these were rendered red, which made a clean run
+  //     look like a sonar failure during the live demo.
+  //   - everything else (ERROR, WARN, ...) \u2192 red (real fail).
+  let gateLabel;
+  if (sonar.gateStatus === "OK") gateLabel = ANSI.green;
+  else if (sonar.gateStatus === "SKIPPED" || sonar.gateStatus === "PENDING") gateLabel = ANSI.gray;
+  else gateLabel = ANSI.red;
   console.log(`  ${ANSI.dim}\ud83d\udd0d Sonar: ${gateLabel}${sonar.gateStatus}${ANSI.reset}${ANSI.dim} (${sonar.openIssues ?? 0} issues)${ANSI.reset}`);
   if (typeof sonar.issuesInitial === "number" || typeof sonar.issuesResolved === "number") {
     const issuesInitial = sonar.issuesInitial ?? sonar.openIssues ?? 0;

package/src/utils/git.js

@@ -65,6 +65,69 @@ export async function revParse(ref) {
   return runGit(["rev-parse", ref]);
 }
 
+/**
+ * List commits in the range `fromSha..toRef`. Used by the post-loop
+ * journal builder to enumerate every commit produced during a `kj run`
+ * — both the coder's own commits AND the post-loop scaffold commit —
+ * so the user-visible summary doesn't lose track of them. Pre-fix the
+ * summary only listed `gitResult.commits` (post-loop only), which made
+ * `kj run "..."` runs look like the coder hadn't committed.
+ *
+ * Returns oldest-first so the list reads in execution order.
+ *
+ * @param {string|null|undefined} fromSha The SHA right BEFORE the run started
+ *   (typically `session.session_start_sha`). Empty/missing → returns [].
+ * @param {string} [toRef="HEAD"]
+ * @returns {Promise<Array<{hash: string, message: string}>>}
+ */
+/**
+ * List the file paths changed in the range `fromSha..toRef`. Used by the
+ * plan-adherence metric (KJC-TSK-0376) to score whether the coder's
+ * file changes fall within any HU's declared scope.
+ *
+ * Returns a deduplicated array of file paths, oldest commit's files
+ * first. Defensive: returns [] on missing `fromSha`, non-zero git exit,
+ * or thrown error — consistent with `listCommitsBetween`'s contract.
+ *
+ * @param {string|null|undefined} fromSha
+ * @param {string} [toRef="HEAD"]
+ * @returns {Promise<string[]>}
+ */
+export async function listFilesChangedSince(fromSha, toRef = "HEAD") {
+  if (!fromSha) return [];
+  const result = await run(
+    "git",
+    ["diff", "--name-only", `${fromSha}..${toRef}`],
+  ).catch(() => null);
+  if (!result || result.exitCode !== 0) return [];
+  const lines = String(result.stdout || "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+  return Array.from(new Set(lines));
+}
+
+export async function listCommitsBetween(fromSha, toRef = "HEAD") {
+  if (!fromSha) return [];
+  const result = await run(
+    "git",
+    ["log", "--reverse", "--format=%H%x09%s", `${fromSha}..${toRef}`],
+  ).catch(() => null);
+  if (!result || result.exitCode !== 0) return [];
+  return String(result.stdout || "")
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter(Boolean)
+    .map((line) => {
+      const tabIdx = line.indexOf("\t");
+      // Defensive: if git emitted no tab (shouldn't happen with our format)
+      // treat the whole line as the hash and leave the message empty rather
+      // than throw — caller can still render the row.
+      if (tabIdx === -1) return { hash: line, message: "" };
+      return { hash: line.slice(0, tabIdx), message: line.slice(tabIdx + 1) };
+    });
+}
+
 export async function syncBaseBranch({ baseBranch, autoRebase }) {
   const local = await revParse(baseBranch);
   const remote = await revParse(`origin/${baseBranch}`);
@@ -109,11 +172,79 @@ export async function hasChanges() {
   return status.length > 0;
 }
 
+/**
+ * Return the relative paths of every uncommitted change (modified,
+ * untracked, staged, etc.) in the working tree. Each path is the
+ * filename as `git status --porcelain` reports it (after the 2-char
+ * status code + space). Returns an empty array when the tree is clean.
+ *
+ * Used by `finalizeGitAutomation` to decide whether the changes
+ * pending at the end of a pipeline are exclusively Karajan
+ * scaffolding (and thus deserve a `chore:` commit message instead
+ * of inheriting the user task's `feat:`).
+ *
+ * NOTE: bypasses `runGit()` because that helper trims stdout, which
+ * eats the leading space of porcelain lines whose first status char
+ * is " " (e.g. " M .gitignore" → "M .gitignore"). The leading space
+ * is structural here — without it the slice(3) below would crop one
+ * character off the first path.
+ */
+export async function listPendingPaths() {
+  const res = await run("git", ["status", "--porcelain"]);
+  if (res.exitCode !== 0) {
+    throw new Error(`git status --porcelain failed: ${res.stderr || res.stdout}`);
+  }
+  const stdout = res.stdout;
+  if (!stdout) return [];
+  const lines = stdout.split("\n").map((l) => l.replace(/\r$/, "")).filter(Boolean);
+  const out = [];
+  for (const line of lines) {
+    // Each line is "XY <path>" (XY = 2-char status, space, path).
+    // Renames look like "R  old -> new"; we want the new path.
+    const after = line.slice(3);
+    const arrow = after.indexOf(" -> ");
+    out.push(arrow !== -1 ? after.slice(arrow + 4) : after);
+  }
+  return out;
+}
+
+// Locale-tolerant detection of "git commit refused because the working
+// tree was already clean by the time we ran it". Observed in N4
+// dogfooding (2026-05-07) — `hasChanges()` reported true after `add -A`
+// but `git commit` then failed with the Spanish message "nada para hacer
+// commit, el árbol de trabajo está limpio". The race window is real:
+// post-loop journal writes can finish between hasChanges and commit, and
+// some files come back from `add -A` with no diff vs HEAD even though
+// they show up in `git status --porcelain`. We treat any of those as
+// "no commit needed" rather than escalating to Solomon.
+const NOTHING_TO_COMMIT_PATTERNS = [
+  /nothing to commit/i,
+  /nada para hacer commit/i,         // git in es_ES locale
+  /no hay nada para confirmar/i,     // git in es_ES alt phrasing
+  /aucune modification ajout[ée]e au commit/i, // fr_FR
+  /nichts zu committen/i,            // de_DE
+];
+function isNothingToCommit(message) {
+  const m = String(message || "");
+  return NOTHING_TO_COMMIT_PATTERNS.some((re) => re.test(m));
+}
+
 export async function commitAll(message) {
   await runGit(["add", "-A"]);
   const changed = await hasChanges();
   if (!changed) return { committed: false };
-  await runGit(["commit", "-m", message]);
+  try {
+    await runGit(["commit", "-m", message]);
+  } catch (err) {
+    // `git status --porcelain` and `git commit` disagreed about whether
+    // there was anything to commit. Don't escalate — the only outcome
+    // either way is "no new commit was created", which the caller
+    // already handles via committed=false.
+    if (isNothingToCommit(err?.message)) {
+      return { committed: false };
+    }
+    throw err;
+  }
   const raw = await runGit(["log", "-1", "--pretty=format:%H%x1f%s"]);
   const [hash, commitMessage] = raw.split("\x1f");
   return { committed: true, commit: { hash, message: commitMessage } };

package/templates/roles/architect/anthropic.md

@@ -63,3 +63,12 @@ Return a single valid JSON object and nothing else.
 
 If the architecture is fully defined, `verdict: "ready"` and `questions: []`.
 </output_format>
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/architect/default.md

@@ -61,3 +61,12 @@ If the architecture is fully defined with no open questions, return `verdict: "r
 - Document WHY each pattern was chosen, not just WHAT
 - If research context is provided, use it to inform architectural decisions
 - Never invent requirements — if something is unclear, add it to questions
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/architect/google.md

@@ -50,3 +50,12 @@ Questions MUST include which isolation level (shared DB + tenant_id column vs sc
 ## Output (strict JSON)
 
 Same shape as Example 1. Exactly one top-level object. No prose around it.
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/architect/openai.md

@@ -49,3 +49,12 @@ You are the Architect. Design the technical architecture BEFORE implementation.
 ```
 
 If fully defined → `verdict: "ready"` and `questions: []`.
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/architect/opencode.md

@@ -48,3 +48,12 @@ Rules for the JSON:
 - Exact keys only. No extras.
 - All arrays may be empty but never null.
 - If `verdict` is "needs_clarification", `questions` must be non-empty.
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/architect.md

@@ -61,3 +61,12 @@ If the architecture is fully defined with no open questions, return `verdict: "r
 - Document WHY each pattern was chosen, not just WHAT
 - If research context is provided, use it to inform architectural decisions
 - Never invent requirements — if something is unclear, add it to questions
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/coder/anthropic.md

@@ -70,3 +70,12 @@ Return a single JSON object matching this schema:
 }
 ```
 </output_format>
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/coder/default.md

@@ -67,3 +67,12 @@ Return a JSON object:
   "summary": "Human-readable summary of changes"
 }
 ```
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/coder/google.md

@@ -76,3 +76,12 @@ An incomplete implementation is worse than an error — don't claim success if p
   "summary": "Human-readable summary of changes"
 }
 ```
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/coder/openai.md

@@ -57,3 +57,12 @@ Return JSON:
   "summary": "Human-readable summary of changes"
 }
 ```
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/coder/opencode.md

@@ -47,3 +47,12 @@ Rules for the JSON:
 - `approach` is one short sentence.
 - `summary` is one short sentence.
 - No extra keys. No text before or after the JSON.
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/coder.md

@@ -12,6 +12,15 @@ You are the **Coder** in a multi-role AI pipeline. Your job is to write code and
 - Before creating a new utility or helper, check if a similar one already exists in the codebase. Reuse existing code over creating duplicates.
 - Follow existing code conventions and patterns in the repository.
 
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan before writing:
+
+- Stay under **~150 LOC per iteration** (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- If the task clearly requires >150 LOC, STOP and report the partition needed. Don't ship a 500-LOC PR — the gate rejects it and the work is redone, burning tokens twice.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+
 ## Task completeness
 
 Before reporting done, verify that ALL parts of the task are addressed:

package/templates/roles/planner/anthropic.md

@@ -48,3 +48,12 @@ Any of:
 }
 ```
 </output_format>
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/planner/default.md

@@ -46,3 +46,12 @@ You are the **Planner** in a multi-role AI pipeline. Your job is to create an im
   "summary": "Plan: 4 steps, estimated 2 files modified, 1 new file"
 }
 ```
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/planner/google.md

@@ -64,3 +64,12 @@ Approach must cite concurrency model, queue semantics, shutdown. Steps include i
   "summary": "Plan: N steps, M files modified, K new files"
 }
 ```
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/planner/openai.md

@@ -44,3 +44,12 @@ You are the Planner. Produce an implementation plan for the task.
   "summary": "Plan: 4 steps, estimated 2 files modified, 1 new file"
 }
 ```
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/planner/opencode.md

@@ -51,3 +51,12 @@ Rules for the JSON:
 - Exact keys only. No extras.
 - `order` is a positive integer.
 - Arrays may be empty but never null.
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/planner.md

@@ -46,3 +46,12 @@ You are the **Planner** in a multi-role AI pipeline. Your job is to create an im
   "summary": "Plan: 4 steps, estimated 2 files modified, 1 new file"
 }
 ```
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/refactorer.md

@@ -37,3 +37,12 @@ You are the **Refactorer** in a multi-role AI pipeline. Your job is to improve c
   "summary": "Refactored 2 files: extracted helper, improved naming"
 }
 ```
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/repairer.md

@@ -92,3 +92,12 @@ Return ONLY a single valid JSON object:
   defines the contract; the code is what's measured against it.
 - Keep changes minimal. One bug at a time. If the test has multiple
   problems, fix the most blocking one first.
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.

package/templates/roles/tester.md

@@ -39,3 +39,12 @@ You are the **Tester** in a multi-role AI pipeline. You are a quality gate for t
   "summary": "Tests pass with 85% coverage. 1 missing scenario identified (non-blocking)."
 }
 ```
+
+## PR atomicity (hard project rule)
+
+Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan your work to stay atomic:
+
+- Aim for **~150 LOC** of changes per unit you produce (safety margin against the 200 hard limit).
+- The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
+- Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
+- Token-economy: oversized PRs get rejected at CI and the work is redone — partitioning upfront saves the round-trip.