@sabaiway/agent-workflow-kit 5.5.0 → 5.7.0

package/tools/gates-declaration.mjs

@@ -10,7 +10,8 @@ import { readFileSync, lstatSync, realpathSync } from 'node:fs';
 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 { isCoverageProducerGate } 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).
@@ -22,33 +23,40 @@ const EXIT_MALFORMED = 5;
 
 const GATE_ID_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const GATE_KEYS = Object.freeze(['id', 'title', 'cmd']);
+// The ONE optional gate key: the coverage-producer marker — a declared CLAIM that this gate writes
+// the lcov the canonical checker reads (coverage-producer.mjs owns what the claim means and why
+// recognition itself stays closed). Boolean only, and FORWARD-ONLY by design: an older kit has no
+// such key and rejects a marker-carrying declaration loudly here, which is the honest failure — it
+// could not honor the claim anyway.
+export const LCOV_PRODUCER_KEY = 'lcovProducer';
+const ALLOWED_GATE_KEYS = Object.freeze([...GATE_KEYS, LCOV_PRODUCER_KEY]);
 
 // ── declaration validation (malformed → exit 5, loud `path: reason`) ─────────────────
 
 // Validate a parsed gates.json object. Strict: only `_README` (string) + `gates` (array of
-// { id, title, cmd }) are allowed; unknown keys anywhere are rejected loudly — the declaration
-// names WHAT to check, never lanes/models/routing. Returns the validated gates array.
+// { id, title, cmd, lcovProducer? }) are allowed; unknown keys anywhere are rejected loudly — the
+// declaration names WHAT to check, never lanes/models/routing. Returns the validated gates array.
 export const validateDeclaration = (parsed) => {
   const reject = (reason) => {
     throw fail(EXIT_MALFORMED, `${GATES_REL}: ${reason}`);
   };
   if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    reject('must be a JSON object { "_README"?: string, "gates": [{ id, title, cmd }, ...] }');
+    reject('must be a JSON object { "_README"?: string, "gates": [{ id, title, cmd, lcovProducer? }, ...] }');
   }
   for (const key of Object.keys(parsed)) {
     if (key !== '_README' && key !== 'gates') reject(`unknown top-level key "${key}" (allowed: _README, gates)`);
   }
   if (parsed._README !== undefined && typeof parsed._README !== 'string') reject('"_README" must be a string');
-  if (!Array.isArray(parsed.gates)) reject('"gates" must be an array of { id, title, cmd }');
+  if (!Array.isArray(parsed.gates)) reject('"gates" must be an array of { id, title, cmd, lcovProducer? }');
   const seenIds = new Set();
   parsed.gates.forEach((gate, index) => {
     const at = `gates[${index}]`;
     if (gate === null || typeof gate !== 'object' || Array.isArray(gate)) {
-      reject(`${at}: must be an object { id, title, cmd }`);
+      reject(`${at}: must be an object { id, title, cmd, lcovProducer? }`);
     }
     for (const key of Object.keys(gate)) {
-      if (!GATE_KEYS.includes(key)) {
-        reject(`${at}: unknown key "${key}" (allowed: id, title, cmd — gates declare WHAT to check, never lane/model/routing)`);
+      if (!ALLOWED_GATE_KEYS.includes(key)) {
+        reject(`${at}: unknown key "${key}" (allowed: ${ALLOWED_GATE_KEYS.join(', ')} — gates declare WHAT to check, never lane/model/routing)`);
       }
     }
     for (const key of GATE_KEYS) {
@@ -56,6 +64,9 @@ export const validateDeclaration = (parsed) => {
         reject(`${at}: "${key}" must be a non-empty string`);
       }
     }
+    if (gate[LCOV_PRODUCER_KEY] !== undefined && typeof gate[LCOV_PRODUCER_KEY] !== 'boolean') {
+      reject(`${at}: "${LCOV_PRODUCER_KEY}" must be a boolean (only the literal true claims this gate writes the lcov the checker reads)`);
+    }
     if (/[\r\n]/.test(gate.cmd)) {
       reject(`${at}: "cmd" must be ONE bash command line — embedded newlines (a multi-line script) are rejected; chain with && or move the script into a file`);
     }
@@ -145,9 +156,12 @@ export const isFinalCapableDeclaration = (gates, projectDir) => {
 // index. ORDER is the whole question: a producer declared AFTER the checker writes the lcov too late,
 // so the checker reads nothing — or, worse, stale bytes an earlier run left behind — and still
 // passes. ONE home for the rule: the written-declaration defects below and the advisor's
-// inert-declaration item both decide through it, so they cannot drift apart.
+// inert-declaration item both decide through it, so they cannot drift apart. Producer-ness itself is
+// the canon's gate-level predicate (cmd closed-world OR the declared marker), so the slice is the
+// only thing this function owns — and the slice is what keeps a marker on the CHECKER from
+// self-pairing.
 export const coverageProducerPrecedes = (gates, checkerIndex) =>
-  gates.slice(0, checkerIndex).some((gate) => matchesCoverageProducer(gate.cmd));
+  gates.slice(0, checkerIndex).some((gate) => isCoverageProducerGate(gate));
 
 // coverageDeclarationDefects(gates, projectDir) → the WRITTEN-declaration coverage rule, as a list
 // of named defects (empty = satisfied): at most ONE canonical coverage checker; if one is present
@@ -174,7 +188,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 +217,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 { COVERAGE_PRODUCER_BODY, matchesCoverageProducer } from './coverage-producer.mjs';
+import { canonicalCheckerGates, coverageDeclarationDefects, isKitOwnedCheckerGate } from './gates-declaration.mjs';
+import { COVERAGE_PRODUCER_BODY, isCoverageProducerGate } 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,23 +508,27 @@ 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
   // declaration this preview cannot read degrades to a stated note, never to a silent withhold.
   const existing = declaredGatesBestEffort(cwd, deps);
+  // Both sides ask the ONE gate-level predicate. The offer side can only ever be a recognized cmd
+  // (this preview never EMITS the marker — it offers nothing it cannot verify), but a declaration
+  // the user wrote by hand may carry it, and the two sides must not answer through two predicates.
   const producerPresent =
-    scripts.entries.some((entry) => matchesCoverageProducer(entry.cmd)) ||
-    existing.gates.some((gate) => matchesCoverageProducer(gate.cmd));
+    scripts.entries.some((entry) => isCoverageProducerGate(entry)) ||
+    existing.gates.some((gate) => isCoverageProducerGate(gate));
   const withholdCoverage = cc.candidate !== null && !producerPresent;
   const coverageNote = withholdCoverage
     ? `the coverage-check candidate was withheld: nothing would PRODUCE the lcov it reads — no offered or ` +
@@ -462,7 +550,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 +559,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 +598,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 +660,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 +704,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 +721,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 +785,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/hide-footprint.mjs

@@ -444,6 +444,15 @@ export const hideFootprint = (opts = {}, deps = {}) => {
   const writtenPatterns = buildBlock(writtenList.map((c) => c.pattern));
   const needsUntrack = includedAsks.filter((a) => a.verdict === 'ask-tracked');
 
+  // The +N/−N delta against the CURRENT managed block (L3). The current set is the RAW fence body
+  // (canonicalized where recognized): a stale pattern the wholesale re-derive would silently drop
+  // is exactly what the removed list must surface.
+  const currentBlockPatterns = [...new Set(fenceBodyLines.map((l) => lineToPattern(l)).filter(Boolean).map((p) => recognizeHideRule(p) ?? p))];
+  const writtenSet = new Set(writtenPatterns);
+  const currentSet = new Set(currentBlockPatterns);
+  const added = writtenPatterns.filter((p) => !currentSet.has(p));
+  const removed = currentBlockPatterns.filter((p) => !writtenSet.has(p)).sort();
+
   // ── build the new file (splice the fence; preserve outside lines) ──────────────
   const fenceLines = writtenPatterns.length ? [START_MARKER, ...writtenPatterns, END_MARKER] : [];
   const newLines = writtenPatterns.length
@@ -471,6 +480,8 @@ export const hideFootprint = (opts = {}, deps = {}) => {
     action,
     visibility: 'hidden',
     wrote: writtenPatterns,
+    added,
+    removed,
     asks: asks.filter((a) => !includedAsks.some((i) => i.pattern === a.pattern)).map((a) => ({ path: a.pattern, reason: a.reason, owner: a.owner })),
     needsUntrack: needsUntrack.map((a) => {
       const target = patternToProbe(a.pattern).replace(/\/$/, '');
@@ -530,16 +541,23 @@ const fmtGlobal = (g) => {
   return [];
 };
 
-const formatReport = (r, dryRun) => {
+export const formatReport = (r, dryRun) => {
   const lines = [dryRun ? 'hide-footprint — DRY RUN (no changes)' : 'hide-footprint'];
-  if (r.visibility === 'visible') return [...lines, `  • deployment is VISIBLE (anchor ${r.anchor} is tracked) — nothing to hide; wrote zero bytes`].join('\n');
-  if (r.ambiguous) return [...lines, `  • AMBIGUOUS visibility (anchor ${r.anchor} is untracked AND not ignored) — cannot tell fresh-uncommitted from broken-hidden; ASK the user before writing`].join('\n');
+  if (r.visibility === 'visible') return [...lines, `  • deployment is VISIBLE (${r.anchor} is tracked) — nothing to hide; wrote zero bytes`].join('\n');
+  if (r.ambiguous) return [...lines, `  • AMBIGUOUS visibility (${r.anchor} is untracked AND not ignored) — cannot tell fresh-uncommitted from broken-hidden; ASK the user before writing`].join('\n');
   lines.push(`  • ${r.action} ${r.excludeFile}`);
   // The block contains every written pattern, but a TRACKED --include path is NOT hidden by it (it is
   // reported separately, below) — so the "hidden" line lists only the genuinely-hidden untracked paths.
   const untrackedOnly = new Set(r.needsUntrack.map((n) => n.path));
   const hiddenNow = r.wrote.filter((p) => !untrackedOnly.has(p));
   if (hiddenNow.length) lines.push(`  • hidden (${hiddenNow.length}): ${hiddenNow.join(', ')}`);
+  // The block delta (L3) — rendered in dry-run and apply alike; sets listed, never counted alone.
+  // --unhide and the reconcile no-op paths carry no delta fields: their reports stay unchanged.
+  if (Array.isArray(r.added) && Array.isArray(r.removed)) {
+    if (r.added.length) lines.push(`  • +${r.added.length} added: ${r.added.join(', ')}`);
+    if (r.removed.length) lines.push(`  • −${r.removed.length} removed: ${r.removed.join(', ')}`);
+    if (!r.added.length && !r.removed.length) lines.push('  • +0/−0 — the hidden set is unchanged');
+  }
   for (const a of r.asks) lines.push(`  • ASK ${a.path} — ${a.reason}`);
   for (const n of r.needsUntrack) lines.push(`  • tracked, NOT hidden: ${n.path} — run \`${n.command}\` to un-track (kept on disk)`);
   if (r.dropped.length) lines.push(`  • skipped ${r.dropped.length} already-ignored (tracked .gitignore)`);

package/tools/lens-region.mjs

@@ -172,6 +172,58 @@ export const frontmatterMaxLines = (text) => {
   return null;
 };
 
+// ── the outcome lines (pure composers — the CLI's one voice) ──────────────────────
+// Every user-facing outcome line the CLI prints, one pure composer per outcome, so the
+// composed-lines guard (test/composed-lines-ux.test.mjs) can render each against the L2
+// user-grade invariants. runCli only ever prints through this table. Raw diagnostics never ride
+// the human sentence: they land on the ONE machine-formatted detail line (`[lens-region]
+// error=<JSON-encoded>` — one line, reversible, control bytes escaped), the `[tool] key=value`
+// channel the L2 rule exempts by grammar. JSON.stringify leaves DEL/C1 and the U+2028/U+2029
+// separators raw, and a dynamic path can carry any byte — both dynamic parts are therefore made
+// line-safe explicitly: the machine value gains extra JSON escapes (still reversible), and the
+// human line collapses every control/separator byte to one space.
+const LINE_UNSAFE = new RegExp('[\\u007f-\\u009f\\u2028\\u2029]', 'g');
+const HUMAN_UNSAFE = new RegExp('[\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+', 'g');
+const escUnsafe = (c) => `\\u${c.codePointAt(0).toString(16).padStart(4, '0')}`;
+const ERROR_DETAIL = (raw) => `[lens-region] error=${JSON.stringify(String(raw)).replace(LINE_UNSAFE, escUnsafe)}`;
+const oneLine = (s) => String(s).replace(HUMAN_UNSAFE, ' ');
+
+export const OUTCOME_LINES = Object.freeze({
+  errorDetail: ERROR_DETAIL,
+  targetAbsent: (target) => `[lens-region] ${target} is absent — skipped (nothing to update; the file is seeded at bootstrap).`,
+  commsNoRegion: (target) => [
+    `[lens-region] no "${COMMS_LABEL}" section in ${target} — left untouched.`,
+    '[lens-region] note: the Communication section is absent or renamed — deployments seeded before it existed simply lack it; add it from the current template to enable refresh. Your file is never rewritten.',
+  ],
+  commsCurrent: () => '[lens-region] Communication section already current — nothing to do (zero-diff).',
+  commsCustom: () => [
+    '[lens-region] Communication section carries a custom edit — preserved verbatim.',
+    '[lens-region] note: the canonical Communication section has changed since this section was edited — compare it with the current template when convenient; your wording is never overwritten.',
+  ],
+  capSkipNote: () => '[lens-region] note: no `maxLines` frontmatter on the target — the line-cap guard is skipped.',
+  commsCapRefused: (target, count, cap) => `[lens-region] refused — refreshing the Communication section would push ${target} to ${count} lines (cap ${cap}); trim the file and re-run. The Communication section was not changed.`,
+  commsRefreshed: () => '[lens-region] refreshed the Communication section to the current canon.',
+  templateCanonStop: () => `[lens-region] STOP — the kit's bundled agent_rules.md template canon is unreadable; reinstall the kit: npx @sabaiway/agent-workflow-kit@latest init`,
+  lensNoRegion: (target) => [
+    `[lens-region] no "${HEADING_LABEL}" section in ${target} — left untouched.`,
+    '[lens-region] note: the planning/review lens section is missing or renamed — it cannot be auto-refreshed; restore the canonical heading to re-enable refresh.',
+  ],
+  engineTooOld: () => '[lens-region] skipped — the installed engine is too old (or incomplete) to supply the lens canon; refresh it with `npx @sabaiway/agent-workflow-engine@latest init`, then re-run.',
+  // The human line keeps the classified "methodology engine not found/invalid" contract; a typed
+  // error (engine-source attaches {stable, reason}) splits its raw reason onto the machine line.
+  engineStop: (err) => {
+    const human = `[lens-region] STOP — ${oneLine(err?.stable ?? err?.message ?? String(err))}`;
+    return err?.reason ? [human, ERROR_DETAIL(err.reason)] : [human];
+  },
+  lensCurrent: () => '[lens-region] lens section already current — nothing to do (zero-diff).',
+  lensCustom: () => [
+    '[lens-region] lens section carries a custom edit — preserved verbatim.',
+    '[lens-region] note: the canonical planning/review lens has changed since this section was edited — compare it with the project methodology canon when convenient; your wording is never overwritten.',
+  ],
+  lensCapRefused: (target, count, cap) => `[lens-region] refused — refreshing would push ${target} to ${count} lines (cap ${cap}); trim the file and re-run. The planning/review lens section was not changed.`,
+  lensRefreshed: () => '[lens-region] refreshed the planning/review lens section to the current canon.',
+});
+
 // ── CLI: `lens-region.mjs reconcile <path/to/agent_rules.md>` ─────────────────────
 // Outcome lines are the contract the upgrade/bootstrap prose relays in plain language; exit 0 on
 // every classified outcome (including the soft skips and the cap refusals), exit 1 ONLY on a
@@ -203,7 +255,7 @@ export const runCli = async (argv, deps = {}) => {
     }
   })();
   if (text === null) {
-    log(`[lens-region] ${argv[1]} is absent — skipped (nothing to reconcile; the substrate seeds it at bootstrap).`);
+    log(OUTCOME_LINES.targetAbsent(argv[1]));
     return 0;
   }
 
@@ -229,43 +281,41 @@ export const runCli = async (argv, deps = {}) => {
     }
   })();
   if (!templateRegion.found) {
-    logError(`[lens-region] reconcile STOP — the kit's bundled agent_rules.md template canon is unreadable${templateRegion.error ? ` (${templateRegion.error})` : ''}; reinstall the kit: npx @sabaiway/agent-workflow-kit@latest init`);
+    logError(OUTCOME_LINES.templateCanonStop());
+    if (templateRegion.error) logError(OUTCOME_LINES.errorDetail(templateRegion.error));
     return 1;
   }
   const commsResult = reconcileCommsText(text, normalizeCommsBody(templateRegion.body), COMMS_PRIORS);
   const currentText = await (async () => {
     if (commsResult.status === 'no-region') {
-      log(`[lens-region] no "${COMMS_LABEL}" section in ${argv[1]} — left untouched.`);
-      log('[lens-region] note: the Communication section is absent or renamed — deployments seeded before it existed simply lack it; add it from the current template to enable refresh. Your file is never rewritten.');
+      for (const line of OUTCOME_LINES.commsNoRegion(argv[1])) log(line);
       return text;
     }
     if (commsResult.status === 'current') {
-      log('[lens-region] Communication section already current — nothing to do (zero-diff).');
+      log(OUTCOME_LINES.commsCurrent());
       return text;
     }
     if (commsResult.status === 'custom') {
-      log('[lens-region] Communication section carries a custom edit — preserved verbatim.');
-      log('[lens-region] note: the canonical Communication section has changed since this section was edited — compare it with the current template when convenient; your wording is never overwritten.');
+      for (const line of OUTCOME_LINES.commsCustom()) log(line);
       return text;
     }
     const commsMax = frontmatterMaxLines(text);
     if (commsMax === null) {
-      log('[lens-region] note: no `maxLines` frontmatter on the target — the line-cap guard is skipped.');
+      log(OUTCOME_LINES.capSkipNote());
     }
     if (commsMax !== null && lineCount(commsResult.text) > commsMax) {
-      log(`[lens-region] refused — refreshing the Communication section would push ${argv[1]} to ${lineCount(commsResult.text)} lines (cap ${commsMax}); trim the file and re-run. The Communication section was not changed.`);
+      log(OUTCOME_LINES.commsCapRefused(argv[1], lineCount(commsResult.text), commsMax));
       return text;
     }
     await atomicWrite(commsResult.text);
-    log('[lens-region] refreshed the Communication section to the current canon.');
+    log(OUTCOME_LINES.commsRefreshed());
     return commsResult.text;
   })();
 
   // 3. No matching lens heading → preserve + advise, engine never consulted (the outcome is
   //    preserve regardless, so the lazy contract holds).
   if (!extractLensRegion(currentText).found) {
-    log(`[lens-region] no "${HEADING_LABEL}" section in ${argv[1]} — left untouched.`);
-    log('[lens-region] note: the planning/review lens section is missing or renamed — it cannot be auto-refreshed; restore the canonical heading to re-enable refresh.');
+    for (const line of OUTCOME_LINES.lensNoRegion(argv[1])) log(line);
     return 0;
   }
 
@@ -276,14 +326,14 @@ export const runCli = async (argv, deps = {}) => {
     detectEngine(dir, { source, rel: LENS_FRAGMENT_REL }).ok && detectEngine(dir, { source, rel: LENS_PRIORS_REL }).ok;
   if (!lensPairPresent) {
     if (detectEngine(dir, { source }).ok) {
-      log('[lens-region] skipped — the installed engine is too old (or incomplete) to supply the lens canon; refresh it with `npx @sabaiway/agent-workflow-engine@latest init`, then re-run.');
+      log(OUTCOME_LINES.engineTooOld());
       return 0;
     }
     try {
       readEngineFragment(dir, { source, rel: LENS_FRAGMENT_REL }); // throws the canonical install-me error
       return 1; // defensive: the pair is unusable — never proceed to a read
     } catch (err) {
-      logError(`[lens-region] reconcile STOP — ${err.message}`);
+      for (const line of OUTCOME_LINES.engineStop(err)) logError(line);
       return 1;
     }
   }
@@ -292,34 +342,35 @@ export const runCli = async (argv, deps = {}) => {
   let fragment;
   let priors;
   try {
-    fragment = readEngineFragment(dir, { source, rel: LENS_FRAGMENT_REL });
-    priors = parseLensPriors(readEngineFragment(dir, { source, rel: LENS_PRIORS_REL }));
+    // deps.engineRead is the injectable read primitive (tests drive the vanished/unreadable arm
+    // deterministically — a chmod-based fixture is root- and platform-dependent).
+    fragment = readEngineFragment(dir, { source, rel: LENS_FRAGMENT_REL, readFileSync: deps.engineRead });
+    priors = parseLensPriors(readEngineFragment(dir, { source, rel: LENS_PRIORS_REL, readFileSync: deps.engineRead }));
   } catch (err) {
-    logError(`[lens-region] reconcile STOP — ${err.message}`);
+    for (const line of OUTCOME_LINES.engineStop(err)) logError(line);
     return 1;
   }
 
   // 5. The pure decision + the cap-guard + one atomic write.
   const result = reconcileLensText(currentText, fragment, priors);
   if (result.status === 'current') {
-    log('[lens-region] lens section already current — nothing to do (zero-diff).');
+    log(OUTCOME_LINES.lensCurrent());
     return 0;
   }
   if (result.status === 'custom') {
-    log('[lens-region] lens section carries a custom edit — preserved verbatim.');
-    log('[lens-region] note: the canonical planning/review lens has changed since this section was edited — compare it with the project methodology canon when convenient; your wording is never overwritten.');
+    for (const line of OUTCOME_LINES.lensCustom()) log(line);
     return 0;
   }
   // refreshed → cap-guard from the TARGET's own frontmatter, then atomic write.
   const maxLines = frontmatterMaxLines(currentText);
   if (maxLines === null) {
-    log('[lens-region] note: no `maxLines` frontmatter on the target — the line-cap guard is skipped.');
+    log(OUTCOME_LINES.capSkipNote());
   } else if (lineCount(result.text) > maxLines) {
-    log(`[lens-region] refused — refreshing would push ${argv[1]} to ${lineCount(result.text)} lines (cap ${maxLines}); trim the file and re-run. The planning/review lens section was not changed.`);
+    log(OUTCOME_LINES.lensCapRefused(argv[1], lineCount(result.text), maxLines));
     return 0;
   }
   await atomicWrite(result.text);
-  log('[lens-region] refreshed the planning/review lens section to the current canon.');
+  log(OUTCOME_LINES.lensRefreshed());
   return 0;
 };