@event4u/agent-config 14.8.0 → 14.9.0

package/src/scripts/check_requirements_trace.ts

@@ -0,0 +1,378 @@
+#!/usr/bin/env tsx
+/**
+ * Requirement → acceptance → evidence INVENTORY. Exits 0 always.
+ *
+ * ## Why a listing and not a gate
+ *
+ * A gate that can fail on day one reds the whole backlog, and this tree has
+ * recorded that failure once already: `road-to-plan-gates-measurement` sits in
+ * `later/` because its counter measured **0** — its own text records "Measured
+ * at parking time: 0" and an advisory window of 0 of 10 gated PRs. So this
+ * script is deliberately a *reader*: it prints the distribution and returns 0
+ * whatever it finds, including when it finds nothing.
+ *
+ * The name carries a `check_` prefix because that is what the gate-population
+ * classifier keys on and the script IS registered for coverage; the exit code is
+ * what makes it a listing rather than an enforcement.
+ *
+ * ## Three populations, reported separately
+ *
+ * The council's correction, and the reason this is not one number. Step 2.1
+ * originally named three roadmaps to dogfood; all three were archived by sibling
+ * pull requests in the same drain run, so the named set was gone before any
+ * window opened. Merging one PR before another would have changed the reported
+ * result with no roadmap edited — which makes merge order part of the
+ * experiment.
+ *
+ *   - `fixture`   — synthetic inputs, for parser and resolver mechanics. Never
+ *                   counts toward adoption: a maintainer-authored fixture is
+ *                   evidence about the reader, not about uptake.
+ *   - `cohort`    — a frozen manifest of files under study, active or archived.
+ *                   Experimental history; may include archived members.
+ *   - `live`      — the current ACTIVE corpus only. This is the compliance
+ *                   number, and the only one a ratchet may read.
+ *
+ * Collapsing them is how a zero from non-adoption becomes indistinguishable
+ * from a zero from non-compliance.
+ *
+ * ## What `unresolved` means, and when it is evaluated
+ *
+ * At the CURRENT head, always. A ref that resolved when it was declared and no
+ * longer resolves is `unresolved`, and that is the intended reading rather than
+ * a defect in it — deleted evidence is what an inventory exists to surface. The
+ * consequence, stated rather than discovered: a completed roadmap can move from
+ * resolved to unresolved with no roadmap edit.
+ *
+ * Usage:
+ *     ./scripts-run src/scripts/check_requirements_trace [--json] [--dir P]
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const ROADMAP_DIR = path.join(REPO_ROOT, 'agents', 'roadmaps');
+
+/** The claim-ledger kebab slug, reused rather than invented. */
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export interface TraceRow {
+    requirement_id: string;
+    acceptance_id: string;
+    evidence_refs: string[];
+}
+
+export interface FileTrace {
+    file: string;
+    rows: TraceRow[];
+    /** `[AC:<id>]` ids found on `verify:` lines. */
+    ac_annotations: string[];
+    /** Rows whose ids do not match the reused slug grammar. */
+    malformed: string[];
+}
+
+/**
+ * Parse the `traceability:` rows out of a roadmap.
+ *
+ * A deliberately small reader over the block form § 2c fixes, and NOT a YAML
+ * parser: the block may appear inside a blockquote (this roadmap dogfoods it
+ * that way) and a real parser would need the whole document to be YAML, which a
+ * roadmap is not. Leading `>` and whitespace are stripped per line.
+ */
+export function parseTrace(text: string): { rows: TraceRow[]; malformed: string[] } {
+    const lines = text.split('\n').map((l) => l.replace(/^\s*>\s?/, ''));
+    const rows: TraceRow[] = [];
+    const malformed: string[] = [];
+    let inBlock = false;
+    let cur: Partial<TraceRow> | null = null;
+    let inRefs = false;
+
+    const flush = (): void => {
+        if (cur === null) return;
+        const { requirement_id: req, acceptance_id: acc } = cur;
+        if (req !== undefined && acc !== undefined) {
+            if (!SLUG.test(req)) malformed.push(`requirement_id \`${req}\` is not a kebab slug`);
+            if (!SLUG.test(acc)) malformed.push(`acceptance_id \`${acc}\` is not a kebab slug`);
+            rows.push({ requirement_id: req, acceptance_id: acc, evidence_refs: cur.evidence_refs ?? [] });
+        }
+        cur = null;
+        inRefs = false;
+    };
+
+    for (const raw of lines) {
+        if (/^\s*traceability:\s*$/.test(raw)) {
+            inBlock = true;
+            continue;
+        }
+        if (!inBlock) continue;
+        // A fence or a non-indented non-list line ends the block.
+        if (/^\s*```/.test(raw) || (raw.trim() !== '' && !/^\s/.test(raw))) {
+            flush();
+            inBlock = false;
+            continue;
+        }
+        const item = /^\s*-\s+requirement_id:\s*(\S+)\s*$/.exec(raw);
+        if (item) {
+            flush();
+            cur = { requirement_id: item[1] as string, evidence_refs: [] };
+            continue;
+        }
+        if (cur === null) continue;
+        const acc = /^\s*acceptance_id:\s*(\S+)\s*$/.exec(raw);
+        if (acc) {
+            cur.acceptance_id = acc[1] as string;
+            inRefs = false;
+            continue;
+        }
+        if (/^\s*evidence_refs:\s*$/.test(raw)) {
+            inRefs = true;
+            continue;
+        }
+        const ref = /^\s*-\s+(\S+)\s*$/.exec(raw);
+        if (ref && inRefs) {
+            (cur.evidence_refs ??= []).push(ref[1] as string);
+        }
+    }
+    flush();
+    return { rows, malformed };
+}
+
+/** `[AC:<id>]` ids on `verify:` lines — the first structural reader of them. */
+export function parseAcAnnotations(text: string): string[] {
+    const out: string[] = [];
+    for (const m of text.matchAll(/verify:\s*\[AC:([a-z0-9-]+)\]/g)) out.push(m[1] as string);
+    return out;
+}
+
+export interface Summary {
+    files: number;
+    rows: number;
+    /** Rows with at least one evidence ref. */
+    linked: number;
+    /** Rows with no evidence ref at all. */
+    unlinked: number;
+    /** Evidence refs that do not resolve at the current head. */
+    unresolved: number;
+    refs: number;
+    ac_annotations: number;
+    /** `[AC:…]` ids with no matching `acceptance_id` in the same file. */
+    dangling_ac: number;
+    malformed: number;
+}
+
+export function summarise(traces: readonly FileTrace[], repoRoot: string): Summary {
+    let rows = 0;
+    let linked = 0;
+    let unlinked = 0;
+    let refs = 0;
+    let unresolved = 0;
+    let dangling = 0;
+    let malformed = 0;
+    for (const t of traces) {
+        rows += t.rows.length;
+        malformed += t.malformed.length;
+        const accIds = new Set(t.rows.map((r) => r.acceptance_id));
+        for (const id of t.ac_annotations) if (!accIds.has(id)) dangling += 1;
+        for (const r of t.rows) {
+            if (r.evidence_refs.length === 0) unlinked += 1;
+            else linked += 1;
+            for (const ref of r.evidence_refs) {
+                refs += 1;
+                // Evaluated at the CURRENT head. A ref that has been deleted is
+                // unresolved, which is the reading this inventory exists for.
+                if (!fs.existsSync(path.join(repoRoot, ref.replace(/:\d+(-\d+)?$/, '')))) {
+                    unresolved += 1;
+                }
+            }
+        }
+    }
+    return {
+        files: traces.length,
+        rows,
+        linked,
+        unlinked,
+        unresolved,
+        refs,
+        ac_annotations: traces.reduce((n, t) => n + t.ac_annotations.length, 0),
+        dangling_ac: dangling,
+        malformed,
+    };
+}
+
+function readLive(dir: string): FileTrace[] {
+    let names: string[] = [];
+    try {
+        names = fs.readdirSync(dir).filter((n) => n.endsWith('.md') && n !== 'README.md').sort();
+    } catch {
+        return [];
+    }
+    const out: FileTrace[] = [];
+    for (const n of names) {
+        const text = fs.readFileSync(path.join(dir, n), 'utf-8');
+        const { rows, malformed } = parseTrace(text);
+        const ac = parseAcAnnotations(text);
+        if (rows.length === 0 && ac.length === 0) continue;
+        out.push({ file: `agents/roadmaps/${n}`, rows, ac_annotations: ac, malformed });
+    }
+    return out;
+}
+
+/** Floors for `--self-test`, declared here so a truncation is a visible diff. */
+const SELF_TEST_MIN_CASES = 5;
+const SELF_TEST_MIN_REJECT = 1;
+const SCRIPT_REL = 'src/scripts/check_requirements_trace.ts';
+
+/**
+ * `--self-test` for a gate that exits 0 ALWAYS — which needs explaining, since
+ * the harness's whole premise is that a gate proves it can go red.
+ *
+ * This one cannot, by design, so the reject case is the harness's OWN floor:
+ * a truncated suite must fail. What the accept cases prove instead is that the
+ * reader DISCRIMINATES — the same discrimination a failing exit would
+ * demonstrate elsewhere, asserted on the output rather than the exit code.
+ * Stated rather than left implicit, because a self-test whose cases all accept
+ * is exactly the degenerate pass the harness warns about.
+ */
+function _fixture(name: string, body: string, args: readonly string[] = []): number {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), `reqtrace-st-${name}-`));
+    const rm = path.join(dir, 'agents', 'roadmaps');
+    fs.mkdirSync(rm, { recursive: true });
+    fs.writeFileSync(path.join(rm, 'a.md'), body, 'utf-8');
+    return runGateCli(REPO_ROOT, SCRIPT_REL, ['--dir', rm, ...args], dir);
+}
+
+const _ROW = 'traceability:\n  - requirement_id: r-one\n    acceptance_id: a-one\n';
+
+function selfTest(): number {
+    const cases: SelfTestCase[] = [
+        { name: 'a declared row is accepted', expect: 'accept', run: () => _fixture('row', _ROW) },
+        {
+            name: 'a dangling [AC:] annotation still exits 0 — this is a listing, not a gate',
+            expect: 'accept',
+            run: () => _fixture('dangling', `${_ROW}\n      verify: [AC:nowhere] x\n`),
+        },
+        {
+            name: 'an empty corpus exits 0 and does not read as a clean bill',
+            expect: 'accept',
+            run: () => _fixture('empty', '# no traceability block here\n'),
+        },
+        {
+            name: 'a non-slug id exits 0 and is reported, never enforced',
+            expect: 'accept',
+            run: () => _fixture('slug', 'traceability:\n  - requirement_id: Not_A_Slug\n    acceptance_id: a\n'),
+        },
+        {
+            name: 'an unknown argument is refused — the one non-zero path there is',
+            expect: 'reject',
+            run: () => _fixture('badarg', _ROW, ['--not-a-flag']),
+        },
+    ];
+    return runSelfTest({
+        gate: 'check_requirements_trace',
+        cases,
+        minCases: SELF_TEST_MIN_CASES,
+        minRejectCases: SELF_TEST_MIN_REJECT,
+    });
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    if (argv.includes('--self-test')) return selfTest();
+    for (let k = 0; k < argv.length; k += 1) {
+        const a = argv[k] as string;
+        if (a === '--json') continue;
+        if (a === '--dir') {
+            k += 1;
+            continue;
+        }
+        if (a === '--self-test') continue;
+        process.stderr.write(`check_requirements_trace: unrecognized argument: ${a}\n`);
+        return 2;
+    }
+    const i = argv.indexOf('--dir');
+    const dir = i >= 0 && i + 1 < argv.length ? path.resolve(argv[i + 1] as string) : ROADMAP_DIR;
+    const root = i >= 0 ? path.dirname(path.dirname(dir)) : REPO_ROOT;
+
+    let corpus = 0;
+    try {
+        corpus = fs.readdirSync(dir).filter((n) => n.endsWith('.md') && n !== 'README.md').length;
+    } catch {
+        corpus = 0;
+    }
+    const live = readLive(dir);
+    const s = summarise(live, root);
+
+    if (argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify({ population: 'live', corpus, ...s, files_detail: live }, null, 2)}\n`);
+        return 0;
+    }
+
+    process.stdout.write(`scanned: ${String(corpus)}\n`);
+    try {
+        assertScanned({
+            gate: 'check_requirements_trace',
+            scanned: corpus,
+            units: 'roadmap file(s)',
+            roots: ['agents/roadmaps'],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            // Reported, and STILL exit 0. A dead scope is a real finding about
+            // this reader, and turning it into a non-zero exit would make the
+            // listing a gate — which is the one thing it must not become.
+            process.stderr.write(`⚠️  ${err.message}\n`);
+        } else {
+            throw err;
+        }
+    }
+
+    process.stdout.write('\n| Roadmap | requirement_id | acceptance_id | evidence refs | unresolved |\n');
+    process.stdout.write('|---|---|---|---|---|\n');
+    if (live.length === 0) {
+        process.stdout.write('| _none declared_ | — | — | — | — |\n');
+    }
+    for (const t of live) {
+        for (const r of t.rows) {
+            const bad = r.evidence_refs.filter(
+                (ref) => !fs.existsSync(path.join(root, ref.replace(/:\d+(-\d+)?$/, ''))),
+            ).length;
+            process.stdout.write(
+                `| ${t.file} | ${r.requirement_id} | ${r.acceptance_id} | ` +
+                    `${String(r.evidence_refs.length)} | ${String(bad)} |\n`,
+            );
+        }
+        for (const id of t.ac_annotations) {
+            const known = t.rows.some((r) => r.acceptance_id === id);
+            if (!known) {
+                process.stdout.write(`| ${t.file} | — | **[AC:${id}] dangling** | — | — |\n`);
+            }
+        }
+    }
+
+    // The line a ratchet reads, and the line a later reading is compared to.
+    // Integers with the corpus they were computed over, never a verdict: "
+    // traceability is patchy" cannot be compared to the next reading.
+    process.stdout.write(
+        `\nlive: rows ${String(s.rows)} · linked ${String(s.linked)} · unlinked ${String(s.unlinked)} · ` +
+            `refs ${String(s.refs)} · unresolved ${String(s.unresolved)} · ` +
+            `ac_annotations ${String(s.ac_annotations)} · dangling_ac ${String(s.dangling_ac)} · ` +
+            `malformed ${String(s.malformed)} · over ${String(corpus)} active roadmap(s), ` +
+            `${String(s.files)} declaring\n`,
+    );
+    process.stdout.write(
+        '    POPULATION: live (active corpus only). A `fixture` population tests this reader\n' +
+            '    and never counts toward adoption; a frozen `cohort` may include archived files\n' +
+            '    and is experimental history. Collapsing the three is how a zero from\n' +
+            '    non-adoption becomes indistinguishable from a zero from non-compliance.\n',
+    );
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exit(main());
+}

package/src/scripts/check_secret_leak.ts

@@ -38,6 +38,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { runSelfTest } from './_lib/gate_self_test.js';
 import { scanText, type SecretFinding } from './_lib/secret_detector.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -107,8 +108,34 @@ function isAllowed(rel: string, lineno: number, allow: readonly AllowEntry[]): b
     return allow.some((a) => a.file === rel && (a.line === null || a.line === lineno));
 }
 
-function isExcluded(rel: string): boolean {
-    return DEFAULT_EXCLUDE.some((rx) => rx.test(rel));
+/** `dist/` — excluded everywhere EXCEPT the pack scope. See `isExcluded`. */
+const DIST_EXCLUDE: RegExp = /(^|\/)dist(\/|$)/;
+
+function isExcluded(rel: string, mode: Mode = 'diff'): boolean {
+    return DEFAULT_EXCLUDE.some((rx) => {
+        // The `dist/` exclusion is the SECOND reason this gate could not see
+        // what ships, and it fires regardless of mode. Mode enumeration was the
+        // first: every git-backed mode walks the git tree, and `dist/cli/**` is
+        // gitignored while `dist/` is a `files[]` root. Adding the pack scope
+        // alone fixed nothing measurable — the payload resolved and then this
+        // filter threw away exactly the paths the scope exists to reach.
+        // Verified: a key-shaped string planted at `dist/zzcanary/leak.txt`
+        // (`git check-ignore -v` names `.gitignore:206`, and `npm pack` ships
+        // it) was missed by the new mode until this branch existed.
+        //
+        // Kept for every OTHER mode, because there the exclusion is right:
+        // `dist/` is a byte-for-byte projection of `src/`, which is scanned at
+        // its own path, so scanning the copy adds no coverage. In the pack scope
+        // the question is different — not "is this content somewhere else in the
+        // repo" but "does this content SHIP" — and for an untracked shipped path
+        // there is no other path to have scanned it at.
+        //
+        // The cost is a duplicate finding for a TRACKED dist file. That is not a
+        // false positive: a projection is byte-identical to its source, so a
+        // finding there is a finding in `src/` too.
+        if (mode === 'pack' && rx.source === DIST_EXCLUDE.source) return false;
+        return rx.test(rel);
+    });
 }
 
 /** Fast binary sniff — a NUL byte in the first 8 KiB means "not text". */
@@ -132,7 +159,48 @@ function gitLines(root: string, args: readonly string[]): string[] {
     return res.stdout.split('\n').filter((l) => l.trim() !== '');
 }
 
-export type Mode = 'diff' | 'all' | 'explicit';
+export type Mode = 'diff' | 'all' | 'explicit' | 'pack';
+
+/**
+ * `pack` exists because the other three cannot see a large part of what ships.
+ *
+ * Every one of them enumerates the GIT tree — `git diff`, `git ls-files`, or an
+ * explicit path list a caller derived from one. `dist/` is a `files[]` root and
+ * `dist/cli/**` is gitignored (`.gitignore:206` is `/dist/*`, and
+ * `git check-ignore -v dist/cli/agent-config.js` names that line), so those
+ * paths are shipped and untracked at the same time and this gate could not
+ * reach them **by construction** — not by misconfiguration.
+ *
+ * Additive on purpose: no existing caller changes behaviour, and the three
+ * git-backed modes are untouched.
+ */
+export function packPayloadFiles(root: string): string[] {
+    const out = spawnSync('npm', ['pack', '--dry-run', '--ignore-scripts', '--json'], {
+        cwd: root,
+        encoding: 'utf-8',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (out.status !== 0 || typeof out.stdout !== 'string') {
+        // Returning [] would hand the scope assertion an empty set, which it
+        // already treats as a gate that could not run — the right verdict, and
+        // reached without inventing a second failure path.
+        return [];
+    }
+    const i = out.stdout.indexOf('[');
+    if (i < 0) return [];
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(out.stdout.slice(i));
+    } catch {
+        return [];
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0) return [];
+    const first = parsed[0] as { files?: { path?: unknown }[] };
+    const files = Array.isArray(first.files) ? first.files : [];
+    return files
+        .map((f) => (typeof f.path === 'string' ? f.path : ''))
+        .filter((pth) => pth !== '');
+}
 
 /**
  * Resolve the file set.
@@ -155,6 +223,9 @@ export function resolveFiles(
     if (mode === 'all') {
         return gitLines(root, ['ls-files']);
     }
+    if (mode === 'pack') {
+        return packPayloadFiles(root);
+    }
     const base = opts.base ?? 'origin/main';
     // An unresolvable base is a scan of NOTHING, not a clean scan.
     //
@@ -191,7 +262,7 @@ export function scanRepo(
     const applyExcludes = mode !== 'explicit';
     const hits: LeakHit[] = [];
     for (const rel of resolveFiles(root, mode, opts)) {
-        if (applyExcludes && isExcluded(rel)) {
+        if (applyExcludes && isExcluded(rel, mode)) {
             continue;
         }
         const abs = path.join(root, rel);
@@ -220,6 +291,7 @@ export function scanRepo(
 interface Args {
     json: boolean;
     all: boolean;
+    pack: boolean;
     base: string | undefined;
     paths: string[];
 }
@@ -228,6 +300,7 @@ function parseArgs(argv: readonly string[]): Args {
     const paths: string[] = [];
     let json = false;
     let all = false;
+    let pack = false;
     let base: string | undefined;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i] as string;
@@ -235,13 +308,17 @@ function parseArgs(argv: readonly string[]): Args {
             json = true;
         } else if (a === '--all') {
             all = true;
+        } else if (a === '--pack') {
+            pack = true;
         } else if (a === '--base') {
             base = argv[++i];
         } else if (a === '-h' || a === '--help') {
             _stdout(
-                'usage: check_secret_leak [paths...] [--all] [--base <ref>] [--json]\n' +
+                'usage: check_secret_leak [paths...] [--all] [--pack] [--base <ref>] [--json]\n' +
                     '  default → scans files changed vs origin/main + untracked (shift-left).\n' +
                     '  --all   → scans the whole tracked tree.\n' +
+                    '  --pack  → scans the npm pack payload, INCLUDING shipped-but-gitignored\n' +
+                    '            paths the three git-backed modes cannot reach.\n' +
                     '  paths   → scans exactly those paths (excludes skipped).\n' +
                     '  Exit 1 on a high-confidence leak.\n',
             );
@@ -253,7 +330,7 @@ function parseArgs(argv: readonly string[]): Args {
             paths.push(a);
         }
     }
-    return { json, all, base, paths };
+    return { json, all, pack, base, paths };
 }
 
 function _stdout(s: string): void {
@@ -263,9 +340,73 @@ function _stderr(s: string): void {
     process.stderr.write(s);
 }
 
+/**
+ * Discrimination, over the one property this branch added.
+ *
+ * The pack scope's whole value is that it reaches paths the git-backed modes
+ * cannot, and it was measurably INERT when first written: the mode resolved the
+ * payload and `DEFAULT_EXCLUDE`'s `dist/` rule then filtered away exactly those
+ * paths. A self-test over `isExcluded` is therefore not a formality here — it
+ * pins the difference between the mode working and the mode existing.
+ *
+ * Deliberately over the pure predicate rather than over a spawned `npm pack`:
+ * the canary in `gate-coverage.yml` already drives the real binary end to end
+ * with a real plant, and duplicating that here would add a pack run per case
+ * for no additional evidence.
+ */
+function selfTest(): number {
+    return runSelfTest({
+        gate: 'check_secret_leak',
+        minCases: 7,
+        minRejectCases: 3,
+        cases: [
+            {
+                name: 'pack scope does NOT exclude dist/ — the blind spot it exists for',
+                expect: 'reject',
+                run: () => (isExcluded('dist/cli/agent-config.js', 'pack') ? 0 : 1),
+            },
+            {
+                name: 'diff scope DOES exclude dist/ — a projection scanned at its source',
+                expect: 'accept',
+                run: () => (isExcluded('dist/cli/agent-config.js', 'diff') ? 0 : 1),
+            },
+            {
+                name: 'all scope also still excludes dist/ — untouched by this change',
+                expect: 'accept',
+                run: () => (isExcluded('dist/agent-src/rules/x.md', 'all') ? 0 : 1),
+            },
+            {
+                // The exclusion carve-out is `dist/` ONLY. If it leaked into the
+                // other rules the pack scope would start reading test fixtures,
+                // which legitimately hold secret-shaped strings.
+                name: 'pack scope still excludes tests/ — the carve-out is dist-only',
+                expect: 'accept',
+                run: () => (isExcluded('tests/fixtures/x.txt', 'pack') ? 0 : 1),
+            },
+            {
+                name: 'pack scope still excludes node_modules/',
+                expect: 'accept',
+                run: () => (isExcluded('node_modules/x/index.js', 'pack') ? 0 : 1),
+            },
+            {
+                name: 'pack scope reaches a second dist subtree, not just dist/cli',
+                expect: 'reject',
+                run: () => (isExcluded('dist/hooks/dispatch.js', 'pack') ? 0 : 1),
+            },
+            {
+                name: 'a shipped non-dist path is scanned in every mode',
+                expect: 'reject',
+                run: () => (isExcluded('src/scripts/x.ts', 'pack') || isExcluded('src/scripts/x.ts', 'diff') ? 0 : 1),
+            },
+        ],
+    });
+}
+
 export function main(argv?: readonly string[]): number {
-    const args = parseArgs(argv ?? process.argv.slice(2));
-    const mode: Mode = args.paths.length > 0 ? 'explicit' : args.all ? 'all' : 'diff';
+    const rawArgv = argv ?? process.argv.slice(2);
+    if (rawArgv.includes('--self-test')) return selfTest();
+    const args = parseArgs(rawArgv);
+    const mode: Mode = args.pack ? 'pack' : args.paths.length > 0 ? 'explicit' : args.all ? 'all' : 'diff';
 
     // Scope assertion, deliberately here and not inside `scanRepo`: that export
     // is called directly by tests and other callers against arbitrary roots, and
@@ -280,6 +421,11 @@ export function main(argv?: readonly string[]): number {
     // re-thrown untouched to preserve it.
     try {
         const targets = resolveFiles(REPO_ROOT, mode, { explicit: args.paths, base: args.base });
+        // The coverage register requires an enforced gate to report what it
+        // inspected. Printed before the assertion so a dead scope still tells
+        // the reader the number it died on, which is the one number that
+        // distinguishes "resolved nothing" from "resolved and filtered".
+        _stdout(`scanned: ${String(targets.length)}\n`);
         assertScanned({
             gate: 'check_secret_leak',
             scanned: targets.length,
@@ -289,9 +435,15 @@ export function main(argv?: readonly string[]): number {
                     ? ['git ls-files']
                     : mode === 'explicit'
                       ? ['<explicit path arguments>']
-                      : [`git diff --name-only --diff-filter=ACMR ${args.base ?? 'origin/main'}`, 'git ls-files --others --exclude-standard'],
-            // `all` and `explicit` carry no reason: zero tracked files, or zero
-            // named paths, is blindness in a repo that has content.
+                      : mode === 'pack'
+                        ? ['npm pack --dry-run --ignore-scripts payload (package.json files[])']
+                        : [`git diff --name-only --diff-filter=ACMR ${args.base ?? 'origin/main'}`, 'git ls-files --others --exclude-standard'],
+            // `all`, `explicit` and `pack` carry no reason: zero tracked files,
+            // zero named paths, or an empty pack payload is blindness in a repo
+            // that has content. `pack` inherits the strict path by omission
+            // rather than by a new branch — an empty payload means a botched
+            // `files[]` or a pack that resolved nothing, which is the loudest
+            // possible signal and the opposite of a clean bill.
             ...(mode === 'diff'
                 ? {
                       allowEmpty:
@@ -317,7 +469,9 @@ export function main(argv?: readonly string[]): number {
     if (args.json) {
         _stdout(JSON.stringify({ check: 'secret-leak', count: hits.length, hits }, null, 2) + '\n');
     } else if (hits.length === 0) {
-        _stdout('✅  check_secret_leak: no high-confidence secret found in the tracked tree.\n');
+        _stdout(
+            `✅  check_secret_leak: no high-confidence secret found in ${mode === 'pack' ? 'the npm pack payload' : 'the tracked tree'}.\n`,
+        );
     } else {
         _stderr(`❌  check_secret_leak: ${hits.length} high-confidence secret finding(s):\n`);
         for (const h of hits) {