@event4u/agent-config 14.11.0 → 14.12.0

package/src/scripts/_lib/gate_baseline.ts

@@ -32,8 +32,10 @@
  * Dates are plain `YYYY-MM-DD`; ages are whole days in UTC, so the verdict does
  * not depend on the machine's timezone.
  */
+import { execFileSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import process from 'node:process';
 
 /** Days a baseline may sit unchanged before it must be fixed or reaffirmed. */
 export const STALE_AFTER_DAYS = 56;
@@ -105,12 +107,132 @@ export function loadBaselines(repoRoot: string, relPath: string = BASELINE_REL):
     } catch {
         return { gates: {} };
     }
+    return parseBaselines(raw);
+}
+
+function parseBaselines(raw: string): BaselineFile {
     const parsed = JSON.parse(raw) as Partial<BaselineFile>;
     const out: BaselineFile = { gates: parsed.gates ?? {} };
     if (parsed.$comment !== undefined) out.$comment = parsed.$comment;
     return out;
 }
 
+/**
+ * A baseline-resolution failure, which is a HARD error and never a fallback.
+ *
+ * `loadBaselines` returns an empty ratchet when the file is missing, and that
+ * is correct for a working-tree read: a repository with no baseline file has no
+ * ratchet. It is NOT correct for a target-commit read. There, a failure to
+ * resolve the ref or the blob means the governing policy could not be
+ * determined — and silently falling back to the working tree would let an
+ * infrastructure error change which policy applies, invisibly. The AI council
+ * was unanimous on this point (2026-08-25) and stated it applies to whichever
+ * invariant won.
+ */
+export class BaselineResolutionError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'BaselineResolutionError';
+    }
+}
+
+/**
+ * Read the baseline as it stands at a specific commit.
+ *
+ * `road-to-merge-surface-zero` Phase 3.1, under the **ABSOLUTE invariant** the
+ * AI council picked 2/2 on 2026-08-25 to resolve blocker B5.
+ *
+ * ## Why the target commit and not the merge base
+ *
+ * The merge-base read was the roadmap's original proposal and it selects the
+ * *contribution* invariant: a PR passes if it did not worsen the state it
+ * branched from. The worked example that killed it uses numbers this repository
+ * actually carries — `main` tightens `ci-parity:local-only` 165 → 160, a PR that
+ * branched earlier measures 163, the merge-base read returns 165, the PR
+ * **passes**, and after it merges `main` measures 163 against a baseline of 160.
+ * **A tightening is undone by a PR that never touched the baseline file and
+ * never saw a red.**
+ *
+ * The remedy of checking both was refused on a correctness ground rather than a
+ * preference: **violation counts are not necessarily compositional.** Conflict
+ * resolution, file movement, generated outputs and interactions with changes on
+ * `main` can make a prospective merge regress even when the isolated PR delta is
+ * non-positive. If trunk health is the invariant, the merge RESULT is what has
+ * to be measured.
+ *
+ * ## Why the TARGET commit specifically, and not the merge tree
+ *
+ * The count is measured on the prospective merge tree; the **policy** is read
+ * from the target. Reading the baseline out of the merge tree would let a PR
+ * loosen the very number it is being judged against, in the same diff.
+ *
+ * @throws BaselineResolutionError when the ref or the blob cannot be resolved.
+ */
+export function loadBaselinesAt(
+    repoRoot: string,
+    targetRef: string,
+    relPath: string = BASELINE_REL,
+    run: (args: string[]) => string = (args) =>
+        execFileSync('git', args, { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }),
+): BaselineFile {
+    let sha: string;
+    try {
+        sha = run(['rev-parse', '--verify', `${targetRef}^{commit}`]).trim();
+    } catch {
+        throw new BaselineResolutionError(
+            `cannot resolve target ref "${targetRef}" — the governing baseline is unknown, ` +
+                'and a working-tree fallback would let an infrastructure error decide the policy.',
+        );
+    }
+    let raw: string;
+    try {
+        raw = run(['show', `${sha}:${relPath}`]);
+    } catch {
+        throw new BaselineResolutionError(
+            `${relPath} does not exist at ${sha.slice(0, 9)} ("${targetRef}") — this is a ` +
+                'resolution failure, NOT an empty ratchet. A missing blob at a named commit ' +
+                'means the read was wrong, not that the ratchet is empty.',
+        );
+    }
+    try {
+        return parseBaselines(raw);
+    } catch {
+        throw new BaselineResolutionError(
+            `${relPath} at ${sha.slice(0, 9)} is not parseable JSON — refusing to continue ` +
+                'with an unknown policy.',
+        );
+    }
+}
+
+/**
+ * The merge-base reading, kept as a DIAGNOSTIC and never as the verdict.
+ *
+ * Both council seats asked for this explicitly. It does not decide pass/fail; it
+ * distinguishes two failures a reader cannot otherwise tell apart:
+ *
+ *   - `branch-regression` — the branch itself made the count worse. Fix the code.
+ *   - `main-tightened` — the branch is unchanged and `main` improved underneath
+ *     it. Rebase, then re-run.
+ *
+ * The distinction matters because the remediations differ, and one seat was
+ * pointed about the wording: "rebase and re-run" is incomplete advice for a PR
+ * that genuinely reintroduced violations, so a diagnostic must say which case it
+ * is rather than always suggesting a rebase.
+ */
+export type RegressionCause = 'branch-regression' | 'main-tightened' | 'none';
+
+export function diagnoseRegression(opts: {
+    actual: number;
+    targetBaseline: number;
+    mergeBaseBaseline: number | null;
+}): RegressionCause {
+    if (opts.actual <= opts.targetBaseline) return 'none';
+    if (opts.mergeBaseBaseline === null) return 'branch-regression';
+    // The branch is at or under the policy it branched from, and it still
+    // exceeds the target's policy: main tightened while this work was open.
+    return opts.actual <= opts.mergeBaseBaseline ? 'main-tightened' : 'branch-regression';
+}
+
 export interface RatchetOptions {
     /** Gate name — the key in the baseline file. */
     gate: string;
@@ -122,6 +244,12 @@ export interface RatchetOptions {
     baselineRel?: string;
     /** Override "now" as `YYYY-MM-DD` (tests); defaults to the current UTC date. */
     today?: string;
+    /**
+     * Read the governing baseline from this commit instead of the working tree.
+     * Defaults to `process.env[TARGET_REF_ENV]`; absent means a local run with
+     * no merge to judge, which is not the same as a failed resolution.
+     */
+    targetRef?: string;
 }
 
 /**
@@ -131,9 +259,30 @@ export interface RatchetOptions {
  * does not print or exit. A gate with no entry behaves exactly as it did before
  * the ratchet existed: any violation fails.
  */
+/**
+ * The env var that switches every ratchet onto the ABSOLUTE invariant at once.
+ *
+ * Set it to the target ref (`origin/main`, or the base SHA a PR job already
+ * knows) and all 18 `checkRatchet` call sites read the governing baseline from
+ * that commit instead of the working tree — no per-gate migration, no chance of
+ * migrating seventeen and forgetting one.
+ *
+ * **Unset is not a fallback.** A local run with no target configured has no
+ * merge to judge, so the working-tree read is the right and only answer there.
+ * What the council forbade is different and is honoured: a target that IS
+ * configured and fails to resolve throws, rather than quietly reverting to the
+ * working tree and changing the governing policy on an infrastructure error.
+ */
+export const TARGET_REF_ENV = 'GATE_BASELINE_TARGET_REF';
+
 export function checkRatchet(opts: RatchetOptions): BaselineVerdict {
     const { gate, actual } = opts;
-    const file = loadBaselines(opts.repoRoot, opts.baselineRel ?? BASELINE_REL);
+    const rel = opts.baselineRel ?? BASELINE_REL;
+    const target = opts.targetRef ?? process.env[TARGET_REF_ENV];
+    const file =
+        target !== undefined && target !== ''
+            ? loadBaselinesAt(opts.repoRoot, target, rel)
+            : loadBaselines(opts.repoRoot, rel);
     const entry = file.gates[gate];
 
     if (entry === undefined) {

package/src/scripts/_lib/skill_estate.ts

@@ -0,0 +1,115 @@
+/**
+ * The skill corpus, measured — the two dimensions `check_estate_count` ratchets.
+ *
+ * WHY TWO. A file count is what a `one_in_one_out` lint can express; it is not
+ * what a skill COSTS. Merging four large skills into one file satisfies a count
+ * ratchet while the description payload a host must carry stays put or grows.
+ * AI council 2/2 (2026-08-24) asked for both dimensions in one gate for exactly
+ * that reason, over the roadmap's own recommendation of a count plus an
+ * informational companion figure: "that supports treating tokens as a coarse
+ * secondary budget — not leaving the only cost-sensitive metric informational
+ * forever."
+ *
+ * WHY NOT THE OTHER TWO CANDIDATES, measured before asking rather than argued:
+ *
+ * - **Catalogue bytes** via `_lib/skill_catalogue.ts` read **0** on this
+ *   checkout. `readProjectedCatalogue` walks `.claude/skills`, which is empty in
+ *   any tree where `task generate-tools` cannot complete — it fails under
+ *   `projection.mode=scoped` without the config package. A ratchet whose reading
+ *   depends on whether a generator ran is a ratchet that reds for the
+ *   environment.
+ * - **Host-listing slots** are the host's decision, not the repository's. A
+ *   measured install published its own budget event stating it had stripped
+ *   every description and dropped 402 entries.
+ *
+ * DEPRECATED SKILLS ARE EXCLUDED, and that is load-bearing rather than tidy:
+ * with them counted, deprecating a skill would create no headroom and the
+ * retirement mechanism would be unusable against its own gate. (Currently 0
+ * skills carry it, so the exclusion is a no-op today and a correctness property
+ * tomorrow.)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { gpt_tokens } from './token_count.js';
+
+/** Where the corpus lives, POSIX — the same string a base-tree subtree takes. */
+export const SKILLS_POSIX = 'src/skills';
+
+export interface SkillEstate {
+    /** Maintained `SKILL.md` files — `lifecycle: deprecated` excluded. */
+    skill_count: number;
+    /**
+     * Exact-BPE tokens across the maintained skills' `description:` fields.
+     *
+     * `null` when the tokeniser could not resolve. A ratchet must never compare
+     * an exact reading against a proxy one — the numbers differ by more than the
+     * growth a gate is trying to catch, so the metric is reported UNRESOLVED
+     * rather than measured with whatever was available.
+     */
+    skill_description_tokens: number | null;
+    /** Excluded from both figures, reported so the exclusion is visible. */
+    deprecated_count: number;
+}
+
+/** `description:` from a `SKILL.md` frontmatter block, unquoted. */
+export function descriptionOf(text: string): string {
+    const fm = /^---\n([\s\S]*?)\n---/.exec(text);
+    if (fm === null) return '';
+    const m = /^description:\s*(.+)$/m.exec(fm[1]!);
+    if (m === null) return '';
+    return m[1]!.trim().replace(/^["']|["']$/g, '');
+}
+
+/** `lifecycle: deprecated` in the frontmatter — the retirement transition state. */
+export function isDeprecated(text: string): boolean {
+    const fm = /^---\n([\s\S]*?)\n---/.exec(text);
+    if (fm === null) return false;
+    return /^lifecycle:\s*["']?deprecated["']?\s*$/m.test(fm[1]!);
+}
+
+/**
+ * Measure the corpus under `root`.
+ *
+ * `root` is a repository root OR a materialised base-ref tree holding
+ * `src/skills/...`, so the floor side runs this exact function over the base
+ * ref's own tree — the property `check_estate_count` already has for the roadmap
+ * estate, and the reason the "before" side cannot be rewritten by the change
+ * under review.
+ */
+export function measureSkillEstate(root: string): SkillEstate {
+    const base = path.join(root, ...SKILLS_POSIX.split('/'));
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(base, { withFileTypes: true });
+    } catch {
+        return { skill_count: 0, skill_description_tokens: null, deprecated_count: 0 };
+    }
+    let count = 0;
+    let deprecated = 0;
+    let tokens = 0;
+    let exact = true;
+    for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!e.isDirectory()) continue;
+        const p = path.join(base, e.name, 'SKILL.md');
+        let text: string;
+        try {
+            text = fs.readFileSync(p, 'utf-8');
+        } catch {
+            continue;
+        }
+        if (isDeprecated(text)) {
+            deprecated += 1;
+            continue;
+        }
+        count += 1;
+        const r = gpt_tokens(descriptionOf(text));
+        if (!r.exact) exact = false;
+        tokens += r.tokens;
+    }
+    return {
+        skill_count: count,
+        skill_description_tokens: exact ? tokens : null,
+        deprecated_count: deprecated,
+    };
+}

package/src/scripts/ai_council/argument_exhaustion.ts

@@ -0,0 +1,130 @@
+/**
+ * The argument-exhaustion stop predicate, with the ordering encoded.
+ *
+ * `road-to-inbox-harvest-2026-08-e-council-topology-evidence` Phase 6.2, and the
+ * resolution of its `early-stop-vs-dissent-ordering` blocker.
+ *
+ * ## The ordering IS the substance
+ *
+ * Anti-conformity repair must fire **before** the cost stop, because
+ * **convergence may be conformity collapse rather than solution stability**. A
+ * round where everyone agrees because nobody pushed back looks, to a cost meter,
+ * exactly like a round where the argument is genuinely finished — and stopping
+ * there reports the collapse as consensus. That is the failure Phase 6 exists to
+ * prevent, so `dissentRepairAttempted` is a **required conjunct of the
+ * predicate**, not a soft check somewhere upstream that the predicate hopes ran.
+ *
+ * Encoding it as a conjunct rather than as call-order discipline is deliberate:
+ * a caller that forgets the order produces a wrong answer silently, while a
+ * caller that forgets to set the field produces `false` — the safe direction,
+ * and a visible one.
+ *
+ * ## Why all four, and why none of them is majority size
+ *
+ * A stop fires only when **every** condition holds:
+ *
+ * 1. `roundsCompleted >= MIN_ROUNDS` — one round is an opening statement, not an
+ *    argument. There is nothing to be exhausted yet.
+ * 2. `dissentRepairAttempted` — the conformity defence got its chance.
+ * 3. every present member is a self-near-duplicate of their own prior round —
+ *    the members have stopped adding, judged by the novelty logic that already
+ *    exists rather than by a new similarity measure.
+ * 4. no unresolved adversarial trigger — an open objection is unfinished
+ *    argument whatever the novelty numbers say.
+ *
+ * **Majority size is absent on purpose** (6.3). Unanimity is the single most
+ * available signal and the single least trustworthy one here: it is exactly what
+ * conformity collapse produces. A predicate that read it would stop soonest in
+ * precisely the case it must not.
+ *
+ * Everything here is pure and reads already-paid outputs — no model call, which
+ * is 6.1's contract and the reason this can be evaluated after every round for
+ * free.
+ */
+
+/** One round is an opening statement; exhaustion needs an exchange. */
+export const MIN_ROUNDS = 2;
+
+export interface StopInputs {
+    /** Rounds completed so far. */
+    roundsCompleted: number;
+    /**
+     * Whether anti-conformity repair ran for the round under judgement.
+     *
+     * The ordering conjunct. `false` when repair was skipped, deferred, or
+     * never reached — all three are the same thing to this predicate, because
+     * all three leave conformity collapse untested.
+     */
+    dissentRepairAttempted: boolean;
+    /**
+     * Per present member: did this round near-duplicate that member's own prior
+     * round? Absent members contribute no entry rather than a `false`.
+     */
+    selfNearDuplicate: readonly boolean[];
+    /** Adversarial triggers raised and not yet resolved. */
+    unresolvedAdversarialTriggers: number;
+}
+
+export type StopBlocker =
+    | 'too-few-rounds'
+    | 'dissent-repair-not-attempted'
+    | 'members-still-adding'
+    | 'unresolved-adversarial-trigger'
+    | 'no-members-present';
+
+export interface StopVerdict {
+    stop: boolean;
+    /** Every condition that failed, not just the first — a caller acting on one
+     *  reason at a time would re-evaluate N times to learn N blockers. */
+    blockers: StopBlocker[];
+}
+
+export function evaluateStop(x: StopInputs): StopVerdict {
+    const blockers: StopBlocker[] = [];
+
+    if (x.roundsCompleted < MIN_ROUNDS) blockers.push('too-few-rounds');
+
+    // The ordering conjunct. Deliberately evaluated as its own condition rather
+    // than folded into a caller-side guard: see the module docstring.
+    if (!x.dissentRepairAttempted) blockers.push('dissent-repair-not-attempted');
+
+    if (x.selfNearDuplicate.length === 0) {
+        // No present member is not "everyone is done" — it is no evidence at
+        // all. `every()` over an empty array is vacuously true, which would
+        // make an empty council the easiest one to stop.
+        blockers.push('no-members-present');
+    } else if (!x.selfNearDuplicate.every((d) => d)) {
+        blockers.push('members-still-adding');
+    }
+
+    if (x.unresolvedAdversarialTriggers > 0) blockers.push('unresolved-adversarial-trigger');
+
+    return { stop: blockers.length === 0, blockers };
+}
+
+/**
+ * The rendering contract for a stopped run (6.4).
+ *
+ * A stopped run must be **textually distinguishable** from a full one. The
+ * failure this prevents is quiet and expensive: an artifact that reads as though
+ * all configured rounds executed, when three of five did, is a claim about
+ * deliberation depth that nobody made on purpose.
+ */
+export interface StopRender {
+    roundsCompleted: number;
+    roundsConfigured: number;
+    savedCalls: number;
+    savedCostUsd: number;
+    exhaustedMembers: readonly string[];
+}
+
+export function renderStop(r: StopRender): string {
+    return [
+        `council: STOPPED EARLY — round ${String(r.roundsCompleted)} of ${String(r.roundsConfigured)}.`,
+        '  reason: argument exhaustion — every present member near-duplicated their own',
+        '          prior round, after anti-conformity repair had already been attempted.',
+        `  exhausted: ${r.exhaustedMembers.length > 0 ? r.exhaustedMembers.join(', ') : '(none named)'}`,
+        `  saved: ${String(r.savedCalls)} call(s), $${r.savedCostUsd.toFixed(4)}`,
+        '  NOT a full run: the remaining configured rounds did not execute.',
+    ].join('\n');
+}

package/src/scripts/check_bundle_path_leakage.ts

@@ -1,6 +1,41 @@
 #!/usr/bin/env tsx
 /**
- * Guard against build-machine path leakage in the tracked install bundle.
+ * Guard against build-machine path leakage in the tracked install bundle AND in
+ * published Markdown.
+ *
+ * ## The published-.md scope (road-to-inbox-harvest-2026-08-e-command-surface-legibility Phase 0)
+ *
+ * The bundle roots below were the original scope. A second population ships the
+ * same leak class: every `.md` inside `package.json` `files[]` — 1,079 files —
+ * and a `/Users/<name>/…` in a shipped skill is the same defect as one in
+ * `install.mjs`.
+ *
+ * **It is EXTENDED here rather than given a second gate**, deliberately: this one
+ * already runs in CI, already carries the patterns, the username masking and the
+ * `scan_scope` dead-scope protection, and a sibling gate would duplicate all
+ * four.
+ *
+ * ### Why the floor is ZERO UNAPPROVED and not the measured 11
+ *
+ * The published-.md baseline measured **11 hits in 8 files, none of them a leak**
+ * (`agents/evidence/analysis/published-md-path-leakage-baseline.md`): three
+ * documentation examples, six occurrences inside the rules that FORBID the
+ * pattern and must quote it, two legitimately absolute paths.
+ *
+ * A numeric floor of 11 was rejected by both council seats, 2026-08-24, for one
+ * reason: it lets an approved hit disappear while a real leak takes its slot, and
+ * the count stays 11. So the floor is **0 unapproved matches**, and the eleven are
+ * pinned exceptions in `.path-leak-allow` — line-pinned, so an entry that drifts
+ * off its line stops matching and the gate REDS, which is the safe direction.
+ *
+ * ### And why NOT "exempt matches inside backticks"
+ *
+ * That was the other candidate, and it was rejected on a false-negative argument
+ * both seats found decisive: **a real leaked path is commonly formatted as code**,
+ * so exempting inline code and fenced blocks opens a channel that hides exactly
+ * the defect this gate exists to catch. It would also hide a skill author's
+ * accidental real path inside an example block — the contribution path where this
+ * class is most likely to arrive.
  *
  * road-to-feedback-9.2.0-followups Phase 4.1. Three 9.1 commits
  * (f8752443b, 5933bf1a9, f30adb5a1) each rebuilt `dist/install/install.mjs`
@@ -75,6 +110,40 @@ const BUNDLE_ROOTS: readonly string[] = [
     'dist/cli-delegate',
 ];
 
+/**
+ * Published `.md` — the second population, derived from `package.json` `files[]`
+ * rather than guessed, so the scope is what the tarball actually ships. Roots
+ * only; the per-file filter below keeps it to `.md`.
+ */
+const PUBLISHED_MD_ROOTS: readonly string[] = [
+    'dist/agent-src',
+    'docs/guidelines',
+    'src/scripts',
+    // NOT `src/agent-src` wholesale: `files[]` ships only these two subtrees, and
+    // scanning the parent would gate content no consumer receives. Caught by this
+    // gate's own test, which asserts every root is inside `files[]`.
+    'src/agent-src/scripts',
+    'src/agent-src/templates/scripts',
+    'agents/templates',
+    'src/templates',
+    'src/config',
+];
+
+/** Named `.md` / text files `files[]` ships individually. */
+const PUBLISHED_MD_FILES: readonly string[] = [
+    'AGENTS.md',
+    'CHANGELOG.md',
+    'CONTRIBUTING.md',
+    'MIGRATION.md',
+    'README.md',
+    'docs/contracts/persona-schema.md',
+    'docs/contracts/provider-lifecycle.md',
+    'docs/contracts/settings-classes.md',
+];
+
+/** Repo-root allow file for audited published-`.md` exceptions. */
+const ALLOW_FILE = '.path-leak-allow';
+
 interface LeakPattern {
     readonly name: string;
     readonly re: RegExp;
@@ -192,6 +261,49 @@ function _splitlines(text: string): string[] {
     return text.split('\n').filter((l) => l.length > 0);
 }
 
+/**
+ * Parse `.path-leak-allow` into `path:line` keys.
+ *
+ * Line-pinned on purpose, and the trade-off is the same one `.secret-allow`
+ * documents for itself: an entry that drifts off its line stops matching and the
+ * gate REDS. That is the safe direction — someone re-audits and moves the pin —
+ * whereas a path-only entry would silently allow a real leak anywhere in the
+ * file. This tree has already been bitten by the opposite: a `.secret-allow` pin
+ * sat one line off on `main` for a day, covering nothing, invisible because that
+ * gate is diff-scoped.
+ */
+export function parse_allow_file(text: string): Set<string> {
+    const out = new Set<string>();
+    for (const raw of text.split('\n')) {
+        const line = raw.replace(/#.*$/, '').trim();
+        if (line === '') continue;
+        out.add(line);
+    }
+    return out;
+}
+
+function allow_set(): Set<string> {
+    try {
+        return parse_allow_file(fs.readFileSync(path.join(REPO, ALLOW_FILE), 'utf-8'));
+    } catch {
+        return new Set();
+    }
+}
+
+/** Every tracked `.md` inside the published roots, plus the named files. */
+function tracked_published_md(): string[] {
+    const seen = new Set<string>();
+    for (const root of PUBLISHED_MD_ROOTS) {
+        for (const rel of _splitlines(_git(['ls-files', root]))) {
+            if (rel.endsWith('.md')) seen.add(rel);
+        }
+    }
+    for (const rel of PUBLISHED_MD_FILES) {
+        for (const got of _splitlines(_git(['ls-files', rel]))) seen.add(got);
+    }
+    return [...seen].sort();
+}
+
 /** Every tracked path under the bundle roots, deduped and sorted. */
 function tracked_bundle_files(): string[] {
     const seen = new Set<string>();
@@ -291,7 +403,12 @@ function parse_args(argv: readonly string[]): Options {
 
 function main(argv: readonly string[] = process.argv.slice(2)): number {
     const opts = parse_args(argv);
-    const targets = opts.files.length > 0 ? opts.files : tracked_bundle_files();
+    const bundle = opts.files.length > 0 ? opts.files : tracked_bundle_files();
+    // Published `.md` joins the default target list. With explicit `--file`
+    // arguments it does NOT — an ad-hoc single-file run stays a single-file run,
+    // which is what the existing tests and the pre-push path rely on.
+    const published = opts.files.length > 0 ? [] : tracked_published_md();
+    const targets = [...bundle, ...published];
 
     // `git ls-files <untracked-root>` returns nothing, by design (BUNDLE_ROOTS
     // lists roots that may not be tracked yet). That tolerance is also the
@@ -305,8 +422,11 @@ function main(argv: readonly string[] = process.argv.slice(2)): number {
         assertScanned({
             gate: 'check_bundle_path_leakage',
             scanned: targets.length,
-            units: 'bundle file(s)',
-            roots: opts.files.length > 0 ? ['<explicit file arguments>'] : BUNDLE_ROOTS,
+            units: 'bundle + published-md file(s)',
+            roots:
+                opts.files.length > 0
+                    ? ['<explicit file arguments>']
+                    : [...BUNDLE_ROOTS, ...PUBLISHED_MD_ROOTS],
         });
     } catch (exc) {
         if (exc instanceof DeadScopeError) {
@@ -316,17 +436,48 @@ function main(argv: readonly string[] = process.argv.slice(2)): number {
         throw exc;
     }
 
-    const hits = scan_files(targets);
+    const allowed = allow_set();
+    const all = scan_files(targets);
+    // The floor is ZERO UNAPPROVED, never a count. A pinned exception that has
+    // drifted off its line simply stops matching, so the hit resurfaces and the
+    // gate reds — deliberately, per the header.
+    const hits = all.filter((h) => !allowed.has(`${h.file}:${String(h.line)}`));
+    const suppressed = all.length - hits.length;
 
     if (hits.length > 0) {
         process.stderr.write(`${format_report(hits)}\n`);
+        // The per-pattern hints are bundle-shaped ("rebuild from a clean
+        // checkout"), which is the wrong instruction for a `.md` hit — nothing is
+        // rebuilt to fix prose. Published-md hits get their own line rather than
+        // a misleading one.
+        if (hits.some((h) => h.file.endsWith('.md'))) {
+            process.stderr.write(
+                `   NOTE: a \`.md\` hit is not fixed by rebuilding. Either anonymise the path,\n` +
+                    `   or — if it IS the pattern being documented — pin it in ${ALLOW_FILE}.\n`,
+            );
+        }
+        if (suppressed > 0) {
+            process.stderr.write(
+                `   (${suppressed} further match(es) are pinned exceptions in ${ALLOW_FILE})\n`,
+            );
+        }
+        process.stderr.write(
+            `   A published-.md match that is the PATTERN BEING DOCUMENTED — a rule quoting\n` +
+                `   the shape it forbids, or an anonymised example — belongs in ${ALLOW_FILE}\n` +
+                `   as \`<path>:<line>\` with its reason above it. A real path does not.\n`,
+        );
         return 1;
     }
 
     if (!opts.quiet) {
+        // A gate that scans nothing and exits green is indistinguishable from a
+        // broken one, so the green path names both populations and the
+        // suppression count — an exception set that quietly grows is the failure
+        // mode a bare "no leakage" line would hide.
         process.stdout.write(
-            `✅  check_bundle_path_leakage: no build-machine path leakage ` +
-                `(${targets.length} tracked bundle file(s) scanned).\n`,
+            `✅  check_bundle_path_leakage: no unapproved path leakage ` +
+                `(${String(bundle.length)} bundle + ${String(published.length)} published-md ` +
+                `file(s) scanned, ${String(suppressed)} pinned exception(s)).\n`,
         );
     }
     return 0;
@@ -359,6 +510,10 @@ if (_isCliEntry() || process.argv[1] === _HERE) {
 export {
     REPO,
     BUNDLE_ROOTS,
+    PUBLISHED_MD_ROOTS,
+    PUBLISHED_MD_FILES,
+    ALLOW_FILE,
+    tracked_published_md,
     LEAK_PATTERNS,
     MAX_SNIPPET,
     MAX_HITS_SHOWN_PER_GROUP,