@sabaiway/agent-workflow-kit 5.4.0 → 5.6.0

package/tools/recommendations.mjs

@@ -55,7 +55,13 @@ import { surveyFamily, surveyGateHook, surveyAdrLayoutStrict } from './family-re
 import { probeSandboxMasks, needsMasksApply } from './sandbox-masks.mjs';
 import { shellQuoteArg } from './review-state.mjs';
 import { isFinalCapableDeclaration } from './run-gates.mjs';
-import { loadDeclaration, canonicalCheckerGates, coverageProducerPrecedes, isReviewDependentGate, GATES_REL } from './gates-declaration.mjs';
+import { loadDeclaration, canonicalCheckerGates, coverageProducerPrecedes, isKitOwnedCheckerGate, GATES_REL } from './gates-declaration.mjs';
+import { matchesCoverageProducer } from './coverage-producer.mjs';
+// Read-only surfaces of the fill (buildOffer) and of the source-size practice (its pure core). The
+// fill's own WRITER is never called from here — the advisor renders its consent-gated command, it
+// does not run it.
+import { buildOffer } from './gates-init.mjs';
+import { INITIAL_ADOPTION_REASON, loadSourceSizeConfig, matchesSourceSizeGate } from './source-size-core.mjs';
 // The declared-path resolution + segment containment this item's convergence lane shares with the
 // autonomy render's allowWrite degrade — ONE leaf, so the two answers cannot drift.
 import { resolveDeclaredDir, dirCovers, isResolvableDeclaredEntry } from './declared-paths.mjs';
@@ -106,6 +112,10 @@ export const SEVERITIES = Object.freeze({
   'gates-declaration': SEVERITY_OPTIONAL,
   'gates-inert': SEVERITY_ATTENTION,
   'gates-inert.no-verification': SEVERITY_ATTENTION,
+  'source-size': SEVERITY_OPTIONAL,
+  // The declared-but-unminted arm reports a CONFIGURED declaration that is broken — a gate certain
+  // to refuse on every run — while the base arm stays an offer to enable something unconfigured.
+  'source-size.unminted': SEVERITY_ATTENTION,
   'gate-hook': SEVERITY_OPTIONAL,
   'commit-guard': SEVERITY_OPTIONAL,
   'read-lane': SEVERITY_OPTIONAL,
@@ -166,6 +176,8 @@ export const WHATS = Object.freeze({
   'gates-declaration': 'no declared gate matrix (docs/ai/gates.json absent or empty) — gates prompt one by one; the apply PREVIEWS its --apply line, writes nothing',
   'gates-inert': 'the declared coverage checker ({id}) has no producer before it — it certifies nothing this run, or reads a stale lcov',
   'gates-inert.no-verification': "all {n} declared gate(s) are the kit's own checkers — the matrix runs no project-verification command",
+  'source-size': 'no source-size gate — module size drifts unmeasured, and an over-cap file is invisible instead of recorded debt',
+  'source-size.unminted': 'the source-size gate is declared but its record ({state}) is not minted — the checker refuses, so this gate reds every run',
   'gate-hook': '{n} declared gate(s) prompt per run — the gate-approval hook is not wired',
   'commit-guard': 'the gate matrix is final-run-capable but no commit-guard arms the pre-commit hook — a commit needs no green receipt yet',
   'read-lane': 'the gate hook is wired but the read-only compound lane is off — pipes/chains of seeded reads still prompt one by one',
@@ -223,6 +235,7 @@ export const BENEFITS = Object.freeze({
   'review-recipe': 'recipe coverage — the review AND execution recipes you configured actually run instead of silently degrading',
   'gates-declaration': 'velocity — your project’s gates run as ONE declared batch with a PASS/FAIL table',
   'gates-inert': 'honest gates — the declared matrix verifies your project instead of reporting green over a check that ran nothing',
+  'source-size': 'maintainability — a module you can hold whole stays reviewable, and size drift becomes recorded, reasoned debt',
   'gate-hook': 'velocity — your own declared gate commands auto-approve byte-exactly (opt-in PreToolUse hook)',
   'commit-guard': 'integrity — commits require the ONE green --final receipt at the exact staged fingerprint (consented pre-commit arm)',
   'read-lane': 'velocity — pipes/chains of your seeded read-only commands auto-approve instead of prompting (opt-in, conservatively classified)',
@@ -263,6 +276,10 @@ export const OPT_IN_CAPABILITIES = Object.freeze([
   // converges the moment any gate exists, so it can never observe this state. The advisor key names
   // the state it reports (an inert declaration), the capability names what the user gains.
   { id: 'gates-verification', mode: 'gates', advisorKey: 'gates-inert' },
+  // The source-size practice is accepted AS a gate — it needs no mode of its own, and its capability
+  // is therefore declared where its declaration lives. It is the DISCOVERY lane for the practice on
+  // every deployment, new and existing alike: nothing else tells a project the practice exists.
+  { id: 'source-size', mode: 'gates', advisorKey: 'source-size' },
   { id: 'gate-hook', mode: 'hook', advisorKey: 'gate-hook' },
   { id: 'read-lane', mode: 'hook', advisorKey: 'read-lane' },
   { id: 'commit-guard', mode: 'commit-guard', advisorKey: 'commit-guard' },
@@ -432,12 +449,23 @@ const probeGates = ({ root, deps, add, skip }) => {
 //
 // Cause A (a canonical coverage checker with no producer anywhere in the declaration) is checked
 // FIRST and reported alone: its remedy — declaring the producer — also resolves cause B, because a
-// producer gate is not a kit checker. Its apply is HAND-APPLY: the producer must precede the
-// checker, and the fill is append-only (it refuses by name rather than reordering), so the edit is
-// the maintainer's.
+// producer gate is not a kit checker. Its apply follows what the FILL can actually do, which the
+// D-8 placement rule changed: when the checker is the declaration's LAST gate and the project's own
+// scripts yield an offerable producer, the fill now PLACES that producer before the checker, so the
+// remedy is the ordinary consent-gated preview. HAND-APPLY remains exactly where no offerable
+// producer exists, or where the checker is not last — there the edit really is the maintainer's,
+// because the fill never reorders entries it did not write.
 //
 // An ABSENT or EMPTY declaration belongs to the gates-declaration item; a malformed one throws out
 // of the validated reader and becomes this probe's stated skip, never a guess.
+// ONE rule for every fill preview this item renders: name only the entries the fill would ACCEPT.
+// An id the declaration already carries is refused as a collision, so an unrestricted preview hands
+// the reader a lane that cannot converge — and both arms of this item render over a declaration that
+// already carries at least one gate the offer also proposes, so both need the rule. With nothing
+// selectable the bare preview is still the honest render: its own notes say why.
+const fillPreviewFor = (root, ids) =>
+  `node ${q(toolPath('gates-init.mjs'))} --cwd ${q(root)}${ids.map((id) => ` --only ${id}`).join('')}`;
+
 export const probeGatesInert = ({ root, deps, add, skip }) => {
   try {
     const declaration = loadDeclaration(root, deps);
@@ -451,18 +479,54 @@ export const probeGatesInert = ({ root, deps, add, skip }) => {
       // only --final refuses that shape — a plain run reports every gate PASS.
       if (coverageProducerPrecedes(gates, gates.indexOf(checkers[0]))) return; // the pair is live
       const id = truncatedTo(oneLineOf(checkers[0].id), templateBudget(WHATS['gates-inert']));
+      // The fill can only help when it would land the producer in the right place: the checker must
+      // be LAST (that is the one position the placement rule inserts before) and the offer must
+      // actually carry a producer the fill would ACCEPT. An offered id that is already declared is
+      // refused as a collision, so counting it here would render a preview that cannot fix what the
+      // item just reported.
+      const declaredIds = new Set(gates.map((gate) => gate.id));
+      const checkerIsLast = checkers[0] === gates[gates.length - 1];
+      // The PRODUCER entry is kept, not just its existence: the rendered preview must name it with
+      // --only. A whole-offer apply here collides by construction — the declaration already carries
+      // the checker, and the offer carries it too — so an unrestricted preview would hand the reader
+      // a lane that refuses instead of the one entry that resolves what the item just reported.
+      const producer = buildOffer(root, deps).entries
+        .find((entry) => !declaredIds.has(entry.id) && matchesCoverageProducer(entry.cmd));
+      // The two ways the fill cannot help are DIFFERENT situations and need different sentences: a
+      // checker that is not last blocks a placement even when a producer is offerable, and saying no
+      // producer exists there would be plainly false to a reader looking at their own scripts.
+      const blocked = checkerIsLast
+        ? `no offerable producer exists here, and the fill never reorders entries it did not write`
+        : `${id} is not the LAST declared gate, so there is no trailing position to place a producer before, and the fill never reorders entries it did not write`;
       add(
         'gates-inert',
         fillTemplate(WHATS['gates-inert'], { id }),
-        `HAND-APPLY: declare or MOVE a suite gate carrying the coverage reporters BEFORE ${id} in ${GATES_REL} (references/modes/gates.md names the exact form), or drop ${id} — the fill is append-only and cannot reorder for you`,
+        checkerIsLast && producer
+          ? fillPreviewFor(root, [producer.id])
+          : `HAND-APPLY: declare or MOVE a suite gate carrying the coverage reporters BEFORE ${id} in ${GATES_REL} (references/modes/gates.md names the exact form), or drop ${id} — ${blocked}`,
       );
       return;
     }
-    if (gates.every((gate) => isReviewDependentGate(gate, root))) {
+    // The source-size checker is one of the kit's OWN checkers, and it is deliberately NOT
+    // review-dependent (it needs no receipt), so the review-dependent predicate alone cannot see it.
+    // Left out, a matrix of nothing but that gate reads as carrying project verification — and a
+    // project that just adopted the practice and declared nothing else would be told it is optimal.
+    // The source-size checker is one of the kit's OWN checkers, and it is deliberately NOT
+    // review-dependent (it needs no receipt), so the review-dependent predicate alone cannot see it.
+    // Left out, a matrix of nothing but that gate reads as carrying project verification — and a
+    // project that just adopted the practice and declared nothing else would be told it is optimal.
+    if (gates.every((gate) => isKitOwnedCheckerGate(gate, root))) {
+      const declaredIds = new Set(gates.map((gate) => gate.id));
+      // Only PROJECT-verification entries: a non-colliding entry is not enough, it has to be one
+      // that RESOLVES the item, and declaring one more kit checker converges nothing — the item
+      // would simply fire again on the next run.
+      const selectable = buildOffer(root, deps).entries
+        .filter((entry) => !declaredIds.has(entry.id) && !isKitOwnedCheckerGate(entry, root))
+        .map((entry) => entry.id);
       add(
         'gates-inert',
         fillTemplate(WHATS['gates-inert.no-verification'], { n: gates.length }),
-        `node ${q(toolPath('gates-init.mjs'))} --cwd ${q(root)}`,
+        fillPreviewFor(root, selectable),
         'gates-inert.no-verification',
       );
     }
@@ -471,6 +535,42 @@ export const probeGatesInert = ({ root, deps, add, skip }) => {
   }
 };
 
+// The SOURCE-SIZE offer (baseline-practices Plan 1). This is the practice's ONE discovery lane: the
+// checker ships with the kit and refuses until a project declares its own scope, so without this
+// item a deployment would never learn the practice exists — the same OPT-IN-SHIPS-INVISIBLE failure
+// the capability registry was built for. New and existing deployments meet it identically, because
+// the advisor section is mandatory at every upgrade.
+//
+// The probe asks ONE question — does the declaration carry the canonical source-size gate? — through
+// the practice's own matcher, so an id squatter (a gate called `source-size` running something else)
+// never reads as adopted. It deliberately does NOT key on the config's state: a project with no
+// config is exactly the project that needs to hear about the practice, and the apply's own refusal
+// is what teaches the one manual step (authoring the scope). A missing declaration is not a skip —
+// there is no source-size gate in it either.
+const probeSourceSize = ({ root, deps, add, skip }) => {
+  try {
+    const declaration = loadDeclaration(root, deps);
+    const gates = declaration.outcome === 'loaded' ? declaration.gates : [];
+    const applyLine = `node ${q(toolPath('source-size-check.mjs'))} --adopt --reason "${INITIAL_ADOPTION_REASON}" --cwd ${q(root)}`;
+    if (gates.some((gate) => matchesSourceSizeGate(gate.cmd, root))) {
+      // A DECLARED gate is not the same fact as a working one: the checker refuses on every config
+      // state but MINTED, so a gate declared over an absent or half-written record reds the matrix
+      // on every run. Reading the declaration alone would report that deployment as adopted and say
+      // nothing about the one thing that is wrong with it.
+      const { state } = loadSourceSizeConfig(root, deps);
+      if (state === 'minted') return; // adopted and armed — converged
+      add('source-size', fillTemplate(WHATS['source-size.unminted'], { state }), applyLine, 'source-size.unminted');
+      return;
+    }
+    // The reason string is PINNED, not composed: it is copied unchanged into every entry the first
+    // mint records, and a first mint records the whole tree — so "this is what the tree already
+    // carried when the practice arrived" is the one sentence that is true of all of them.
+    add('source-size', fillTemplate(WHATS['source-size'], {}), applyLine);
+  } catch (err) {
+    skip('source-size', err);
+  }
+};
+
 // The D10 consumer surface: once the declaration is FINAL-capable (the canonical core checks
 // present, the checker LAST — the run-gates helper is the one home of that rule), offer the
 // consented commit-guard install — for a MANAGED guardless pre-commit hook AND for an absent one
@@ -1054,6 +1154,7 @@ const PROBES = Object.freeze([
   probeReviewRecipe,
   probeGates,
   probeGatesInert,
+  probeSourceSize,
   probeCommitGuard,
   probeReadLane,
   probeStateBlockHook,

package/tools/release-scan.mjs

@@ -35,11 +35,44 @@ const ATTRIBUTION = [
   { re: /reviewed by (claude|codex|chatgpt|gpt|gemini|copilot|cursor|the (ai|model|agent))/i, label: 'AI review attribution' },
   { re: /authored[- ]by[: ][^\n]{0,40}\b(claude|chatgpt|gemini|copilot)\b/i, label: 'AI authorship attribution' },
 ];
+// A line whose FIRST non-space token opens a comment (or a markdown heading) — the surface where a
+// backend name beside a disposition is a credit rather than a data value.
+//
+// STATED RESIDUAL of the two anchored rules below, named rather than implied: they see only lines
+// that OPEN with a comment marker, so a credit inside a string literal, in ordinary markdown prose
+// outside a heading, or in a trailing inline comment is invisible to them. Closing that class needs
+// a code/comment/string lexer this scanner deliberately does not have (the version-pin rung below
+// records what hand-rolling one cost). The UNANCHORED pair narrows the gap for the one construction
+// that has actually shipped past this gate; nothing here proves no attribution exists — it is a
+// high-signal guard, not a proof.
+const COMMENT_LINE = String.raw`^\s*(?://|/\*|\*|#)`;
+const DISPOSITIONS = 'CONFIRM|REFUTE|REVISE|SHIP';
+// Spelled per letter rather than flagged: the four rules below must be case-insensitive on the NAME
+// and case-SENSITIVE on the disposition, and a regex flag cannot apply to half a pattern. All four
+// share this constant, so an ALL-CAPS credit cannot slip past one of them.
+const BACKEND_ANY_CASE = '[Aa][Gg][Yy]|[Cc][Oo][Dd][Ee][Xx]';
+
 const REVIEWER_IDENTITY = [
   // backend-then-round: a bridge name, a separator, then r<N> (with optional +/round suffixes).
   { re: /\b(?:agy|codex)(?:\s+|-)r\d+(?:(?:\+|\/)r?\d+)*(?:-[a-z0-9]+)*\b/i, label: 'reviewer-round identity' },
   // round-then-backend (reverse order): r<N>, a separator, then a bridge name — the release-review gap.
   { re: /\br\d+(?:\s+|-)(?:agy|codex)\b/i, label: 'reviewer-round identity' },
+  // backend beside a DISPOSITION, in a COMMENT: the form a fold note takes when it credits who
+  // decided instead of stating what was decided. Two narrowings make it usable. The line must be a
+  // comment, because a receipt FIXTURE legitimately pairs a backend field with a verdict value and
+  // that is data, not attribution. And the disposition half is case-SENSITIVE, because prose says
+  // "ship" and "revise" constantly while a recorded disposition is written in caps.
+  { re: new RegExp(`${COMMENT_LINE}[^\\n]*\\b(?:${BACKEND_ANY_CASE})\\b[^\\n]{0,24}\\b(?:${DISPOSITIONS})\\b`), label: 'reviewer-round identity' },
+  { re: new RegExp(`${COMMENT_LINE}[^\\n]*\\b(?:${DISPOSITIONS})\\b[^\\n]{0,24}\\b(?:${BACKEND_ANY_CASE})\\b`), label: 'reviewer-round identity' },
+  // The exact PARENTHESISED credit — an open paren, a bridge name, a comma, a disposition, and the
+  // reverse order — matched ANYWHERE on the line, so it also lands inside a string literal, a
+  // markdown sentence and a trailing inline comment, none of which the comment anchor above can
+  // see. It stays clear of data because a fixture QUOTES its values, and a quote sits exactly where
+  // this rule requires the bare disposition word. Both orders END on a word boundary, so a longer
+  // word sharing a disposition's prefix is not a credit — the boundary is what a commit gate needs,
+  // and requiring the CLOSING paren instead would drop the hyphenated form this rule exists for.
+  { re: new RegExp(`\\((?:${BACKEND_ANY_CASE}),\\s*(?:${DISPOSITIONS})\\b`), label: 'reviewer-round identity' },
+  { re: new RegExp(`\\((?:${DISPOSITIONS}),\\s*(?:${BACKEND_ANY_CASE})\\b`), label: 'reviewer-round identity' },
 ];
 
 const allowlistCovers = (matched, allowlist) =>

package/tools/source-size-check.mjs

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+// source-size-check.mjs — the source-size practice's CLI and its writer half. The pure read core
+// (config, scope, counting, the canonical gate-cmd matcher) lives in source-size-core.mjs, the
+// verdict in source-size-judge.mjs and its wording in source-size-report.mjs; all three are imported
+// here. NOTHING in the read graph imports THIS module, so the advisor surfaces can ask about the
+// practice without ever reaching a writer (D-18).
+//
+// What --check judges: every in-scope file against the config's `defaults`, and every RECORDED size
+// against the ratchet instead — a record may not grow, may not sit above what the tree measures, and
+// may not outlive its file. Each declared root carries the same ratchet over its summed lines, so
+// splitting one big file into six buys no headroom.
+//
+// What --write-baseline does: regenerates the machine keys from the tree, and ONLY the machine keys.
+// The authored half is copied through with its VALUES and their ORDER preserved exactly; the file
+// itself is canonically serialized, so its formatting becomes the writer's (that is what makes a
+// regeneration of an unchanged tree reproduce the same bytes). A regeneration that RAISES any value takes
+// --reason "<text>" — the checker cannot invent the human's reason — and that string lands verbatim
+// in the entry it raises. A pure tighten needs none: shrinking is progress. The printed old→new
+// delta is the durable record where docs/ai is git-hidden; it is what the commit message carries.
+//
+// What --adopt does: mints the record and declares the gate — the whole adoption as ONE consented
+// line, because the alternative is a two-step ceremony whose halves can be left half-done. It
+// composes the two writers it already has (this module's mint, the fill's consented apply restricted
+// to this one id) and owns no write of its own.
+//
+// Exit codes: 0 green / 1 violation or refusal / 2 usage, config or enumeration error.
+// Dependency-free, Node >= 22. No side effects on import.
+
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { assertDocsAiDeployment, writeDocsAiFileAtomic } from './atomic-write.mjs';
+import {
+  AUTHORED_KEYS,
+  SOURCE_SIZE_CONFIG_REL,
+  SOURCE_SIZE_GATE_ID,
+  loadSourceSizeConfig,
+  matchesSourceSizeGate,
+  reasonDefect,
+  scopeFail,
+} from './source-size-core.mjs';
+import { changesFor, isRaise, judgeTree, ownEntry } from './source-size-judge.mjs';
+import { GATES_REL, loadDeclaration } from './gates-declaration.mjs';
+import { applyFill } from './gates-init.mjs';
+import {
+  absentRefusalLines,
+  adoptAbsentRefusalLines,
+  checkReportLines,
+  gateAlreadyDeclaredLines,
+  gateDeclaredLines,
+  gateRefusedLines,
+  reasonRequiredLines,
+  recordNoLongerHoldsLines,
+  recordRecognizedLines,
+  unmintedRefusalLines,
+  writtenLines,
+} from './source-size-report.mjs';
+
+const usageFail = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { exitCode: 2 });
+const RECORD_NOUN = 'the source-size record';
+
+export const runCheck = ({ cwd, deps = {} }) => {
+  const { state, config, missingMachineKeys } = loadSourceSizeConfig(cwd, deps);
+  if (state === 'absent') return { code: 1, lines: absentRefusalLines(cwd) };
+  if (state !== 'minted') return { code: 1, lines: unmintedRefusalLines(cwd, { state, missing: missingMachineKeys }) };
+  const verdict = judgeTree(cwd, config, deps);
+  return { code: verdict.findings.length === 0 ? 0 : 1, lines: checkReportLines({ cwd, config, verdict }) };
+};
+
+// ── the writer ────────────────────────────────────────────────────────────────────────────────────
+
+// planRecord computes what the regeneration WOULD write, before any reason is applied — so a raise
+// can be refused without ever building an entry that carries no reason. It reads the JUDGE's
+// projection, never its own: the checker's verdict and the file the writer produces are then two
+// renderings of one computation, and neither can promise what the other would not do.
+const planRecord = ({ config, verdict }) => {
+  const oldBaseline = config.baseline ?? {};
+  const oldAggregate = config.aggregate ?? {};
+  const files = verdict.scope.files.map((rel) => {
+    const next = verdict.projected.get(rel);
+    const recorded = ownEntry(oldBaseline, rel);
+    return { rel, next, recorded, changes: changesFor(rel, next, recorded) };
+  });
+  const roots = config.roots.map((root) => ({
+    root,
+    lines: verdict.rootLines.get(root) ?? 0,
+    recorded: ownEntry(oldAggregate, root),
+  }));
+  const deltas = [
+    ...files.flatMap(({ changes }) => changes),
+    // A record whose file left scope is REMOVED, never kept: that is what makes a split or a rename
+    // visible in the delta instead of silently surviving as headroom.
+    ...Object.entries(oldBaseline)
+      .filter(([rel]) => !verdict.measured.has(rel))
+      .flatMap(([rel, recorded]) => changesFor(rel, {}, recorded)),
+    ...roots
+      .filter(({ lines, recorded }) => (recorded ? recorded.lines : null) !== lines)
+      .map(({ root, lines, recorded }) => ({ target: root, dimension: 'aggregate lines', from: recorded ? recorded.lines : null, to: lines })),
+    ...Object.entries(oldAggregate)
+      .filter(([root]) => !config.roots.includes(root))
+      .map(([root, recorded]) => ({ target: root, dimension: 'aggregate lines', from: recorded.lines, to: null })),
+  ];
+  return { files, roots, deltas, raises: deltas.filter(isRaise) };
+};
+
+// The reason of an entry the regeneration did NOT raise is the one already recorded — a tighten
+// rewrites a number, never the human sentence that justified it.
+const materialize = ({ files, roots }, reason) => ({
+  baseline: Object.fromEntries(
+    files
+      .filter(({ next }) => Object.keys(next).length > 0)
+      .map(({ rel, next, recorded, changes }) => [rel, {
+        ...next,
+        reason: changes.some(isRaise) ? reason : recorded.reason,
+      }]),
+  ),
+  aggregate: Object.fromEntries(
+    roots.map(({ root, lines, recorded }) => [root, {
+      lines,
+      reason: !recorded || lines > recorded.lines ? reason : recorded.reason,
+    }]),
+  ),
+});
+
+// The file is CANONICALLY serialized: the authored VALUES and the ORDER the human wrote them in are
+// preserved exactly, their formatting is not — this file is machine-maintained and the writer owns
+// half of it, so one deterministic rendering is what makes "regenerate an unchanged tree and get the
+// same bytes" true at all.
+const serialize = (parsed, machineKeys) => {
+  const authored = Object.fromEntries(Object.keys(parsed).filter((key) => AUTHORED_KEYS.includes(key)).map((key) => [key, parsed[key]]));
+  return `${JSON.stringify({ ...authored, ...machineKeys }, null, 2)}\n`;
+};
+
+export const runWriteBaseline = ({ cwd, reason, deps = {} }) => {
+  // Checked BEFORE the config is read, so a project that was never deployed hears about the
+  // deployment rather than about a file it has no place to put.
+  assertDocsAiDeployment(cwd, deps, { stop: scopeFail, rel: SOURCE_SIZE_CONFIG_REL, noun: RECORD_NOUN });
+  const { state, config, parsed, text } = loadSourceSizeConfig(cwd, deps);
+  if (state === 'absent') return { code: 1, lines: absentRefusalLines(cwd) };
+  const verdict = judgeTree(cwd, config, deps);
+  const plan = planRecord({ config, verdict });
+  if (plan.raises.length > 0 && reason === undefined) return { code: 1, lines: reasonRequiredLines(cwd, plan.deltas) };
+  const body = serialize(parsed, materialize(plan, reason));
+  // Whether anything was written is decided by the BYTES, not by the delta count: completing a
+  // hand-edited half record changes the file while raising nothing at all.
+  const changed = body !== text;
+  if (changed) writeDocsAiFileAtomic(cwd, SOURCE_SIZE_CONFIG_REL, body, deps, { stop: scopeFail, noun: RECORD_NOUN });
+  return { code: 0, lines: writtenLines({ cwd, deltas: plan.deltas, reason: plan.raises.length > 0 ? reason : undefined, changed }) };
+};
+
+// ── the adoption verb (D-16) ──────────────────────────────────────────────────────────────────────
+
+// Declaring the gate is delegated to the FILL's own consented apply, restricted to this one id: the
+// fill owns every rule about what a written declaration may look like (placement, id collisions, the
+// coverage invariant, the atomic write), and a second writer here would be a second set of those
+// rules — the one that drifts. `--adopt` is therefore a composition, never a re-implementation.
+//
+// The already-declared arm is checked FIRST and through the practice's own matcher: an earlier
+// partial run leaves a minted record and a declared gate, and re-running must converge rather than
+// collide. A gate that merely CARRIES the id without being this checker does not count — it reaches
+// the fill and collides there, loudly, which is the honest answer to a squatter.
+// The READ is inside the try with the write, deliberately: by the time this runs the record is
+// already minted, so ANY failure here — a malformed declaration the reader throws on, just as much
+// as a collision the fill refuses — must still report both halves. Letting the read escape would
+// surface a bare error carrying neither the mint that succeeded nor the exit contract this tool
+// documents.
+const declareGate = (cwd, deps) => {
+  try {
+    applyFill({ cwd, onlyIds: [SOURCE_SIZE_GATE_ID] }, deps);
+    return { code: 0, lines: gateDeclaredLines(GATES_REL, SOURCE_SIZE_GATE_ID) };
+  } catch (err) {
+    return { code: 1, lines: gateRefusedLines(GATES_REL, err?.message ?? String(err)) };
+  }
+};
+
+// Is the canonical gate ALREADY there? Asked through the practice's own matcher, so a gate that
+// merely carries the id — running something else entirely — never reads as adopted; it reaches the
+// fill and collides there, loudly, which is the honest answer to a squatter.
+//
+// An unreadable declaration is NOT a verdict here. This read is a shortcut, and aborting on it would
+// report an outcome before the record was settled; the fill re-reads the same file and refuses
+// authoritatively AFTER, so the partial report names both halves truthfully.
+const gateIsDeclared = (cwd, deps) => {
+  try {
+    const declaration = loadDeclaration(cwd, deps);
+    return (declaration.outcome === 'loaded' ? declaration.gates : []).some((gate) => matchesSourceSizeGate(gate.cmd, cwd));
+  } catch {
+    return false;
+  }
+};
+
+// A MINTED record is RECOGNIZED, never regenerated. Adoption carries a PINNED reason — the advisor
+// renders it as a fixed string, and its item keeps firing while the gate is undeclared — so a
+// re-run after a partial adoption would let that one sentence raise whatever the tree grew in the
+// meantime. That is exactly the laundering the reason requirement exists to prevent, so the verb
+// asks the checker instead: a record that no longer holds is a ratchet question with its own
+// reasoned lane, and it must be answered BEFORE a gate is declared over it — declaring one that is
+// certain to red the matrix is what the offer rules refuse everywhere else.
+const recognizeRecord = ({ cwd, deps }) => {
+  const verdict = runCheck({ cwd, deps });
+  if (verdict.code !== 0) return { code: verdict.code, lines: [...verdict.lines, ...recordNoLongerHoldsLines(GATES_REL)] };
+  return { code: 0, lines: recordRecognizedLines(cwd) };
+};
+
+// --adopt = settle the record, then declare the gate. The order is not a preference: the fill offers
+// the gate ONLY over a minted config (declaring it earlier would declare a gate that refuses), so
+// the record is what makes the declaration offerable at all.
+export const runAdopt = ({ cwd, reason, deps = {} }) => {
+  const { state } = loadSourceSizeConfig(cwd, deps);
+  if (state === 'absent') return { code: 1, lines: adoptAbsentRefusalLines(cwd) };
+  // ADOPTED is asked FIRST, and it is a question about the GATE alone. Idempotence cannot be made
+  // conditional on the record still holding: a declared gate reports its own staleness on every run,
+  // with the reasoned lane, and stopping here would tell a reader the gate was not declared while it
+  // plainly is — which is exactly what re-running the advisor's one-liner on a drifted tree does.
+  // Once the gate is there and the record is minted, nothing is left to adopt.
+  const declared = gateIsDeclared(cwd, deps);
+  if (declared && state === 'minted') return { code: 0, lines: gateAlreadyDeclaredLines(GATES_REL) };
+  // Either half carries its OWN self-servable refusals (a raise with no reason, a project with no
+  // docs/ai, a record the tree outgrew). They are returned unchanged: re-wording them here would be
+  // the second practice this module exists to avoid, and each already names the step that clears it.
+  const record = state === 'minted' ? recognizeRecord({ cwd, deps }) : runWriteBaseline({ cwd, reason, deps });
+  if (record.code !== 0) return record;
+  if (declared) return { code: 0, lines: [...record.lines, ...gateAlreadyDeclaredLines(GATES_REL)] };
+  const gate = declareGate(cwd, deps);
+  return { code: gate.code, lines: [...record.lines, ...gate.lines] };
+};
+
+// ── CLI ───────────────────────────────────────────────────────────────────────────────────────────
+
+const MODES = Object.freeze(['--check', '--write-baseline', '--adopt']);
+
+const HELP = `source-size-check — the declared source-size practice (agent-workflow family).
+
+Usage:
+  node source-size-check.mjs --check [--cwd <project-root>]
+  node source-size-check.mjs --write-baseline [--reason "<text>"] [--cwd <project-root>]
+  node source-size-check.mjs --adopt [--reason "<text>"] [--cwd <project-root>]
+
+Judges every in-scope file against ${SOURCE_SIZE_CONFIG_REL}: git-tracked files under a declared
+root carrying a declared extension, minus the excluded path-segment prefixes. Scope is DECLARED,
+never guessed — with the config absent the check REFUSES and prints the exact file to author.
+Symlinks and submodule gitlinks are skipped by kind; an unmerged index, a non-UTF-8 in-scope path,
+an unverifiable in-scope file and an empty declared scope are refusals, never silent greens.
+
+Counting: lines, and the longest line in BYTES. 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.
+
+A file carrying a recorded baseline entry is recorded DEBT: it is judged against the record, which
+may not grow, may not sit above the measured size, and may not outlive its file. Each declared root
+carries the same ratchet over its summed lines.
+
+--write-baseline regenerates the machine keys (baseline, aggregate) from the tree. The authored keys
+keep their values and their order; the file is canonically serialized, so its formatting is the
+writer's. A regeneration that RAISES any recorded value needs --reason; the string is recorded in
+the entry it raised. A pure tighten needs none.
+
+--adopt is the ONE-line adoption: it mints the record and declares the source-size gate (and NOTHING
+else) in docs/ai/gates.json. It is idempotent on an already-adopted project. With the config absent
+it refuses with the exact file to author — that authoring is the practice's single manual step, and
+the refusal says so. A refused declaration exits nonzero and reports both halves: what was minted and
+what was not declared.
+
+Exit codes: 0 green; 1 violation or refusal; 2 usage, config or enumeration error.`;
+
+const takeOption = (argv, flag) => {
+  const at = argv.indexOf(flag);
+  if (at === -1) return { rest: argv, value: undefined };
+  if (argv[at + 1] === undefined) throw usageFail(`${flag} needs a value`);
+  return { rest: [...argv.slice(0, at), ...argv.slice(at + 2)], value: argv[at + 1] };
+};
+
+export const main = (argv, ctx = {}) => {
+  try {
+    if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
+    const cwdOption = takeOption(argv, '--cwd');
+    const reasonOption = takeOption(cwdOption.rest, '--reason');
+    // Resolved BEFORE the run and before anything is rendered: every path this run names is then
+    // meaningful from any directory, not only from the one that invoked it.
+    const cwd = resolve(ctx.cwd ?? process.cwd(), cwdOption.value ?? '.');
+    // Counted over the ARGUMENTS, not over the mode list: filtering the list collapses repeats, so
+    // `--adopt --adopt` read as exactly one mode and a WRITE ran under an argument list this very
+    // guard had just called invalid.
+    const modes = reasonOption.rest.filter((arg) => MODES.includes(arg));
+    if (modes.length === 0) throw usageFail(`nothing to do — pass one of ${MODES.join(', ')} (see --help)`);
+    if (modes.length > 1) throw usageFail(`pass exactly ONE mode, got: ${modes.join(', ')}`);
+    const unknown = reasonOption.rest.filter((arg) => !MODES.includes(arg));
+    if (unknown.length > 0) throw usageFail(`unknown argument: ${unknown[0]}`);
+    if (reasonOption.value !== undefined) {
+      if (modes[0] === '--check') throw usageFail('--reason belongs to --write-baseline and --adopt — a check records nothing');
+      const defect = reasonDefect(reasonOption.value);
+      if (defect) throw usageFail(defect);
+    }
+    const deps = ctx.deps ?? {};
+    const run = { '--check': runCheck, '--write-baseline': runWriteBaseline, '--adopt': runAdopt }[modes[0]];
+    const { code, lines } = run({ cwd, reason: reasonOption.value, deps });
+    return { code, stdout: lines.join('\n'), stderr: '' };
+  } catch (err) {
+    return { code: err.exitCode ?? 1, stdout: '', stderr: `source-size-check: ${err.message}` };
+  }
+};
+
+// Compared by REAL path, not lexically: ESM resolves a symlinked entry point to its target, so a
+// lexical comparison is false whenever the tool is invoked through a link — and a gate whose cmd
+// names a link would then exit 0 having run nothing, which reads as PASS.
+// Exported as a test seam (the coverage-check keyFor idiom): the unresolvable arm cannot be reached
+// through the CLI, where an existing entry point is a precondition of getting this far.
+export const sameFile = (a, b) => {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+};
+const isDirectRun = Boolean(process.argv[1]) && sameFile(fileURLToPath(import.meta.url), process.argv[1]);
+if (isDirectRun) {
+  const result = main(process.argv.slice(2));
+  if (result.stdout) process.stdout.write(result.stdout.endsWith('\n') ? result.stdout : `${result.stdout}\n`);
+  if (result.stderr) process.stderr.write(result.stderr.endsWith('\n') ? result.stderr : `${result.stderr}\n`);
+  process.exitCode = result.code;
+}