@event4u/agent-config 14.10.0 → 14.12.0

package/src/scripts/ai_council/quorum_wiring.ts

@@ -37,8 +37,9 @@ import {
     type QuorumCommand,
     type QuorumDispatch,
     type QuorumEventPhase,
+    type StanceAgreement,
 } from './events_log.js';
-import { evaluateQuorum, SOLO_FLOOR_MIN_PRESENT, type QuorumResult } from './quorum.js';
+import { evaluateQuorum, formatAttendanceCaveats, SOLO_FLOOR_MIN_PRESENT, withUnparsed, type QuorumResult } from './quorum.js';
 import { absentReasonFromCliFailure, classifyCliFailure } from './transport_resolver.js';
 
 type Dict = Record<string, unknown>;
@@ -117,6 +118,12 @@ export function _emitQuorumEvent(
          * absence is what the `false` on every line honestly records.
          */
         minPresent?: number;
+        /**
+         * Phase 3 — whether the seats agreed, when a stance tally ran.
+         * Omitted by every caller that ran none, which `appendQuorumEvent`
+         * records as `not_tallied` rather than as a bare `false`.
+         */
+        stanceAgreement?: StanceAgreement;
     },
 ): void {
     appendQuorumEvent({
@@ -128,6 +135,7 @@ export function _emitQuorumEvent(
         configuredTotal: ctx.configuredTotal ?? quorum.total,
         result: quorum,
         ...(ctx.minPresent !== undefined ? { minPresent: ctx.minPresent } : {}),
+        ...(ctx.stanceAgreement !== undefined ? { stanceAgreement: ctx.stanceAgreement } : {}),
         absent: absent.map(
             (a): QuorumAbsence => ({
                 member: String(a['member'] ?? ''),
@@ -154,9 +162,11 @@ export function _postRunQuorum(
     members: ExternalAIClient[],
     responses: CouncilResponse[],
     ai_cfg: Dict,
+    parse_outcomes?: ReadonlyMap<string, string>,
 ): { quorum: QuorumResult; absent: Dict[] } {
     const absent: Dict[] = [];
     let present = 0;
+    let unparsed = 0;
     for (let i = 0; i < members.length; i++) {
         const m = members[i] as ExternalAIClient;
         const r = responses[i];
@@ -167,7 +177,33 @@ export function _postRunQuorum(
         // banner printed `2/2 present` — a single-voice verdict presented as
         // convergence, on a paid run. An empty answer contributes nothing to a
         // quorum by definition, whatever the transport thought of it.
+        // Step 2.3 — the same argument, one rung further in. The byte check
+        // below settles "did the transport deliver anything"; it cannot settle
+        // "was what it delivered usable content", and a prose refusal passes it
+        // unchanged. So a member whose findings answer reached `parse_failed`
+        // is pulled out of `present` into its own bucket rather than folded
+        // into `N/N present`. It is NOT merged with the error cases: those are
+        // transport failures with an `AbsentReason` taxonomy the absent-member
+        // table renders, and re-labelling one of them `unparsed` would lose the
+        // auth/timeout/quota distinction. Hence the error branch below wins for
+        // a member that both errored and parsed badly — the transport failure
+        // is the stronger fact.
+        //
+        // `parse_outcomes` is optional because the run path derives it AFTER
+        // the post-run attendance event is emitted: the event stays a
+        // transport-level reading by design, and the rendered artefact is where
+        // AC-2 asks for the distinction. A caller with no map gets the exact
+        // pre-2.3 behaviour, key-for-key.
         if (r !== undefined && !r.error && r.text.trim() !== '') {
+            if (parse_outcomes?.get(m.name) === 'parse_failed') {
+                unparsed += 1;
+                absent.push({
+                    member: m.name,
+                    reason: 'unparsed',
+                    detail: 'answer present, no parser could read it',
+                });
+                continue;
+            }
             present += 1;
             continue;
         }
@@ -179,7 +215,46 @@ export function _postRunQuorum(
             detail: raw,
         });
     }
-    return { quorum: evaluateQuorum(members.length, present, _quorum_setting_from(ai_cfg)), absent };
+    return { quorum: evaluateQuorum(members.length, present, _quorum_setting_from(ai_cfg), unparsed), absent };
+}
+
+/**
+ * Which of the three agreement states a stance tally represents.
+ *
+ * `undefined` when no tally ran — the emitter records that as `not_tallied`,
+ * which is a fact ("nobody asked"), not a `false` that reads as disagreement.
+ * Returned as an optional rather than a nullable so the caller can spread it
+ * under `exactOptionalPropertyTypes`, where an explicit `undefined` and an
+ * absent key are different things.
+ */
+export function stanceAgreementOf(
+    tally: { consensus: unknown } | null,
+): StanceAgreement | undefined {
+    if (tally === null) {
+        return undefined;
+    }
+    return tally.consensus !== null ? 'consensus' : 'split';
+}
+
+/**
+ * Re-derive the rendered attendance line once the findings parser has spoken.
+ *
+ * Lives here rather than at the call site because it is the second half of the
+ * split `withUnparsed` documents: the post-run event stays a TRANSPORT-level
+ * reading so every rate over `events.log` keeps its denominator, and the
+ * rendered artefact is where AC-2 asks for the unparsed distinction. Counting
+ * `parse_failed` outcomes is the whole derivation; keeping it next to
+ * `_postRunQuorum` keeps both readings in one file.
+ */
+export function annotateRenderedQuorum(
+    quorum: QuorumResult | null,
+    parse_outcomes: ReadonlyMap<string, string> | null | undefined,
+): QuorumResult | null {
+    if (quorum === null || parse_outcomes === null || parse_outcomes === undefined) {
+        return quorum;
+    }
+    const unparsed = Array.from(parse_outcomes.values()).filter((o) => o === 'parse_failed').length;
+    return withUnparsed(quorum, unparsed);
 }
 
 /**
@@ -205,7 +280,9 @@ export function _format_quorum_line(q: QuorumResult, phase?: QuorumEventPhase):
     // a solo answer concludes, and nothing in the line distinguishes "both
     // members agreed" from "one member answered". The counts were always there;
     // what was missing is the word that stops a reader inferring convergence.
-    const degraded =
-        q.present < q.total ? `  ⚠️  DEGRADED — ${String(q.total - q.present)} member(s) did not answer; this is not convergence.` : '';
-    return `council:quorum · ${tag}${q.present}/${q.total} present, needed ${q.threshold} — ${verdict}.${degraded}`;
+    // Step 2.3 moved the wording into `formatAttendanceCaveats` so this line and
+    // its mirror in `orchestrator.ts` cannot drift apart, and added the
+    // present-unparsed clause there — see that function for why the two counts
+    // are disjoint.
+    return `council:quorum · ${tag}${q.present}/${q.total} present, needed ${q.threshold} — ${verdict}.${formatAttendanceCaveats(q)}`;
 }

package/src/scripts/ai_council/stance_tally.ts

@@ -218,6 +218,28 @@ export function tally_stances(
  * Render the **Vote Tally** verdict section: one line per option, the threshold,
  * and a cleared-or-escalated line. Deterministic — pure projection of the tally.
  */
+/**
+ * Tally the stance lines of a finished round, or `null` when tallying is off.
+ *
+ * Wraps the member-shape mapping so a caller does not re-derive it: an errored
+ * response has no stance line to read, and the member key is
+ * `provider:model` because that is what `parse_stance_line` records. Exists so
+ * ONE tally is computed per pass and reused — two tallies over the same
+ * responses are two chances to disagree, and the attendance event and the
+ * handoff envelope both consume this one.
+ */
+export function tallyFromResponses(
+    responses: ReadonlyArray<{ provider: string; model: string; text: string; error?: string | null }>,
+    enabled: boolean,
+): StanceTallyResult | null {
+    if (!enabled) {
+        return null;
+    }
+    return tally_stances(
+        responses.filter((r) => !r.error).map((r) => ({ member: `${r.provider}:${r.model}`, text: r.text })),
+    );
+}
+
 export function render_vote_tally(result: StanceTallyResult): string {
     const lines: string[] = ['### Vote Tally'];
     if (result.options.length === 0) {

package/src/scripts/bench_hook_latency.ts

@@ -580,6 +580,58 @@ export function perTurnComposite(
     };
 }
 
+/**
+ * A1.1 — append ONE composite reading to the durable store.
+ *
+ * The bench used to print the composite and discard it, which made
+ * `per_turn_composite.arming_precondition` ("at least 10 CI gate readings … from
+ * at least 2 distinct runner sessions") impossible to evaluate at all. This is
+ * the write half; `check_composite_arming.ts` is the read half.
+ *
+ * THE SESSION DISCRIMINATOR IS THE LOAD-BEARING FIELD, not the count. The
+ * precondition asks for two distinct runner SESSIONS because the instability it
+ * excludes was measured on ONE machine — a sibling metric read 44-157 % at n=12
+ * and 69-74 % at n=50 there — so twelve readings from one session is exactly the
+ * shape the floor rejects, and a bare counter cannot see the difference.
+ *
+ * A null composite is written as null rather than skipped. Dropping it silently
+ * would make the store's own length a lie about how many runs contributed, and
+ * the reader needs to distinguish "no run" from "a run whose slots were
+ * incomplete" — `perTurnComposite` returns null exactly because a composite over
+ * a subset reads LOW, and low is the direction that makes a ceiling look met.
+ */
+export function composeReadingRecord(
+    composite: { ms: number; parts: Record<string, number> } | null,
+    tool_calls: number,
+    env: NodeJS.ProcessEnv = process.env,
+): Record<string, unknown> {
+    // In CI a session is the workflow run on a given runner; locally it is the
+    // host plus the process's own start, so two consecutive local runs are
+    // distinguishable while one run's records stay grouped.
+    const ciRun = env['GITHUB_RUN_ID'];
+    const session =
+        ciRun !== undefined && ciRun !== ''
+            ? `gh-${ciRun}-${env['RUNNER_OS'] ?? os.platform()}-${env['GITHUB_RUN_ATTEMPT'] ?? '1'}`
+            : `local-${os.hostname()}-${String(process.pid)}`;
+    return {
+        composite_ms: composite === null ? null : composite.ms,
+        parts: composite === null ? null : composite.parts,
+        tool_calls,
+        session,
+        platform: `${os.platform()}-${os.arch()}`,
+        node: process.version,
+        commit: env['GITHUB_SHA'] ?? null,
+        run_id: ciRun ?? null,
+        recorded_at: new Date().toISOString(),
+    };
+}
+
+/** Append one JSONL record. Creates the file and its directory if absent. */
+export function appendReading(storePath: string, record: Record<string, unknown>): void {
+    fs.mkdirSync(path.dirname(storePath), { recursive: true });
+    fs.appendFileSync(storePath, `${JSON.stringify(record)}\n`, 'utf-8');
+}
+
 interface HistoryEntry {
     recorded_at: string;
     invocation_path: InvocationPath;
@@ -895,6 +947,16 @@ export function main(argv: string[] = process.argv.slice(2)): number {
             : perTurnComposite(results, compositeCfg.tool_calls ?? 10);
     if (compositeCfg !== undefined) {
         const calls = compositeCfg.tool_calls ?? 10;
+        // A1.1: persist the reading BEFORE the ceiling comparison below, so a run
+        // that fails the gate still contributes its number. A store that only
+        // gets the passing runs is biased in the direction that makes a ceiling
+        // look met, which is the same bias the null-composite rule guards.
+        const recIdx = argv.indexOf('--record-composite');
+        if (recIdx >= 0) {
+            const dest = argv[recIdx + 1] ?? path.join(REPO_ROOT, 'agents', 'evidence', 'hook-composite-readings.jsonl');
+            appendReading(dest, composeReadingRecord(composite, calls));
+            process.stdout.write(`recorded composite reading → ${path.relative(REPO_ROOT, dest)}\n`);
+        }
         if (composite === null) {
             process.stdout.write(
                 `ℹ️  per-turn composite not computed — a slot the definition needs is missing from this run\n`,

package/src/scripts/build_proof.ts

@@ -24,7 +24,11 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { REPO, LEDGER_REL, load_ledger, pointer_unresolved } from './check_claims.js';
-import { collect as collectEnforcement, summarise as summariseEnforcement } from './check_enforcement_coverage.js';
+import {
+    collect as collectEnforcement,
+    denominator_line as enforcementDenominatorLine,
+    summarise as summariseEnforcement,
+} from './check_enforcement_coverage.js';
 import { collectSkillGaps } from './check_skill_gaps.js';
 import { loadRows as loadComparisonRows } from './check_comparison.js';
 import { computeStatus as domainSoundnessStatus } from './domain_soundness_status.js';
@@ -415,6 +419,13 @@ function render(): string {
                 `${s.local_only} local-only · ${s.undeclared} undeclared (no \`enforced_by\` yet).`,
         );
         L.push('');
+        // The denominator, WITH the frame that produced it. Until 2026-08-23 the
+        // tree published five figures for this one property because every one was
+        // quoted without saying which population it was taken over. This line is
+        // the single sanctioned statement of it, and `check_enforcement_denominator`
+        // reds when a published doc restates a count instead of citing this block.
+        L.push(`\`${enforcementDenominatorLine(s.frames)}\``);
+        L.push('');
         L.push('| Rule | Effective level | Declared backstop(s) |');
         L.push('|---|---|---|');
         const declared = rows

package/src/scripts/capture_skill_catalogue.ts

@@ -434,11 +434,32 @@ function runLimitsMode(): number {
 /** The package's two projection-mode counts, one walk. Shared by both modes. */
 function projectionModeCounts(): ProjectionModeCounts {
     const stats = scoped_projection_stats(REPO, iter_skills());
+    // The tier split is a per-machine runtime artefact (gitignored), so absent is
+    // the normal state and must read as "unmeasured", never as zero.
+    let tierACount: number | null = null;
+    let tierBCount: number | null = null;
+    const tiersFile = path.join(REPO, 'agents', 'runtime', 'state', 'skill-tiers.json');
+    if (fs.existsSync(tiersFile)) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(tiersFile, 'utf-8')) as {
+                tier_a?: unknown;
+                tier_b?: unknown;
+            };
+            if (Array.isArray(parsed.tier_a) && Array.isArray(parsed.tier_b)) {
+                tierACount = parsed.tier_a.length;
+                tierBCount = parsed.tier_b.length;
+            }
+        } catch {
+            /* a malformed split is an absent split — never a partial count */
+        }
+    }
     return {
         scoped: stats.projected,
         legacyAll: stats.total,
         prunedUnderScoped: stats.pruned,
         activePacks: stats.active_packs,
+        tierACount,
+        tierBCount,
     };
 }
 

package/src/scripts/check_always_budget.ts

@@ -29,6 +29,7 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import YAML from 'yaml';
 
+import { asOf } from './_lib/as_of.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 // src/scripts/check_always_budget.ts → parents[2] is the repo root
@@ -435,7 +436,7 @@ function recordTrend(totalExt: number, sizes: Array<[string, number, number]>):
 
 /** datetime.now(timezone.utc).isoformat(timespec="seconds") → ...+00:00. */
 function isoSeconds(): string {
-    const d = new Date();
+    const d = asOf();
     const pad = (v: number): string => String(v).padStart(2, '0');
     return (
         `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}` +

package/src/scripts/check_augmentignore.ts

@@ -24,6 +24,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { asOfMs } from './_lib/as_of.js';
 import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const QUIET = process.argv.slice(2).includes('--quiet');
@@ -76,7 +77,7 @@ function check(): number {
     }
 
     const mtimeMs = fs.statSync(target).mtimeMs;
-    const age_days = (Date.now() - mtimeMs) / 86400000;
+    const age_days = (asOfMs() - mtimeMs) / 86400000;
     if (age_days > STALE_DAYS) {
         notes.push(
             `ℹ️  .augmentignore is ${Math.trunc(age_days)} days old (threshold: ${STALE_DAYS}) — ` +

package/src/scripts/check_beta_review_markers.ts

@@ -19,6 +19,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { asOf } from './_lib/as_of.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -185,7 +186,7 @@ function parse_args(argv: readonly string[]): ParsedArgs {
 
 /** Today's date as an ordinal, in local time (mirrors date.today()). */
 function _todayOrdinal(): number {
-    const now = new Date();
+    const now = asOf();
     return _dateOrdinal(now.getFullYear(), now.getMonth() + 1, now.getDate());
 }
 

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,