@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/check_no_currency_in_cost_surfaces.ts

@@ -0,0 +1,225 @@
+#!/usr/bin/env tsx
+/**
+ * No cost surface built by `road-to-delivered-cost-truth` prints a currency
+ * figure or a per-token rate (AC-7).
+ *
+ * WHY THIS IS A GATE AND NOT A CONVENTION
+ * ---------------------------------------
+ * The suite does not know a consumer's contract — subscription, per-token,
+ * committed spend, a reseller rate — so any monetary figure it printed would be
+ * extrapolated from a rate it invented. That is worse than no number, because it
+ * is actionable and wrong, and it is exactly the kind of thing that gets added
+ * back later by someone who reasonably thinks a cost report should show cost.
+ *
+ * SCOPE IS A NAMED LIST, NOT A PATTERN. The gate guards the surfaces this
+ * roadmap built, and nothing else: `cache_realization_report` legitimately
+ * carries a `cost_usd` block for back-compat with downstream consumers, and a
+ * gate that swept `src/scripts/*cost*` would fail on it and be neutered with an
+ * allowlist within a release.
+ *
+ * Exit codes: 0 clean · 1 a currency marker on a guarded surface · 2 misuse.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/check_no_currency_in_cost_surfaces [--root <dir>] [--quiet]
+ *   ./scripts-run src/scripts/check_no_currency_in_cost_surfaces --self-test
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { CURRENCY_MARKERS } from './_lib/config_cost.js';
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
+import { assertWatchlistResolves, DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+
+const HERE = path.dirname(new URL(import.meta.url).pathname);
+const REPO_ROOT = path.resolve(HERE, '..', '..');
+
+/** The surfaces this roadmap built. A named list, deliberately. */
+export const GUARDED_SURFACES: readonly string[] = [
+    'src/scripts/config_cost_report.ts',
+    'src/scripts/asset_delivery_ledger.ts',
+    'src/scripts/_lib/config_cost.ts',
+    'src/scripts/_lib/asset_delivery_ledger.ts',
+];
+
+/**
+ * Lines that may name a marker without printing one.
+ *
+ * A gate over currency SYMBOLS cannot read intent, and every guarded file has to
+ * be able to explain the ban — including `CURRENCY_MARKERS` itself, which is a
+ * list of the very strings being banned. Comments and the marker declaration are
+ * therefore out of scope, and the discriminator is whether the string can reach
+ * a rendered line.
+ */
+function isExempt(line: string): boolean {
+    const t = line.trim();
+    return t.startsWith('*') || t.startsWith('//') || t.startsWith('/*') || t.includes('CURRENCY_MARKERS');
+}
+
+/**
+ * Source-level patterns, derived from {@link CURRENCY_MARKERS} with ONE
+ * exception that the self-test found and that matters more than it looks.
+ *
+ * A bare `$` substring matches TEMPLATE-LITERAL INTERPOLATION — `${value}` — so
+ * the first cut of this gate flagged every interpolated line in every guarded
+ * file, including its own ledger renderer. A gate whose first real run produces
+ * dozens of false positives gets an allowlist within a release, and then it
+ * guards nothing.
+ *
+ * Excluding `${` alone was not enough — a REGEX ANCHOR is also a bare `$`, and
+ * the second run flagged `/\.md$/`. Both false positives share a shape: `$`
+ * appears constantly in TypeScript for reasons that have nothing to do with
+ * money.
+ *
+ * So the pattern is positive rather than subtractive: a currency `$` is followed
+ * by a DIGIT (`$42`) or by an interpolated amount (`$${n}`). Anchors, plain
+ * interpolation and `$` inside identifiers all fall outside it. Both directions
+ * are pinned by self-test cases — a rejecting `$${n}` and an accepting anchor —
+ * because a positive pattern that is too narrow fails silently.
+ *
+ * The companion `isCurrencyFree` keeps plain substring matching, correctly: it
+ * reads RENDERED output, where no template or regex syntax survives and a `$` is
+ * a dollar sign.
+ */
+export const SOURCE_PATTERNS: ReadonlyArray<{ marker: string; re: RegExp }> = CURRENCY_MARKERS.map((m) => ({
+    marker: m,
+    re: m === '$' ? /\$(?=\d|\$\{)/ : new RegExp(m.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')),
+}));
+
+export interface Finding {
+    file: string;
+    line: number;
+    marker: string;
+    text: string;
+}
+
+export function scanFile(source: string, rel: string): Finding[] {
+    const out: Finding[] = [];
+    source.split('\n').forEach((line, i) => {
+        if (isExempt(line)) return;
+        for (const p of SOURCE_PATTERNS) {
+            if (p.re.test(line)) out.push({ file: rel, line: i + 1, marker: p.marker, text: line.trim().slice(0, 100) });
+        }
+    });
+    return out;
+}
+
+export function evaluate(root: string = REPO_ROOT, ledger?: GateLedger): { scanned: number; findings: Finding[] } {
+    const findings: Finding[] = [];
+    let scanned = 0;
+    ledger?.plan(GUARDED_SURFACES);
+    for (const rel of GUARDED_SURFACES) {
+        const abs = path.join(root, rel);
+        if (!fs.existsSync(abs)) {
+            ledger?.skip(rel, 'no_applicable_files');
+            continue;
+        }
+        scanned += 1;
+        const hits = scanFile(fs.readFileSync(abs, 'utf-8'), rel);
+        findings.push(...hits);
+        if (hits.length > 0) ledger?.fail(rel, `${String(hits.length)} currency marker(s)`);
+        else ledger?.complete(rel);
+    }
+    return { scanned, findings };
+}
+
+// ---------------------------------------------------------------- self-test
+
+function selfTestCases(): SelfTestCase[] {
+    const mk = (name: string, expect: 'reject' | 'accept', body: string): SelfTestCase => ({
+        name,
+        expect,
+        run: () => {
+            const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cur-'));
+            try {
+                fs.mkdirSync(path.join(dir, 'src', 'scripts', '_lib'), { recursive: true });
+                for (const rel of GUARDED_SURFACES) fs.writeFileSync(path.join(dir, rel), body);
+                return runGateCli(REPO_ROOT, 'src/scripts/check_no_currency_in_cost_surfaces.ts', ['--root', dir, '--quiet'], REPO_ROOT);
+            } finally {
+                fs.rmSync(dir, { recursive: true, force: true });
+            }
+        },
+    });
+    return [
+        mk('a dollar figure in rendered output → reject', 'reject', `out.push(\`cost: $\${n}\`);\n`),
+        mk('a euro figure → reject', 'reject', `out.push(\`Kosten: €\${n}\`);\n`),
+        mk('a per-token rate → reject', 'reject', `out.push('rate: 3.00 per token');\n`),
+        mk('a USD label → reject', 'reject', `out.push('total USD');\n`),
+        mk('tokens only → accept', 'accept', `out.push(\`\${n} tok\`);\n`),
+        // Both false positives the first two runs produced, pinned so a future
+        // widening of the pattern cannot reintroduce them silently.
+        mk('a regex end anchor is not a dollar sign → accept', 'accept', `const x = /\\.md$/.test(name);\n`),
+        mk('plain interpolation is not a dollar sign → accept', 'accept', 'out.push(`${a} of ${b}`);\n'),
+        mk('a comment explaining the ban → accept', 'accept', `// never print $ or EUR here\nout.push('tok');\n`),
+        mk('the marker declaration itself → accept', 'accept', `export const CURRENCY_MARKERS = ['$', 'EUR'] as const;\n`),
+    ];
+}
+
+// ---------------------------------------------------------------------- CLI
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    if (argv.includes('--self-test')) {
+        return runSelfTest({ gate: 'check_no_currency_in_cost_surfaces', cases: selfTestCases(), minCases: 8, minRejectCases: 4 });
+    }
+    const quiet = argv.includes('--quiet');
+    const ri = argv.indexOf('--root');
+    const rootArg = ri !== -1 ? argv[ri + 1] : undefined;
+    const root = rootArg !== undefined ? path.resolve(rootArg) : REPO_ROOT;
+
+    const ledger = new GateLedger('check_no_currency_in_cost_surfaces');
+    let v: { scanned: number; findings: Finding[] };
+    try {
+        v = evaluate(root, ledger);
+    } catch (err) {
+        process.stderr.write(`❌  check_no_currency_in_cost_surfaces: ${(err as Error).message}\n`);
+        return 2;
+    }
+
+    try {
+        // Watchlist-driven: the corpus is a named list of files, not a tree walk,
+        // so an empty scan means the watchlist stopped resolving — which is a
+        // dead scope, not a clean run.
+        assertWatchlistResolves({
+            gate: 'check_no_currency_in_cost_surfaces',
+            candidates: GUARDED_SURFACES,
+            repoRoot: root,
+        });
+        reportScanned({
+            gate: 'check_no_currency_in_cost_surfaces',
+            scanned: v.scanned,
+            units: 'guarded cost surface(s)',
+            roots: GUARDED_SURFACES,
+            allowEmpty: 'WATCHLIST_DRIVEN: the corpus is the named surface list above, asserted by assertWatchlistResolves',
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  check_no_currency_in_cost_surfaces: ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+    ledger.report();
+
+    if (v.findings.length > 0) {
+        for (const f of v.findings) {
+            process.stderr.write(`❌  ${f.file}:${String(f.line)} renders '${f.marker}':\n      ${f.text}\n`);
+        }
+        process.stderr.write(
+            '\n    A cost surface here reports TOKENS. The suite does not know the consumer\'s\n' +
+                '    contract, so a monetary figure would be extrapolated from a rate it invented —\n' +
+                '    actionable and wrong, which is worse than absent.\n',
+        );
+        return 1;
+    }
+    if (!quiet) {
+        process.stdout.write(`✅  no currency figure or per-token rate on any cost surface (${String(v.scanned)} file(s)).\n`);
+    }
+    return 0;
+}
+
+if (process.env['GATE_SELF_TEST_CHILD'] !== '1' || process.argv.includes('--root')) {
+    if (process.argv[1] !== undefined && import.meta.url === `file://${process.argv[1]}`) {
+        process.exit(main());
+    }
+}

package/src/scripts/check_no_external_sources.ts

@@ -23,11 +23,39 @@
  * - A retained source link must be stored encrypted via
  *   src/scripts/_lib/link_crypto.ts, never in plaintext.
  *
+ * ## What `road-to-source-silence` added (Phase 3.1, 3.2, 3.3, and dormant 1.1)
+ *
+ * The name-list scan above is unchanged and still authoritative. Three surfaces
+ * were added around it, because a list can only catch a name somebody already
+ * wrote down:
+ *
+ * - **3.1 — paths are scanned like content.** A denied token in a FILENAME or
+ *   directory name failed nothing before; `rel` reached the extension skip-list
+ *   and the hit record and nothing else. It is now matched against the same
+ *   deny set, and a hit blocks exactly like a content line. Measured at
+ *   introduction: 0 hits, so this lands enforcing rather than baselined.
+ * - **3.2 — an attribution-SHAPE heuristic** (`_lib/source_shape.ts`), which is
+ *   independent of any name list. Tiered per the resolved
+ *   `how-loud-the-slug-heuristic-is` blocker: **block inside `agents/**`, warn
+ *   elsewhere.** The warn tier is written to a machine-readable report
+ *   (`--report`) rather than only printed, which is the council's own
+ *   requirement — "warnings must be visible and RETAINED in CI artifacts …
+ *   so the warn tier is auditable after the fact".
+ * - **3.3 — both new classes are ratcheted**, not allowlisted. Pre-existing
+ *   shape debt is a committed count in `src/config/gate-violation-baselines.json`
+ *   that may only shrink; a new occurrence raises the count and fails the gate.
+ *   No individual violation is named or excused.
+ * - **1.1 — keyed-digest matching, DORMANT.** `deny_digests` ships empty and
+ *   this code path does nothing until a maintainer performs the atomic cutover
+ *   in `docs/maintainers/source-deny-digests.md`. The plaintext `deny` array
+ *   stays in force and is NOT deleted.
+ *
  * Exit codes: 0 = clean, 1 = at least one denied token in a non-skipped tracked
- * file, 2 = usage / config error.
+ * file (or a shape-count regression), 2 = usage / config error, 3 = strict
+ * digest mode requested with no key (`_lib/source_digest.ts`).
  *
  * Usage:
- *     node scripts/check_no_external_sources.ts [--json]
+ *     node scripts/check_no_external_sources.ts [--json] [--report <path>]
  */
 
 import { spawnSync } from 'node:child_process';
@@ -36,7 +64,23 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { checkRatchet } from './_lib/gate_baseline.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { DigestMatcher, digestMode, EXIT_NO_KEY, KEY_ENV, STRICT_ENV } from './_lib/source_digest.js';
+import {
+    legacySourceHeaderHits,
+    shapeHits as shapeHitsOf,
+    shapePathHits,
+    tierFor,
+    type ShapeClass,
+} from './_lib/source_shape.js';
+import {
+    dedupVerdict,
+    findingKey,
+    hunkTargets,
+    isSnapshotPatch,
+    isSnapshotPath,
+} from './_lib/source_snapshot_dedup.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // parents[2] of src/scripts/<file> is the repo root.
@@ -52,17 +96,33 @@ const _SKIP_EXT = new Set([
 
 interface DenyConfig {
     deny: string[];
+    /** Phase 1.1 — HMAC-SHA256 digests of the deny set. Ships EMPTY (dormant). */
+    deny_digests?: string[];
     skip_paths?: string[];
     [k: string]: unknown;
 }
 
 interface Hit {
     file: string;
+    /** 0 for a PATH hit — there is no line to point at. */
     line: number;
     token: string;
     text: string;
 }
 
+/** One attribution-shape finding (Phase 3.2). */
+interface ShapeFinding {
+    file: string;
+    line: number;
+    cls: ShapeClass;
+    tier: 'block' | 'warn';
+    /** The offending value, truncated. Written to the report, never to stdout. */
+    value: string;
+}
+
+/** Baseline key for the block-tier shape count (Phase 3.3). */
+export const SHAPE_GATE_KEY = 'check_no_external_sources:shape-block';
+
 /** Thrown to mirror Python `raise SystemExit(msg)` (exit code derived by caller). */
 class ExitError extends Error {}
 
@@ -297,12 +357,42 @@ function main(argv: readonly string[]): number {
         throw exc;
     }
 
+    // Phase 1.1 — dormant unless a maintainer has performed the atomic cutover.
+    const digests = cfg.deny_digests ?? [];
+    const strict = (process.env[STRICT_ENV] ?? '') !== '';
+    const mode = digestMode({ digests, key: process.env[KEY_ENV], strict });
+    if (mode.strict && !mode.active) {
+        process.stderr.write(`❌  ${mode.message}\n`);
+        return EXIT_NO_KEY;
+    }
+    if (mode.message !== '') {
+        process.stderr.write(`${mode.message}\n`);
+    }
+    const matcher = mode.active ? new DigestMatcher(digests, process.env[KEY_ENV] as string) : null;
+
     const hits: Hit[] = [];
+    const shapes: ShapeFinding[] = [];
+    /** Pre-narrowing `source-header` count. Reported, never enforced. */
+    let legacyHeaderShadow = 0;
     for (const rel of tracked) {
-        if (_SKIP_EXT.has(_suffixLower(rel))) {
+        if (_skipped(rel, skipGlobs)) {
             continue;
         }
-        if (_skipped(rel, skipGlobs)) {
+        // --- Phase 3.1: the PATH is scanned exactly like a content line. -----
+        for (const [raw, rx] of patterns) {
+            if (rx.test(rel)) {
+                hits.push({ file: rel, line: 0, token: raw, text: `(path) ${rel}`.slice(0, 160) });
+            }
+        }
+        if (matcher) {
+            for (const tok of matcher.hits(rel)) {
+                hits.push({ file: rel, line: 0, token: `digest:${tok}`, text: `(path) ${rel}`.slice(0, 160) });
+            }
+        }
+        for (const h of shapePathHits(rel)) {
+            shapes.push({ file: rel, line: 0, cls: h.cls, tier: tierFor(rel), value: h.value });
+        }
+        if (_SKIP_EXT.has(_suffixLower(rel))) {
             continue;
         }
         let text: string;
@@ -317,6 +407,7 @@ function main(argv: readonly string[]): number {
             continue;
         }
         const lines = _splitlines(text);
+        const tier = tierFor(rel);
         for (let idx = 0; idx < lines.length; idx += 1) {
             const line = lines[idx] as string;
             for (const [raw, rx] of patterns) {
@@ -329,11 +420,160 @@ function main(argv: readonly string[]): number {
                     });
                 }
             }
+            if (matcher) {
+                for (const tok of matcher.hits(line)) {
+                    hits.push({
+                        file: rel,
+                        line: idx + 1,
+                        token: `digest:${tok}`,
+                        text: _pyStrip(line).slice(0, 160),
+                    });
+                }
+            }
+            for (const h of shapeHitsOf(line)) {
+                shapes.push({ file: rel, line: idx + 1, cls: h.cls, tier, value: h.value });
+            }
+            // SHADOW METRIC, gating nothing. A council condition of the
+            // 2026-08-30 narrowing: "keep the old detector shadow-reporting
+            // until at least one subsequent corpus-changing release passes both
+            // detectors". It exists so the discontinuity from 243 to 148 stays
+            // visible and auditable rather than becoming a number nobody can
+            // reconstruct.
+            if (tier === 'block') {
+                legacyHeaderShadow += legacySourceHeaderHits(line).length;
+            }
         }
     }
 
+    // --- Phase 3.2 + 3.3: tier the shape findings and ratchet the block tier.
+    const blockShapesAll = shapes.filter((s2) => s2.tier === 'block');
+    const warnShapes = shapes.filter((s2) => s2.tier === 'warn');
+
+    // --- Phase 3.4: provenance-aware deduplication of R2 snapshot mirrors. ----
+    // A finding inside a review-input snapshot is excluded from the ratchet ONLY
+    // when an identical class+value is independently block-counted in the
+    // current tracked tree. Earned per finding; fails closed. The refused
+    // alternative (lower the tier for the whole snapshot corpus) and the two
+    // legs are documented in `_lib/source_snapshot_dedup.ts`.
+    const trackedPaths = new Set(tracked);
+    const blockIndex = new Map<string, Set<string>>();
+    for (const s2 of blockShapesAll) {
+        if (isSnapshotPath(s2.file)) {
+            continue;
+        }
+        const k = findingKey(s2.cls, s2.value);
+        let set = blockIndex.get(k);
+        if (!set) {
+            set = new Set();
+            blockIndex.set(k, set);
+        }
+        set.add(s2.file);
+    }
+    const targets = new Map<string, ReadonlyMap<number, string>>();
+    for (const rel of tracked) {
+        if (!isSnapshotPatch(rel)) {
+            continue;
+        }
+        try {
+            targets.set(rel, hunkTargets(fs.readFileSync(path.join(ROOT, rel), 'utf-8')));
+        } catch {
+            // Unreadable patch — no hunk targets, so no finding in it can take
+            // Leg 1. It does NOT follow that they fail closed: Leg 2 still
+            // excludes a finding whose value is block-counted elsewhere in the
+            // scanned tree. Corrected after the R2 review of this branch, which
+            // caught this comment claiming a guarantee the code does not give.
+        }
+    }
+    const dedupInput = { blockIndex, targets, trackedPaths };
+    const blockShapes: ShapeFinding[] = [];
+    const excluded: Array<ShapeFinding & { leg: string; matched: string }> = [];
+    for (const s2 of blockShapesAll) {
+        const v = isSnapshotPath(s2.file)
+            ? dedupVerdict({ file: s2.file, line: s2.line, cls: s2.cls, value: s2.value }, dedupInput)
+            : { excluded: false, leg: null, matchedPath: null, reason: 'not a snapshot finding' };
+        if (v.excluded) {
+            excluded.push({ ...s2, leg: v.leg ?? '?', matched: v.matchedPath ?? '' });
+        } else {
+            blockShapes.push(s2);
+        }
+    }
+    const dedupByLeg = {
+        hunk: excluded.filter((e) => e.leg === 'hunk').length,
+        tree: excluded.filter((e) => e.leg === 'tree').length,
+    };
+
+    const verdict = checkRatchet({ repoRoot: ROOT, gate: SHAPE_GATE_KEY, actual: blockShapes.length });
+
+    // The council's retention requirement: the warn tier is written where CI can
+    // keep it, not merely printed into a log that scrolls away.
+    const ri = argv.indexOf('--report');
+    if (ri >= 0 && argv[ri + 1] !== undefined) {
+        const out = path.resolve(ROOT, argv[ri + 1] as string);
+        fs.mkdirSync(path.dirname(out), { recursive: true });
+        fs.writeFileSync(
+            out,
+            _jsonDumps2({
+                deny_hits: hits.length,
+                digest_mode: { active: mode.active, digests: mode.digests, key_missing: mode.keyMissing },
+                shape: {
+                    block: blockShapes.length,
+                    warn: warnShapes.length,
+                    baseline: verdict.baseline,
+                    status: verdict.status,
+                    // The council's shadow-metric condition, in the ARTEFACT
+                    // rather than only on stdout (R2 finding 8): "keep the old
+                    // detector shadow-reporting until at least one subsequent
+                    // corpus-changing release passes both detectors" cannot be
+                    // checked across releases by anything that is not written
+                    // down. `pre_dedup` says why the two numbers differ, so a
+                    // reader can reconstruct the comparison instead of being
+                    // told it holds.
+                    legacy_source_header: {
+                        count: legacyHeaderShadow,
+                        pre_dedup: true,
+                        note: 'pre-2026-08-30 predicate; enforces nothing; not comparable to the audited delta, which was measured after snapshot deduplication',
+                    },
+                },
+                // Phase 3.4 — every exclusion names its leg and the tracked
+                // file whose independent block-count justified it, so the
+                // weaker `tree` leg is auditable after the fact rather than
+                // invisible. The council required exactly this.
+                snapshot_dedup: {
+                    excluded: excluded.length,
+                    by_leg: dedupByLeg,
+                    exclusions: excluded,
+                },
+                block_findings: blockShapes,
+                warn_findings: warnShapes,
+            }) + '\n',
+            'utf-8',
+        );
+    }
+
+    const ok = hits.length === 0 && verdict.ok;
+
     if (asJson) {
-        process.stdout.write(_jsonDumps2({ ok: hits.length === 0, hits }) + '\n');
+        // `ok` and `hits` keep their pinned meaning for the name-list scan; the
+        // shape block is additive so an existing consumer is unaffected.
+        process.stdout.write(
+            _jsonDumps2({
+                ok,
+                hits,
+                shape: {
+                    block: blockShapes.length,
+                    warn: warnShapes.length,
+                    baseline: verdict.baseline,
+                    status: verdict.status,
+                    ok: verdict.ok,
+                    snapshot_dedup: { excluded: excluded.length, by_leg: dedupByLeg },
+                    legacy_source_header: {
+                        count: legacyHeaderShadow,
+                        pre_dedup: true,
+                        note: 'pre-2026-08-30 predicate; enforces nothing; not comparable to the audited delta, which was measured after snapshot deduplication',
+                    },
+                },
+            }) + '\n',
+        );
     } else {
         if (hits.length > 0) {
             process.stdout.write(`❌  ${hits.length} external-source reference(s) in the tracked tree:\n\n`);
@@ -350,8 +590,43 @@ function main(argv: readonly string[]): number {
         } else {
             process.stdout.write('✅  No external inspiration-source references in the tracked tree.\n');
         }
+        // The shape tier reports on every run — a count that is only printed
+        // when it fails is a count nobody watches shrink.
+        process.stdout.write(
+            `\nattribution shape — block(agents/**) ${String(blockShapes.length)}` +
+                ` / baseline ${String(verdict.baseline)} · warn(elsewhere) ${String(warnShapes.length)}\n`,
+        );
+        process.stdout.write(
+            `legacy source-header shadow — ${String(legacyHeaderShadow)} raw finding(s) under the` +
+                ` PRE-2026-08-30 predicate. Reported, enforces nothing, and NOT` +
+                ` comparable to the 95 audited: this count is pre-dedup, while the` +
+                ` audited delta was measured after snapshot deduplication. See the` +
+                ` check_no_external_sources:shape-block baseline note.\n`,
+        );
+        if (excluded.length > 0) {
+            process.stdout.write(
+                `snapshot dedup — ${String(excluded.length)} review-snapshot finding(s) excluded` +
+                    ` (hunk-target ${String(dedupByLeg.hunk)} · tracked-tree ${String(dedupByLeg.tree)});` +
+                    ' each matched an identical class+value block-counted in a scanned file.' +
+                    ' Per-exclusion legs and matched paths: --report <path>.\n',
+            );
+        }
+        process.stdout.write(`${verdict.ok ? '✅' : '❌'}  ${verdict.message}\n`);
+        if (!verdict.ok) {
+            process.stdout.write(
+                '\nThe shape heuristic flags attribution by FORM, not by name: a speaking\n' +
+                    '`**Source:**` value, a quoted agents/tmp(.old)/<name>/ directory, or an\n' +
+                    'un-allowlisted github.com/<owner>/<repo> URL. Rewrite the reference to an\n' +
+                    'opaque round identifier or an ENC1: token (src/scripts/_lib/link_crypto.ts).\n' +
+                    'Run with --report <path> for the per-finding list. See rule:\n' +
+                    'source-confidentiality and roadmap road-to-source-silence Phase 3.\n',
+            );
+        }
     }
-    return hits.length > 0 ? 1 : 0;
+    // No second `scanned:` line: `assertScanned` above already emits it, and this
+    // copy landed AFTER the --json payload, which made the pinned JSON output
+    // unparseable. Caught by the CLI-contract test, not by inspection.
+    return ok ? 0 : 1;
 }
 
 function _isCliEntry(): boolean {

package/src/scripts/check_pack_conformance_fixture.ts

@@ -374,7 +374,17 @@ export function renderDoc(): string {
     const proven = GATES.filter((g) => g.mechanism !== 'real-tree-only');
     const blocked = GATES.filter((g) => g.mechanism === 'real-tree-only');
     const L: string[] = [];
-    L.push('<!-- GENERATED by src/scripts/check_pack_conformance_fixture.ts --emit-doc — DO NOT EDIT BY HAND -->');
+    // `stability:` frontmatter is MANDATORY for every file under docs/contracts/
+    // (STABILITY.md § Frontmatter requirement), and check_public_links reads it.
+    // It is emitted here rather than hand-added to the page, because the page is
+    // derived — a hand-added block is reverted by the next `--emit-doc` and
+    // reds this gate's own freshness check in the meantime.
+    L.push('---');
+    L.push('stability: beta');
+    L.push('keep-beta-until: 2026-11-24');
+    L.push('---');
+    L.push('');
+    L.push('<!-- GENERATED by check_pack_conformance_fixture --emit-doc — DO NOT EDIT BY HAND -->');
     L.push('');
     L.push(`# Pack conformance — partial: ${String(proven.length)} of ${String(GATES.length)} gates independently fixture-proven`);
     L.push('');