@sabaiway/agent-workflow-kit 5.4.0 → 5.6.0

package/tools/source-size-config.mjs

@@ -0,0 +1,244 @@
+// source-size-config.mjs — the practice's declaration: what docs/ai/source-size.json may say, which
+// of its four states it is in, and how it is read back. Nothing here touches the tree.
+//
+//   • CONFIG STATES — ABSENT (no entry at the path) / AUTHORED (authored keys, machine keys absent) /
+//     INCOMPLETE (one machine key without the other — a hand-edited half, which routes to the mint
+//     lane) / MINTED (both machine keys). A malformed or unknown-keyed config is a loud STOP
+//     (exit 2), never a guess, and the template placeholders are REFUSED until replaced, so a
+//     printed authoring template can never be pasted into an empty-green scope.
+//   • A RECORDED size is debt, not permission: every entry carries a reason, and the reason lands
+//     verbatim in the JSON, the commit message and the release CHANGELOG — so it is validated as the
+//     single line those three surfaces can carry.
+//
+// Dependency-free, Node >= 22. No side effects on import.
+
+import { readFileSync, lstatSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { SOURCE_SIZE_CONFIG_REL, configFail, configPathFor, isLineUnsafe } from './source-size-refusal.mjs';
+
+export const SOURCE_SIZE_SCHEMA = 1;
+export const SOURCE_SIZE_DEFAULTS = Object.freeze({ maxLines: 400, maxLineBytes: 1000 });
+export const REASON_MAX_BYTES = 300;
+// The reason a FIRST mint records: every value is new, so every value is a raise, and "this is what
+// the tree already carried when the practice arrived" is the honest sentence for all of them.
+export const INITIAL_ADOPTION_REASON = 'initial adoption';
+
+export const AUTHORED_KEYS = Object.freeze(['_README', 'schema', 'defaults', 'roots', 'exclude', 'extensions']);
+export const MACHINE_KEYS = Object.freeze(['baseline', 'aggregate']);
+const ENTRY_KEYS = Object.freeze(['lines', 'maxLineBytes', 'reason']);
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+// A template placeholder — the authoring refusal prints angle-bracketed values on purpose so the
+// printed file is INERT until a human replaces them; the validator is what makes that promise true.
+const PLACEHOLDER_RE = /^<.*>$/;
+const BAD_SEGMENTS = new Set(['', '.', '..']);
+
+const declaredPathDefect = (value, what) => {
+  if (typeof value !== 'string' || value.length === 0) return `${what} must be a non-empty string`;
+  if (PLACEHOLDER_RE.test(value)) {
+    return `${what} still carries the authoring placeholder ${value} — replace it with a real value; the practice never guesses its own scope`;
+  }
+  if (isAbsolute(value) || value.startsWith('/')) return `${what} "${value}" must be repo-relative, never absolute`;
+  if (value.split('/').some((s) => BAD_SEGMENTS.has(s))) return `${what} "${value}" must carry no empty, "." or ".." path segment`;
+  return null;
+};
+
+const extensionDefect = (value) => {
+  if (typeof value !== 'string' || value.length === 0) return 'an "extensions" entry must be a non-empty string';
+  if (PLACEHOLDER_RE.test(value)) {
+    return `an "extensions" entry still carries the authoring placeholder ${value} — replace it with a real extension; the kit ships NO default file-type list, because a fixed one silently exempts every unlisted language`;
+  }
+  if (!value.startsWith('.') || value.length < 2 || value.includes('/')) {
+    return `an "extensions" entry must look like ".mjs", got ${JSON.stringify(value)}`;
+  }
+  return null;
+};
+
+const positiveIntDefect = (value, what) =>
+  Number.isSafeInteger(value) && value > 0 ? null : `${what} must be a positive integer, got ${JSON.stringify(value)}`;
+
+const nonNegativeIntDefect = (value, what) =>
+  Number.isSafeInteger(value) && value >= 0 ? null : `${what} must be a non-negative integer, got ${JSON.stringify(value)}`;
+
+// A reason lands VERBATIM in the JSON entry, the commit message and the release CHANGELOG, so it is
+// a single line under a byte cap — an empty, multiline or control-byte reason is refused (D-3a). It
+// is the ONE value no escaper may rescue: the three destinations would each need different bytes, so
+// the line-safety boundary refuses it at the door instead of rendering it safely.
+export const reasonDefect = (reason) => {
+  if (typeof reason !== 'string' || reason.length === 0) return 'a reason must be a non-empty string';
+  if (isLineUnsafe(reason)) {
+    return 'a reason must be ONE line with no control bytes (it is copied verbatim into JSON, the commit message and the CHANGELOG)';
+  }
+  const bytes = Buffer.byteLength(reason, 'utf8');
+  if (bytes > REASON_MAX_BYTES) return `a reason must be at most ${REASON_MAX_BYTES} UTF-8 bytes, got ${bytes}`;
+  return null;
+};
+
+// Whole-segment prefix containment: "a/b" contains "a/b" and "a/b/c", never "a/bc".
+export const segmentPrefixOf = (prefix, path) => path === prefix || path.startsWith(`${prefix}/`);
+
+// practiceFacts(config) → the numbers every surface that SPEAKS for the practice states: the caps,
+// how much is declared, and how much is recorded. Derived in ONE place so the plan-time render and
+// the checker's own green line can never state two different counts of the same tree.
+// `recordedFiles` / `aggregateLines` are null while that machine half is absent — "not recorded at
+// all" is a different fact from "recorded as zero", and the two states read differently to a human.
+export const practiceFacts = (config) => ({
+  maxLines: config.defaults.maxLines,
+  maxLineBytes: config.defaults.maxLineBytes,
+  roots: config.roots.length,
+  recordedFiles: config.baseline === null ? null : Object.keys(config.baseline).length,
+  aggregateLines: config.aggregate === null
+    ? null
+    : Object.values(config.aggregate).reduce((sum, entry) => sum + entry.lines, 0),
+});
+
+// `requiredDimensions: 'any'` — a per-file record may pin EITHER dimension or both, because only the
+// dimension that actually violated should be recorded: an entry pinning a dimension that was never
+// over the cap makes the ratchet refuse later changes nobody chose. `'lines'` — a root budget has
+// exactly one dimension, so it is required there.
+const validateEntryMap = (map, what, requiredDimensions, extra) => {
+  if (!isPlainObject(map)) throw configFail(`"${what}" must be an object`);
+  for (const [key, entry] of Object.entries(map)) {
+    if (!isPlainObject(entry)) throw configFail(`"${what}"."${key}" must be an object`);
+    const unknown = Object.keys(entry).filter((k) => !ENTRY_KEYS.includes(k));
+    if (unknown.length > 0) throw configFail(`"${what}"."${key}" carries unknown key(s): ${unknown.join(', ')}`);
+    for (const dimension of ['lines', 'maxLineBytes']) {
+      if (!Object.hasOwn(entry, dimension)) continue;
+      const defect = nonNegativeIntDefect(entry[dimension], `"${what}"."${key}".${dimension}`);
+      if (defect) throw configFail(defect);
+    }
+    if (requiredDimensions === 'lines' && !Object.hasOwn(entry, 'lines')) {
+      throw configFail(nonNegativeIntDefect(entry.lines, `"${what}"."${key}".lines`));
+    }
+    if (requiredDimensions === 'any' && !Object.hasOwn(entry, 'lines') && !Object.hasOwn(entry, 'maxLineBytes')) {
+      throw configFail(`"${what}"."${key}" must record at least one of "lines" or "maxLineBytes" — an entry that pins no dimension records nothing`);
+    }
+    const reason = reasonDefect(entry.reason);
+    if (reason) throw configFail(`"${what}"."${key}".reason: ${reason}`);
+    if (extra) extra(key, entry);
+  }
+};
+
+// validateSourceSizeConfig(parsed) → the normalized config. THROWS configFail (exit 2) on anything it
+// cannot judge — an unknown key included, because a typo'd key would otherwise disarm a rule.
+export const validateSourceSizeConfig = (parsed) => {
+  if (!isPlainObject(parsed)) throw configFail(`${SOURCE_SIZE_CONFIG_REL} must contain a JSON object`);
+  const known = new Set([...AUTHORED_KEYS, ...MACHINE_KEYS]);
+  const unknown = Object.keys(parsed).filter((k) => !known.has(k));
+  if (unknown.length > 0) {
+    throw configFail(`${SOURCE_SIZE_CONFIG_REL} carries unknown key(s): ${unknown.join(', ')} — known keys are ${[...known].join(', ')}`);
+  }
+  if (parsed.schema !== SOURCE_SIZE_SCHEMA) {
+    throw configFail(`"schema" must be ${SOURCE_SIZE_SCHEMA}, got ${JSON.stringify(parsed.schema)}`);
+  }
+  if (!isPlainObject(parsed.defaults)) throw configFail('"defaults" must be an object carrying maxLines and maxLineBytes');
+  const unknownDefaults = Object.keys(parsed.defaults).filter((k) => !['maxLines', 'maxLineBytes'].includes(k));
+  if (unknownDefaults.length > 0) throw configFail(`"defaults" carries unknown key(s): ${unknownDefaults.join(', ')}`);
+  for (const key of ['maxLines', 'maxLineBytes']) {
+    const defect = positiveIntDefect(parsed.defaults[key], `"defaults".${key}`);
+    if (defect) throw configFail(defect);
+  }
+  for (const key of ['roots', 'extensions']) {
+    if (!Array.isArray(parsed[key]) || parsed[key].length === 0) {
+      throw configFail(`"${key}" must be a non-empty array — scope is DECLARED, never guessed, so an empty "${key}" is a misdeclaration rather than an empty green`);
+    }
+    for (const value of parsed[key]) {
+      const defect = key === 'roots' ? declaredPathDefect(value, 'a "roots" entry') : extensionDefect(value);
+      if (defect) throw configFail(defect);
+    }
+  }
+  // A root declared twice is not "overlapping itself" by the rule below (the rule compares distinct
+  // values), yet it double-counts everywhere a root is ITERATED rather than keyed — the printed
+  // delta most visibly, which is the durable record of a regeneration.
+  const declaredRoots = new Set();
+  for (const root of parsed.roots) {
+    if (declaredRoots.has(root)) throw configFail(`"roots" declares "${root}" twice — a duplicated root double-counts its files wherever roots are iterated`);
+    declaredRoots.add(root);
+  }
+  for (const outer of parsed.roots) {
+    for (const inner of parsed.roots) {
+      if (outer !== inner && segmentPrefixOf(outer, inner)) {
+        throw configFail(`"roots" entries overlap: "${inner}" sits inside "${outer}" — an overlapping root double-counts its files in the aggregate`);
+      }
+    }
+  }
+  if (Object.hasOwn(parsed, 'exclude')) {
+    if (!Array.isArray(parsed.exclude)) throw configFail('"exclude" must be an array of literal path prefixes');
+    for (const value of parsed.exclude) {
+      const defect = declaredPathDefect(value, 'an "exclude" entry');
+      if (defect) throw configFail(defect);
+    }
+  }
+  if (Object.hasOwn(parsed, 'baseline')) {
+    validateEntryMap(parsed.baseline, 'baseline', 'any', (key) => {
+      const defect = declaredPathDefect(key, 'a "baseline" key');
+      if (defect) throw configFail(defect);
+    });
+  }
+  if (Object.hasOwn(parsed, 'aggregate')) {
+    validateEntryMap(parsed.aggregate, 'aggregate', 'lines', (key, entry) => {
+      if (Object.hasOwn(entry, 'maxLineBytes')) {
+        throw configFail(`"aggregate"."${key}" carries maxLineBytes — the aggregate budgets LINES only; summing per-file longest-line bytes has no meaning as a budget`);
+      }
+    });
+  }
+  return {
+    schema: parsed.schema,
+    defaults: { ...parsed.defaults },
+    roots: [...parsed.roots],
+    exclude: Object.hasOwn(parsed, 'exclude') ? [...parsed.exclude] : [],
+    extensions: [...parsed.extensions],
+    baseline: Object.hasOwn(parsed, 'baseline') ? { ...parsed.baseline } : null,
+    aggregate: Object.hasOwn(parsed, 'aggregate') ? { ...parsed.aggregate } : null,
+  };
+};
+
+// loadSourceSizeConfig(cwd) → { state, path, config, parsed, text, missingMachineKeys }. The states:
+// ABSENT (no file) / AUTHORED (no machine key) / INCOMPLETE (one machine key without the other — a
+// hand-edited half) / MINTED (both). `config` is null only in the ABSENT state; every other state
+// carries a fully validated config, INCOMPLETE included: the key that IS there is judged by the same
+// rules as ever. `parsed` and `text` are the file as written — the writer copies the authored VALUES
+// (and their order) from `parsed`, and compares its own bytes against `text` to know whether it
+// actually changed anything.
+export const loadSourceSizeConfig = (cwd, deps = {}) => {
+  const read = deps.readFile ?? readFileSync;
+  const lstat = deps.lstat ?? lstatSync;
+  const path = configPathFor(cwd);
+  // ABSENT means no ENTRY at the path, which only an lstat can answer: reading through a DANGLING
+  // SYMLINK fails with the same code as a missing file, and calling that "absent" would tell the
+  // reader to author a file the path already holds — through the very link that is broken. The
+  // sibling loaders draw the line here for the same reason (orchestration-config.mjs:262-273).
+  try {
+    lstat(path);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { state: 'absent', path, config: null };
+    throw configFail(`${path} could not be read (${err.message})`);
+  }
+  let raw;
+  try {
+    raw = read(path, 'utf8');
+  } catch (err) {
+    throw configFail(`${path} could not be read (${err.message})`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw configFail(`${path} is not valid JSON (${err.message}) — fix it by hand; a malformed config is a STOP, never a guess`);
+  }
+  const config = validateSourceSizeConfig(parsed);
+  const present = MACHINE_KEYS.filter((key) => Object.hasOwn(parsed, key));
+  // MINTED means the WHOLE machine half. A file carrying one machine key without the other is a
+  // state no regenerator produces — it was hand-edited into it — so it is INCOMPLETE and routes to
+  // the mint lane, which writes both. Refusing it as a config error would deadlock the only
+  // self-service lane, because the regenerator reads its config through this very function.
+  const state = present.length === MACHINE_KEYS.length ? 'minted' : present.length === 0 ? 'authored' : 'incomplete';
+  return {
+    state,
+    path,
+    config,
+    parsed,
+    text: raw,
+    missingMachineKeys: MACHINE_KEYS.filter((key) => !present.includes(key)),
+  };
+};

package/tools/source-size-core.mjs

@@ -0,0 +1,53 @@
+// source-size-core.mjs — the PURE READ core of the source-size practice (D-18): the ONE import point
+// for every surface that must ask about the practice without reaching a writer. It owns no logic and
+// no write API, and spawns only a read-only git query, so the read-graph purity suite
+// (test/read-graph-purity.test.mjs) stays true however the halves behind it move.
+//
+// The halves, each holding ONE rule set and each within the cap this practice declares:
+//   • source-size-refusal.mjs  — the two exit classes, and the absolute config path every refusal names
+//   • source-size-config.mjs   — the config file: its grammar, its four states, its reader
+//   • source-size-scope.mjs    — which files are judged (D-6) and how big each one is (D-7)
+//   • source-size-gate-cmd.mjs — whether a declared gate cmd IS this checker (the canonical matcher)
+//
+// Re-export only: a consumer imports the practice, never a particular half, so a later split moves
+// code without touching a single call site.
+
+export {
+  SOURCE_SIZE_CONFIG_REL,
+  SOURCE_SIZE_STOP,
+  SOURCE_SIZE_WHY,
+  configFail,
+  configPathFor,
+  escapeForLine,
+  isLineUnsafe,
+  jsonForLine,
+  scopeFail,
+} from './source-size-refusal.mjs';
+
+export {
+  AUTHORED_KEYS,
+  INITIAL_ADOPTION_REASON,
+  MACHINE_KEYS,
+  REASON_MAX_BYTES,
+  SOURCE_SIZE_DEFAULTS,
+  SOURCE_SIZE_SCHEMA,
+  loadSourceSizeConfig,
+  practiceFacts,
+  reasonDefect,
+  segmentPrefixOf,
+  validateSourceSizeConfig,
+} from './source-size-config.mjs';
+
+export {
+  countBytes,
+  enumerateIndex,
+  measureFile,
+  resolveScope,
+} from './source-size-scope.mjs';
+
+export {
+  SOURCE_SIZE_GATE_ID,
+  SOURCE_SIZE_TOOL_PATH,
+  dqUnsafePath,
+  matchesSourceSizeGate,
+} from './source-size-gate-cmd.mjs';

package/tools/source-size-gate-cmd.mjs

@@ -0,0 +1,55 @@
+// source-size-gate-cmd.mjs — whether a declared gate cmd IS this checker. Mirrors the SHAPE of the
+// review-dependent matcher (gates-declaration.mjs) without joining either of its arrays: this gate is
+// neither a final core check nor review-dependent.
+//
+// Dependency-free, Node >= 22. No side effects on import.
+
+import { realpathSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// STRICT full command — `node` + ONE (quoted or bare) path token + the exact basename + ` --check` +
+// END — and the token must realpath-resolve to THIS kit's own checker, so an id squatter never
+// matches.
+//
+// Separators are PLAIN SPACES, not \s: a newline between the tokens is not a command a runner would
+// execute as written. The token is screened by the rules of the quoting it actually carries, because
+// the two halves are interpreted differently and a single screen would be wrong for one of them:
+//   • QUOTED — double quotes survive most bytes, so only what breaks OUT of them is refused.
+//   • BARE   — anything the shell may split, expand or glob makes the executed command different
+//              from the string, so a bare token is admitted only from a known-safe alphabet.
+// Either way the point is the same: a path that resolves literally here while the shell would read
+// it differently must never be called canonical, or the matcher certifies a command that never runs.
+export const dqUnsafePath = (text) => [...text].some((ch) => {
+  const code = ch.codePointAt(0);
+  return ch === '"' || ch === '$' || code === 96 || code === 92 || code === 13 || code === 10;
+});
+
+// Stated as the bytes the shell ACTS on, not as an alphabet of blessed ones: an allow-list refuses
+// perfectly ordinary paths (`@`, `+`, `,`, `%`, `=`, anything non-ASCII) that the shell passes
+// through verbatim, and refusing a command that really is canonical is its own defect. Whitespace
+// and ASCII control bytes are refused too — a bare token cannot contain them and still be one token.
+const SHELL_ACTIVE_BARE = new Set([...'"\'\\$|&;<>(){}[]*?!#~^`']);
+const bareTokenSafe = (text) => text.length > 0 && ![...text].some((ch) => {
+  const code = ch.codePointAt(0);
+  return code <= 0x20 || code === 0x7f || SHELL_ACTIVE_BARE.has(ch);
+});
+
+const CHECK_CMD_RE = /^node +(?:"((?:[^"]*[/\\])?source-size-check\.mjs)"|((?:[^\s"]*[/\\])?source-size-check\.mjs)) +--check$/;
+export const SOURCE_SIZE_GATE_ID = 'source-size';
+export const SOURCE_SIZE_TOOL_PATH = fileURLToPath(new URL('./source-size-check.mjs', import.meta.url));
+
+export const matchesSourceSizeGate = (cmd, projectDir) => {
+  if (typeof cmd !== 'string') return false;
+  const match = CHECK_CMD_RE.exec(cmd.trim());
+  if (!match) return false;
+  const token = match[1] ?? match[2];
+  const admissible = match[1] !== undefined ? !dqUnsafePath(token) : bareTokenSafe(token);
+  if (!admissible) return false;
+  const abs = isAbsolute(token) ? token : join(projectDir, token);
+  try {
+    return realpathSync(abs) === realpathSync(SOURCE_SIZE_TOOL_PATH);
+  } catch {
+    return false; // unresolvable → never canonical (fail closed)
+  }
+};

package/tools/source-size-judge.mjs

@@ -0,0 +1,114 @@
+// source-size-judge.mjs — the verdict as FACTS, never as words, and the ONE projection everything
+// else reads. Measures every in-scope file once, projects the record the regenerator WOULD write for
+// it, and states each difference against what is recorded today. The rendering half turns those
+// differences into words; the writer half turns the very same projection into the file — so the
+// checker can never demand something the regenerator would not do, nor pass a tree the regenerator
+// would rewrite.
+//
+// The ratchet, stated once (D-3, D-4): a recorded size is DEBT, not permission. It may not grow
+// (that is a raise, and a raise is reasoned); it may not sit ABOVE what the tree measures (a stale
+// record is headroom nobody earned); it may not outlive the violation it records (a file back under
+// the cap keeps no record); and a record whose file is gone is an error, because that is what makes
+// a split or a rename visible instead of silent. The per-root budget rides the same rules over the
+// summed LINES of the root — splitting one file into six buys no headroom at all.
+//
+// Dependency-free, Node >= 22. No writes, no side effects on import.
+
+import { measureFile, resolveScope } from './source-size-scope.mjs';
+
+export const DIMENSIONS = Object.freeze(['lines', 'maxLineBytes']);
+
+// The measured dimension names ARE the baseline-entry keys; `defaults` spells the line cap
+// differently, so the two vocabularies are bridged in exactly one place.
+export const DEFAULT_KEY = Object.freeze({ lines: 'maxLines', maxLineBytes: 'maxLineBytes' });
+
+// THE projection: a record exists for a dimension exactly while that dimension violates the declared
+// default. An entry pinning a dimension that was never over the cap would make the ratchet refuse
+// later changes nobody chose, so the entry appears with the violation and disappears with it.
+export const recordFor = (measured, defaults) => Object.fromEntries(
+  DIMENSIONS.filter((dimension) => measured[dimension] > defaults[DEFAULT_KEY[dimension]])
+    .map((dimension) => [dimension, measured[dimension]]),
+);
+
+// A change is a RAISE when it puts a number where there was none, or a bigger one where there was a
+// smaller — the whole class a human's reason is required for. Everything else lowers or removes.
+export const isRaise = ({ from, to }) => to !== null && (from === null || to > from);
+
+// A recorded entry is read by OWN key only. A declared root may legitimately be named like an
+// Object.prototype member ("constructor", "toString"), and a plain lookup would then answer with an
+// INHERITED value — which reads as "already recorded", so the raise goes unnoticed and the entry is
+// written with no reason at all, producing a config this tool's own validator refuses.
+export const ownEntry = (map, key) => (Object.hasOwn(map, key) ? map[key] : undefined);
+
+// changesFor(target, projected, recorded) → the per-dimension old→new pairs that actually differ.
+// The refusal, the printed delta and the reason an entry ends up with all read THIS.
+export const changesFor = (target, projected, recorded) => DIMENSIONS
+  .map((dimension) => ({
+    target,
+    dimension,
+    from: recorded && Object.hasOwn(recorded, dimension) ? recorded[dimension] : null,
+    to: Object.hasOwn(projected, dimension) ? projected[dimension] : null,
+  }))
+  .filter(({ from, to }) => from !== to);
+
+const GROWTH_KINDS = new Set(['over-default', 'grew', 'aggregate-grew', 'aggregate-unrecorded']);
+
+// D-9: the unmechanizable question — real decomposition, or the same coupling spread thinner? — is
+// asked exactly where a record went DOWN or disappeared, and the checker itself raises it there.
+const LOWERED_KINDS = new Set(['stale', 'record-obsolete', 'entry-gone']);
+
+export const hasGrowth = (findings) => findings.some((f) => GROWTH_KINDS.has(f.kind));
+export const hasLoweredRecord = (findings) => findings.some((f) => LOWERED_KINDS.has(f.kind));
+
+const findingOfChange = (rel, { dimension, from, to }, measured, defaults) => {
+  const allowed = defaults[DEFAULT_KEY[dimension]];
+  if (from === null) return { kind: 'over-default', rel, dimension, actual: to, allowed };
+  // `to === null` — the file is back under the cap, so the projection records nothing. The measured
+  // value is what the reader needs to see; the record is simply obsolete.
+  if (to === null) return { kind: 'record-obsolete', rel, dimension, actual: measured[dimension], allowed, recorded: from };
+  return to > from
+    ? { kind: 'grew', rel, dimension, actual: to, recorded: from }
+    : { kind: 'stale', rel, dimension, actual: to, recorded: from };
+};
+
+const judgeAggregate = (rootLines, aggregate) => {
+  const findings = [];
+  for (const [root, actual] of rootLines) {
+    if (!Object.hasOwn(aggregate, root)) {
+      findings.push({ kind: 'aggregate-unrecorded', root, actual });
+      continue;
+    }
+    const value = aggregate[root].lines;
+    if (actual > value) findings.push({ kind: 'aggregate-grew', root, actual, recorded: value });
+    else if (actual < value) findings.push({ kind: 'aggregate-stale', root, actual, recorded: value });
+  }
+  // The recorded set must MIRROR the declared roots: a budget nobody declares any more is a leftover
+  // that hides its own root's disappearance, and deleting an entry must never be a way to disarm it.
+  for (const root of Object.keys(aggregate)) {
+    if (!rootLines.has(root)) findings.push({ kind: 'aggregate-root-gone', root, recorded: aggregate[root].lines });
+  }
+  return findings;
+};
+
+// judgeTree(cwd, config) → { scope, measured, projected, rootLines, findings }. EVERY in-scope file
+// is measured, recorded or not: the fail-closed scope rule has no baseline exception, so an
+// unreadable or non-UTF-8 file refuses even when its size is recorded debt.
+export const judgeTree = (cwd, config, deps = {}) => {
+  const scope = resolveScope(cwd, config, deps);
+  const measured = new Map(scope.files.map((rel) => [rel, measureFile(cwd, rel, deps)]));
+  const projected = new Map(scope.files.map((rel) => [rel, recordFor(measured.get(rel), config.defaults)]));
+  const baseline = config.baseline ?? {};
+  const findings = [];
+  for (const rel of scope.files) {
+    findings.push(...changesFor(rel, projected.get(rel), ownEntry(baseline, rel))
+      .map((change) => findingOfChange(rel, change, measured.get(rel), config.defaults)));
+  }
+  for (const rel of Object.keys(baseline)) {
+    if (!measured.has(rel)) findings.push({ kind: 'entry-gone', rel, recorded: baseline[rel] });
+  }
+  const rootLines = new Map(
+    [...scope.perRoot].map(([root, files]) => [root, files.reduce((sum, rel) => sum + measured.get(rel).lines, 0)]),
+  );
+  findings.push(...judgeAggregate(rootLines, config.aggregate ?? {}));
+  return { scope, measured, projected, rootLines, findings };
+};

package/tools/source-size-refusal.mjs

@@ -0,0 +1,70 @@
+// source-size-refusal.mjs — how the source-size practice STOPS, and what every stop must name. The
+// leaf every other half reads, so a refusal raised deep in the scope walk carries the same contract
+// as one raised by the config reader:
+//   • exit 2 — the INPUTS are unusable (usage, a malformed config, a failed enumeration); the
+//     practice could not judge anything, and no step it could name would change that.
+//   • exit 1 — the practice REFUSED: a violation, a stale record, an unverifiable in-scope source
+//     file, or a declared state the reader must move on (an absent or unminted config). Every one of
+//     these carries a step the reader can perform.
+//   • every refusal names the config of the project it ACTUALLY judged, absolute: under a foreign or
+//     relative --cwd a repo-relative name points at whatever directory the reader happens to be in.
+//   • the WHY rides the RENDERED refusals only — the ones the report composes (absent / unminted /
+//     check-FAIL / reason-required). The thrown exit-1 scope refusals (an unverifiable in-scope
+//     source file, a non-UTF-8 path, an unmerged index, an empty declared scope) and the exit-2
+//     config, usage and enumeration errors do NOT carry it: a sentence about module size explains
+//     nothing about a tree that could not be judged at all. That same sentence is what every other
+//     surface speaking for the practice quotes (D-17), so it lives here, in the leaf every half
+//     already reads: a practice explained in three slightly different sentences is three practices.
+//
+// Dependency-free, Node >= 22. No side effects on import.
+
+import { resolve } from 'node:path';
+
+export const SOURCE_SIZE_CONFIG_REL = 'docs/ai/source-size.json';
+
+// Quoted VERBATIM by every surface that explains the practice: the plan-time render, the checker's
+// rendered refusals, the constraints row a grounded review payload carries. The checker's GREEN line
+// states the practice's FACTS instead — caps, recorded count, aggregate — and never this sentence.
+export const SOURCE_SIZE_WHY = 'A module you can hold whole is the unit of review, test pairing and safe edit; the caps turn size drift into recorded, reasoned debt instead of invisible growth.';
+
+export const configPathFor = (cwd) => resolve(cwd, 'docs', 'ai', 'source-size.json');
+
+export const SOURCE_SIZE_STOP = 'SOURCE_SIZE_STOP';
+
+// ── the line-safety boundary ───────────────────────────────────────────────────────
+// ONE definition of what may never reach a rendered line — C0, DEL, C1, the two Unicode line
+// separators, and a LONE surrogate — and every consumer DERIVED from it. The set is stated once
+// because the alternative was demonstrated across review rounds: each surface guarded part of it,
+// and each partial guard read as complete until a different character walked through it.
+//
+// The lone surrogate is here for a reason the others are not: it does not break a line, it breaks
+// IDENTITY. Written as UTF-8 it becomes the replacement character, byte for byte identical to a
+// name that really contains one — so two different names would print the same, which is the exact
+// property the escaping exists to prevent. A valid PAIR is an ordinary character and is untouched.
+//
+// Three consumers, three jobs:
+//   • escapeForLine — a value going into PROSE. Reversible: the backslash is escaped too, so a real
+//     newline and a name that literally spells its escape can never render as the same string.
+//   • jsonForLine   — a value going into the PASTEABLE suggestion, which must stay valid JSON a
+//     human copies back into the config. JSON.stringify already escapes C0, the backslash and lone
+//     surrogates, so only DEL/C1/separators survive it; escaping exactly those cannot double-escape
+//     anything, and the result still JSON.parses back to the original name.
+//   • isLineUnsafe  — the predicate, for the two values no escaper may touch: a reason (copied
+//     VERBATIM into three different files, so it is refused at the door instead — and a
+//     non-well-formed one could not land verbatim anywhere) and a rendered command (escapes would
+//     change the path the shell receives, so the command is withheld).
+const LINE_UNSAFE_CLASS = '\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029';
+const LONE_SURROGATE = '[\\ud800-\\udbff](?![\\udc00-\\udfff])|(?<![\\ud800-\\udbff])[\\udc00-\\udfff]';
+const UNSAFE = new RegExp(`[${LINE_UNSAFE_CLASS}]|${LONE_SURROGATE}`, 'g');
+const ESCAPED = new RegExp(`[\\\\${LINE_UNSAFE_CLASS}]|${LONE_SURROGATE}`, 'g');
+const asEscape = (ch) => `\\u${ch.codePointAt(0).toString(16).padStart(4, '0')}`;
+
+export const isLineUnsafe = (text) => new RegExp(`[${LINE_UNSAFE_CLASS}]|${LONE_SURROGATE}`).test(String(text));
+export const escapeForLine = (text) => String(text).replace(ESCAPED, (ch) => (ch === '\\' ? '\\\\' : asEscape(ch)));
+export const jsonForLine = (value) => JSON.stringify(value).replace(UNSAFE, asEscape);
+
+const stopWith = (exitCode) => (message) =>
+  Object.assign(new Error(`[agent-workflow-kit] ${escapeForLine(message)}`), { code: SOURCE_SIZE_STOP, exitCode });
+
+export const configFail = stopWith(2);
+export const scopeFail = stopWith(1);