@sabaiway/agent-workflow-kit 5.5.0 → 5.6.0

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);

package/tools/source-size-report.mjs

@@ -0,0 +1,254 @@
+// source-size-report.mjs — the words a verdict is delivered in. Every refusal this practice prints
+// must name the file, the actual value, the allowed value AND a step the reader can perform against
+// THIS build — never a bare "too big" and never a command that does not exist yet.
+//
+// Two render contracts, honestly separated (D-3a):
+//   • TIGHTEN — the tree shrank below what is recorded. Shrinking is progress, so the regenerator is
+//     printed EXACTLY as it should be pasted; no reason is needed and none is asked for.
+//   • GROWTH — the regeneration would RAISE a recorded value. The checker cannot invent the human's
+//     reason, so the command is printed as a TEMPLATE carrying the placeholder, and the requirement
+//     is stated rather than implied.
+// The exception both share: on a project path that does not survive double-quoting, NO command is
+// rendered (a rendered one could run somewhere else) — the parameters, the reason requirement and
+// the manual lane are stated instead.
+//
+// The standing echo (D-17 U4) rides the same two renders: a PASS states the practice in one line, so
+// the enforced path itself keeps the caps in front of the reader, and every refusal CLOSES with the
+// canonical WHY sentence — a cap whose reason has to be looked up is a cap that reads as arbitrary.
+//
+// Dependency-free, Node >= 22. No writes, no side effects on import.
+
+import { SOURCE_SIZE_WHY, configPathFor, escapeForLine, isLineUnsafe, jsonForLine } from './source-size-refusal.mjs';
+import { INITIAL_ADOPTION_REASON, SOURCE_SIZE_DEFAULTS, SOURCE_SIZE_SCHEMA, practiceFacts } from './source-size-config.mjs';
+import { SOURCE_SIZE_TOOL_PATH, dqUnsafePath } from './source-size-gate-cmd.mjs';
+import { hasGrowth, hasLoweredRecord, isRaise } from './source-size-judge.mjs';
+
+// The project directory is project-controlled too, so the path every refusal names enters its line
+// escaped like any other such value. configPathFor itself stays literal — it also builds the real
+// filesystem path the writer opens.
+const namedConfig = (cwd) => escapeForLine(configPathFor(cwd));
+
+export const GROWTH_REASON_PLACEHOLDER = '<why this size is accepted>';
+
+// The authoring template (D-5): GENERIC, and INERT by construction — its roots/extensions carry
+// placeholders the validator refuses, so it can never be pasted into an empty-green scope.
+export const authoringTemplate = () => JSON.stringify({
+  _README: 'Source-size practice: declared scope + thresholds + the recorded ratchet. Authored keys: schema, defaults, roots, exclude, extensions. Machine keys: baseline, aggregate — each recorded entry carries a reason, and a recorded size is debt, not permission. Strict JSON — unknown keys refused.',
+  schema: SOURCE_SIZE_SCHEMA,
+  defaults: { ...SOURCE_SIZE_DEFAULTS },
+  roots: ['<a directory this practice covers>'],
+  exclude: [],
+  extensions: ['<.an-extension-this-practice-covers>'],
+}, null, 2);
+
+// A rendered command carries the RESOLVED tool path and an explicit quoted --cwd, so it means the
+// same thing from any directory. It is WITHHELD on either of two grounds, and the render says WHICH
+// one fired: a reader told their path "does not survive double-quoting" when it quotes perfectly
+// goes off to fix the wrong thing. The grounds are made DISJOINT by testing line-safety FIRST — a
+// newline satisfies both, and a path that cannot be printed at all is not a quoting question. The
+// recovery lane is identical either way; only the diagnosis differs.
+const WITHHELD_SHELL = 'source-size: no paste-ready command is printed — this project\'s path does not survive double-quoting, so a rendered command could run somewhere other than the project it names.';
+const WITHHELD_LINE = 'source-size: no paste-ready command is printed — this project\'s path carries a character that cannot appear in a rendered line, and escaping it would change the path the shell receives.';
+// The withheld fallback is the reader's ONLY remaining instruction, so it has to be the instruction
+// for what they were actually doing. Sending an adoption to the regenerator would leave them with a
+// record and no gate — half an adoption, handed over as the way out — so the lane is per MODE.
+const WITHHELD_LANE = 'Run the regenerator yourself with the working directory set to this project (source-size-check.mjs --write-baseline, plus --reason "<text>" for any raise), or record each size by hand below.';
+const WITHHELD_ADOPT_LANE = `Run source-size-check.mjs --adopt --reason "${INITIAL_ADOPTION_REASON}" yourself, with the working directory set to this project — it mints the record and declares the gate in one step.`;
+
+// → { command, withheld }: exactly one of the two is non-null. ONE renderer for every mode this tool
+// prints, so a withhold can never apply to some of its own commands and not others.
+const rendered = (cwd, mode, reason) => {
+  const paths = [SOURCE_SIZE_TOOL_PATH, cwd];
+  if (paths.some(isLineUnsafe)) return { command: null, withheld: WITHHELD_LINE };
+  if (paths.some(dqUnsafePath)) return { command: null, withheld: WITHHELD_SHELL };
+  return { command: `node "${SOURCE_SIZE_TOOL_PATH}" ${mode} --cwd "${cwd}"${reason === undefined ? '' : ` --reason "${reason}"`}`, withheld: null };
+};
+const regenerator = (cwd, reason) => rendered(cwd, '--write-baseline', reason);
+
+const SPLIT_QUALITY_FOCUS = 'source-size: REVIEW FOCUS — a recorded size went DOWN or disappeared: check that this is real decomposition and not the same coupling spread across more files (paste this line into the review dispatch focus).';
+
+// Every refusal THIS module renders closes with the canonical WHY. The two thrown classes do not
+// carry it — the 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: both
+// are about a tree the practice could not judge at all, where a sentence about module size explains
+// nothing.
+const WHY_LINE = `source-size: WHY — ${SOURCE_SIZE_WHY}`;
+const refusal = (lines) => [...lines, WHY_LINE];
+
+// The standing summary (D-17 U4) — one line, from the CONFIG alone. There is no headroom to report:
+// the ratchet refuses actual > recorded and actual < recorded alike, so a recorded aggregate is EXACT
+// by construction, and saying that is the honest form of "how much room is left". Reached only on a
+// MINTED config (a check refuses every other state before it renders anything).
+const practiceLine = (config) => {
+  const facts = practiceFacts(config);
+  return `source-size: practice — caps ${facts.maxLines} lines · ${facts.maxLineBytes} bytes per line over ${facts.roots} declared root(s) · ${facts.recordedFiles} file(s) carry a recorded size (debt, not permission) · aggregate ${facts.aggregateLines} line(s), EXACT: growth takes a reasoned bump, never free headroom.`;
+};
+
+export const absentRefusalLines = (cwd) => refusal([
+  `source-size: REFUSED — ${namedConfig(cwd)} is absent, so the scope of this practice is undeclared.`,
+  'Scope is DECLARED, never guessed: the kit ships no default root list and no default file-type list, because a fixed one would silently exempt every unlisted language. Authoring this file is the ONE manual step of the practice.',
+  'Create it with this content, replacing every placeholder value:',
+  authoringTemplate(),
+]);
+
+// Both not-yet-MINTED states route to the same lane — the regenerator writes the machine half — so
+// they differ only in what they say happened: AUTHORED is the state a human creates, INCOMPLETE is a
+// machine half no regenerator produces, which means the file was hand-edited into it.
+export const unmintedRefusalLines = (cwd, { state, missing }) => {
+  const { command, withheld } = regenerator(cwd, INITIAL_ADOPTION_REASON);
+  return refusal([
+    state === 'incomplete'
+      ? `source-size: REFUSED — ${namedConfig(cwd)} is INCOMPLETE: it carries a machine half no regenerator produces (missing ${missing.map((key) => `"${key}"`).join(', ')}), so the ratchet holds only part of this tree.`
+      : `source-size: REFUSED — ${namedConfig(cwd)} is AUTHORED but not yet MINTED (it records no size yet), so there is nothing for the ratchet to hold.`,
+    'Mint it — the regenerator records what this tree already carries; recording a value for the first time is a raise, so it takes a reason:',
+    command === null ? `${withheld} Run source-size-check.mjs --write-baseline --reason "${INITIAL_ADOPTION_REASON}" with the working directory set to this project.` : `  ${command}`,
+  ]);
+};
+
+// Every finding names a path or a root the PROJECT chose, and each one crosses the line-safety
+// boundary ONCE — in lineSafeFinding, before any branch sees it. Nine branches each remembering to
+// escape would be nine chances to forget, and the tenth branch nobody has written yet would start
+// out forgetting; here a branch cannot render an unsafe value even if it tries. The PASTEABLE
+// suggestion goes through the boundary's JSON consumer instead — same set, different serialization,
+// because those are bytes a human copies back into the config.
+const lineSafeFinding = (finding) => ({
+  ...finding,
+  ...(finding.rel === undefined ? {} : { rel: escapeForLine(finding.rel) }),
+  ...(finding.root === undefined ? {} : { root: escapeForLine(finding.root) }),
+});
+
+const FINDING_LINE = Object.freeze({
+  'over-default': (f) => `${f.rel}: ${f.dimension} ${f.actual} exceeds the declared default ${f.allowed}`,
+  grew: (f) => `${f.rel}: ${f.dimension} ${f.actual} exceeds its recorded baseline ${f.recorded} — recorded debt is not permission to grow`,
+  stale: (f) => `${f.rel}: ${f.dimension} ${f.actual} is under the recorded ${f.recorded} — the baseline is STALE, tighten it`,
+  'record-obsolete': (f) => `${f.rel}: ${f.dimension} ${f.actual} no longer exceeds the declared default ${f.allowed} — the record must go`,
+  'entry-gone': (f) => `${f.rel}: recorded in "baseline" but no longer in scope — split, renamed or deleted; the record must go`,
+  'aggregate-grew': (f) => `${f.root}: aggregate lines ${f.actual} exceeds the recorded budget ${f.recorded} — splitting a file buys no aggregate headroom`,
+  'aggregate-stale': (f) => `${f.root}: aggregate lines ${f.actual} is under the recorded budget ${f.recorded} — the budget is STALE, tighten it`,
+  'aggregate-unrecorded': (f) => `${f.root}: declared root carries NO recorded aggregate budget (${f.actual} lines measured) — the record must mirror the declared roots exactly`,
+  'aggregate-root-gone': (f) => `${f.root}: recorded in "aggregate" but no longer a declared root — the record must mirror the declared roots exactly`,
+});
+
+// The suggested entry is the WHOLE projected record, not the dimensions that happen to have changed:
+// an entry printed from the findings alone would drop a recorded dimension that stayed put, and
+// pasting it would fail the very next check. The projection already carries exactly the dimensions
+// that violate the declared defaults and nothing else.
+const suggestedEntryLines = (verdict) => {
+  const rels = [...new Set(verdict.findings.filter((f) => f.kind === 'over-default' || f.kind === 'grew').map((f) => f.rel))];
+  return rels.map((rel) => {
+    const parts = Object.entries(verdict.projected.get(rel)).map(([dimension, value]) => `"${dimension}": ${value}`);
+    return `  ${jsonForLine(rel)}: { ${[...parts, `"reason": "${GROWTH_REASON_PLACEHOLDER}"`].join(', ')} }`;
+  });
+};
+
+const servableStep = (cwd, verdict) => {
+  const growth = hasGrowth(verdict.findings);
+  const entries = suggestedEntryLines(verdict);
+  const { command, withheld } = regenerator(cwd, growth ? GROWTH_REASON_PLACEHOLDER : undefined);
+  const byHand = entries.length === 0 ? [] : ['Or record each size by hand under "baseline" — the validator accepts exactly these bytes:', ...entries];
+  if (command === null) return [withheld, WITHHELD_LANE, ...entries];
+  return [
+    growth
+      ? 'This regeneration RAISES a recorded value, so the reason is REQUIRED — it is recorded in the entry it raises, and it is what the commit message and the CHANGELOG restate:'
+      : 'Nothing here grows — regenerate the record (no reason needed; shrinking is progress):',
+    `  ${command}`,
+    ...byHand,
+  ];
+};
+
+export const checkReportLines = ({ cwd, config, verdict }) => {
+  const lines = verdict.scope.emptyRoots.map(
+    (rel) => `source-size: NOTE — the declared root "${escapeForLine(rel)}" matches no tracked file with a declared extension`);
+  if (verdict.findings.length === 0) {
+    lines.push(`source-size: PASS — ${verdict.scope.files.length} in-scope file(s) within the declared caps`, practiceLine(config));
+    return lines;
+  }
+  lines.push(`source-size: FAIL — ${verdict.findings.length} finding(s) against ${namedConfig(cwd)}:`);
+  for (const finding of verdict.findings) lines.push(`  ${FINDING_LINE[finding.kind](lineSafeFinding(finding))}`);
+  lines.push(...servableStep(cwd, verdict));
+  if (hasLoweredRecord(verdict.findings)) lines.push(SPLIT_QUALITY_FOCUS);
+  return refusal(lines);
+};
+
+// The delta is the DURABLE RECORD on a deployment whose docs/ai is git-hidden: it is what the commit
+// message carries and what the release CHANGELOG restates. It is printed WHOLE — a refusal that
+// showed only the raises would drop the tightens and removals riding the same regeneration from the
+// record it promises, so the raises are MARKED instead of filtered.
+export const deltaLines = (deltas) => deltas.map(
+  ({ target, dimension, from, to }) =>
+    `  ${escapeForLine(target)}: ${dimension} ${from ?? 'none'} → ${to ?? 'none'}${isRaise({ from, to }) ? ' (raise)' : ''}`);
+
+export const reasonRequiredLines = (cwd, deltas) => {
+  const { command, withheld } = regenerator(cwd, GROWTH_REASON_PLACEHOLDER);
+  const raises = deltas.filter(isRaise).length;
+  return refusal([
+    `source-size: REFUSED — this regeneration RAISES ${raises} recorded value(s), and a raise takes a reason (it lands verbatim in the entry it raises, in the commit message and in the CHANGELOG). The whole old→new it would write:`,
+    ...deltaLines(deltas),
+    command === null ? `${withheld} ${WITHHELD_LANE}` : `  ${command}`,
+  ]);
+};
+
+// ── --adopt (D-16) ────────────────────────────────────────────────────────────────────────────────
+// The verb touches TWO files, so it reports the two halves separately, ALWAYS. A failure in the
+// second must never read as a failure of the first: a reader told only "adopt failed" would re-run a
+// mint that already succeeded, or hand-write a record that is already on disk. Every line below
+// therefore names what WAS done before what was not.
+
+// ABSENT config. This says the one thing the check refusal need not: authoring the scope is the
+// EXPECTED first step of adoption, not a failure — the template and the WHY are the same ones the
+// check prints, because a second wording of the same refusal would be a second practice.
+export const adoptAbsentRefusalLines = (cwd) => {
+  const { command, withheld } = rendered(cwd, '--adopt', INITIAL_ADOPTION_REASON);
+  return refusal([
+    `source-size: --adopt REFUSED — ${namedConfig(cwd)} is absent, so this practice has no declared scope yet.`,
+    'Authoring that file is the ONE manual step of the practice, and reaching it here is EXPECTED, not a failure: the kit ships no default root list and no default file-type list, because a fixed one would silently exempt every unlisted language.',
+    'Create it with this content, replacing every placeholder value:',
+    authoringTemplate(),
+    'Then re-run this same verb — it mints the record and declares the gate in one step:',
+    command === null ? `${withheld} ${WITHHELD_ADOPT_LANE}` : `  ${command}`,
+  ]);
+};
+
+// Byte-identity cannot tell a recognition from a regeneration that rewrote the same bytes, and the
+// two differ exactly when the tree has moved — so the run SAYS which one it did.
+export const recordRecognizedLines = (cwd) => [
+  `source-size: the record in ${namedConfig(cwd)} already holds for this tree — recognized, not regenerated (adoption never rewrites a minted record).`,
+];
+
+// The record the tree outgrew. The checker's own refusal has already printed the numbers and the
+// reasoned lane; this line adds the ONE thing that refusal cannot know — that a gate was on its way
+// in and did not land, so nothing was half-armed.
+export const recordNoLongerHoldsLines = (rel) => [
+  `source-size: --adopt STOPPED before declaring — the ${escapeForLine(rel)} gate was NOT declared, because the recorded sizes above no longer hold and the gate would refuse on every run.`,
+  'Settle the record with its own reason first (the command above), then re-run --adopt: the settled record is recognized and only the gate is declared.',
+];
+
+export const gateAlreadyDeclaredLines = (rel) => [
+  `source-size: the ${escapeForLine(rel)} gate is already declared — nothing to declare; --adopt converged.`,
+];
+
+export const gateDeclaredLines = (rel, id) => [
+  `source-size: gate "${escapeForLine(id)}" declared in ${escapeForLine(rel)} — the practice now runs with the matrix.`,
+];
+
+// The PARTIAL outcome, and the reason it is not simply an error: the record IS minted and the tree
+// IS judgeable — only the declaration step was refused, and a re-run converges from here without
+// re-doing the mint.
+export const gateRefusedLines = (rel, message) => refusal([
+  `source-size: --adopt INCOMPLETE — the record was minted, the gate was NOT declared in ${escapeForLine(rel)}.`,
+  `  ${escapeForLine(message)}`,
+  'Fix what the line above names and re-run the same verb: the minted record is recognized, so the re-run only declares the gate.',
+]);
+
+// `changed` is decided by comparing the serialized bytes with the file's own — never by the delta
+// count alone: completing a half-written machine record changes the file while raising nothing, and
+// reporting that as "unchanged" would hide a write that happened.
+export const writtenLines = ({ cwd, deltas, reason, changed }) => {
+  if (!changed) return [`source-size: baseline unchanged — ${namedConfig(cwd)} already records this tree`];
+  if (deltas.length === 0) return [`source-size: baseline rewritten — no recorded value changed; ${namedConfig(cwd)} was completed or re-serialized`];
+  return [
+    `source-size: baseline regenerated — ${deltas.length} change(s) in ${namedConfig(cwd)}:`,
+    ...deltaLines(deltas),
+    ...(reason === undefined ? [] : [`reason: ${reason}`]),
+  ];
+};

package/tools/source-size-scope.mjs

@@ -0,0 +1,145 @@
+// source-size-scope.mjs — which files the practice judges (D-6) and how big each one is (D-7). The
+// two rules ride together because they meet in measureFile: the same strict-UTF-8 decoder decides
+// both whether a PATH can be addressed losslessly and whether a file's BYTES can be judged, and both
+// refuse through the same fail-closed lane.
+//
+//   • SCOPE (fail-closed) — git-tracked files under a declared root carrying a declared extension,
+//     minus the excluded path-segment prefixes. Symlinks and submodule gitlinks are skipped BY KIND.
+//     An unmerged index, a non-UTF-8 in-scope FILENAME, an unverifiable in-scope file and an empty
+//     declared scope are REFUSALS (exit 1); a failed enumeration is exit 2. The enumeration is
+//     NUL-delimited and every path test runs on BYTES, so a tracked path carrying a tab or a newline
+//     is judged byte-exactly instead of being mangled by line splitting.
+//   • COUNTING — lines, and the longest line in BYTES. Terminators never count, CR included.
+//
+// Dependency-free, Node >= 22. No side effects on import; the only child process is a read-only git
+// query, so the read-graph purity suite stays true.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { configFail, configPathFor, scopeFail } from './source-size-refusal.mjs';
+
+const LF = 0x0a;
+const CR = 0x0d;
+const TAB = 0x09;
+const SLASH = 0x2f;
+
+const GIT_MAX_BUFFER = 256 * 1024 * 1024;
+const SYMLINK_MODE = '120000';
+const GITLINK_MODE = '160000';
+
+// Raw bytes in, raw bytes out: `ls-files -s -z` emits mode, object and stage, then a TAB, then the
+// path, then a NUL — and the path half is never decoded before it has been matched, so a name
+// carrying a tab or a newline survives intact (splitting on lines would mangle it).
+const parseIndexEntries = (buf) => {
+  const entries = [];
+  let start = 0;
+  while (start < buf.length) {
+    let end = buf.indexOf(0, start);
+    if (end === -1) end = buf.length;
+    const record = buf.subarray(start, end);
+    const tab = record.indexOf(TAB);
+    if (tab !== -1) {
+      const head = record.subarray(0, tab).toString('utf8').split(' ');
+      entries.push({ mode: head[0], stage: Number(head[2]), path: record.subarray(tab + 1) });
+    }
+    start = end + 1;
+  }
+  return entries;
+};
+
+// A path whose bytes are not valid UTF-8 round-trips to something DIFFERENT (the replacement char is
+// lossy) — that is the whole test, and it is exact.
+const decodeStrict = (buf) => {
+  const text = buf.toString('utf8');
+  return Buffer.from(text, 'utf8').equals(buf) ? text : null;
+};
+
+const bufSegmentPrefix = (path, prefix) =>
+  path.length >= prefix.length &&
+  path.subarray(0, prefix.length).equals(prefix) &&
+  (path.length === prefix.length || path[prefix.length] === SLASH);
+
+const bufEndsWith = (path, suffix) =>
+  path.length >= suffix.length && path.subarray(path.length - suffix.length).equals(suffix);
+
+export const enumerateIndex = (cwd, deps = {}) => {
+  const spawn = deps.spawn ?? spawnSync;
+  const result = spawn('git', ['ls-files', '-s', '-z'], { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+  if (result.error || result.status !== 0) {
+    const why = result.error ? result.error.message : `git exited ${result.status}`;
+    throw configFail(`the git index could not be enumerated in ${cwd} (${why}) — the declared scope is unknown, so nothing is judged`);
+  }
+  return parseIndexEntries(result.stdout);
+};
+
+// resolveScope(cwd, config) → { files: [rel…] sorted, perRoot: Map<root, [rel…]>, emptyRoots: [root…] }.
+// Every exclusion is BY RULE (root / extension / exclude prefix) or BY KIND (symlink, gitlink); an
+// in-scope path that cannot be addressed losslessly is a refusal, never a quiet skip.
+export const resolveScope = (cwd, config, deps = {}) => {
+  const entries = enumerateIndex(cwd, deps);
+  const unmerged = entries.filter((e) => e.stage !== 0);
+  if (unmerged.length > 0) {
+    throw scopeFail(`the git index is UNMERGED (${unmerged.length} conflict-stage entr(ies)) — an ambiguous index cannot be judged; resolve the conflict, then re-run`);
+  }
+  const roots = config.roots.map((rel) => ({ rel, buf: Buffer.from(rel, 'utf8') }));
+  const excludes = config.exclude.map((rel) => Buffer.from(rel, 'utf8'));
+  const extensions = config.extensions.map((ext) => Buffer.from(ext, 'utf8'));
+  const perRoot = new Map(config.roots.map((rel) => [rel, []]));
+  const files = [];
+  for (const entry of entries) {
+    const root = roots.find((r) => bufSegmentPrefix(entry.path, r.buf));
+    if (!root) continue;
+    if (!extensions.some((ext) => bufEndsWith(entry.path, ext))) continue;
+    if (excludes.some((ex) => bufSegmentPrefix(entry.path, ex))) continue;
+    if (entry.mode === SYMLINK_MODE || entry.mode === GITLINK_MODE) continue;
+    const rel = decodeStrict(entry.path);
+    if (rel === null) {
+      throw scopeFail(`an in-scope tracked path's NAME is not valid UTF-8 (bytes ${entry.path.toString('hex')}) — it cannot be addressed losslessly, so nothing is judged; rename it, or add its prefix to "exclude" in ${configPathFor(cwd)}`);
+    }
+    files.push(rel);
+    perRoot.get(root.rel).push(rel);
+  }
+  if (files.length === 0) {
+    throw scopeFail(`the declared scope matches ZERO tracked files (roots: ${config.roots.join(', ')}; extensions: ${config.extensions.join(', ')}) — an empty scope is a misdeclaration, never an empty green; either widen "roots" / "extensions" in ${configPathFor(cwd)}, or track a file the declared scope covers`);
+  }
+  files.sort();
+  for (const list of perRoot.values()) list.sort();
+  return { files, perRoot, emptyRoots: [...perRoot].filter(([, list]) => list.length === 0).map(([rel]) => rel) };
+};
+
+// countBytes(buf) → { lines, maxLineBytes }. A terminator never counts (the CR of a CRLF included);
+// a last line with no final newline still counts; an empty file is 0 lines.
+export const countBytes = (buf) => {
+  let lines = 0;
+  let maxLineBytes = 0;
+  let start = 0;
+  const widen = (from, to) => {
+    lines += 1;
+    if (to - from > maxLineBytes) maxLineBytes = to - from;
+  };
+  for (let i = 0; i < buf.length; i += 1) {
+    if (buf[i] !== LF) continue;
+    widen(start, i > start && buf[i - 1] === CR ? i - 1 : i);
+    start = i + 1;
+  }
+  if (start < buf.length) widen(start, buf.length);
+  return { lines, maxLineBytes };
+};
+
+// measureFile(cwd, rel) → { lines, maxLineBytes }. The judged bytes are the WORKTREE bytes of an
+// index-visible path; an in-scope file the checker cannot verify is exit 1 naming the exclude lane,
+// never a silent or green skip.
+export const measureFile = (cwd, rel, deps = {}) => {
+  const read = deps.readFile ?? readFileSync;
+  let buf;
+  try {
+    buf = read(join(cwd, rel));
+  } catch (err) {
+    throw scopeFail(`${rel}: in-scope but unverifiable (${err.message}) — a file the checker cannot read is never a silent skip; fix it, or add its prefix to "exclude" in ${configPathFor(cwd)}`);
+  }
+  if (decodeStrict(buf) === null) {
+    throw scopeFail(`${rel}: in-scope but not valid UTF-8 — its size cannot be judged; add its prefix to "exclude" in ${configPathFor(cwd)}`);
+  }
+  return countBytes(buf);
+};