@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/ai_council/topology_vocabulary.ts

@@ -0,0 +1,175 @@
+/**
+ * The council-rung topology vocabulary, closed at seven names.
+ *
+ * `road-to-inbox-harvest-2026-08-e-council-topology-evidence` step 7.1 asks
+ * for a vocabulary that "admits no eighth member without a schema change" and
+ * in which `team` / `user_required` are "not representable". Those are two
+ * different claims and they need two different mechanisms, so this module
+ * carries both.
+ *
+ * ## Where this sits — and what it deliberately is NOT
+ *
+ * It is **not** a resolver. `src/scripts/_lib/judgment_ladder.ts` is the ONE
+ * task-side resolver, and `src/scripts/_lib/one_resolver_invariant.ts` fails
+ * the build on a second one. This module exports a NAME SET and two
+ * predicates; it classifies nothing, reads no request, and takes no routing
+ * decision. It also lives under `ai_council/`, which the one-resolver scan
+ * treats as council-internal and skips by construction — the topology
+ * refinement hangs off the council rung *after* the ladder has already
+ * resolved to it, exactly as the roadmap's goal diagram draws it.
+ *
+ * The selector that will eventually CONSUME this vocabulary is step 7.2 and is
+ * not built here. Shipping the vocabulary first is deliberate: it is the half
+ * that can be closed without pre-empting the selector's design.
+ *
+ * ## Claim 1 — no eighth member without a source change that fails a gate
+ *
+ * {@link COUNCIL_TOPOLOGIES} is a frozen `as const` tuple, so its `length` is
+ * the literal `7` and {@link CouncilTopology} is a closed union. Appending an
+ * eighth entry turns the length into `8`, and {@link VocabularyIsClosed}'s
+ * first assertion then fails `npm run typecheck` — a CI gate. The same edit
+ * also fails {@link auditCouncilTopologyVocabulary}, which is the runtime half
+ * for the compiled `dist/` path where types no longer exist.
+ *
+ * ## Claim 2 — `team` and `user_required` are not representable
+ *
+ * Omitting two strings from a list is the weak form: nothing stops the next
+ * author adding them. The strong form binds the exclusion to the vocabularies
+ * that actually own those names, via TYPE-ONLY imports that are erased at
+ * compile time and couple nothing at runtime:
+ *
+ * - `team` is a `LadderVerdict` — rung 3, `judgment_ladder.ts:45`. The ladder
+ *   owns it.
+ * - `user_required` is an `ImpactClass` — `necessity.ts:550`, and it sits in
+ *   `LOCKED_IMPACT_CLASSES` (`necessity.ts:557-560`), the set structurally
+ *   locked to `user` routing. The Hard Floor owns it.
+ *
+ * {@link VocabularyIsClosed} asserts that NO `LadderVerdict` and NO
+ * `ImpactClass` is a `CouncilTopology` — which is stronger than naming two
+ * strings, because it also excludes `script`, `subagent`, `council`, `ask`,
+ * `in-session`, `high_impact` and the rest. It further asserts that the two
+ * names in {@link RESERVED_BY_OTHER_LAYERS} really ARE members of those
+ * foreign vocabularies, so a rename on the ladder or in the necessity gate
+ * reds this file rather than silently orphaning the exclusion.
+ *
+ * ## Why not a JSON schema, and why not the config contract
+ *
+ * `src/scripts/schemas/` carries no council schema at all — `.ai-council.yml`
+ * is validated by the hand-rolled loader in `ai_council/config.ts`, so there
+ * is no enum surface there to extend. And this vocabulary is deliberately
+ * absent from `docs/contracts/ai-council-config.md`: that document describes
+ * what a USER may configure, while step 12.4 requires consumer surfaces to
+ * request capabilities and never topology names. Documenting it as config
+ * would invite exactly the coupling 12.4 forbids.
+ */
+import type { LadderVerdict } from '../_lib/judgment_ladder.js';
+
+import type { ImpactClass } from './necessity.js';
+
+/**
+ * The closed topology vocabulary, verbatim from the roadmap's goal diagram
+ * (`road-to-inbox-harvest-2026-08-e-council-topology-evidence.md:62-68`).
+ * Order is the diagram's order and carries no precedence.
+ */
+export const COUNCIL_TOPOLOGIES = Object.freeze([
+    'single_external',
+    'dual_independent',
+    'advisor_diversity',
+    'peer_review',
+    'judge_synthesis',
+    'targeted_cross_exam',
+    'full_debate',
+] as const);
+
+/** The closed union. There is no widening escape hatch on purpose. */
+export type CouncilTopology = (typeof COUNCIL_TOPOLOGIES)[number];
+
+/** Declared arity. Changing the tuple without changing this reds the type layer. */
+export const COUNCIL_TOPOLOGY_ARITY = 7;
+
+/**
+ * Names owned by other layers, restated here so the runtime half can reject
+ * them without importing a value across the layer boundary. The type layer
+ * below pins each one to its real owning vocabulary.
+ */
+export const RESERVED_BY_OTHER_LAYERS = Object.freeze(['team', 'user_required'] as const);
+
+/** A name this vocabulary must never admit. */
+export type ReservedElsewhere = (typeof RESERVED_BY_OTHER_LAYERS)[number];
+
+/** Fails to instantiate unless `T` is exactly `true`. */
+type Assert<T extends true> = T;
+
+/**
+ * The compile-time half of both claims. Every member must stay `true`; each
+ * one is a distinct way the vocabulary could be opened, and `npm run
+ * typecheck` is the gate that runs them.
+ *
+ * 1. arity is exactly {@link COUNCIL_TOPOLOGY_ARITY} — an eighth member reds it
+ * 2. no ladder verdict is a topology — `team` included, by construction
+ * 3. no impact class is a topology — `user_required` included, by construction
+ * 4. both reserved names are real members of those foreign vocabularies, so a
+ *    rename upstream cannot orphan the exclusion into a dead string
+ * 5. neither reserved name is representable as a topology
+ *
+ * The `[X] extends [never]` tuple form is deliberate: it suppresses
+ * distribution, so an empty `Extract` reads as the single type `never` rather
+ * than as an empty union of branches.
+ */
+export type VocabularyIsClosed = [
+    Assert<(typeof COUNCIL_TOPOLOGIES)['length'] extends typeof COUNCIL_TOPOLOGY_ARITY ? true : false>,
+    Assert<[Extract<CouncilTopology, LadderVerdict>] extends [never] ? true : false>,
+    Assert<[Extract<CouncilTopology, ImpactClass>] extends [never] ? true : false>,
+    Assert<ReservedElsewhere extends LadderVerdict | ImpactClass ? true : false>,
+    Assert<[Extract<CouncilTopology, ReservedElsewhere>] extends [never] ? true : false>,
+];
+
+/** Is this value one of the seven? `team` and `user_required` are not. */
+export function isCouncilTopology(value: unknown): value is CouncilTopology {
+    return typeof value === 'string' && (COUNCIL_TOPOLOGIES as readonly string[]).includes(value);
+}
+
+/**
+ * The runtime half, and the reason it takes arguments rather than reading the
+ * constants directly: a guard that can only ever be handed the correct input
+ * has unknown sensitivity. Callers in `dist/` pass the shipped constants; the
+ * test passes mutations and asserts each one is caught.
+ *
+ * @returns one string per problem found; empty means the vocabulary is closed.
+ */
+export function auditCouncilTopologyVocabulary(
+    topologies: readonly string[] = COUNCIL_TOPOLOGIES,
+    reserved: readonly string[] = RESERVED_BY_OTHER_LAYERS,
+): string[] {
+    const problems: string[] = [];
+    if (topologies.length !== COUNCIL_TOPOLOGY_ARITY) {
+        problems.push(
+            `arity: expected exactly ${COUNCIL_TOPOLOGY_ARITY} topologies, found ${topologies.length}. ` +
+                'The vocabulary is closed; an eighth member is a schema change, not an append.',
+        );
+    }
+    if (new Set(topologies).size !== topologies.length) {
+        problems.push('duplicate: the vocabulary contains a repeated name.');
+    }
+    for (const name of reserved) {
+        if (topologies.includes(name)) {
+            problems.push(
+                `reserved: \`${name}\` is owned by another layer (the judgment ladder for ` +
+                    '`team`, the locked impact classes for `user_required`) and is not ' +
+                    'representable as a council topology.',
+            );
+        }
+    }
+    return problems;
+}
+
+/**
+ * Module-load guard. Types are erased in `dist/`, so without this the runtime
+ * artefact carries no version of claim 1 or claim 2 at all. It can only fire
+ * on a source edit that also reds `npm run typecheck`, which is the point:
+ * two independent layers, not one restated twice.
+ */
+const _shippedProblems = auditCouncilTopologyVocabulary();
+if (_shippedProblems.length > 0) {
+    throw new Error(`council topology vocabulary is not closed:\n  ${_shippedProblems.join('\n  ')}`);
+}

package/src/scripts/asset_delivery_ledger.ts

@@ -0,0 +1,157 @@
+#!/usr/bin/env tsx
+/**
+ * Per-asset delivery ledger — which assets produce the standing payload
+ * (`road-to-delivered-cost-truth` step 2.1).
+ *
+ * `check_preamble_payload_budget` measures three BUCKET totals and refuses
+ * growth. It cannot say which asset inside a bucket produces the cost, so a
+ * reduction effort has a number (35,692 tokens over a published milestone) and
+ * no target. This command ranks the assets behind that number.
+ *
+ * Class A per ADR-124: in-process, per-invocation, no socket, no daemon, no
+ * network, no writes outside a stdout/JSON report.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/asset_delivery_ledger [--format text|json]
+ *     [--top <n>] [--root <path>]
+ */
+import * as path from 'node:path';
+
+import {
+    buildLedger,
+    reconcile,
+    RECONCILE_MARGIN,
+    type AssetRow,
+    type LedgerVerdict,
+    type Reconciliation,
+} from './_lib/asset_delivery_ledger.js';
+import { measureDeterministicPayload } from './check_preamble_payload_budget.js';
+import { prefixStableDirRoots } from './_lib/prefix_stable_surfaces.js';
+
+const HERE = path.dirname(new URL(import.meta.url).pathname);
+const REPO_ROOT = path.resolve(HERE, '..', '..');
+
+export interface Options {
+    format: 'text' | 'json';
+    top: number;
+    root: string;
+}
+
+export function parseArgs(argv: string[]): Options {
+    const opts: Options = { format: 'text', top: 20, root: REPO_ROOT };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === undefined) continue;
+        if (a === '--format') opts.format = (argv[++i] as Options['format']) ?? opts.format;
+        else if (a.startsWith('--format=')) opts.format = a.slice('--format='.length) as Options['format'];
+        else if (a === '--top') opts.top = Number(argv[++i]) || opts.top;
+        else if (a.startsWith('--top=')) opts.top = Number(a.slice('--top='.length)) || opts.top;
+        else if (a === '--root') opts.root = path.resolve(argv[++i] ?? opts.root);
+        else if (a.startsWith('--root=')) opts.root = path.resolve(a.slice('--root='.length));
+    }
+    if (opts.format !== 'text' && opts.format !== 'json') opts.format = 'text';
+    return opts;
+}
+
+export interface Report {
+    schema: 'asset-delivery-ledger/v1';
+    ledger: LedgerVerdict;
+    reconciliation: Reconciliation[];
+    reconcile_margin: number;
+}
+
+export function buildReport(root: string): Report {
+    // Roots come from the prefix-stable registry, the same module the payload
+    // gate resolves its census roots from. A third statement of the same
+    // boundary is the drift shape this repository already pays for.
+    const [rulesRel, skillsRel] = prefixStableDirRoots();
+    const ledger = buildLedger(
+        path.join(root, rulesRel ?? 'dist/agent-src/rules'),
+        path.join(root, skillsRel ?? 'dist/agent-src/skills'),
+        root,
+    );
+    return {
+        schema: 'asset-delivery-ledger/v1',
+        ledger,
+        reconciliation: reconcile(ledger, measureDeterministicPayload(root)),
+        reconcile_margin: RECONCILE_MARGIN,
+    };
+}
+
+function pct(v: number): string {
+    return `${(v * 100).toFixed(1)}%`;
+}
+
+export function renderText(r: Report, top: number): string {
+    const out: string[] = [];
+    const l = r.ledger;
+    out.push('Per-asset delivery ledger — what every spawn pays for');
+    out.push(
+        `  measurement: ${l.exact_throughout ? 'exact BPE throughout' : 'MIXED — some rows fall back to the chars/4 proxy'}`,
+    );
+    out.push(`  total: ${l.total_tokens} tok across ${l.rows.length} asset(s)`);
+    out.push(
+        `  by kind: rules ${l.by_kind.rule.tokens} tok (${l.by_kind.rule.count}) · ` +
+            `skill catalogue lines ${l.by_kind['skill-catalogue-line'].tokens} tok (${l.by_kind['skill-catalogue-line'].count})`,
+    );
+    out.push('');
+    out.push(`Top ${Math.min(top, l.rows.length)} by delivered tokens:`);
+    out.push(`  ${'tokens'.padStart(7)}  ${'share'.padStart(6)}  ${'method'.padEnd(6)}  asset`);
+    for (const row of l.rows.slice(0, top)) {
+        out.push(
+            `  ${String(row.tokens).padStart(7)}  ${pct(row.share).padStart(6)}  ${row.method.padEnd(6)}  ${row.name} (${row.kind})`,
+        );
+    }
+    out.push('');
+    out.push('Reconciliation against the payload gate\'s own bucket totals:');
+    if (r.reconciliation.length === 0) {
+        out.push('  no bucket to reconcile against — the payload census measured nothing');
+    }
+    for (const rec of r.reconciliation) {
+        const mark = rec.within_margin ? '✅' : '❌';
+        out.push(
+            `  ${mark} ${rec.bucket}: ledger ${rec.ledger_proxy_tokens} tok vs bucket ${rec.bucket_tokens} tok ` +
+                `(drift ${pct(rec.drift)}, margin ${pct(r.reconcile_margin)}) · both chars/4` +
+                `\n       exact BPE for the same assets: ${rec.ledger_exact_tokens} tok` +
+                ` (${pct(1 - rec.ledger_exact_tokens / Math.max(rec.ledger_proxy_tokens, 1))} below the proxy)`,
+        );
+    }
+    out.push('');
+    out.push('  Reconciled like-for-like: both sides are chars/4, so what remains is real');
+    out.push('  disagreement rather than a method gap. The exact BPE figure is shown beside each');
+    out.push('  bucket because the gap is the interesting part — chars/4 overestimates short');
+    out.push('  structured lines far more than it does prose, which is why the skill catalogue');
+    out.push('  and the rule bodies diverge from the proxy by very different amounts.');
+    return out.join('\n') + '\n';
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const opts = parseArgs(argv);
+    let report: Report;
+    try {
+        report = buildReport(opts.root);
+    } catch (err) {
+        process.stderr.write(`❌  asset_delivery_ledger: ${(err as Error).message}\n`);
+        return 2;
+    }
+
+    if (report.ledger.rows.length === 0) {
+        process.stderr.write(
+            '❌  asset_delivery_ledger: no asset measured. The standing rule and skill trees are\n' +
+                '    generated (`task sync && task generate-tools`); a checkout that has not run them\n' +
+                '    has nothing to rank. This is a stated reason, not an empty ledger reported as zero.\n',
+        );
+        return 2;
+    }
+
+    process.stdout.write(
+        opts.format === 'json' ? JSON.stringify(report, null, 2) + '\n' : renderText(report, opts.top),
+    );
+    return report.reconciliation.every((r) => r.within_margin) ? 0 : 1;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === `file://${process.argv[1]}`) {
+    process.exit(main());
+}
+
+export type { AssetRow };

package/src/scripts/attest_artifact.ts

@@ -0,0 +1,193 @@
+#!/usr/bin/env tsx
+/**
+ * Content attestation for any artifact a hook would INJECT.
+ *
+ * `road-to-skill-ecosystem-runtime-enforcement` Phase 5, Steps 6-7, and the
+ * ordering in that step is the argument: attestation is the **precondition** for
+ * auto-injection, not a follow-up to it.
+ *
+ * ── The threat, concretely ──────────────────────────────────────────────────
+ * A hook that reads a tracked file and injects its contents into the model's
+ * context turns that file into a **standing injection amplifier**. Whoever can
+ * write the file can write the agent's instructions, on every session, without
+ * a review — which is `untrusted-input-defense`'s found-instructions case
+ * arriving through a file the repository itself vouches for. The file being
+ * tracked is not the control: a tracked file changes in a pull request, and a
+ * pull request that changes an injected file is indistinguishable in the diff
+ * from one that changes documentation.
+ *
+ * ── The contract ────────────────────────────────────────────────────────────
+ * An injectable artifact carries a sidecar `<file>.attest.json` holding the
+ * sha256 of its bytes and the date the attestation was recorded. Before
+ * injecting, a caller asks {@link verifyArtifact}:
+ *
+ *   - hash matches   → `ok`, inject.
+ *   - hash differs   → `mismatch`, REFUSE. The content changed since a human
+ *     vouched for it; re-attesting is a deliberate act with a diff.
+ *   - no sidecar     → `unattested`, REFUSE. **Not "allow because nothing said
+ *     no"** — that default makes the whole mechanism opt-out, and the file an
+ *     attacker adds is exactly the one with no sidecar.
+ *   - file missing   → `absent`, REFUSE.
+ *
+ * ── What this does NOT claim ────────────────────────────────────────────────
+ * The sidecar is committed beside the artifact, so an attacker who can write
+ * both can write a consistent pair. This is NOT a cryptographic signature and
+ * does not pretend to be one. What it buys is that the change becomes VISIBLE:
+ * a diff that touches an injected file must also touch its attestation, and a
+ * hash line changing in a review is a question, where a prose change in the same
+ * file is not. Making a change reviewable is the honest claim; making it
+ * impossible would need a key this repository does not have.
+ *
+ * Exit codes: 0 verified · 1 refused (mismatch / unattested / absent) · 2 usage.
+ *
+ * Usage:
+ *     ./scripts-run src/scripts/attest_artifact --record <file>
+ *     ./scripts-run src/scripts/attest_artifact --verify <file>
+ *     ./scripts-run src/scripts/attest_artifact --verify <file> --json
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+/** Sidecar suffix. Beside the artifact, so a move takes the attestation with it. */
+export const ATTEST_SUFFIX = '.attest.json';
+
+export type AttestStatus = 'ok' | 'mismatch' | 'unattested' | 'absent';
+
+export interface Attestation {
+    schema_version: 1;
+    /** sha256 of the artifact's bytes, hex. */
+    sha256: string;
+    /** `YYYY-MM-DD` the attestation was recorded. */
+    recorded_at: string;
+    /** Bytes at record time — a cheap second signal that costs nothing to store. */
+    bytes: number;
+}
+
+export interface Verdict {
+    status: AttestStatus;
+    /** True only for `ok`. Every other status refuses. */
+    inject: boolean;
+    detail: string;
+    expected?: string;
+    actual?: string;
+}
+
+export function sidecarPath(artifact: string): string {
+    return `${artifact}${ATTEST_SUFFIX}`;
+}
+
+export function hashFile(artifact: string): string {
+    return crypto.createHash('sha256').update(fs.readFileSync(artifact)).digest('hex');
+}
+
+/**
+ * Verify an artifact against its sidecar.
+ *
+ * Every non-`ok` status sets `inject: false`. That is the whole safety property
+ * and it is expressed as data rather than left to each caller's `if`: a caller
+ * that reads `verdict.inject` cannot accidentally treat `unattested` as
+ * permissive, which is the mistake an `status === 'mismatch'` check invites.
+ */
+export function verifyArtifact(artifact: string, today?: string): Verdict {
+    void today;
+    if (!fs.existsSync(artifact)) {
+        return { status: 'absent', inject: false, detail: `${artifact} does not exist` };
+    }
+    const side = sidecarPath(artifact);
+    if (!fs.existsSync(side)) {
+        return {
+            status: 'unattested',
+            inject: false,
+            detail:
+                `${artifact} has no ${ATTEST_SUFFIX} sidecar — REFUSED. An unattested artifact is ` +
+                'not "allowed because nothing said no": that default makes attestation opt-out, and ' +
+                'the file an attacker adds is precisely the one with no sidecar.',
+        };
+    }
+    let att: Partial<Attestation>;
+    try {
+        att = JSON.parse(fs.readFileSync(side, 'utf8')) as Partial<Attestation>;
+    } catch (e) {
+        return {
+            status: 'unattested',
+            inject: false,
+            detail: `${side} does not parse (${e instanceof Error ? e.message : String(e)}) — treated as absent`,
+        };
+    }
+    const actual = hashFile(artifact);
+    if (typeof att.sha256 !== 'string' || att.sha256 === '') {
+        return { status: 'unattested', inject: false, detail: `${side} carries no sha256`, actual };
+    }
+    if (att.sha256 !== actual) {
+        return {
+            status: 'mismatch',
+            inject: false,
+            detail:
+                `${artifact} changed since it was attested — REFUSED. Re-attest deliberately ` +
+                `(--record) so the new hash lands in a diff a reviewer sees.`,
+            expected: att.sha256,
+            actual,
+        };
+    }
+    return { status: 'ok', inject: true, detail: `${artifact} matches its attestation`, expected: att.sha256, actual };
+}
+
+/** Record (or re-record) an attestation. Deliberate, and it lands in a diff. */
+export function recordAttestation(artifact: string, today = new Date().toISOString().slice(0, 10)): Attestation {
+    const att: Attestation = {
+        schema_version: 1,
+        sha256: hashFile(artifact),
+        recorded_at: today,
+        bytes: fs.statSync(artifact).size,
+    };
+    fs.writeFileSync(sidecarPath(artifact), `${JSON.stringify(att, null, 2)}\n`, 'utf8');
+    return att;
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const usage =
+        'usage: attest_artifact (--record | --verify) <file> [--json]\n' +
+        '  --verify exits 1 on mismatch, unattested or absent. Refusal is the default.\n';
+    if (argv.includes('-h') || argv.includes('--help')) {
+        process.stdout.write(usage);
+        return 0;
+    }
+    const asJson = argv.includes('--json');
+    const record = argv.includes('--record');
+    const verify = argv.includes('--verify');
+    const file = argv.find((a) => !a.startsWith('--'));
+    if (record === verify || file === undefined) {
+        process.stderr.write(`attest_artifact: error: exactly one of --record / --verify plus a file\n${usage}`);
+        return 2;
+    }
+    const target = path.resolve(file);
+    if (record) {
+        if (!fs.existsSync(target)) {
+            process.stderr.write(`attest_artifact: ${file} does not exist\n`);
+            return 2;
+        }
+        const att = recordAttestation(target);
+        process.stdout.write(`✅  attested ${file} — sha256 ${att.sha256.slice(0, 16)}… (${String(att.bytes)} bytes)\n`);
+        return 0;
+    }
+    const v = verifyArtifact(target);
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(v, null, 2)}\n`);
+    } else if (v.inject) {
+        process.stdout.write(`✅  ${v.detail}\n`);
+    } else {
+        process.stderr.write(`❌  [${v.status}] ${v.detail}\n`);
+    }
+    return v.inject ? 0 : 1;
+}
+
+/* c8 ignore start */
+if (process.argv[1] !== undefined && pathToFileURL(path.resolve(process.argv[1])).href === pathToFileURL(_HERE).href) {
+    process.exit(main());
+}
+/* c8 ignore stop */

package/src/scripts/audit_auto_rules.ts

@@ -29,6 +29,7 @@ import { parse as parseYaml } from 'yaml';
 
 import { artefact_roots } from './_lib/agent_src.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { generatedBy } from './_lib/generated_by.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/audit_auto_rules.py → parent.parent.parent == repo root.
@@ -270,7 +271,7 @@ export function render_markdown(rules: RuleEntry[]): string {
         `<!-- analyzed: ${dateStr} | commit: ${commitShort} | files: ${rules.length} -->`,
         '# Auto-Rule Audit',
         '',
-        'Generated by `scripts/audit_auto_rules.py` for Phase 5 of',
+        generatedBy('audit_auto_rules', 'For Phase 5 of'),
         '`agents/roadmaps/archive/road-to-augment-limit-fit.md`. Re-run after',
         'any rule add/merge/deprecate to refresh the baseline.',
         '',

package/src/scripts/audit_command_surface.ts

@@ -548,7 +548,7 @@ export function render_md(commands: Command[], pairs: OverlapPair[]): string {
     const lines: string[] = [
         '# Command-Surface Inventory',
         '',
-        '> Generated by `scripts/audit_command_surface.py`. ' +
+        '> Generated by `audit_command_surface`. Do not edit. ' +
             'Source: `.agent-src.uncondensed/commands/`.',
         '',
         '## Summary',

package/src/scripts/audit_mcp_tools.ts

@@ -25,7 +25,7 @@ import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
-// src/scripts/audit_mcp_tools.ts → parent.parent.parent of the .py file = repo root.
+// audit_mcp_tools → parent.parent.parent of the .py file = repo root.
 export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 export const CATALOG = path.join(ROOT, 'src/scripts/mcp_server/consumer_tool_catalog.json');
 export const TOOLS_TS = path.join(ROOT, 'src/scripts/mcp_server/tools.ts');
@@ -145,7 +145,7 @@ function _render(catalog: Catalog, handlers: Map<string, number>, cat_lines: Map
     lines.push('');
     lines.push('# MCP tool inventory');
     lines.push('');
-    lines.push('> Generated by [`src/scripts/audit_mcp_tools.ts`](../../src/scripts/audit_mcp_tools.ts)');
+    lines.push('> Generated by [`audit_mcp_tools`](../../audit_mcp_tools)');
     lines.push('> from the source-of-truth catalog');
     lines.push('> [`src/scripts/mcp_server/consumer_tool_catalog.json`](../../src/scripts/mcp_server/consumer_tool_catalog.json).');
     lines.push('> Do **not** hand-edit; rerun `./scripts-run src/scripts/audit_mcp_tools --write`.');

package/src/scripts/audit_skill_overlap_allowlist.json

@@ -1,4 +1,9 @@
 {
   "_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": []
+  "entries": [
+    {
+      "pair": "test-driven-development::testing-anti-patterns",
+      "reason": "Structural vocabulary overlap from a shared testing domain (test, assertion, mock, fixture, red, green), not duplicated responsibility. The two are architecturally distinct: test-driven-development is the PROCEDURE — four mode contracts with diff-checked Forbidden columns, mode inference on resume, the delete-and-restart law; testing-anti-patterns is the DIAGNOSTIC CATALOGUE — tautological assertions, hardcoded expectations, over-mocking, test-data realism. They answer different questions at different call sites. Measured 2026-08-26 with the audit's own collect()+_cosine(): the pair sat at 0.7000 before this change and 0.7120 after, so it was already at the cap and any body edit to either skill re-trips the gate. Migrating 11 lines of rationale into a non-SKILL.md companion was tried and measured (0.7056) and REJECTED: it still failed, and it removes guidance from the file the agent actually loads, which optimises for the detector rather than the reader. Merging was rejected — a procedure and a failure catalogue have distinct invocation needs. Invalidation trigger: reassess if either skill's scope materially changes, or if substantive guidance becomes duplicated between them rather than merely sharing vocabulary. Council 2026-08-26, 2/2 convergent (anthropic/claude-sonnet-4-5, openai/codex-default), agents/evidence/council/tdd-overlap-disposition.md."
+    }
+  ]
 }

package/src/scripts/audit_user_type_axis.ts

@@ -35,6 +35,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { SRC_SKILLS } from './_lib/agent_src.js';
 import { checkRatchet } from './_lib/gate_baseline.js';
 import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
+import { generatedBy } from './_lib/generated_by.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -198,7 +199,7 @@ export function _render_report(
     const lines: string[] = [
         '# User-type axis — frontmatter coverage audit',
         '',
-        'Generated by `scripts/audit_user_type_axis.py` (step-9 Phase 4).',
+        generatedBy('audit_user_type_axis', '(step-9 Phase 4.)'),
         '',
         `- Declared user-types (\`user-types/*.yml\`): **${declared.size}**`,
         `- Distinct frontmatter values across skills: **${byValue.size}**`,