@sabaiway/agent-workflow-kit 5.5.0 → 5.6.0

package/tools/gates-declaration.mjs

@@ -11,6 +11,7 @@ import { join, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { fail, loadConfig, CONFIG_REL } from './orchestration-config.mjs';
 import { matchesCoverageProducer } from './coverage-producer.mjs';
+import { matchesSourceSizeGate } from './source-size-core.mjs';
 
 // The per-project declaration (strict JSON, hand-editable). cwd-relative — errors show a path the
 // user can open (the orchestration-config CONFIG_REL idiom).
@@ -174,7 +175,8 @@ export const coverageDeclarationDefects = (gates, projectDir) => {
       message:
         `${GATES_REL}: the canonical coverage checker (${checkers[0].id}) must be the LAST declared gate — ` +
         `${after.map((g) => g.id).join(', ')} would run after it consumed the lcov. REORDER the declaration by hand ` +
-        '(the gate itself is fine — this is an ORDERING refusal, and the fill is append-only, so it cannot reorder for you)',
+        '(the gate itself is fine — this is an ORDERING refusal about entries that are ALREADY declared: the fill ' +
+        'places a new entry before a trailing checker, but it never reorders what it did not write)',
     }];
   }
   if (!coverageProducerPrecedes(gates, index)) {
@@ -202,6 +204,16 @@ const REVIEW_DEPENDENT_CHECKS = ['review-state', 'commit-guard', 'coverage-check
 export const isReviewDependentGate = (gate, projectDir) =>
   REVIEW_DEPENDENT_CHECKS.some((check) => matchesCanonicalCheck(check, gate.cmd, projectDir));
 
+// isKitOwnedCheckerGate — is this gate one of the KIT's own checkers, rather than something the
+// project declared to verify itself? A separate question from review-dependence, and the two stopped
+// coinciding the moment a kit checker arrived that needs no receipt: the source-size gate is
+// deliberately in neither FINAL_CORE_CHECKS nor REVIEW_DEPENDENT_CHECKS, so every surface asking
+// "does this declaration verify the PROJECT?" through the review-dependent predicate alone read a
+// matrix of nothing but that gate as project verification. Three surfaces asked it, each knowing a
+// different half; this is the one home, so a future kit checker is added once.
+export const isKitOwnedCheckerGate = (gate, projectDir) =>
+  isReviewDependentGate(gate, projectDir) || matchesSourceSizeGate(gate.cmd, projectDir);
+
 // ── the pregate subset derivation (#66 / Decision 7 — ONE home for producer and factory) ─────
 
 export const unknownPregateExcludeIds = (gates, exclude) => {

package/tools/gates-init.mjs

@@ -45,11 +45,12 @@
 //     tool path (spaces survive; executes from the project root).
 //
 // Write discipline: preview (dry-run) is the DEFAULT and writes NOTHING — a declined offer leaves
-// the file byte-identical. `--apply` appends EXACTLY the consented entries (`--only <id>`
+// the file byte-identical. `--apply` writes EXACTLY the consented entries (`--only <id>`
 // repeatable) through the shared atomic-write core (tools/atomic-write.mjs — exclusive-create
-// tmp+rename, TOCTOU re-check, symlink STOPs): append-only, never modifies or removes an existing
-// entry, refuses id collisions, refuses a malformed declaration (never writes over what it cannot
-// parse). Deployment-gated: docs/ai presence (lstat, no-follow) on EVERY run; the
+// tmp+rename, TOCTOU re-check, symlink STOPs): ADD-ONLY (it never modifies, removes or reorders an
+// existing entry), refuses id collisions, refuses a malformed declaration (never writes over what it
+// cannot parse). WHERE a consented entry lands is a PLACEMENT rule, not a blind append — see
+// placeEntries below. Deployment-gated: docs/ai presence (lstat, no-follow) on EVERY run; the
 // .workflow-version == lineage-head stamp gate on --apply only (the velocity/gate-hook precedent).
 //
 // Exit codes: 0 done / dry-run; 1 precondition STOP (no deployment, stamp, symlink, malformed
@@ -60,10 +61,20 @@ import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { discoverGateCandidates, EXPECTED_WORKFLOW_VERSION } from './velocity-profile.mjs';
 import { GATES_REL, validateDeclaration } from './run-gates.mjs';
-import { coverageDeclarationDefects, isReviewDependentGate } from './gates-declaration.mjs';
+import { canonicalCheckerGates, coverageDeclarationDefects, isKitOwnedCheckerGate } from './gates-declaration.mjs';
 import { COVERAGE_PRODUCER_BODY, matchesCoverageProducer } from './coverage-producer.mjs';
 import { loadConfig } from './orchestration-config.mjs';
 import { assertDocsAiDeployment, writeDocsAiFileAtomic, lstatNoFollow } from './atomic-write.mjs';
+// The source-size practice, through its PURE READ core only (D-18): this module asks whether the
+// practice is minted, never how to mint it — the checker's writer half stays outside the read graph.
+import {
+  INITIAL_ADOPTION_REASON,
+  SOURCE_SIZE_GATE_ID,
+  SOURCE_SIZE_TOOL_PATH,
+  escapeForLine,
+  isLineUnsafe,
+  loadSourceSizeConfig,
+} from './source-size-core.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const KIT_ROOT = resolve(HERE, '..');
@@ -95,9 +106,11 @@ export const TRUST_CHAIN_DISCLOSURE =
 const USAGE = `usage: gates-init [--dry-run | --apply] [--only <id>]... [--cwd <dir>] [--help]
 
 The consented FILL preview for the project's own docs/ai/gates.json (D9). Default is --dry-run:
-prints the derived { id, title, cmd } entries and writes NOTHING. --apply APPENDS exactly the
-consented entries (--only <id> selects a subset; append-only — existing entries are never
-modified or removed, an id collision is refused). The offer is CLOSED-WORLD: only a
+prints the derived { id, title, cmd } entries and writes NOTHING. --apply WRITES exactly the
+consented entries (--only <id> selects a subset; add-only — existing entries are never modified,
+removed or reordered, an id collision is refused). A consented entry lands at the END, except that
+a non-checker entry goes BEFORE a declaration's trailing canonical coverage checker, which must
+stay last. The offer is CLOSED-WORLD: only a
 terminating-class script name (test / lint / type-check / build — never release/publish/deploy,
 never watch/serve, never a write-mode variant) whose BODY is a member of the literal runner
 allowlist is offered, as the hook-free \`COREPACK_ENABLE_NETWORK=0 <pm> exec -- <body>\` form for
@@ -410,6 +423,77 @@ export const flowCheckCandidate = (cwd, deps = {}) => {
   }
 };
 
+// The conditional SOURCE-SIZE candidate — keyed on the practice's own declaration rather than on a
+// recipe: the gate is offered ONLY over a MINTED docs/ai/source-size.json, because on any other
+// state the checker REFUSES by design (an absent config has no declared scope; an authored or
+// half-written one records nothing yet), and a declared gate that refuses is a matrix this preview
+// would have reddened on the user's behalf. The two states are told apart out loud: a project that
+// never declared the practice hears nothing (there is no offer to make), while one that authored it
+// and stopped short hears WHY the gate is not offered yet — the mint is the step it is missing.
+// A path is unrenderable when EITHER guard fires, and both are asked ONCE, before anything about
+// this candidate is printed. They are the same question wearing two coats: double-quoting cannot
+// survive a shell-active byte, and a line-unsafe byte cannot be printed at all — U+2028 quotes
+// perfectly and still breaks the line, so a surface screening only shell metacharacters lets it walk
+// into a declared gate cmd while reading as fully guarded.
+const unrenderableToolPath = (text) => isLineUnsafe(text) || DQ_UNSAFE_PATH_PATTERN.test(text);
+
+export const sourceSizeCandidate = (cwd, deps = {}) => {
+  const toolPath = deps.sourceSizeTool ?? SOURCE_SIZE_TOOL_PATH;
+  try {
+    const { state } = loadSourceSizeConfig(resolve(cwd), deps);
+    if (state === 'absent') return { candidate: null, note: null };
+    // Asked BEFORE the state branches: every branch below prints this path, so a check that only one
+    // of them performs is a guard the other silently lacks.
+    if (unrenderableToolPath(toolPath)) {
+      // The withheld path is NAMED, so it crosses the line-safety boundary before it is rendered —
+      // escaped rather than dropped, because two different paths must never print as the same one.
+      // The advice still follows the STATE: over an unminted record a hand-declared gate is red on
+      // every run, so pointing there would hand the reader their next failure as the way out.
+      const lane = state === 'minted'
+        ? 'declare the gate by hand'
+        : `mint the record first — run source-size-check.mjs --adopt --reason "${INITIAL_ADOPTION_REASON}" with the working directory set to this project, then declare the gate by hand`;
+      return {
+        candidate: null,
+        note:
+          `the source-size candidate was withheld: the resolved kit path cannot be rendered into a ` +
+          `command — it carries bytes that do not survive double-quoting, or a byte that cannot appear ` +
+          `in a printed line at all (${escapeForLine(toolPath)}) — ${lane}`,
+      };
+    }
+    if (state !== 'minted') {
+      // The named recovery is the reader's next keystroke, so it is a command they can actually run:
+      // the resolved absolute path and an explicit --cwd, carrying the reason a FIRST mint requires
+      // (recording a value for the first time is a raise, and the bare verb would refuse). The
+      // PROJECT path is screened by the same predicate — a rendered command naming a path the shell
+      // would read differently could run somewhere other than the project it names.
+      const project = resolve(cwd);
+      const recovery = unrenderableToolPath(project)
+        ? `run source-size-check.mjs --adopt --reason "${INITIAL_ADOPTION_REASON}" yourself, with the working directory set to this project (no command is printed: this project's path cannot be rendered into one)`
+        : `run node "${toolPath}" --adopt --reason "${INITIAL_ADOPTION_REASON}" --cwd "${project}"`;
+      return {
+        candidate: null,
+        note:
+          `the source-size candidate was withheld: the declared practice is not yet MINTED (${state}) — ` +
+          `the checker refuses until it records this tree, so declaring the gate now would red the matrix; ` +
+          `${recovery}, then re-run this preview`,
+      };
+    }
+    return {
+      candidate: {
+        id: SOURCE_SIZE_GATE_ID,
+        title: 'Source files within the declared size caps (the recorded ratchet)',
+        cmd: `node "${toolPath}" --check`,
+      },
+      note: null,
+    };
+  } catch (err) {
+    return {
+      candidate: null,
+      note: `the source-size practice config is unreadable (${err.message}) — the source-size candidate was not evaluated`,
+    };
+  }
+};
+
 // Every --only id must name an OFFERED entry — enforced in BOTH paths (dry-run and apply), before
 // any empty-offer shortcut, so a typo is a loud usage error, never a silent filter or a silent
 // "nothing to offer" success.
@@ -424,15 +508,16 @@ const assertOnlyIdsOffered = (offer, onlyIds = []) => {
   }
 };
 
-// The full offer: script entries + the conditional review-state / flow-check / coverage-check
-// candidates (coverage-check LAST — the `run-gates --final` declaration-shape rule requires the
-// checker as the last declared gate, so a whole-offer apply is final-ready by construction). The
-// pair keys on plan-execution.review reviewed/council OR a flow block (the P21 trio); flow-check
-// itself appears only under a flow block.
+// The full offer: script entries + the conditional review-state / flow-check / source-size /
+// coverage-check candidates (coverage-check LAST — the `run-gates --final` declaration-shape rule
+// requires the checker as the last declared gate, so a whole-offer apply is final-ready by
+// construction). The pair keys on plan-execution.review reviewed/council OR a flow block (the P21
+// trio); flow-check itself appears only under a flow block; source-size only over a minted practice.
 export const buildOffer = (cwd, deps = {}) => {
   const scripts = deriveScripts(cwd, deps);
   const rs = reviewStateCandidate(cwd, deps);
   const fc = flowCheckCandidate(cwd, deps);
+  const ss = sourceSizeCandidate(cwd, deps);
   const cc = coverageCheckCandidate(cwd, deps);
   // Decision 3 — the checker is never offered DEAD. The producer may come from this offer or from
   // a declaration the user already wrote by hand, so the rule reads the merged picture; a
@@ -462,7 +547,7 @@ export const buildOffer = (cwd, deps = {}) => {
   //   readable, no gate   → the claim and the advice both hold;
   //   readable, has gate  → a green matrix proves plenty and the user already declared their own.
   const declarationState =
-    existing.unreadable !== null ? 'unreadable' : existing.gates.some((gate) => !isReviewDependentGate(gate, cwd)) ? 'has-gate' : 'no-gate';
+    existing.unreadable !== null ? 'unreadable' : existing.gates.some((gate) => !isKitOwnedCheckerGate(gate, cwd)) ? 'has-gate' : 'no-gate';
   const noVerificationNote =
     scripts.entries.length > 0
       ? null
@@ -471,10 +556,10 @@ export const buildOffer = (cwd, deps = {}) => {
             ? `, and none is declared either, so a green matrix would prove only that the kit's own checkers ran; declare your own in ${GATES_REL}`
             : ''
         }`;
-  const candidates = [rs.candidate, fc.candidate, withholdCoverage ? null : cc.candidate].filter(Boolean);
+  const candidates = [rs.candidate, fc.candidate, ss.candidate, withholdCoverage ? null : cc.candidate].filter(Boolean);
   return {
     entries: [...scripts.entries, ...candidates],
-    notes: [...scripts.notes, noVerificationNote, unreadableNote, rs.note, fc.note, coverageNote].filter(Boolean),
+    notes: [...scripts.notes, noVerificationNote, unreadableNote, rs.note, fc.note, ss.note, coverageNote].filter(Boolean),
   };
 };
 
@@ -510,7 +595,7 @@ export const formatPreview = (offer, applyInvocation = null, { explicitOnly = fa
   return lines.join('\n');
 };
 
-// ── the existing declaration (append-only source) ──────────────────────────────────────
+// ── the existing declaration (the base every placement is computed against) ────────────
 const loadExistingDeclaration = (cwd, deps = {}) => {
   const read = deps.readFile ?? readFileSync;
   const lstat = deps.lstat ?? lstatSync;
@@ -572,7 +657,30 @@ const readStampValue = (cwd, deps = {}) => {
   }
 };
 
-// ── apply (append exactly the consented entries) ───────────────────────────────────────
+// ── the PLACEMENT rule (D-8) ───────────────────────────────────────────────────────────
+// WHERE a consented entry lands. A blind append made the fill unusable on exactly the declarations
+// it should serve best: the canonical coverage checker must be the LAST gate, so appending any
+// other entry after it produced a declaration the written-declaration validator correctly reds —
+// and the only way to consent to a new gate on a final-capable declaration was to hand-edit.
+//
+// The rule is one sentence: a non-checker entry goes BEFORE a trailing canonical checker, everything
+// else goes at the end. It is ADD-ONLY still — existing entries keep their relative order, none is
+// modified or removed; only the insertion point moves. A consented CHECKER stays after the trailing
+// one on purpose: two canonical checkers is a duplicate the validator must refuse by name, and
+// hiding that shape behind a clever placement would refuse it for the wrong reason.
+export const placeEntries = (existingGates, selected, projectDir) => {
+  const last = existingGates[existingGates.length - 1];
+  const isChecker = (gate) => canonicalCheckerGates([gate], projectDir).length === 1;
+  if (last === undefined || !isChecker(last)) return [...existingGates, ...selected];
+  return [
+    ...existingGates.slice(0, -1),
+    ...selected.filter((entry) => !isChecker(entry)),
+    last,
+    ...selected.filter(isChecker),
+  ];
+};
+
+// ── apply (write exactly the consented entries, each at its placement) ─────────────────
 export const applyFill = ({ cwd, onlyIds = [] }, deps = {}) => {
   assertDocsAiDeployment(cwd, deps, { stop, noun: 'a gate declaration', rel: GATES_REL });
   const stampValue = readStampValue(cwd, deps);
@@ -593,14 +701,14 @@ export const applyFill = ({ cwd, onlyIds = [] }, deps = {}) => {
   const collisions = selected.filter((e) => existingIds.has(e.id)).map((e) => e.id);
   if (collisions.length) {
     throw stop(
-      `id collision — already declared in ${GATES_REL}: ${collisions.join(', ')} (append-only: the ` +
+      `id collision — already declared in ${GATES_REL}: ${collisions.join(', ')} (add-only: the ` +
         `fill never modifies or removes an existing entry; pick the others with --only, or edit by hand)`,
     );
   }
 
   const merged = {
     _README: existing.outcome === 'loaded' && existing.readme !== undefined ? existing.readme : templateReadme(deps),
-    gates: [...existingGates, ...selected],
+    gates: placeEntries(existingGates, selected, cwd),
   };
   validateDeclaration(merged); // every written declaration passes the runner's validator, always
   // Decision 4 — the coverage invariant is enforced on the declaration that GETS WRITTEN, not on
@@ -610,7 +718,11 @@ export const applyFill = ({ cwd, onlyIds = [] }, deps = {}) => {
   if (defects.length) throw stop(`${defects[0].message} — nothing was written`);
   const body = `${JSON.stringify(merged, null, 2)}\n`;
   const { writtenPath } = writeDocsAiFileAtomic(cwd, GATES_REL, body, deps, { stop, noun: 'a gate declaration' });
-  return { outcome: 'written', writtenPath, appended: selected.map((e) => e.id), notes: offer.notes };
+  const placed = selected.map((e) => e.id);
+  // `appended` is the DEPRECATED alias of `placed`, carrying the same array: this result is a public
+  // tools/ payload, and dropping a field an external consumer reads would make a placement rule a
+  // BREAKING change. The name is the only thing that was ever wrong — the value never was.
+  return { outcome: 'written', writtenPath, placed, appended: placed, notes: offer.notes };
 };
 
 // ── CLI ────────────────────────────────────────────────────────────────────────────────
@@ -670,7 +782,7 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
       for (const note of result.notes) log(`  note: ${note}`); // the user learns WHY (same note as the preview)
       return EXIT_OK;
     }
-    log(`[agent-workflow-kit] appended ${result.appended.length} consented gate(s) to ${GATES_REL}: ${result.appended.join(', ')}`);
+    log(`[agent-workflow-kit] declared ${result.placed.length} consented gate(s) in ${GATES_REL}: ${result.placed.join(', ')}`);
     for (const note of result.notes) log(`  note: ${note}`); // a mixed offer never silently omits what was screened
     log(`[agent-workflow-kit] ${TRUST_CHAIN_DISCLOSURE}`);
     return EXIT_OK;

package/tools/procedures.mjs

@@ -5,7 +5,8 @@
 // steps LIVE from the installed agent-workflow-engine (references/procedures.md — AD-016 live read, no
 // bundled mirror), reads the per-project, hand-edited config (docs/ai/orchestration.json), runs the
 // read-only backend detector, and prints the activity's steps VERBATIM + the resolved effective recipe
-// per slot (default = Reviewed-when-a-backend-is-ready, Council on request, slot-aware incl. Delegated).
+// per slot (default = Reviewed-when-a-backend-is-ready, Council on request, slot-aware incl. Delegated),
+// plus the project's DECLARED source-size practice when it declares one (D-17 U1).
 //
 // Invariants (mirror recipes.mjs): pure-where-possible, READ-ONLY (never writes, never commits, never
 // runs a subscription CLI). The deterministic resolution lives in the kit (resolveActivityRecipe), not
@@ -44,6 +45,10 @@ import { AUTONOMY_REL, loadAutonomy, resolveAutonomy, isSparseSeedConfig } from
 // acyclic — pinned by test/read-graph-purity.test.mjs (FLOW-READ-GRAPH-PURITY).
 import { resolveFlowStorePath, readFlowStore } from './flow-store-read.mjs';
 import { CHAIN_KIND } from './flow-record.mjs';
+// The declared source-size practice (D-17 U1), read through the practice's PURE READ core — never
+// source-size-check.mjs, which owns the writer half: this advisor is a read root of
+// test/read-graph-purity.test.mjs, and the core exists so a surface can ask without reaching a writer.
+import { SOURCE_SIZE_CONFIG_REL, SOURCE_SIZE_WHY, loadSourceSizeConfig, practiceFacts } from './source-size-core.mjs';
 export { CONFIG_REL };
 
 // ── argument + override parsing (usage errors → exit 2) ─────────────────────────────
@@ -361,6 +366,49 @@ const flowHalvesAdvice = (flow, probe) => {
   ];
 };
 
+// ── the declared source-size practice (D-17 U1) ────────────────────────────────────
+// A practice the agent meets only when a gate refuses is a practice learned too late: the caps, their
+// reason and the plan-time rung ride EVERY named-activity render, so the layout is cut to them while
+// the plan is being written. Composed from the project's live declaration, never from constants here.
+// Each config state speaks as itself: ABSENT renders NOTHING (a project that declares no practice must
+// not be handed invented limits); AUTHORED and INCOMPLETE render the declared caps plus the honest
+// "nothing is recorded yet" line — both are pre-mint states, and treating INCOMPLETE as MINTED would
+// report a half record as the whole tree's debt; MINTED renders the recorded counts too.
+// A config that cannot be read renders ONE loud line carrying the reader's own message and the render
+// still completes: the exit code for a broken source-size config belongs to the practice's own
+// checker (exit 2 there, and its declared gate reds the matrix on it), while THIS tool's exit
+// contract is about its own config and the engine.
+
+export const DECLARED_PRACTICE_HEADER = `Declared source-size practice (${SOURCE_SIZE_CONFIG_REL}) — known BEFORE the code is written:`;
+
+const declaredPracticeAdvice = (cwd, readFile, lstat) => {
+  let declaration;
+  try {
+    declaration = loadSourceSizeConfig(cwd, { readFile, lstat });
+  } catch (err) {
+    return [`Declared source-size practice: UNREADABLE — ${(err && err.message) || err} — fix ${SOURCE_SIZE_CONFIG_REL} by hand; a declared practice is never guessed around.`];
+  }
+  if (declaration.state === 'absent') return [];
+  const facts = practiceFacts(declaration.config);
+  // The two pre-mint states share a LANE (the ratchet holds nothing, the mint step is next) but not a
+  // FACT: an incomplete file carries half the machine record, so "no size is recorded" would be a
+  // plain untruth about it — it names the missing half instead. Neither ever prints minted counts.
+  // The mint step is named, not rendered: on a project path that does not survive double-quoting the
+  // checker deliberately withholds a paste-ready command, and this advisor never re-decides that.
+  const unmintedRecord = declaration.state === 'incomplete'
+    ? `  recorded: PARTIAL — the machine record is half-written (missing ${declaration.missingMachineKeys.map((key) => `"${key}"`).join(', ')}), so the ratchet holds nothing yet; run \`source-size-check.mjs --check\` for the mint step.`
+    : '  recorded: NOTHING YET — the caps are declared but no size is recorded, so the ratchet holds nothing; run `source-size-check.mjs --check` for the mint step.';
+  return [
+    DECLARED_PRACTICE_HEADER,
+    `  caps: ${facts.maxLines} lines · ${facts.maxLineBytes} bytes per line, over ${facts.roots} declared root(s).`,
+    declaration.state === 'minted'
+      ? `  recorded: ${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.`
+      : unmintedRecord,
+    `  why: ${SOURCE_SIZE_WHY}`,
+    '  at plan time: every Step that CREATES a file names the file and its single responsibility, and the planned layout fits these caps — the gate is the backstop, never the teacher.',
+  ];
+};
+
 // The verbatim per-backend DRIVING CONTRACT block (M-contract): the exact invocation descriptor(s),
 // the closed flag set, the grounding note, the round-2/continue delta, and the guarded passthrough
 // tiers — every descriptor printed VERBATIM from the registry mirror of the bridge manifest
@@ -397,7 +445,7 @@ const contractLines = ({ cmd, contract, settings }) => {
   return lines;
 };
 
-const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flowHalves }) => {
+const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice }) => {
   const lines = [
     section,
     '',
@@ -417,6 +465,7 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
   const advice = reviewLoopAdvice(slots, activity);
   if (advice.length) lines.push('', ...advice);
   lines.push('', ...costLanesAdvice());
+  if (declaredPractice.length) lines.push('', ...declaredPractice);
   if (warnings.length) {
     lines.push('', 'warnings:');
     for (const w of warnings) lines.push(`  ⚠ ${w}`);
@@ -424,7 +473,7 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
   return lines.join('\n');
 };
 
-const buildJson = ({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves }) => ({
+const buildJson = ({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice }) => ({
   activity,
   section,
   slots: Object.fromEntries(
@@ -439,6 +488,9 @@ const buildJson = ({ activity, section, slots, configSource, warnings, plans, au
   costLanes: costLanesAdvice(),
   // ADDITIVE (AD-044 Plan 4): the per-activity autonomy block, structured (empty when unresolvable).
   autonomy: autonomyAdvice(activity, autonomy),
+  // ADDITIVE (D-17 U1): the SAME composed lines the human render prints — one array, two renders, so
+  // a scripted reader and a human can never be told different things about the declared practice.
+  declaredPractice,
   // CONDITIONAL (flow P8): the armed-halves block rides ONLY a flow-carrying config — the unarmed
   // JSON key set stays byte-exact (unarmed neutrality outranks the additive-key precedent).
   ...(flowHalves == null ? {} : { flowHalves }),
@@ -461,6 +513,12 @@ ${CONFIG_REL} + the read-only backend detector, and prints both. A per-run
 --override <slot>=<recipe> (repeatable) overrides the configured/default recipe for that slot.
 Read-only: never writes, never commits, never runs a subscription CLI.
 
+Also prints the project's DECLARED source-size practice (${SOURCE_SIZE_CONFIG_REL}) when it declares
+one — the caps, what is recorded, why the practice exists, and the plan-time rung — as the
+declaredPractice block (--json: the same lines under "declaredPractice"). A project with no such
+file renders nothing; a file that cannot be read renders ONE loud UNREADABLE line and still exits 0
+(the practice's own checker owns the exit code for its config).
+
 Exit codes: 0 success (an unsatisfiable override degrades loudly, still 0);
             2 usage (unknown activity / bad --override); 1 config or engine error
             (incl. a malformed ${AUTONOMY_REL} — the advisory still renders, the exit flips).`;
@@ -515,9 +573,10 @@ export const main = (argv, ctx = {}) => {
     // unarmed project keeps byte-identical output (human AND JSON) and never pays the store probe.
     const flowProbe = ctx.flowProbe ?? defaultFlowProbe;
     const flowHalves = config?.flow == null ? null : flowHalvesAdvice(config.flow, flowProbe(cwd));
+    const declaredPractice = declaredPracticeAdvice(cwd, readFile, lstat);
     const stdout = json
-      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves }), null, 2)
-      : formatHuman({ activity, section, slots, warnings, plans, autonomy, flowHalves });
+      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice }), null, 2)
+      : formatHuman({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice });
     if (autonomy?.error) {
       return { code: 1, stdout, stderr: `procedures: malformed ${AUTONOMY_REL} — ${autonomy.error}` };
     }

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,