@sabaiway/agent-workflow-kit 5.6.0 → 5.7.0

package/tools/ensure-ops.mjs

@@ -0,0 +1,284 @@
+// ensure-ops.mjs — the FOUR upgrade ensure operations, one function each, behind one shared outcome
+// shape. The CLI that orders and runs them is ensure-configs.mjs; this module owns what each ensure
+// DOES and, more importantly, what it is allowed to CLAIM.
+//
+// Why they became code at all: `references/modes/upgrade.md` prescribed each of them as prose an agent
+// was expected to carry out by hand ("create it from the template if missing", "copy the pair from
+// references/scripts/ if missing"). A prescribed state-changing operation with no runnable command is
+// a step that silently varies per session — the feedback item this phase answers.
+//
+// The invariants every op holds (they are what the tests pin):
+//   • CREATE-ONLY seeds. A seed never clobbers: the write is the link-based create-only arm of
+//     atomic-write.mjs, so a file that appears between the probe and the write survives byte-for-byte
+//     and the op says `already-present` rather than reporting a write it did not do.
+//   • The DECISION lives where it already lived. The orchestration `_README` refresh asks
+//     orchestration-config.mjs (refreshReadme / the known-prior canonical set) and writes through
+//     orchestration-write.mjs — the file's one writer. Nothing here re-derives either.
+//   • Every token names a state this run PROVED. `already-present` follows a probe; `skipped-no-node`
+//     names the missing package.json; an ADR-layout read that fails is `adr-layout-unverifiable` and
+//     writes NOTHING (the STRICT survey, fail-closed — the lenient status wrapper reads an unreadable
+//     tree as `none`, which here would mean seeding a rotator beside a store nobody could inspect).
+//   • A failed op is a non-zero signal, never a line that reads like success.
+//
+// Dependency-free, Node >= 22. Every fs primitive is injectable (deps.*). No side effects on import.
+
+import { readFileSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { CANON_README, CONFIG_REL, SEED_CONFIG, loadConfig, normalizeCanonical, refreshReadme } from './orchestration-config.mjs';
+import { seedConfig, writeConfig } from './orchestration-write.mjs';
+import { lstatNoFollow, writeDocsAiFileAtomic, writeProjectFileCreateOnly } from './atomic-write.mjs';
+import { GATES_REL } from './gates-declaration.mjs';
+import { AUTONOMY_REL } from './autonomy-config.mjs';
+import { surveyAdrLayoutStrict } from './family-registry.mjs';
+import { ENSURE_TOKENS, FAILURE_CAUSES, SEED_SCRIPTS } from './ensure-vocabulary.mjs';
+
+// The closed vocabulary lives in its own PURE leaf so the read-only doc-parity lint can bind the
+// relayed token set without importing this module's writer graph. Re-exported here because every
+// consumer of the ops also speaks the vocabulary.
+export {
+  ENSURE_OPS,
+  ENSURE_TOKENS,
+  DRY_RUN_TOKENS,
+  FAILURE_CAUSES,
+  RELAYED_ENSURE_TOKENS,
+  SEED_SCRIPTS,
+  WRITE_TOKENS,
+} from './ensure-vocabulary.mjs';
+
+const PACKAGE_JSON = 'package.json';
+const SCRIPTS_DIR = 'scripts';
+
+const outcome = (op, token, lines, failed = false) => {
+  if (!ENSURE_TOKENS.includes(token)) {
+    throw new Error(`[agent-workflow-kit] unknown ensure outcome "${token}" — the token vocabulary is closed`);
+  }
+  return { op, token, failed, lines };
+};
+const ok = (op, token, ...lines) => outcome(op, token, lines, false);
+// A LOUD failure the doc gives its OWN token (today: malformed-preserved — the file is preserved, and
+// that is exactly what the reader must be told).
+const loudToken = (op, token, ...lines) => outcome(op, token, lines, true);
+// Every other LOUD failure: the token is always `failed`, the closed cause word opens the first line.
+const loud = (op, cause, ...lines) => {
+  if (!FAILURE_CAUSES.includes(cause)) {
+    throw new Error(`[agent-workflow-kit] unknown ensure failure cause "${cause}" — the cause vocabulary is closed`);
+  }
+  return outcome(op, 'failed', [`${cause} — ${lines[0]}`, ...lines.slice(1)], true);
+};
+
+// The closed-vocabulary DOOR, exported as a seam so the refusal itself is testable: EVERY outcome in
+// this module is composed through one of these two, and a word outside the closed sets throws here
+// instead of reaching a caller that has no idea how to relay it.
+export const composeOutcome = outcome;
+export const composeFailure = loud;
+
+const causeOf = (err) => String((err && err.message) || err);
+
+// The CLI's catch-all, here rather than there so EVERY outcome in the system — including the one
+// nobody planned for — is composed through the closed vocabulary. A throw that reached here is
+// `unexpected-error`: the cause word is still one of the closed set, and the thrown message follows
+// it (a bare `${op}: …` line would be the one failure in the system that names no cause).
+export const failedOutcome = (op, err) => loud(op, 'unexpected-error', `${op}: ${causeOf(err)}`);
+
+// `already-present` must mean a FILE is there. An lstat that merely finds SOMETHING would let a
+// directory or a symlink named gates.json report a green ensure while the declaration the project
+// needs does not exist — an exit 0 proving nothing (both review backends found this).
+const NODE_KIND = (st) => (st.isSymbolicLink() ? 'a symlink' : st.isDirectory() ? 'a directory' : 'not a regular file');
+const probeSeedTarget = (abs, lstat) => {
+  const st = lstatNoFollow(abs, lstat);
+  if (st === null) return { present: false };
+  return st.isFile() ? { present: true } : { present: true, wrongKind: NODE_KIND(st) };
+};
+
+// A leftover temp file never fails a completed write, and is never silent either.
+const tmpNote = (rel, tmpLeftBehind) =>
+  (tmpLeftBehind ? [`${rel}: the write stands, but its temp file could not be removed — delete it by hand: ${tmpLeftBehind}`] : []);
+
+// ── 1. orchestration.json — seed, or refresh ONLY a still-canonical onboarding note ────────────────
+
+// Which no-change outcome is it? refreshReadme returns `changed: false` for two very different trees:
+// a note that already IS the current canonical, and a note the user rewrote. Reporting both as
+// "already current" would claim the second is something it is not.
+const unchangedNoteToken = (config) =>
+  normalizeCanonical(config?._README ?? '') === normalizeCanonical(CANON_README) ? 'already-current' : 'customized-preserved';
+
+const applyNoteRefresh = (cwd, config, dryRun, deps) => {
+  const { config: next, changed } = refreshReadme(config);
+  if (!changed) {
+    const token = unchangedNoteToken(config);
+    return ok(
+      'orchestration',
+      token,
+      token === 'already-current'
+        ? `${CONFIG_REL}: the onboarding note is the current canonical — nothing written`
+        : `${CONFIG_REL}: the onboarding note carries your own wording — preserved verbatim, nothing written`,
+    );
+  }
+  if (dryRun) return ok('orchestration', 'would-refresh-note', `${CONFIG_REL}: the onboarding note matches a previous canonical and would be refreshed (every recipe you set is kept)`);
+  writeConfig(cwd, next, deps);
+  return ok('orchestration', 'note-refreshed', `${CONFIG_REL}: the onboarding note was refreshed to the current canonical (every recipe you set is kept)`);
+};
+
+// A load failure is not automatically "malformed": a file that VANISHED between the reader's own
+// lstat and its read surfaces as unreadable, and calling that preserved-and-malformed would state
+// two things this run did not observe. Probe once more and classify by what is there NOW.
+const loadFailureOutcome = (cwd, err, lstat, whenSeeding) => {
+  if (lstatNoFollow(join(cwd, CONFIG_REL), lstat) === null) {
+    return loud('orchestration', 'race-unresolved', `${CONFIG_REL}: could not be read and is not there now — something is creating and removing it underneath this run; nothing written, re-run when the tree is settled`);
+  }
+  const where = whenSeeding ? 'appeared while this run was seeding it, and ' : '';
+  return loudToken('orchestration', 'malformed-preserved', `${CONFIG_REL}: ${where}could not be read as the config it must be — preserved untouched, nothing written. ${causeOf(err)}`);
+};
+
+export const ensureOrchestration = ({ cwd, dryRun = false, deps = {} }) => {
+  const read = deps.readFile ?? readFileSync;
+  const lstat = deps.lstat ?? lstatSync;
+  // The KIND comes before the content: a symlink pointing at valid JSON parses fine and would report
+  // `already-current` over a file this ensure would refuse to write through — an exit 0 that proves
+  // nothing about the config the project actually has.
+  const kind = probeSeedTarget(join(cwd, CONFIG_REL), lstat);
+  if (kind.wrongKind) {
+    return loud('orchestration', 'wrong-node-kind', `${CONFIG_REL}: exists but is ${kind.wrongKind} — nothing was read or written; resolve it by hand, then re-run`);
+  }
+  let loaded;
+  try {
+    loaded = loadConfig(cwd, read, lstat);
+  } catch (err) {
+    // Malformed / unreadable: preserved untouched, and LOUD — clobbering a file we cannot parse would
+    // destroy hand-authored configuration to fix a note.
+    return loadFailureOutcome(cwd, err, lstat, false);
+  }
+  if (loaded.config !== null) return applyNoteRefresh(cwd, loaded.config, dryRun, deps);
+  if (dryRun) return ok('orchestration', 'would-seed', `${CONFIG_REL}: absent — would be created from the canonical seed`);
+
+  const { created, tmpLeftBehind } = seedConfig(cwd, SEED_CONFIG, deps);
+  const seedNote = tmpNote(CONFIG_REL, tmpLeftBehind);
+  if (created) return ok('orchestration', 'seeded', `${CONFIG_REL}: created from the canonical seed`, ...seedNote);
+  // It appeared between the probe and the write. Nothing was overwritten; read it once more and
+  // report what it now IS, rather than a claim about the file we did not write.
+  let second;
+  try {
+    second = loadConfig(cwd, read, lstat);
+  } catch (err) {
+    return loadFailureOutcome(cwd, err, lstat, true);
+  }
+  if (second.config === null) {
+    return loud('orchestration', 'race-unresolved', `${CONFIG_REL}: something is creating and removing this file underneath this run — nothing written; re-run when the tree is settled`, ...seedNote);
+  }
+  const refreshed = applyNoteRefresh(cwd, second.config, dryRun, deps);
+  return { ...refreshed, lines: [...refreshed.lines, ...seedNote] };
+};
+
+// ── 2/3. gates.json + autonomy.json — seed-if-missing, existing file preserved byte-for-byte ───────
+
+const seedFromTemplate = ({ op, rel, template, noun, cwd, kitRoot, dryRun, deps }) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const read = deps.readFile ?? readFileSync;
+  const probe = probeSeedTarget(join(cwd, rel), lstat);
+  if (probe.wrongKind) {
+    return loud(op, 'wrong-node-kind', `${rel}: exists but is ${probe.wrongKind} — nothing was written, and this is NOT a usable declaration; resolve it by hand, then re-run`);
+  }
+  if (probe.present) return ok(op, 'already-present', `${rel}: already present — preserved byte-for-byte, nothing written`);
+  if (dryRun) return ok(op, 'would-seed', `${rel}: absent — would be created from the bundled template`);
+  let body;
+  try {
+    body = String(read(join(kitRoot, 'references', 'templates', template), 'utf8'));
+  } catch (err) {
+    return loud(op, 'template-unreadable', `${rel}: the bundled template could not be read, so nothing was written — reinstall the kit. ${causeOf(err)}`);
+  }
+  const { created, tmpLeftBehind } = writeDocsAiFileAtomic(cwd, rel, body, deps, { noun, createOnly: true });
+  return created
+    ? ok(op, 'seeded', `${rel}: created from the bundled template`, ...tmpNote(rel, tmpLeftBehind))
+    : ok(op, 'already-present', `${rel}: appeared while this run was seeding it — the existing file stands, byte-for-byte`, ...tmpNote(rel, tmpLeftBehind));
+};
+
+export const ensureGates = ({ cwd, kitRoot, dryRun = false, deps = {} }) =>
+  seedFromTemplate({ op: 'gates', rel: GATES_REL, template: 'gates.json', noun: 'a gate declaration', cwd, kitRoot, dryRun, deps });
+
+export const ensureAutonomy = ({ cwd, kitRoot, dryRun = false, deps = {} }) =>
+  seedFromTemplate({ op: 'autonomy', rel: AUTONOMY_REL, template: 'autonomy.json', noun: 'an autonomy policy', cwd, kitRoot, dryRun, deps });
+
+// ── 4. scripts/ — the ADR-cascade enforcement pairs, detect-first ──────────────────────────────────
+
+// A project with no package.json at its root is not where Node enforcement scripts belong. Stated,
+// never silent: the token names the evidence, and the three config ensures still run.
+const isNodeProject = (cwd, lstat) => lstatNoFollow(join(cwd, PACKAGE_JSON), lstat) !== null;
+
+const OLD_ADR_LAYOUTS = new Set(['old', 'old-unrotated']);
+
+// The scripts ensure copies file by file, so a failure PARTWAY leaves earlier copies in place. Saying
+// so is the difference between a failure the reader can act on and one they read as "nothing happened"
+// — the CLI's summary therefore claims nothing about writes, and this line states the truth per op.
+const partialNote = (lines) => {
+  const copied = lines.filter((line) => line.includes(': copied from the bundled scripts')).length;
+  return copied > 0 ? [`the copying stopped PARTWAY — the ${copied} file(s) named above were already copied and are NOT rolled back`] : [];
+};
+
+export const ensureScripts = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const read = deps.readFile ?? readFileSync;
+  if (!isNodeProject(cwd, lstat)) {
+    return ok('scripts', 'skipped-no-node', `${SCRIPTS_DIR}/: no ${PACKAGE_JSON} at the project root — the seeded pairs are Node enforcement; nothing written`);
+  }
+  let layout;
+  try {
+    layout = surveyAdrLayoutStrict(cwd, deps);
+  } catch (err) {
+    return loud('scripts', 'adr-layout-unverifiable', `${SCRIPTS_DIR}/: the ADR-store layout could not be read, so nothing was written — a rotator seeded beside an un-migrated store reds the ADR gate. ${causeOf(err)}`);
+  }
+  if (OLD_ADR_LAYOUTS.has(layout)) {
+    return ok(
+      'scripts',
+      'old-adr-layout-migration-instructed',
+      `${SCRIPTS_DIR}/: this project is still on the older ADR layout (${layout}) — nothing written. Run the opt-in /agent-workflow-kit migrate-adr-store (it previews, and never commits); the seed lands on the next upgrade.`,
+    );
+  }
+  const lines = [];
+  let anyCreated = false;
+  for (const name of SEED_SCRIPTS) {
+    const rel = `${SCRIPTS_DIR}/${name}`;
+    const probe = probeSeedTarget(join(cwd, SCRIPTS_DIR, name), lstat);
+    if (probe.wrongKind) {
+      return loud('scripts', 'wrong-node-kind', `${rel}: exists but is ${probe.wrongKind} — that is not the enforcement script this run places`, ...lines, ...partialNote(lines));
+    }
+    if (probe.present) {
+      lines.push(`${rel}: already present — preserved, never overwritten`);
+      continue;
+    }
+    if (dryRun) {
+      lines.push(`${rel}: absent — would be copied from the bundled scripts`);
+      continue;
+    }
+    let body;
+    try {
+      body = String(read(join(kitRoot, 'references', 'scripts', name), 'utf8'));
+    } catch (err) {
+      return loud('scripts', 'bundle-unreadable', `${rel}: the bundled script could not be read — reinstall the kit. ${causeOf(err)}`, ...lines, ...partialNote(lines));
+    }
+    // The WRITE is caught here, not by the CLI's catch-all: a throw that escapes this loop would take
+    // the accumulated lines with it, and the run would report a failure without saying which files it
+    // had already copied.
+    let result;
+    try {
+      result = writeProjectFileCreateOnly(cwd, rel, body, deps, { noun: 'a seeded enforcement script' });
+    } catch (err) {
+      return loud('scripts', 'write-refused', `${rel}: ${causeOf(err)}`, ...lines, ...partialNote(lines));
+    }
+    anyCreated = anyCreated || result.created;
+    lines.push(result.created ? `${rel}: copied from the bundled scripts` : `${rel}: appeared while this run was seeding it — the existing file stands`);
+    lines.push(...tmpNote(rel, result.tmpLeftBehind));
+  }
+  if (dryRun) {
+    const wouldSeed = lines.some((line) => line.includes('would be copied'));
+    return outcome('scripts', wouldSeed ? 'would-seed' : 'already-present', lines, false);
+  }
+  return outcome('scripts', anyCreated ? 'seeded' : 'already-present', lines, false);
+};
+
+// The op table the CLI walks — name → implementation, in ENSURE_OPS order.
+export const ENSURE_IMPLEMENTATIONS = Object.freeze({
+  orchestration: ensureOrchestration,
+  gates: ensureGates,
+  autonomy: ensureAutonomy,
+  scripts: ensureScripts,
+});

package/tools/ensure-vocabulary.mjs

@@ -0,0 +1,71 @@
+// ensure-vocabulary.mjs — the CLOSED vocabulary of the upgrade ensures: which operations exist, which
+// outcome tokens they may print, which cause words may open a failure line, and which of those the
+// mode doc teaches.
+//
+// It is a PURE LEAF (no imports at all) for one reason: the read-only doc-parity lint binds the
+// relayed token set into `references/modes/upgrade.md`, and reading a vocabulary must never drag the
+// ensure implementation — and through it the orchestration WRITER and the atomic-write core — into a
+// read-only tool's import graph. Vocabulary here, behaviour in ensure-ops.mjs.
+
+// The FIXED order the CLI runs them in — the order references/modes/upgrade.md already prescribed.
+export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', 'scripts']);
+
+// Tokens that assert a WRITE happened. --dry-run may never emit one of these (the CLI's contract test
+// walks this set), and each has exactly one `would-` counterpart below.
+export const WRITE_TOKENS = Object.freeze(['seeded', 'note-refreshed']);
+export const DRY_RUN_TOKENS = Object.freeze(['would-seed', 'would-refresh-note']);
+
+// The CLOSED outcome vocabulary. Closed at RUNTIME, not by convention: composing an outcome with a
+// token outside this list throws, so an op cannot quietly invent a word the mode doc has never heard
+// of and the caller has no idea how to relay. EVERY operational failure prints the ONE token
+// `failed` and names its CAUSE at the head of its detail line — a specific token would read as
+// vocabulary the mode doc never taught (both review backends found exactly that).
+export const ENSURE_TOKENS = Object.freeze([
+  ...WRITE_TOKENS,
+  ...DRY_RUN_TOKENS,
+  'already-current',
+  'already-present',
+  'customized-preserved',
+  'malformed-preserved',
+  'skipped-no-node',
+  'old-adr-layout-migration-instructed',
+  'failed',
+]);
+
+// The closed CAUSE set — the word that opens a `failed` line. Closed for the same reason the tokens
+// are: the doc promises "a failed line names its cause", and this is that list. `unexpected-error`
+// is the honest cause for a throw nobody planned for: the failure is still named, never bare.
+export const FAILURE_CAUSES = Object.freeze([
+  'race-unresolved',
+  'template-unreadable',
+  'bundle-unreadable',
+  'adr-layout-unverifiable',
+  'wrong-node-kind',
+  'write-refused',
+  'unexpected-error',
+]);
+
+// The subset references/modes/upgrade.md enumerates, so the agent relaying an upgrade knows every
+// outcome by name. doc-parity binds each of these into that doc: a reworded doc that drops one fails
+// the check instead of silently teaching an outcome set the tool no longer has. The dry-run pair is
+// deliberately outside it — upgrade never runs the preview.
+export const RELAYED_ENSURE_TOKENS = Object.freeze([
+  'seeded',
+  'note-refreshed',
+  'already-current',
+  'customized-preserved',
+  'malformed-preserved',
+  'already-present',
+  'skipped-no-node',
+  'old-adr-layout-migration-instructed',
+  'failed',
+]);
+
+// The four files the enforcement-script ensure seeds (AD-051's ADR cascade + the tokenizer it needs).
+// Seed nothing else: the other tokenizer-era tests red beside an OLD archiver.
+export const SEED_SCRIPTS = Object.freeze([
+  'archive-decisions.mjs',
+  'archive-decisions.test.mjs',
+  'markdown-blocks.mjs',
+  'markdown-blocks.test.mjs',
+]);

package/tools/gates-declaration.mjs

@@ -10,7 +10,7 @@ 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
@@ -23,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) {
@@ -57,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`);
     }
@@ -146,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

package/tools/gates-init.mjs

@@ -62,7 +62,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { discoverGateCandidates, EXPECTED_WORKFLOW_VERSION } from './velocity-profile.mjs';
 import { GATES_REL, validateDeclaration } from './run-gates.mjs';
 import { canonicalCheckerGates, coverageDeclarationDefects, isKitOwnedCheckerGate } from './gates-declaration.mjs';
-import { COVERAGE_PRODUCER_BODY, matchesCoverageProducer } from './coverage-producer.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
@@ -523,9 +523,12 @@ export const buildOffer = (cwd, deps = {}) => {
   // 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 ` +

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