@event4u/agent-config 9.12.0 → 9.13.0

package/src/scripts/audit_skill_overlap.ts

@@ -3,35 +3,51 @@
  * Skill-family content-overlap analysis (6.0.0-C Phase 4 Step 8).
  *
  * Ported from the retired Python `src/scripts/audit_skill_overlap.py` (ADR-200 —
- * Python→TS migration, Phase 8 / Wave 8c). Mirrors the Python CLI
- * contract EXACTLY — the `--threshold` / `--quiet` flags, exit codes
- * (0 ok / 3 no skills), the stdout/stderr split, byte-identical stdout
- * messages, and byte-identical written artefacts (`json.dumps(...,
- * indent=2)` for the JSON + the exact Markdown renderer).
+ * Python→TS migration, Phase 8 / Wave 8c). The numeric contract — keyword
+ * vector, cosine, banker's rounding, pair ordering, `json.dumps(..., indent=2)`
+ * byte shape, and the Markdown renderer — is preserved so historical reports
+ * stay comparable. The CLI grew a `--root` flag; the exit codes are unchanged
+ * (0 ok / 3 dead scan scope).
  *
- * No `_lib` imports — the retired Python implementation has none; it carries its own
- * `_skill_roots()` (which references the `.agent-src.uncondensed/skills`
- * layout literally — this twin reproduces that literal faithfully, since
- * the .py original carries it).
+ * SCAN ROOT (repaired 2026-08-02, road-to-overlap-truth-and-skill-cut Phase 1):
+ * the ported `_skill_roots()` resolved the pre-ADR-051 source containers, both
+ * of which were deleted when `src/skills` became the source of truth. The tool
+ * therefore walked a directory that does not exist and could never report an
+ * overlap for the 287-skill corpus. That resolution is GONE, not kept as a
+ * fallback branch: the default root is the shared `SRC_SKILLS()` resolver, and
+ * an empty scan is a hard failure via {@link assertScanned} rather than an
+ * empty result.
  *
  * Walks every `SKILL.md`, builds a keyword vector from the body
  * (frontmatter stripped), and flags pairs whose content cosine-similarity
  * is >= OVERLAP_THRESHOLD. Same-domain (shared `packs:`) >= threshold pairs
  * are the merge candidates. THIS SCRIPT MERGES NOTHING.
  *
- * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
+ * `--strict` makes a same-pack pair at or above threshold a BUILD FAILURE
+ * (exit 1) unless the pair carries a reviewed justification in
+ * `audit_skill_overlap_allowlist.json`, capped at 20 entries. The cap is the
+ * point: it forces periodic re-litigation instead of an allowlist that grows
+ * quietly until the gate means nothing. Cross-pack pairs never block — a
+ * cross-pack merge changes install shape and is a different decision.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
+import { SRC_SKILLS } from './_lib/agent_src.js';
+import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/audit_skill_overlap.py → parent.parent.parent == repo root.
 export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 export const REPORT_DIR = path.join(ROOT, 'agents', 'reports');
-export const OUT_JSON = path.join(REPORT_DIR, 'skill-overlap.json');
-export const OUT_MD = path.join(REPORT_DIR, 'skill-overlap.md');
+export const OUT_JSON_NAME = 'skill-overlap.json';
+export const OUT_MD_NAME = 'skill-overlap.md';
+export const OUT_JSON = path.join(REPORT_DIR, OUT_JSON_NAME);
+export const OUT_MD = path.join(REPORT_DIR, OUT_MD_NAME);
+export const ALLOWLIST = path.join(ROOT, 'src', 'scripts', 'audit_skill_overlap_allowlist.json');
+export const ALLOWLIST_CAP = 20;
 // re.compile(r"^---\n(.*?)\n---", re.DOTALL) — used with .search (anywhere).
 const FM_RE = /^---\n([\s\S]*?)\n---/m;
 export const OVERLAP_THRESHOLD = 0.7;
@@ -70,49 +86,16 @@ function _isFile(p: string): boolean {
         return false;
     }
 }
-
-/** Sorted immediate child entries (mirrors `sorted(p.iterdir())` / `p.glob`). */
-function _iterdirSorted(p: string): string[] {
-    let names: string[];
-    try {
-        names = fs.readdirSync(p);
-    } catch {
-        return [];
-    }
-    names.sort();
-    return names.map((n) => path.join(p, n));
-}
-
 /**
- * Mirror `_skill_roots`:
- *   roots = [d for d in (ROOT/"packages").glob("*\/.agent-src.uncondensed/skills")
- *            if d.is_dir()] if (ROOT/"packages").is_dir() else []
- *   legacy = ROOT/".agent-src.uncondensed"/"skills"
- *   if not roots and legacy.is_dir(): roots = [legacy]
+ * The one scan root: `src/skills`, via the shared ADR-051 resolver.
  *
- * `packages.glob("*\/.agent-src.uncondensed/skills")` iterates packages
- * children sorted (pathlib glob over a single level is unsorted, and the
- * retired Python implementation did NOT sort here — it relied on `collect()`'s `seen`
- * dedup keyed on dir name. To stay deterministic we sort the package
- * children; the resulting root order only affects first-win dedup, and no
- * skill dir name collides across packages in practice.)
+ * There is deliberately no fallback. A second, silently-tried root is how the
+ * previous resolution stayed green while reading nothing — the caller passes an
+ * explicit `--root` when it wants a different tree (fixtures, tests), and any
+ * root that yields zero skills fails loudly in {@link main}.
  */
-export function _skill_roots(): string[] {
-    const pkgs = path.join(ROOT, 'packages');
-    let roots: string[] = [];
-    if (_isDir(pkgs)) {
-        for (const child of _iterdirSorted(pkgs)) {
-            const cand = path.join(child, '.agent-src.uncondensed', 'skills');
-            if (_isDir(cand)) {
-                roots.push(cand);
-            }
-        }
-    }
-    const legacy = path.join(ROOT, '.agent-src.uncondensed', 'skills');
-    if (roots.length === 0 && _isDir(legacy)) {
-        roots = [legacy];
-    }
-    return roots;
+export function _default_skill_root(): string {
+    return SRC_SKILLS();
 }
 
 /**
@@ -162,8 +145,19 @@ export function _cosine(a: Map<string, number>, b: Map<string, number>): number
     return da && db ? num / (da * db) : 0.0;
 }
 
+/**
+ * Which text the similarity vector is built from.
+ *
+ * `body` is the CANONICAL metric — the one every historical report, the 0.70
+ * threshold, and the merge decisions are calibrated against. `description` is
+ * an explicitly non-canonical second view: routing happens on descriptions, and
+ * body similarity does not measure it, so the two answer different questions
+ * and their scores are never mixed or compared against the same threshold.
+ */
+export type Field = 'body' | 'description';
+
 /** Mirror `_parse`: yaml.safe_load frontmatter, body after the FM match. */
-export function _parse(md: string): Skill {
+export function _parse(md: string, field: Field = 'body'): Skill {
     const text = fs.readFileSync(md, 'utf-8');
     let fm: Json = {};
     let body = text;
@@ -179,11 +173,13 @@ export function _parse(md: string): Skill {
     const isObj = fm !== null && typeof fm === 'object' && !Array.isArray(fm);
     const name = isObj ? (fm as Record<string, Json>)['name'] : null;
     const packsVal = isObj ? (fm as Record<string, Json>)['packs'] : null;
+    const descVal = isObj ? (fm as Record<string, Json>)['description'] : null;
+    const source = field === 'description' ? (descVal ? String(descVal) : '') : body;
     return {
         name: name ? String(name) : path.basename(path.dirname(md)),
         relpath: _relPosix(md, ROOT),
         packs: Array.isArray(packsVal) ? new Set(packsVal.map((x) => String(x))) : new Set(),
-        vector: _keyword_vector(body),
+        vector: _keyword_vector(source),
     };
 }
 
@@ -247,22 +243,20 @@ function _pathlibCompare(a: string, b: string): number {
     return pa.length - pb.length;
 }
 
-export function collect(): Skill[] {
+export function collect(root: string = _default_skill_root(), field: Field = 'body'): Skill[] {
     const skills: Skill[] = [];
     const seen = new Set<string>();
-    for (const root of _skill_roots()) {
-        for (const md of _rglobSkillMd(root)) {
-            // if "_archive" in md.parts: continue
-            if (md.split(path.sep).includes('_archive')) {
-                continue;
-            }
-            const key = path.basename(path.dirname(md));
-            if (seen.has(key)) {
-                continue;
-            }
-            seen.add(key);
-            skills.push(_parse(md));
+    for (const md of _rglobSkillMd(root)) {
+        // if "_archive" in md.parts: continue
+        if (md.split(path.sep).includes('_archive')) {
+            continue;
         }
+        const key = path.basename(path.dirname(md));
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        skills.push(_parse(md, field));
     }
     return skills;
 }
@@ -354,17 +348,30 @@ function _pct(x: number): string {
     return `${pct}%`;
 }
 
-export function render_md(skills: Skill[], pairs: Pair[], threshold: number): string {
+export function render_md(
+    skills: Skill[],
+    pairs: Pair[],
+    threshold: number,
+    field: Field = 'body',
+): string {
     const merge = pairs.filter((p) => p.same_domain);
     const cross = pairs.filter((p) => !p.same_domain);
     const L: string[] = [
         '# Skill-family overlap report (6.0.0-C Phase 4 Step 8)\n',
-        `> Content cosine-similarity over ${skills.length} skills; pairs at ` +
-            `≥ ${_pct(threshold)}. **Same-domain pairs (shared \`packs:\`) are the ` +
-            `merge candidates** consumed by ` +
-            `[\`evidence-based-pruning.md\`](../../docs/contracts/evidence-based-pruning.md). ` +
-            `This report merges NOTHING — it is input to a future, human-driven ` +
-            `consolidation roadmap.\n`,
+        field === 'description'
+            ? `> **NON-CANONICAL measurement.** Cosine over the \`description:\` ` +
+              `frontmatter only, across ${skills.length} skills, at ≥ ${_pct(threshold)}. ` +
+              `Routing happens on descriptions, so this answers a question the ` +
+              `canonical body metric does not — but its scores are NOT comparable ` +
+              `to the canonical 0.70 merge threshold and must never be mixed into ` +
+              `a merge decision. The canonical run is the one without ` +
+              `\`--descriptions\`.\n`
+            : `> Content cosine-similarity over ${skills.length} skills; pairs at ` +
+              `≥ ${_pct(threshold)}. **Same-domain pairs (shared \`packs:\`) are the ` +
+              `merge candidates** consumed by ` +
+              `[\`evidence-based-pruning.md\`](../../docs/contracts/evidence-based-pruning.md). ` +
+              `This report merges NOTHING — it is input to a future, human-driven ` +
+              `consolidation roadmap.\n`,
         `\n- Skills scanned: **${skills.length}**`,
         `\n- Overlap pairs ≥ ${_pct(threshold)}: **${pairs.length}** ` +
             `(${merge.length} same-domain merge candidates, ${cross.length} cross-domain)\n`,
@@ -476,30 +483,126 @@ class FloatTag {
 
 export function main(argv: string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
-    const skills = collect();
-    if (skills.length === 0) {
-        process.stderr.write('❌  No skills found under the package skill roots.\n');
+    const root = args.root ?? _default_skill_root();
+    const skills = collect(root, args.field);
+    try {
+        assertScanned({
+            gate: 'audit_skill_overlap',
+            scanned: skills.length,
+            units: 'skill(s)',
+            roots: [_relPosix(root, ROOT)],
+        });
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) {
+            throw exc;
+        }
+        process.stderr.write(`❌  ${exc.message}\n`);
         return 3;
     }
     const pairs = find_pairs(skills, args.threshold);
-    fs.mkdirSync(REPORT_DIR, { recursive: true });
+    const outDir = args.outDir ?? REPORT_DIR;
+    const outJson = path.join(outDir, OUT_JSON_NAME);
+    const outMd = path.join(outDir, OUT_MD_NAME);
+    fs.mkdirSync(outDir, { recursive: true });
     const jsonObj = {
         threshold: new FloatTag(args.threshold),
         skills_scanned: skills.length,
         pairs: pairs.map(_pairToJson),
     };
-    fs.writeFileSync(OUT_JSON, _dumpsWithFloats(jsonObj), 'utf-8');
-    fs.writeFileSync(OUT_MD, render_md(skills, pairs, args.threshold), 'utf-8');
+    fs.writeFileSync(outJson, _dumpsWithFloats(jsonObj), 'utf-8');
+    fs.writeFileSync(outMd, render_md(skills, pairs, args.threshold, args.field), 'utf-8');
+    const merge = pairs.filter((p) => p.same_domain);
     if (!args.quiet) {
-        const merge = pairs.filter((p) => p.same_domain).length;
         process.stdout.write(
             `✅  Skill overlap: ${skills.length} skills, ${pairs.length} pair(s) ` +
-                `≥ ${_pct(args.threshold)} (${merge} same-domain merge candidate(s)).\n`,
+                `≥ ${_pct(args.threshold)} (${merge.length} same-domain merge candidate(s)).\n`,
+        );
+        process.stdout.write(`   JSON: ${_relPosix(outJson, ROOT)}\n`);
+        process.stdout.write(`   MD:   ${_relPosix(outMd, ROOT)}\n`);
+    }
+    // Deliberately NOT gated on --quiet: an advisory CI step whose only output
+    // is suppressed by the pipeline's default --quiet is a report nobody reads,
+    // which is one step away from the silent-green defect this tool just came
+    // back from. The counts line always ships when the table is requested.
+    if (args.printTable) {
+        process.stdout.write(
+            `ℹ️  skill overlap${args.strict ? '' : ' (advisory)'}: ${skills.length} skills scanned, ` +
+                `${merge.length} same-domain pair(s) ≥ ${_pct(args.threshold)}\n`,
+        );
+        for (const p of merge) {
+            process.stdout.write(
+                `   ${p.similarity.toFixed(3)}  ${p.a} ↔ ${p.b}  [${p.shared_packs.join(', ')}]\n`,
+            );
+        }
+    }
+
+    if (!args.strict) {
+        return 0;
+    }
+    let allow: Set<string>;
+    try {
+        allow = _loadAllowlist(args.allowlist ?? ALLOWLIST);
+    } catch (exc) {
+        process.stderr.write(`❌  ${exc instanceof Error ? exc.message : String(exc)}\n`);
+        return 2;
+    }
+    const blocking = merge.filter((p) => !allow.has(_pairKey(p.a, p.b)));
+    if (blocking.length === 0) {
+        return 0;
+    }
+    process.stderr.write(
+        `❌  audit_skill_overlap: ${blocking.length} same-pack pair(s) at or above ` +
+            `${_pct(args.threshold)} with no reviewed justification:\n`,
+    );
+    for (const p of blocking) {
+        process.stderr.write(
+            `   ${p.similarity.toFixed(3)}  ${p.a} ↔ ${p.b}  [${p.shared_packs.join(', ')}]\n`,
+        );
+    }
+    process.stderr.write(
+        `   Merge the pair, or add {"pair": "${_pairKey(blocking[0]!.a, blocking[0]!.b)}", "reason": "…"} ` +
+            `to ${_relPosix(args.allowlist ?? ALLOWLIST, ROOT)} (cap ${ALLOWLIST_CAP}).\n`,
+    );
+    return 1;
+}
+
+/** Order-independent key for an unordered pair. */
+export function _pairKey(a: string, b: string): string {
+    return a < b ? `${a}::${b}` : `${b}::${a}`;
+}
+
+/**
+ * Reviewed same-pack overlaps, capped. Over-cap throws rather than warning:
+ * per the autonomous-execution allowlist-growth antipattern, an allowlist that
+ * outgrows its cap means the threshold is wrong, not that the corpus needs
+ * twenty-one exceptions.
+ */
+export function _loadAllowlist(file: string): Set<string> {
+    if (!_isFile(file)) {
+        return new Set();
+    }
+    const data = JSON.parse(fs.readFileSync(file, 'utf-8')) as {
+        entries?: Array<{ pair: string; reason: string }>;
+    };
+    const entries = Array.isArray(data.entries) ? data.entries : [];
+    if (entries.length > ALLOWLIST_CAP) {
+        throw new Error(
+            `audit_skill_overlap: allowlist has ${entries.length} entries (> ${ALLOWLIST_CAP}). ` +
+                'Per the autonomous-execution allowlist-growth antipattern, the threshold is wrong, ' +
+                'not the corpus — re-litigate the bar, do not grow the list.',
         );
-        process.stdout.write(`   JSON: ${_relPosix(OUT_JSON, ROOT)}\n`);
-        process.stdout.write(`   MD:   ${_relPosix(OUT_MD, ROOT)}\n`);
     }
-    return 0;
+    const out = new Set<string>();
+    for (const e of entries) {
+        const [a, b] = String(e.pair).split('::');
+        if (a === undefined || b === undefined || (e.reason ?? '').trim() === '') {
+            throw new Error(
+                `audit_skill_overlap: allowlist entry ${JSON.stringify(e)} needs "pair": "a::b" and a non-empty "reason".`,
+            );
+        }
+        out.add(_pairKey(a, b));
+    }
+    return out;
 }
 
 /** json.dumps(indent=2) with FloatTag → Python-float repr. */
@@ -545,23 +648,58 @@ function _dumpsWithFloats(obj: Json, level = 0): string {
 interface Args {
     threshold: number;
     quiet: boolean;
+    /** Absolute scan root; `undefined` = the `src/skills` default. */
+    root?: string;
+    /** Absolute report directory; `undefined` = `agents/reports`. */
+    outDir?: string;
+    /** Print the same-domain pair table to stdout even under `--quiet`. */
+    printTable: boolean;
+    /** Fail the build on an unjustified same-pack pair at or above threshold. */
+    strict: boolean;
+    /** Allowlist path override (tests); `undefined` = the shipped file. */
+    allowlist?: string;
+    /** Which text the vector is built from. `description` is NON-canonical. */
+    field: Field;
 }
 
 export function parse_args(argv: string[]): Args {
-    const args: Args = { threshold: OVERLAP_THRESHOLD, quiet: false };
+    const args: Args = {
+        threshold: OVERLAP_THRESHOLD,
+        quiet: false,
+        printTable: false,
+        strict: false,
+        field: 'body',
+    };
+    const takeValue = (flag: string, inline: string | undefined, next: () => string | undefined): string => {
+        const v = inline ?? next();
+        if (v === undefined) {
+            process.stderr.write(`argument ${flag}: expected one argument\n`);
+            process.exit(2);
+        }
+        return v;
+    };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i] as string;
         if (a === '--quiet') {
             args.quiet = true;
-        } else if (a === '--threshold') {
-            const v = argv[++i];
-            if (v === undefined) {
-                process.stderr.write('argument --threshold: expected one argument\n');
-                process.exit(2);
-            }
-            args.threshold = Number(v);
-        } else if (a.startsWith('--threshold=')) {
-            args.threshold = Number(a.slice('--threshold='.length));
+        } else if (a === '--strict') {
+            args.strict = true;
+        } else if (a === '--allowlist' || a.startsWith('--allowlist=')) {
+            const inline = a.startsWith('--allowlist=') ? a.slice('--allowlist='.length) : undefined;
+            args.allowlist = path.resolve(ROOT, takeValue('--allowlist', inline, () => argv[++i]));
+        } else if (a === '--descriptions') {
+            args.field = 'description';
+        } else if (a === '--print-table') {
+            args.printTable = true;
+        } else if (a === '--threshold' || a.startsWith('--threshold=')) {
+            const inline = a.startsWith('--threshold=') ? a.slice('--threshold='.length) : undefined;
+            args.threshold = Number(takeValue('--threshold', inline, () => argv[++i]));
+        } else if (a === '--root' || a.startsWith('--root=')) {
+            const inline = a.startsWith('--root=') ? a.slice('--root='.length) : undefined;
+            args.root = path.resolve(ROOT, takeValue('--root', inline, () => argv[++i]));
+        } else if (a === '--out-dir' || a.startsWith('--out-dir=')) {
+            const inline = a.startsWith('--out-dir=') ? a.slice('--out-dir='.length) : undefined;
+            args.outDir = path.resolve(ROOT, takeValue('--out-dir', inline, () => argv[++i]));
         } else {
             process.stderr.write(`unrecognized arguments: ${a}\n`);
             process.exit(2);

package/src/scripts/audit_skill_overlap_allowlist.json

@@ -0,0 +1,4 @@
+{
+  "_comment": "Reviewed same-pack overlaps at or above the canonical 0.70 threshold. Each entry needs a real reason — a pair is here because a human read both skills and decided the overlap is structural, not because the gate was noisy. Capped at 20 by audit_skill_overlap.ts: crossing the cap means the threshold is wrong, not that the corpus needs a twenty-first exception. Empty is the healthy state.",
+  "entries": []
+}

package/src/scripts/build_proof.ts

@@ -146,6 +146,11 @@ function render(): string {
     const entries = [...ledger.values()].sort((a, b) => a.id.localeCompare(b.id));
     const backed = entries.filter((e) => e.status === 'backed');
     const unbacked = entries.filter((e) => e.status === 'unbacked');
+    // `resolved-null` is neither backed nor debt: the question was asked, the
+    // answer came back null, and the entry is closed. Counting it as debt
+    // would inflate the inventory with items that can never shrink; counting
+    // it as backed would claim a win that was never measured.
+    const resolvedNull = entries.filter((e) => e.status === 'resolved-null');
 
     const L: string[] = [];
     L.push('<!-- GENERATED by src/scripts/build_proof.ts — do NOT hand-edit.');
@@ -232,6 +237,13 @@ function render(): string {
         L.push('allowed to carry a marker in public prose. Hiding them would be the');
         L.push('opposite of the point.');
     }
+    if (resolvedNull.length > 0) {
+        L.push('');
+        L.push(`And our **nulls**: ${resolvedNull.length} claim(s) are \`resolved-null\` —`);
+        L.push('measured, the threshold was missed, and the entry is closed rather than');
+        L.push('left open forever. A null that stays filed as pending debt is a claim');
+        L.push('quietly waiting to be re-argued.');
+    }
     L.push('');
     L.push('## 2. We publish honest nulls');
     L.push('');
@@ -419,9 +431,11 @@ function render(): string {
     {
         const ledger = [...load_ledger().values()].sort((a, b) => a.id.localeCompare(b.id));
         const backed = ledger.filter((e) => e.status === 'backed').length;
+        const nulls = ledger.filter((e) => e.status === 'resolved-null').length;
         L.push(
             `**Axis 2 — evidence form per public claim.** ${ledger.length} ledger entries · ` +
-                `${backed} backed · ${ledger.length - backed} unbacked inventory.`,
+                `${backed} backed · ${ledger.length - backed - nulls} unbacked inventory · ` +
+                `${nulls} resolved-null.`,
         );
         L.push('');
         L.push('| Claim id | Kind | Status | Evidence pointer |');

package/src/scripts/check_dependency_floors.ts

@@ -44,11 +44,14 @@ const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..')
  * exact pin cannot suffer the freshest-patch failure (the version is either
  * cached or it is not), but it also forfeits patch fixes — so each one is
  * named here rather than silently tolerated.
+ *
+ * Empty since the code-graph parser pair (`web-tree-sitter` /
+ * `tree-sitter-wasms`) left `dependencies` — it was the only entry. The pair's
+ * ABI pin now lives in `code_graph/loader.ts`'s install hint, because that is
+ * the only place a re-enabler reads it; this gate scans `dependencies` and so
+ * no longer sees the pair at all.
  */
-export const EXACT_PIN_EXCEPTIONS: Readonly<Record<string, string>> = {
-    'web-tree-sitter': 'ABI-locked against tree-sitter-wasms; see code-graph engine pin',
-    'tree-sitter-wasms': 'ABI-locked against web-tree-sitter; see code-graph engine pin',
-};
+export const EXACT_PIN_EXCEPTIONS: Readonly<Record<string, string>> = {};
 
 /**
  * Floors that are non-settled ON PURPOSE, because every version below them is
@@ -74,8 +77,15 @@ const EXACT_VERSION = /^\d+\.\d+\.\d+$/;
 /**
  * Every violation in `dependencies`, as human-readable lines. Empty array
  * means the manifest cannot produce a freshest-patch `ETARGET` for a consumer.
+ *
+ * `exactPinExceptions` defaults to the module's list and is injectable so the
+ * allow-an-exact-pin branch stays covered now that the real list is empty —
+ * otherwise the only way to test it would be to add a fake production entry.
  */
-export function evaluate(dependencies: Readonly<Record<string, string>>): string[] {
+export function evaluate(
+    dependencies: Readonly<Record<string, string>>,
+    exactPinExceptions: Readonly<Record<string, string>> = EXACT_PIN_EXCEPTIONS,
+): string[] {
     const errors: string[] = [];
     for (const [name, range] of Object.entries(dependencies)) {
         const security = SECURITY_FLOOR_EXCEPTIONS[name];
@@ -89,7 +99,7 @@ export function evaluate(dependencies: Readonly<Record<string, string>>): string
             continue;
         }
         if (EXACT_VERSION.test(range)) {
-            if (!(name in EXACT_PIN_EXCEPTIONS)) {
+            if (!(name in exactPinExceptions)) {
                 errors.push(
                     `${name}@${range}: exact pin without an entry in EXACT_PIN_EXCEPTIONS — ` +
                         'add the reason there, or use a settled caret floor (^X.Y.0)',

package/src/scripts/check_gate_coverage.ts

@@ -31,13 +31,13 @@
  * Exit codes: 0 all enforced gates cleared their floor · 1 a gate is blind,
  * collapsed, or silent · 2 the manifest itself is missing/empty/malformed.
  */
-import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import yaml from 'js-yaml';
+import { runCountedProbe } from './_lib/counted_probe.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -184,11 +184,11 @@ export function classify(
 
 function run_gate(spec: GateSpec): { scanned: number | null; crashed: boolean; exit_code: number | null } {
   const runner = path.join(REPO_ROOT, 'scripts-run');
-  const r = spawnSync(runner, [`src/scripts/${spec.id}`, ...spec.argv], {
-    cwd: REPO_ROOT,
-    encoding: 'utf8',
-  });
-  if (r.error !== undefined || r.status === null) return { scanned: null, crashed: true, exit_code: null };
+  // Bounded read: a gate whose output overflowed would lose its `scanned:`
+  // line and be classified `silent` — the scan-scope guard reporting a dead
+  // scope that is merely truncated. `runCountedProbe` throws instead.
+  const r = runCountedProbe(runner, [`src/scripts/${spec.id}`, ...spec.argv], { cwd: REPO_ROOT });
+  if (r.failure !== null && r.status === null) return { scanned: null, crashed: true, exit_code: null };
   // A gate may legitimately exit non-zero (it found real violations) and still
   // have scanned plenty — coverage and verdict are different questions.
   return { scanned: parse_scanned(`${r.stdout}\n${r.stderr}`), crashed: false, exit_code: r.status };

package/src/scripts/check_kernel_rule_bundle.ts

@@ -36,6 +36,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { KERNEL_RULE_FILENAMES } from './_lib/kernel_rules.js';
+import { runCountedProbe } from './_lib/counted_probe.js';
 
 const KERNEL_RULES: ReadonlySet<string> = KERNEL_RULE_FILENAMES;
 
@@ -56,13 +57,13 @@ const KERNEL_DIR = 'src/rules';
 const DEFAULT_LABEL = 'bundled-always-rules-acknowledged';
 
 function _git_changed_files(base_ref: string): string[] {
-    const res = spawnSync('git', ['diff', '--name-only', `${base_ref}...HEAD`], {
-        encoding: 'utf8',
-    });
+    // Bounded read: a truncated diff would shrink the change set and let the
+    // bundle guard pass on files it never saw.
+    const res = runCountedProbe('git', ['diff', '--name-only', `${base_ref}...HEAD`]);
     // Python uses check_output(stderr=STDOUT, text=True): on non-zero it raises
     // CalledProcessError and the handler prints the combined output. spawnSync
     // does not raise; mirror by checking status and combining stdout+stderr.
-    if (res.status !== 0) {
+    if (!res.ok) {
         const combined = `${res.stdout ?? ''}${res.stderr ?? ''}`;
         process.stderr.write(`❌  git diff failed: ${combined.trim()}\n`);
         return [];

package/src/scripts/check_token_quality_golden.ts

@@ -113,20 +113,6 @@ export function router_triggers(router: Json): Map<string, Array<Record<string,
   return map;
 }
 
-// trigger_coverage.ts word semantics: lowercase alpha-led tokens, len > 2.
-const _WORD = /[a-z][a-z0-9_]+/g;
-
-function _tokens(text: string): Set<string> {
-  const out = new Set<string>();
-  const low = text.toLowerCase();
-  _WORD.lastIndex = 0;
-  let m: RegExpExecArray | null;
-  while ((m = _WORD.exec(low)) !== null) {
-    if (m[0].length > 2) out.add(m[0]);
-  }
-  return out;
-}
-
 /**
  * Whether a task exercises ≥1 trigger of the rule (prompt↔trigger
  * falsifiability, Phase 3). Kernel rules always fire.
@@ -140,16 +126,12 @@ export function task_fires_rule(
   if (kernel.has(ruleId)) return true;
   const triggers = router_triggers(router).get(ruleId) ?? [];
   const low = task.prompt.toLowerCase();
-  const toks = _tokens(task.prompt);
   const files = Array.isArray(task.context_files) ? task.context_files : [];
   const cmd = typeof task.command === 'string' ? task.command : '';
   for (const trig of triggers) {
     if ('keyword' in trig || 'phrase' in trig) {
       const needle = String(trig.keyword ?? trig.phrase).toLowerCase();
       if (needle && low.includes(needle)) return true;
-    } else if ('intent' in trig) {
-      const words = _tokens(String(trig.intent));
-      if (words.size > 0 && [...words].every((w) => toks.has(w))) return true;
     } else if ('path_prefix' in trig) {
       const prefix = String(trig.path_prefix);
       if (files.some((f) => f.startsWith(prefix))) return true;