karajan-code 2.11.0 → 2.12.0

package/README.md

@@ -23,7 +23,9 @@
 
 ---
 
-> **v2.11.0 released** — Dogfooding pass release. Two-day pass through a 10-level test plan surfaced and fixed a long tail of UX papercuts and three latent bugs that only show up on fresh `/tmp` repos: the `SonarStage` no longer loops on remoteless projects (was burning iterations until `max_iterations`-fallback-approval), the post-loop `commitAll` now tolerates the locale-specific "nothing to commit" race, the HU sub-pipeline branches off `master`/`HEAD` when the configured `main` doesn't exist, and `runFlow` now seals `session.status` at the boundary so `kj status` never shows zombi `running` runs again. Plus `hu-board` gains automatic ephemeral-project cleanup and an in-UI help modal for the five views. 14 PRs (#624–#637), 4452/4452 tests passing. Safe upgrade from 2.10.2.
+> **v2.12.0 released** — Quality-measurement release. Two new features land together: every `kj run` against a known plan now scores how faithfully the coder followed it (deterministic 0–100 **plan adherence** metric, four weighted components, rendered in `summary.md`), and a small **golden-tasks** regression suite (`todo-rest-api`, `npm-package-cli`, `react-counter-component`) catches output-quality drops between Karajan versions before npm publish. Plus the shrink-budget CI gate now exempts human-facing docs from its 200-LOC ceiling while keeping AI-rule files (CLAUDE.md, AGENTS.md, role prompts) capped. 3 PRs for plan adherence (#645–#647), 4 for golden tasks (#648, #650–#652), 1 for the CI policy (#649). 4522/4522 tests passing. Safe upgrade from 2.11.0.
+>
+> **v2.11.0** — Dogfooding pass release. Two-day pass through a 10-level test plan surfaced and fixed a long tail of UX papercuts and three latent bugs that only show up on fresh `/tmp` repos: the `SonarStage` no longer loops on remoteless projects (was burning iterations until `max_iterations`-fallback-approval), the post-loop `commitAll` now tolerates the locale-specific "nothing to commit" race, the HU sub-pipeline branches off `master`/`HEAD` when the configured `main` doesn't exist, and `runFlow` now seals `session.status` at the boundary so `kj status` never shows zombi `running` runs again. Plus `hu-board` gains automatic ephemeral-project cleanup and an in-UI help modal for the five views. 14 PRs (#624–#637), 4452/4452 tests passing. Safe upgrade from 2.10.2.
 >
 > **v2.10.2** — Patch release. `kj init` wizard expanded from 9 prompts to a full setup: per-role provider selection (10 roles, "inherit / pick CLI / disable"), automatic SonarQube token generation via REST API (no more web UI walkthrough), git automation flags (`auto_commit/push/pr`) and HU Board security (bind host + port). +16 new tests. Safe upgrade from 2.10.1.
 >

package/package.json

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

package/src/audit/plan-adherence.js

@@ -0,0 +1,222 @@
+/**
+ * Plan adherence metric — KJC-TSK-0376 (deepeval-inspired).
+ * Pure offline 0-100 score: how faithfully did the coder follow the plan?
+ * Components (weighted): commit_attribution 40%, acceptance_tests 30%,
+ * scope_discipline 20%, dependency_order 10%. Components return null
+ * when no data; aggregator redistributes the weight.
+ * See docs/plan-adherence.md (PR-C) for the full spec.
+ */
+
+const WEIGHTS = {
+  commit_attribution: 40,
+  acceptance_tests: 30,
+  scope_discipline: 20,
+  dependency_order: 10,
+};
+
+/**
+ * Build a regex that matches the HU id anywhere in a commit message
+ * (case-insensitive, word-boundary friendly). The `_` and `-` characters
+ * appear inside HU ids so we anchor on whole-token rather than \b.
+ */
+function huIdMatcher(huId) {
+  const escaped = String(huId).replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
+  return new RegExp(`(^|[^a-z0-9])${escaped}([^a-z0-9]|$)`, "i");
+}
+
+/**
+ * Slugify an HU title for branch-name / scope matching. Mirrors the
+ * `buildHuBranchName` slug rule (lowercase, non-alnum → "-").
+ */
+function slugify(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, "-")
+    .replaceAll(/(^-+)|(-+$)/g, "");
+}
+
+/**
+ * Try to attribute a single commit to one of the plan's HUs.
+ *
+ * Order of evidence, strongest first:
+ *   1. The HU id appears in the commit message.
+ *   2. The HU id appears in the branch name where the commit lives
+ *      (commit.branch is supplied by listCommitsBetween's caller when
+ *      it knows the per-HU branches).
+ *   3. The HU title slug matches the commit message.
+ *
+ * Returns the matched huId, or null when none of the above fires.
+ */
+export function attributeCommitToHu(commit, hus) {
+  if (!commit || !Array.isArray(hus) || hus.length === 0) return null;
+  const msg = String(commit.message || "");
+  const branch = String(commit.branch || "");
+  for (const hu of hus) {
+    if (!hu?.id) continue;
+    const matcher = huIdMatcher(hu.id);
+    if (matcher.test(msg)) return hu.id;
+    if (branch && matcher.test(branch)) return hu.id;
+  }
+  // Fallback: title slug
+  for (const hu of hus) {
+    const slug = slugify(hu.title);
+    if (!slug || slug.length < 6) continue;
+    if (slugify(msg).includes(slug)) return hu.id;
+  }
+  return null;
+}
+
+/**
+ * Component 1: commit attribution. Returns null when the run produced
+ * no commits at all (avoids penalising analysis-only or doc-only runs).
+ */
+export function computeCommitAttribution(commits, plan) {
+  if (!Array.isArray(commits) || commits.length === 0) return null;
+  if (!plan?.hus || plan.hus.length === 0) return null;
+  let attributed = 0;
+  for (const commit of commits) {
+    if (attributeCommitToHu(commit, plan.hus)) attributed += 1;
+  }
+  return Math.round((attributed / commits.length) * 100);
+}
+
+/**
+ * Component 2: acceptance test coverage. Heuristic: each HU declares
+ * `acceptance_tests`. We check whether at least one commit from that
+ * HU's pool has a `test:`-prefixed message. Per-HU score (1 or 0),
+ * averaged across HUs that DO declare tests. Returns null when no HU
+ * declares acceptance tests.
+ */
+export function computeAcceptanceTestCoverage(commits, plan) {
+  if (!plan?.hus || plan.hus.length === 0) return null;
+  if (!Array.isArray(commits) || commits.length === 0) return null;
+  const husWithTests = plan.hus.filter(
+    (hu) => Array.isArray(hu?.acceptance_tests) && hu.acceptance_tests.length > 0,
+  );
+  if (husWithTests.length === 0) return null;
+
+  let covered = 0;
+  for (const hu of husWithTests) {
+    const huCommits = (commits || []).filter(
+      (c) => attributeCommitToHu(c, [hu]) === hu.id,
+    );
+    const hasTestCommit = huCommits.some((c) =>
+      /^test[:(]/i.test(String(c.message || "").trim()),
+    );
+    if (hasTestCommit) covered += 1;
+  }
+  return Math.round((covered / husWithTests.length) * 100);
+}
+
+/**
+ * Component 3: scope discipline. For each file changed by the run, we
+ * try to match it against at least one HU's id slug, title slug, or
+ * `scope` text. A file that matches no HU is flagged as out-of-scope.
+ * Returns null when the run changed no files.
+ */
+export function computeScopeDiscipline(filesChanged, plan) {
+  if (!Array.isArray(filesChanged) || filesChanged.length === 0) return null;
+  if (!plan?.hus || plan.hus.length === 0) return null;
+  const huKeywords = plan.hus.map((hu) => ({
+    id: hu.id,
+    matchers: [
+      slugify(hu.id),
+      slugify(hu.title),
+      // Pull alpha-rich words from `scope` text (length >= 4).
+      ...String(hu.scope || "")
+        .toLowerCase()
+        .split(/[^a-z]+/)
+        .filter((w) => w.length >= 4),
+    ].filter(Boolean),
+  }));
+  let inScope = 0;
+  for (const file of filesChanged) {
+    const slug = slugify(file);
+    const matched = huKeywords.some((hk) =>
+      hk.matchers.some((m) => slug.includes(m) || file.includes(m)),
+    );
+    if (matched) inScope += 1;
+  }
+  return Math.round((inScope / filesChanged.length) * 100);
+}
+
+/**
+ * Component 4: dependency order. For every `(parent, child)` edge
+ * declared via `child.blocked_by`, check that the EARLIEST commit
+ * attributed to `parent` is older than the EARLIEST commit attributed
+ * to `child`. Returns null when no dependency edges exist.
+ *
+ * `commits` are expected oldest-first (the shape `listCommitsBetween`
+ * returns). When that's not the case the score still makes sense — we
+ * just compare relative positions in the array.
+ */
+export function computeDependencyOrder(commits, plan) {
+  if (!plan?.hus || plan.hus.length === 0) return null;
+  const edges = [];
+  for (const hu of plan.hus) {
+    for (const parentId of hu.blocked_by || []) {
+      edges.push([parentId, hu.id]);
+    }
+  }
+  if (edges.length === 0) return null;
+  if (!Array.isArray(commits) || commits.length === 0) return null;
+
+  // Build huId → first commit index (oldest first attribution).
+  const firstIndex = new Map();
+  commits.forEach((commit, idx) => {
+    const huId = attributeCommitToHu(commit, plan.hus);
+    if (huId && !firstIndex.has(huId)) firstIndex.set(huId, idx);
+  });
+
+  let respected = 0;
+  let evaluable = 0;
+  for (const [parentId, childId] of edges) {
+    const p = firstIndex.get(parentId);
+    const c = firstIndex.get(childId);
+    if (p === undefined || c === undefined) continue; // can't evaluate
+    evaluable += 1;
+    if (p < c) respected += 1;
+  }
+  if (evaluable === 0) return null;
+  return Math.round((respected / evaluable) * 100);
+}
+
+/**
+ * Aggregator: compute every component and weight them. Components
+ * that return `null` are excluded and their weight redistributed
+ * proportionally across the rest, so a run that legitimately has no
+ * acceptance tests or no dependencies isn't penalised.
+ *
+ * Returns the full structured result (see file header for shape).
+ */
+export function computePlanAdherenceScore({ commits, plan, filesChanged }) {
+  const breakdown = {
+    commit_attribution: computeCommitAttribution(commits, plan),
+    acceptance_tests: computeAcceptanceTestCoverage(commits, plan),
+    scope_discipline: computeScopeDiscipline(filesChanged, plan),
+    dependency_order: computeDependencyOrder(commits, plan),
+  };
+
+  // Weighted average over non-null components only.
+  let totalWeight = 0;
+  let weightedSum = 0;
+  for (const [key, weight] of Object.entries(WEIGHTS)) {
+    const value = breakdown[key];
+    if (value === null || value === undefined) continue;
+    totalWeight += weight;
+    weightedSum += value * weight;
+  }
+  const score = totalWeight === 0 ? null : Math.round(weightedSum / totalWeight);
+
+  // Per-HU detail: was the HU "touched" (attributed at least one commit)?
+  const hu_scores = (plan?.hus || []).map((hu) => {
+    const huCommits = (commits || []).filter(
+      (c) => attributeCommitToHu(c, [hu]) === hu.id,
+    );
+    const issues = [];
+    if (huCommits.length === 0) issues.push("no commit attributed");
+    return { huId: hu.id, attributed: huCommits.length > 0, issues };
+  });
+
+  return { score, breakdown, hu_scores };
+}

package/src/golden/asserter.js

@@ -0,0 +1,90 @@
+/**
+ * Golden tasks asserter (KJC-TSK-0374). Parses a `summary.md` produced
+ * by a real `kj run` and compares it against a GoldenTask's structural
+ * expectations. Pure: no I/O, no subprocess. Subprocess driver lands
+ * in PR-3a; the 3 fixtures + baseline + spec land in PR-3b.
+ *
+ * Three of the five assertion families live here (the ones derivable
+ * from summary.md alone): expected_commits_min, expected_audit_status,
+ * expected_plan_adherence_min. expected_test_files and
+ * allowed_loc_range need filesystem access — PR-3a wires those.
+ */
+
+const COMMIT_LINE = /^- `([^`]+)`\s+(.*)$/;
+const SCORE_LINE = /^\*\*Score\*\*:\s*(\d+)\s*\/\s*100/m;
+const AUDIT_ROW = /^\|\s*`audit`\s*\|\s*([^|]+?)\s*\|/m;
+
+function extractSection(content, heading) {
+  const re = new RegExp(`^## ${heading}\\s*$([\\s\\S]*?)(?=^## |\\Z)`, "m");
+  const m = content.match(re);
+  return m ? m[1].trim() : "";
+}
+
+function parseCommits(content) {
+  const section = extractSection(content, "Commits");
+  if (!section || /No commits/.test(section)) return [];
+  return section
+    .split("\n")
+    .map((line) => line.match(COMMIT_LINE))
+    .filter(Boolean)
+    .map(([, hash, message]) => ({ hash, message }));
+}
+
+function parseAuditStatus(content) {
+  const m = content.match(AUDIT_ROW);
+  if (!m) return null;
+  const cell = m[1];
+  if (/✅|pass/i.test(cell)) return "pass";
+  if (/❌|fail/i.test(cell)) return "fail";
+  if (/⚠|warn/i.test(cell)) return "warning";
+  return null;
+}
+
+function parsePlanAdherence(content) {
+  const section = extractSection(content, "Plan adherence");
+  if (!section) return null;
+  const m = section.match(SCORE_LINE);
+  if (!m) return null;
+  const score = Number(m[1]);
+  return Number.isFinite(score) ? score : null;
+}
+
+export function parseSummary(content) {
+  const text = String(content || "");
+  return {
+    commits: parseCommits(text),
+    auditStatus: parseAuditStatus(text),
+    planAdherenceScore: parsePlanAdherence(text),
+  };
+}
+
+export function assertFromSummary(task, parsed) {
+  const failures = [];
+
+  const fail = (kind, expected, actual, message) => failures.push({ kind, expected, actual, message });
+
+  if (parsed.commits.length < task.expected_commits_min) {
+    fail("commits_min", `>= ${task.expected_commits_min}`, parsed.commits.length,
+      `expected at least ${task.expected_commits_min} commit(s); got ${parsed.commits.length}`);
+  }
+
+  if (parsed.auditStatus !== task.expected_audit_status) {
+    const got = parsed.auditStatus === null ? "no audit row in summary" : `"${parsed.auditStatus}"`;
+    fail("audit_status", task.expected_audit_status, parsed.auditStatus,
+      `expected audit "${task.expected_audit_status}"; got ${got}`);
+  }
+
+  if (typeof task.expected_plan_adherence_min === "number") {
+    const score = parsed.planAdherenceScore;
+    const min = task.expected_plan_adherence_min;
+    if (score === null) {
+      fail("plan_adherence_missing", `>= ${min}`, null,
+        `expected plan adherence >= ${min}; summary has no Plan adherence section`);
+    } else if (score < min) {
+      fail("plan_adherence_below", `>= ${min}`, score,
+        `expected plan adherence >= ${min}; got ${score}`);
+    }
+  }
+
+  return { ok: failures.length === 0, failures };
+}

package/src/golden/loader.js

@@ -0,0 +1,52 @@
+/**
+ * Golden tasks loader (KJC-TSK-0374). Reads + validates JSON files
+ * under a directory; aggregates errors; rejects duplicate ids.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { safeParseGoldenTask } from "./schema.js";
+
+export async function loadGoldenTasks(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true }).catch((err) => {
+    throw new Error(`golden tasks directory not readable: ${dir} (${err.code || err.message})`);
+  });
+  const jsonFiles = entries
+    .filter((e) => e.isFile() && e.name.endsWith(".json"))
+    .map((e) => path.join(dir, e.name))
+    .sort();
+
+  const tasks = [];
+  const errors = [];
+  const seenIds = new Map();
+
+  for (const filePath of jsonFiles) {
+    let raw;
+    try {
+      const content = await fs.readFile(filePath, "utf8");
+      raw = JSON.parse(content);
+    } catch (err) {
+      errors.push(`${path.basename(filePath)}: invalid JSON (${err.message})`);
+      continue;
+    }
+    const result = safeParseGoldenTask(raw);
+    if (!result.ok) {
+      const summary = result.issues.map((iss) => `  - ${iss.path || "(root)"}: ${iss.message}`).join("\n");
+      errors.push(`${path.basename(filePath)}:\n${summary}`);
+      continue;
+    }
+    const existing = seenIds.get(result.task.id);
+    if (existing) {
+      errors.push(`${path.basename(filePath)}: duplicate id "${result.task.id}" (also in ${existing})`);
+      continue;
+    }
+    seenIds.set(result.task.id, path.basename(filePath));
+    tasks.push(result.task);
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`golden tasks failed validation:\n${errors.join("\n")}`);
+  }
+
+  return { tasks };
+}

package/src/golden/runner.js

@@ -0,0 +1,92 @@
+/**
+ * Golden tasks subprocess runner (KJC-TSK-0374). Spawns `kj run` in
+ * a sandbox dir, reads back summary.md, evaluates the schema's
+ * filesystem-dependent assertions (expected_test_files, allowed_loc_range),
+ * and merges them with `assertFromSummary` into a single result.
+ *
+ * The kj subprocess + diff calls are injected so unit tests can drive
+ * the runner without spawning anything (real e2e is opt-in via PR-3b).
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runCommand as defaultRun } from "../utils/process.js";
+import { parseSummary, assertFromSummary } from "./asserter.js";
+
+async function findLatestSummary(workDir) {
+  const journalRoot = path.join(workDir, ".karajan", "sessions");
+  const sessions = await fs.readdir(journalRoot).catch(() => []);
+  if (sessions.length === 0) return null;
+  const stats = await Promise.all(sessions.map(async (id) => {
+    const file = path.join(journalRoot, id, "summary.md");
+    const stat = await fs.stat(file).catch(() => null);
+    return stat ? { file, mtimeMs: stat.mtimeMs } : null;
+  }));
+  const valid = stats.filter(Boolean).sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return valid[0]?.file ?? null;
+}
+
+async function findMissingTestFiles(workDir, paths) {
+  const checks = await Promise.all(paths.map(async (rel) =>
+    [rel, await fs.stat(path.join(workDir, rel)).then(() => true).catch(() => false)]));
+  return checks.filter(([, ok]) => !ok).map(([rel]) => rel);
+}
+
+async function totalLocSince(workDir, baseSha, run) {
+  const res = await run("git", ["diff", "--numstat", `${baseSha}..HEAD`], { cwd: workDir }).catch(() => null);
+  if (!res || res.exitCode !== 0) return null;
+  return String(res.stdout || "").split("\n").filter(Boolean)
+    .map((l) => l.split("\t")).filter(([a]) => a !== "-")
+    .reduce((sum, [a]) => sum + Number(a || 0), 0);
+}
+
+export async function runGoldenTask(task, opts = {}) {
+  const run = opts.run || defaultRun;
+  const fsApi = opts.fs || fs;
+  const workDir = opts.workDir;
+  if (!workDir) throw new Error("runGoldenTask requires opts.workDir");
+
+  const baseSha = opts.baseSha || null;
+  const kjResult = await run("kj", ["run", task.prompt, "-y"], {
+    cwd: workDir,
+    timeout: (task.timeout_minutes || 30) * 60_000,
+  });
+
+  const summaryPath = opts.summaryPath || await findLatestSummary(workDir);
+  if (!summaryPath) {
+    return { ok: false, kjExit: kjResult?.exitCode ?? -1, failures: [{
+      kind: "no_summary", expected: "summary.md", actual: null,
+      message: "kj run finished without producing a summary.md",
+    }] };
+  }
+  const content = await fsApi.readFile(summaryPath, "utf8");
+  const parsed = parseSummary(content);
+  const summaryAssertion = assertFromSummary(task, parsed);
+
+  const failures = [...summaryAssertion.failures];
+
+  if (Array.isArray(task.expected_test_files) && task.expected_test_files.length > 0) {
+    const missing = await findMissingTestFiles(workDir, task.expected_test_files);
+    if (missing.length > 0) {
+      failures.push({ kind: "test_files_missing", expected: task.expected_test_files, actual: missing,
+        message: `expected test files not produced: ${missing.join(", ")}` });
+    }
+  }
+
+  if (baseSha) {
+    const loc = await totalLocSince(workDir, baseSha, run);
+    const [min, max] = task.allowed_loc_range;
+    if (loc !== null && (loc < min || loc > max)) {
+      failures.push({ kind: "loc_out_of_range", expected: `${min}..${max}`, actual: loc,
+        message: `LOC added (${loc}) is outside the allowed range [${min}, ${max}]` });
+    }
+  }
+
+  return {
+    ok: failures.length === 0,
+    kjExit: kjResult?.exitCode ?? null,
+    summaryPath,
+    parsed,
+    failures,
+  };
+}

package/src/golden/schema.js

@@ -0,0 +1,41 @@
+/**
+ * Golden tasks regression suite — schema (KJC-TSK-0374). Pure data,
+ * no I/O. See docs/golden-tasks.md (PR-3) for the full spec.
+ */
+
+import * as v from "valibot";
+
+const NonEmptyString = v.pipe(v.string(), v.minLength(1));
+const Percent = v.pipe(v.number(), v.minValue(0), v.maxValue(100));
+
+const NonNegInt = v.pipe(v.number(), v.integer(), v.minValue(0));
+const LocRangeSchema = v.pipe(v.array(NonNegInt), v.length(2),
+  v.check((arr) => arr[0] <= arr[1], "allowed_loc_range: min must be <= max"));
+
+export const GoldenTaskSchema = v.looseObject({
+  id: v.pipe(NonEmptyString, v.regex(/^[a-z0-9_-]+$/, "id must be lowercase a-z0-9_-")),
+  title: NonEmptyString,
+  prompt: NonEmptyString,
+  description: v.optional(v.string()),
+  timeout_minutes: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 30),
+  expected_commits_min: NonNegInt,
+  expected_audit_status: v.picklist(["pass", "warning", "fail"]),
+  expected_test_files: v.array(NonEmptyString),
+  allowed_loc_range: LocRangeSchema,
+  expected_plan_adherence_min: v.optional(Percent),
+});
+
+/** @typedef {import("valibot").InferOutput<typeof GoldenTaskSchema>} GoldenTask */
+
+export function parseGoldenTask(raw) {
+  return v.parse(GoldenTaskSchema, raw);
+}
+
+export function safeParseGoldenTask(raw) {
+  const result = v.safeParse(GoldenTaskSchema, raw);
+  if (result.success) return { ok: true, task: result.output };
+  return { ok: false, issues: result.issues.map((iss) => ({
+    path: (iss.path || []).map((p) => p.key).join("."),
+    message: iss.message,
+  })) };
+}

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

@@ -23,7 +23,9 @@
 
 import { generateDiff } from "../../review/diff-generator.js";
 import { finalizeGitAutomation } from "../../git/automation.js";
-import { listCommitsBetween } from "../../utils/git.js";
+import { listCommitsBetween, listFilesChangedSince } from "../../utils/git.js";
+import { loadPlan, projectSlug as slugFor } from "../../plan/plan-store.js";
+import { computePlanAdherenceScore } from "../../audit/plan-adherence.js";
 import { saveSession, markSessionStatus } from "../../session/store.js";
 import {
   setReviewerFeedback, setBudget, setRtkSavings, resetRetryCount,
@@ -166,6 +168,36 @@ export async function finalizeApprovedSession({ config, gitCtx, task, logger, se
       try { allCommits = (await listCommitsBetween(session.head_at_start || session.session_start_sha)) || []; }
       catch { allCommits = gitResult?.commits || []; }
       const summaryCommits = allCommits.length > 0 ? allCommits : (gitResult?.commits || []);
+
+      // KJC-TSK-0376 — plan adherence metric (deepeval-inspired). When the
+      // run executed against a known plan (`kj run --plan <id>`), score how
+      // faithfully the coder followed it. Pure offline; safe-by-default
+      // (try/catch swallows missing helper or unreadable plan).
+      let planAdherence = null;
+      try {
+        const planId = session._planRef?.planId
+          || stageResults?.huReviewer?.planId
+          || null;
+        if (planId) {
+          const projectDir = config?.projectDir
+            || session.config_snapshot?.projectDir
+            || process.cwd();
+          const plan = await loadPlan(projectDir, planId).catch(() => null);
+          if (plan && Array.isArray(plan.hus) && plan.hus.length > 0) {
+            const filesChanged = await listFilesChangedSince(
+              session.head_at_start || session.session_start_sha,
+            ).catch(() => []);
+            planAdherence = computePlanAdherenceScore({
+              commits: summaryCommits,
+              plan,
+              filesChanged,
+            });
+          }
+        }
+      } catch (err) {
+        logger?.warn?.(`Plan adherence calculation skipped: ${err.message}`);
+      }
+
       await writeSummaryJournalV2(journalDir, {
         task: session.task,
         result: "APPROVED",
@@ -188,6 +220,7 @@ export async function finalizeApprovedSession({ config, gitCtx, task, logger, se
           installed: session.autoInstalledSkills,
           recommended: session.skillsRecommended,
         },
+        planAdherence,
       }, { logger });
       logger.info(`Session journal written to ${journalDir}`);
     } catch (err) {
@@ -361,7 +394,6 @@ export async function tryAutoStartBoard(config, logger, emitter, eventBase) {
 
   try {
     const { startBoard, renderBoardBanner } = await import("../../commands/board.js");
-    const { projectSlug: slugFor } = await import("../../plan/plan-store.js");
     const boardPort = config.hu_board.port || 4000;
     // Scope the board URL to the current run's project (`/p/<slug>`) so
     // the user lands on a filtered view, not the global dashboard.

package/src/session/journal/summary-writer.js

@@ -199,11 +199,50 @@ export function buildSummaryMarkdown(input) {
 
   sections.push("", "## Commits", "", renderCommits(input.commits));
 
+  // KJC-TSK-0376 — plan adherence metric (deepeval-inspired). Only
+  // rendered when the run executed against a known plan and the
+  // calculation produced a non-null score (a run with no commits or
+  // no files changed yields nulls everywhere → omit the section).
+  const planAdherenceSection = renderPlanAdherence(input.planAdherence);
+  if (planAdherenceSection) {
+    sections.push("", "## Plan adherence", "", planAdherenceSection);
+  }
+
   sections.push("", "## Journal files", "", renderJournalLinks(input.files));
 
   return sections.join("\n") + "\n";
 }
 
+function renderPlanAdherence(planAdherence) {
+  if (!planAdherence || typeof planAdherence !== "object") return "";
+  if (planAdherence.score === null || planAdherence.score === undefined) return "";
+  const lines = [`**Score**: ${planAdherence.score}/100`, ""];
+  const breakdown = planAdherence.breakdown || {};
+  lines.push("| Component | Score | Weight |");
+  lines.push("| --- | --- | --- |");
+  const rows = [
+    ["Commit attribution", breakdown.commit_attribution, "40%"],
+    ["Acceptance tests",   breakdown.acceptance_tests,   "30%"],
+    ["Scope discipline",   breakdown.scope_discipline,   "20%"],
+    ["Dependency order",   breakdown.dependency_order,   "10%"],
+  ];
+  for (const [label, value, weight] of rows) {
+    const cell = value === null || value === undefined ? "n/a" : `${value}/100`;
+    lines.push(`| ${label} | ${cell} | ${weight} |`);
+  }
+  const huScores = Array.isArray(planAdherence.hu_scores) ? planAdherence.hu_scores : [];
+  if (huScores.length > 0) {
+    const unattributed = huScores.filter((h) => !h.attributed);
+    if (unattributed.length > 0) {
+      lines.push("", `_${unattributed.length} HU(s) without an attributed commit:_`);
+      for (const h of unattributed) {
+        lines.push(`- \`${h.huId}\``);
+      }
+    }
+  }
+  return lines.join("\n");
+}
+
 /**
  * Write summary.md to the given journal directory. Always writes (the file
  * is the entry point; even a barebones session should have one).

package/src/utils/git.js

@@ -80,6 +80,33 @@ export async function revParse(ref) {
  * @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(

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.