@event4u/agent-config 9.11.0 → 9.13.0

package/src/scripts/ai_council/stance_tally.ts

@@ -51,7 +51,14 @@ export interface StanceTallyResult {
     consensus: OptionTally | null; // the option clearing the threshold, or null
     split: boolean; // true when no option clears the threshold
     abstain_count: number;
-    needs_repair: string[]; // members whose stance line was missing/unparseable
+    /**
+     * Members whose stance line was missing or unparseable. They COUNT toward
+     * `w_total` (they responded) and back no option — see the
+     * refusal-preservation invariant in `tally_stances`. Surfaced by
+     * `render_vote_tally` so a shrunken-signal quorum is visible rather than
+     * merely computed.
+     */
+    needs_repair: string[];
 }
 
 // Tolerant of whitespace and case; requires the three explicit fields in order.
@@ -150,7 +157,23 @@ export function tally_stances(
         parsed.push({ member, ...p });
     }
 
-    const w_total = parsed.length; // base weight 1.0 each, abstain included
+    // ── Refusal-preservation invariant (road-to-governance-invariants P2) ──
+    //
+    // Selection may never rank an option higher *because* a member refused
+    // less. A safety refusal is not a scored-down property, and — measured by
+    // spike S0.1 — the way this engine could be steered was not a weight but a
+    // DENOMINATOR: `w_total` once counted only members whose stance line
+    // parsed, so a refusal phrased as prose ("I will not answer this") vanished
+    // from the quorum and made consensus EASIER. Same two backers, margin
+    // −0.25 and no consensus when the refusal parsed as an abstention;
+    // +0.4167 and consensus when it did not parse. Δ 0.6667, outcome flipped.
+    //
+    // The fix is structural rather than a new gate: a member who RESPONDED
+    // counts toward the quorum whether or not its stance line parsed. It backs
+    // no option either way, so an unparseable response now behaves exactly like
+    // an abstention — the fail-safe direction. Members who never responded are
+    // dropped upstream (`!r.error`) and are correctly absent from `members`.
+    const w_total = parsed.length + needs_repair.length; // responded, abstain + unparseable included
     const threshold = CONSENSUS_FRACTION * w_total;
     let abstain_count = 0;
 
@@ -208,6 +231,18 @@ export function render_vote_tally(result: StanceTallyResult): string {
     if (result.abstain_count > 0) {
         lines.push(`- abstain — ${result.abstain_count} member(s) (raises the bar)`);
     }
+    // Refusal divergence, as an OBSERVATION and never a selection input
+    // (road-to-governance-invariants P2). A member whose stance did not parse
+    // still counts toward the quorum; saying so here is what makes a shrunken
+    // signal visible to a reader instead of merely present in a struct field
+    // no caller reads. Nothing in the tally consumes this string.
+    if (result.needs_repair.length > 0) {
+        lines.push(
+            `- unparsed — ${result.needs_repair.length} member(s) responded without a ` +
+                `readable stance (${result.needs_repair.join(', ')}); counted in the ` +
+                'quorum, backing nothing',
+        );
+    }
     lines.push(`Threshold: ⅔ × ${result.w_total} = ${result.threshold.toFixed(2)}`);
     lines.push(
         result.consensus !== null

package/src/scripts/audit_auto_rules.ts

@@ -136,14 +136,14 @@ export function _split_frontmatter(text: string): [Record<string, Json>, string]
 interface TriggerSummary {
     path_prefixes: string[];
     keywords: string[];
-    intents: string[];
+    phrases: string[];
 }
 
 /** Mirror `_trigger_summary`. */
 export function _trigger_summary(triggers: Json): TriggerSummary {
     const paths: string[] = [];
     const keywords: string[] = [];
-    const intents: string[] = [];
+    const phrases: string[] = [];
     const list: Json[] = Array.isArray(triggers) ? triggers : [];
     for (const entry of list) {
         if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
@@ -156,11 +156,11 @@ export function _trigger_summary(triggers: Json): TriggerSummary {
         if ('keyword' in e) {
             keywords.push(String(e['keyword']));
         }
-        if ('intent' in e) {
-            intents.push(String(e['intent']));
+        if ('phrase' in e) {
+            phrases.push(String(e['phrase']));
         }
     }
-    return { path_prefixes: paths, keywords, intents };
+    return { path_prefixes: paths, keywords, phrases };
 }
 
 interface RuleEntry {
@@ -208,7 +208,7 @@ export function collect(): RuleEntry[] {
             description_chars: pyLen(desc),
             triggers,
             trigger_count:
-                triggers.path_prefixes.length + triggers.keywords.length + triggers.intents.length,
+                triggers.path_prefixes.length + triggers.keywords.length + triggers.phrases.length,
             routes_to,
             body_chars: pyLen(body),
             file_chars: pyLen(text),
@@ -292,7 +292,7 @@ export function render_markdown(rules: RuleEntry[]): string {
         const triggers =
             `${r.triggers.path_prefixes.length}p / ` +
             `${r.triggers.keywords.length}k / ` +
-            `${r.triggers.intents.length}i`;
+            `${r.triggers.phrases.length}ph`;
         const routes = r.routes_to.map((x) => String(x)).join(', ') || '—';
         lines.push(
             `| ${i} | \`${r.name}\` | ${_pyTruthy(r.tier) ? String(r.tier) : '—'} | ` +
@@ -302,7 +302,7 @@ export function render_markdown(rules: RuleEntry[]): string {
         i++;
     }
     lines.push('');
-    lines.push('Trigger key: `Np` = path-prefix, `Nk` = keyword, `Ni` = intent.');
+    lines.push('Trigger key: `Np` = path-prefix, `Nk` = keyword, `Nph` = phrase.');
     lines.push('');
     return lines.join('\n');
 }
@@ -393,7 +393,7 @@ function _ruleToJson(r: RuleEntry): Record<string, Json> {
         triggers: {
             path_prefixes: r.triggers.path_prefixes,
             keywords: r.triggers.keywords,
-            intents: r.triggers.intents,
+            phrases: r.triggers.phrases,
         },
         trigger_count: r.trigger_count,
         routes_to: r.routes_to,

package/src/scripts/audit_likelihood.ts

@@ -16,7 +16,7 @@
  * For every auto-rule from `agents/reports/auto-rules-audit.json`:
  *
  * 1. Build a token set from `description`, `triggers[].keyword`,
- *    `triggers[].intent`, and the rule name itself.
+ *    `triggers[].phrase`, and the rule name itself.
  * 2. Index a corpus of skills (`SKILL.md`), contexts, guidelines, and
  *    command files.
  * 3. Score `corpus_hits = sum(1 for token in tokens if token in corpus)`.
@@ -197,9 +197,9 @@ function _ruleTokens(rule: Json): Set<string> {
     add(tokens(String(rule['name'] ?? '').replaceAll('-', ' ')));
     const trig = rule['triggers'] ?? {};
     const kw: Json[] = Array.isArray(trig['keywords']) ? trig['keywords'] : [];
-    const intents: Json[] = Array.isArray(trig['intents']) ? trig['intents'] : [];
+    const phrases: Json[] = Array.isArray(trig['phrases']) ? trig['phrases'] : [];
     add(tokens(kw.map((x) => String(x)).join(' ')));
-    add(tokens(intents.map((x) => String(x)).join(' ')));
+    add(tokens(phrases.map((x) => String(x)).join(' ')));
     return out;
 }
 

package/src/scripts/audit_overlap.ts

@@ -54,7 +54,7 @@ const _ALL_DIGITS = /^[0-9]+$/;
 interface RuleTriggers {
     path_prefixes: string[];
     keywords: string[];
-    intents: string[];
+    phrases: string[];
 }
 
 interface RuleEntry {
@@ -194,7 +194,7 @@ function analyse(rules: RuleEntry[]): Pair[] {
         for (const x of keyword_set(r.triggers.keywords.join(' '))) {
             kw.add(x);
         }
-        for (const x of keyword_set(r.triggers.intents.join(' '))) {
+        for (const x of keyword_set(r.triggers.phrases.join(' '))) {
             kw.add(x);
         }
         keywords.push(kw);

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 |');