@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/check_input_references.ts

@@ -0,0 +1,228 @@
+#!/usr/bin/env tsx
+/**
+ * Every in-body `${x}` on an artifact that declares `inputs:` is backed by a
+ * declaration.
+ *
+ * road-to-an-invocation-contract-that-reaches-the-wire 2.2.
+ *
+ * SCOPED TO DECLARING ARTIFACTS, ON PURPOSE
+ *
+ * An artifact with no `inputs:` block is not checked at all. That is what lets
+ * this arrive with zero findings over a corpus where nothing declares anything
+ * yet, and grow only with adoption — a check that fired on every artifact would
+ * have to be introduced together with a migration nobody asked for, which is
+ * exactly what the optional block was designed to avoid.
+ *
+ * THE COUNTING UNIT IS THE CENSUS'S, IMPORTED
+ *
+ * A reference counts when it appears in PROSE — outside fenced code blocks,
+ * indented blocks and inline code spans. `proseOnly` is imported from
+ * `report_invocation_surface.ts` rather than restated, because two copies of
+ * that definition would drift and the whole point of this phase is that the
+ * declaration and what depends on it cannot disagree.
+ *
+ * The consequence is stated rather than hidden: a `${target}` inside a fenced
+ * usage example is NOT checked. That is the conservative direction. A skill
+ * teaching Terraform has `${local.x}` in a fence and would otherwise be
+ * reported against a declaration it never claimed to satisfy — a false positive
+ * on working content, which is the failure that makes a young gate get
+ * disabled. When adoption makes in-fence usage examples common, widening the
+ * unit is a deliberate change with its own diff.
+ *
+ * Exit codes: 0 every reference backed · 1 an unbacked reference · 2 the corpus
+ * could not be read.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import * as yaml from 'js-yaml';
+
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { assertScanned, reportScanned } from './_lib/scan_scope.js';
+import { proseOnly } from './report_invocation_surface.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export const GATE = 'check_input_references';
+
+/** The reference form this checks. Only the plurality syntax is a reference. */
+const REFERENCE_RE = /\$\{([a-z][a-z0-9_]*)\}/g;
+
+export interface Unbacked {
+    readonly file: string;
+    readonly name: string;
+    readonly declared: readonly string[];
+}
+
+/** Declared input names, or `null` when the artifact declares no block at all. */
+export function declaredInputs(text: string): string[] | null {
+    const m = /^---\n([\s\S]*?)\n---/.exec(text);
+    if (m === null) return null;
+    let fm: unknown;
+    try {
+        fm = yaml.load(m[1]!);
+    } catch {
+        return null;
+    }
+    if (fm === null || typeof fm !== 'object') return null;
+    const inputs = (fm as Record<string, unknown>)['inputs'];
+    if (!Array.isArray(inputs)) return null;
+    const names: string[] = [];
+    for (const item of inputs) {
+        if (item === null || typeof item !== 'object') continue;
+        const name = (item as Record<string, unknown>)['name'];
+        if (typeof name === 'string') names.push(name);
+    }
+    return names;
+}
+
+/**
+ * Prose `${x}` references with no matching declaration.
+ *
+ * Returns `[]` for an artifact that declares no block — not because it has no
+ * references, but because it is out of scope.
+ */
+export function unbackedReferences(text: string, file = '<data>'): Unbacked[] {
+    const declared = declaredInputs(text);
+    if (declared === null) return [];
+    const seen = new Set<string>();
+    const out: Unbacked[] = [];
+    for (const m of proseOnly(text).matchAll(REFERENCE_RE)) {
+        const name = m[1]!;
+        if (declared.includes(name) || seen.has(name)) continue;
+        seen.add(name);
+        out.push({ file, name, declared });
+    }
+    return out;
+}
+
+function walk(dir: string, match: (n: string) => boolean, out: string[] = []): string[] {
+    if (!fs.existsSync(dir)) return out;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        const p = path.join(dir, e.name);
+        if (e.isDirectory()) walk(p, match, out);
+        else if (match(e.name)) out.push(p);
+    }
+    return out;
+}
+
+export function scan(root: string): { findings: Unbacked[]; scanned: number; declaring: number } {
+    const files = [
+        ...walk(path.join(root, 'dist', 'agent-src', 'commands'), (n) => n.endsWith('.md')),
+        ...walk(path.join(root, 'src', 'skills'), (n) => n === 'SKILL.md'),
+    ].sort();
+
+    const findings: Unbacked[] = [];
+    let declaring = 0;
+    for (const f of files) {
+        const text = fs.readFileSync(f, 'utf8');
+        if (declaredInputs(text) !== null) declaring += 1;
+        findings.push(...unbackedReferences(text, path.relative(root, f)));
+    }
+    return { findings, scanned: files.length, declaring };
+}
+
+export function main(argv: readonly string[]): number {
+    if (argv.includes('--self-test')) return selfTest();
+    const rootIdx = argv.indexOf('--root');
+    const root = rootIdx === -1 ? ROOT : (argv[rootIdx + 1] ?? ROOT);
+
+    const { findings, scanned, declaring } = scan(root);
+    const ledger = new GateLedger(GATE);
+    ledger.plan(findings.map((f) => `${f.file}:${f.name}`));
+    for (const f of findings) {
+        ledger.fail(`${f.file}:${f.name}`, `\`\${${f.name}}\` is not declared`);
+    }
+
+    // A gate that read nothing has not passed. This fires BEFORE the verdict,
+    // because certifying against an empty corpus is the false green the coverage
+    // manifest exists to refuse — named by the provider-diverse ratification
+    // review as one condition that would have flipped its verdict.
+    assertScanned({ gate: GATE, scanned: scanned, units: 'artifact(s)', roots: ['dist/agent-src/commands', 'src/skills'] });
+
+    reportScanned({
+        gate: GATE,
+        scanned,
+        units: 'artifact(s)',
+        roots: ['dist/agent-src/commands', 'src/skills'],
+    });
+    ledger.report();
+
+    if (findings.length > 0) {
+        for (const f of findings) {
+            process.stdout.write(
+                `❌  ${GATE}: ${f.file} references \`\${${f.name}}\` with no \`inputs.${f.name}\` ` +
+                    `(declared: ${f.declared.length > 0 ? f.declared.join(', ') : 'none'}).\n`,
+            );
+        }
+        process.stdout.write(
+            '\nAdd the declaration, or drop the reference. Only artifacts that declare ' +
+                '`inputs:` at all are checked, so this never asks an artifact to start ' +
+                'declaring — it asks a declaration to be complete.\n',
+        );
+        return 1;
+    }
+
+    process.stdout.write(
+        `✅  ${GATE}: every in-body reference is backed ` +
+            `(${String(declaring)} of ${String(scanned)} artifact(s) declare \`inputs:\`).\n`,
+    );
+    return 0;
+}
+
+/**
+ * A self-test is what proves a gate DISCRIMINATES. An enforced scan floor only
+ * proves it read something; the verdict has to move.
+ */
+function selfTest(): number {
+    const plant = (name: string, body: string): string => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), `input-refs-${name}-`));
+        const skills = path.join(dir, 'src', 'skills', 'probe');
+        fs.mkdirSync(skills, { recursive: true });
+        fs.writeFileSync(path.join(skills, 'SKILL.md'), body, 'utf-8');
+        return dir;
+    };
+    const declaring = (ref: string): string =>
+        `---\nname: probe\ninputs:\n  - name: a\n    type: string\n---\n\nUses ${ref} here.\n`;
+
+    const run = (root: string): number =>
+        runGateCli(ROOT, path.join('src', 'scripts', 'check_input_references.ts'), ['--root', root], ROOT);
+
+    return runSelfTest({
+        gate: GATE,
+        minCases: 4,
+        minRejectCases: 2,
+        cases: [
+            {
+                name: 'an empty corpus is refused, not certified green',
+                expect: 'reject',
+                run: () => run(fs.mkdtempSync(path.join(os.tmpdir(), 'input-refs-empty-'))),
+            },
+            {
+                name: 'a reference the declaration backs passes',
+                expect: 'accept',
+                run: () => run(plant('backed', declaring('${a}'))),
+            },
+            {
+                name: 'a reference nothing declares fails',
+                expect: 'reject',
+                run: () => run(plant('unbacked', declaring('${b}'))),
+            },
+            {
+                name: 'an artifact with no declaration is out of scope, however it references',
+                expect: 'accept',
+                run: () =>
+                    run(plant('noblock', '---\nname: probe\n---\n\nUses ${anything} here.\n')),
+            },
+        ],
+    });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/check_inputs_parity.ts

@@ -0,0 +1,235 @@
+#!/usr/bin/env tsx
+/**
+ * What the MCP server reads from an `inputs:` block equals what a real YAML
+ * parser reads from it.
+ *
+ * road-to-an-invocation-contract-that-reaches-the-wire — added after review.
+ *
+ * WHY THIS GATE EXISTS
+ *
+ * The server's `_parse_inputs` is a hand-rolled reader of a YAML subset,
+ * because the MCP server is stdlib-only and bundled and must not grow a YAML
+ * dependency to read one optional block. A hand-rolled reader of a format it
+ * does not fully implement has exactly one dangerous failure mode: reading
+ * something DIFFERENT from what the author wrote, silently. A host is then told
+ * about an argument that does not exist, or not told about one that does — and
+ * the schema validates either way, because the schema checks the YAML, not the
+ * reader.
+ *
+ * An independent review found that failure live: the reader's key scan ran at
+ * any depth, so a `default:` mapping whose first child was `name:` overwrote
+ * the parameter's own name. It also silently misread `required: True`, the
+ * flow form, a comment at column zero, and a block scalar. Every one of those
+ * is schema-valid.
+ *
+ * So the reader now DECLINES what it cannot model, and this gate makes every
+ * decline and every divergence a build failure with a named remedy. The
+ * contract is: write the block form, or the build tells you. That is strictly
+ * better than a reader that is clever and occasionally wrong, and it is why the
+ * reader is allowed to stay stdlib-only.
+ *
+ * Exit codes: 0 parity holds · 1 a divergence · 2 the corpus could not be read.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import * as yaml from 'js-yaml';
+
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { assertScanned, reportScanned } from './_lib/scan_scope.js';
+import { _frontmatter_text, _parse_inputs, type PromptInput } from './mcp_server/prompts.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export const GATE = 'check_inputs_parity';
+
+/** The same reduction `_parse_inputs` produces, taken from a real YAML parse. */
+export function yamlInputs(fmText: string): PromptInput[] | null {
+    let doc: unknown;
+    try {
+        doc = yaml.load(fmText);
+    } catch {
+        return null;
+    }
+    if (doc === null || typeof doc !== 'object') return null;
+    const raw = (doc as Record<string, unknown>)['inputs'];
+    if (raw === undefined) return null;
+    if (!Array.isArray(raw)) return [];
+    const out: PromptInput[] = [];
+    for (const item of raw) {
+        if (item === null || typeof item !== 'object') continue;
+        const r = item as Record<string, unknown>;
+        if (typeof r['name'] !== 'string') continue;
+        out.push({
+            name: r['name'],
+            description: typeof r['description'] === 'string' ? r['description'] : '',
+            required: r['required'] === true,
+        });
+    }
+    return out;
+}
+
+export interface Divergence {
+    readonly file: string;
+    readonly server: PromptInput[];
+    readonly yaml: PromptInput[];
+}
+
+const same = (a: readonly PromptInput[], b: readonly PromptInput[]): boolean =>
+    a.length === b.length &&
+    a.every(
+        (x, i) =>
+            x.name === b[i]!.name &&
+            x.required === b[i]!.required &&
+            x.description === b[i]!.description,
+    );
+
+/** Compare both readers over one document. `null` when it declares no block. */
+export function compare(text: string, file: string): Divergence | null {
+    const fm = _frontmatter_text(text);
+    if (fm === '') return null;
+    const expected = yamlInputs(fm);
+    if (expected === null) return null;
+    const actual = _parse_inputs(fm);
+    return same(actual, expected) ? null : { file, server: actual, yaml: expected };
+}
+
+function walk(dir: string, match: (n: string) => boolean, out: string[] = []): string[] {
+    if (!fs.existsSync(dir)) return out;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        const p = path.join(dir, e.name);
+        if (e.isDirectory()) walk(p, match, out);
+        else if (match(e.name)) out.push(p);
+    }
+    return out;
+}
+
+export function scan(root: string): { findings: Divergence[]; scanned: number } {
+    const files = [
+        ...walk(path.join(root, 'src', 'domains'), (n) => n === 'command.md'),
+        ...walk(path.join(root, 'src', 'skills'), (n) => n === 'SKILL.md'),
+        ...walk(path.join(root, 'dist', 'agent-src', 'commands'), (n) => n.endsWith('.md')),
+    ].sort();
+
+    const findings: Divergence[] = [];
+    for (const f of files) {
+        const d = compare(fs.readFileSync(f, 'utf8'), path.relative(root, f));
+        if (d !== null) findings.push(d);
+    }
+    return { findings, scanned: files.length };
+}
+
+export function main(argv: readonly string[]): number {
+    if (argv.includes('--self-test')) return selfTest();
+    const rootIdx = argv.indexOf('--root');
+    const root = rootIdx === -1 ? ROOT : (argv[rootIdx + 1] ?? ROOT);
+
+    const { findings, scanned } = scan(root);
+    const ledger = new GateLedger(GATE);
+    ledger.plan(findings.map((f) => f.file));
+    for (const f of findings) {
+        ledger.fail(f.file, `server read ${String(f.server.length)}, YAML read ${String(f.yaml.length)}`);
+    }
+
+    // A gate that read nothing has not passed. This fires BEFORE the verdict,
+    // because certifying against an empty corpus is the false green the coverage
+    // manifest exists to refuse — named by the provider-diverse ratification
+    // review as one condition that would have flipped its verdict.
+    assertScanned({ gate: GATE, scanned: scanned, units: 'artifact(s)', roots: ['src/domains', 'src/skills', 'dist/agent-src/commands'] });
+
+    reportScanned({
+        gate: GATE,
+        scanned,
+        units: 'artifact(s)',
+        roots: ['src/domains', 'src/skills', 'dist/agent-src/commands'],
+    });
+    ledger.report();
+
+    if (findings.length > 0) {
+        for (const f of findings) {
+            process.stdout.write(
+                `❌  ${GATE}: ${f.file} — the MCP reader and YAML disagree about \`inputs:\`.\n` +
+                    `      server: ${JSON.stringify(f.server)}\n` +
+                    `      yaml:   ${JSON.stringify(f.yaml)}\n`,
+            );
+        }
+        process.stdout.write(
+            '\nThe server reads one shape, deliberately — a block sequence of `- name:` items ' +
+                'with scalar values on their own lines. Rewrite the declaration in that shape. ' +
+                'The flow form, a block scalar and a nested mapping under an item key are ' +
+                'refused rather than guessed at, and this gate is how the refusal is visible ' +
+                'instead of becoming a wrong argument on the wire.\n',
+        );
+        return 1;
+    }
+
+    process.stdout.write(
+        `✅  ${GATE}: the MCP reader and YAML agree on every declared \`inputs:\` block.\n`,
+    );
+    return 0;
+}
+
+/**
+ * One rejecting case per way the reader and YAML can part company, plus the
+ * agreeing case — because a suite that only proves passes proves nothing.
+ */
+function selfTest(): number {
+    const plant = (name: string, fm: string): string => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), `inputs-parity-${name}-`));
+        const skills = path.join(dir, 'src', 'skills', 'probe');
+        fs.mkdirSync(skills, { recursive: true });
+        fs.writeFileSync(path.join(skills, 'SKILL.md'), `---\nname: probe\n${fm}---\n\nbody\n`, 'utf-8');
+        return dir;
+    };
+    const run = (root: string): number =>
+        runGateCli(ROOT, path.join('src', 'scripts', 'check_inputs_parity.ts'), ['--root', root], ROOT);
+
+    return runSelfTest({
+        gate: GATE,
+        minCases: 6,
+        minRejectCases: 5,
+        cases: [
+            {
+                name: 'an empty corpus is refused, not certified green',
+                expect: 'reject',
+                run: () => run(fs.mkdtempSync(path.join(os.tmpdir(), 'inputs-parity-empty-'))),
+            },
+            {
+                name: 'the supported block form agrees',
+                expect: 'accept',
+                run: () => run(plant('ok', 'inputs:\n  - name: a\n    type: string\n    required: true\n')),
+            },
+            {
+                name: 'the flow form is a divergence',
+                expect: 'reject',
+                run: () => run(plant('flow', 'inputs: [{name: a, type: string}]\n')),
+            },
+            {
+                name: 'a nested mapping under an item key is a divergence',
+                expect: 'reject',
+                run: () =>
+                    run(plant('nested', 'inputs:\n  - name: opts\n    type: string\n    default:\n      name: fallback\n')),
+            },
+            {
+                name: 'a block scalar is a divergence',
+                expect: 'reject',
+                run: () =>
+                    run(plant('scalar', 'inputs:\n  - name: a\n    type: string\n    description: >\n      long\n')),
+            },
+            {
+                name: 'a dash on its own line is a divergence',
+                expect: 'reject',
+                run: () => run(plant('bareDash', 'inputs:\n  -\n    name: a\n    type: string\n')),
+            },
+        ],
+    });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/check_kernel_edit_ratified.ts

@@ -30,10 +30,14 @@
  *
  * Gated: a diff touching a kernel rule under `src/rules/` (the nine of
  * `_lib/kernel_rules.ts`), a governance hook (`src/scripts/hooks/block_*.ts`),
- * or this gate itself — so it cannot be weakened without its own record. Such
- * a diff must carry a ratification artifact under
- * the ratifications directory with `verdict: ratified`, valid per the
- * ratification-artifact contract.
+ * hook plumbing — the YAML sources `hook_manifest.yaml` and
+ * `host_lowering.yaml`, their compiled siblings `hook_manifest.json` and
+ * `host_lowering.json`, the dispatcher `hooks/dispatch_hook.ts`, the
+ * kernel-rule list `_lib/kernel_rules.ts`, a `*-dispatcher.sh`, either hook
+ * budget file (see `PLUMBING_SOURCE_RE`) — or this gate itself, so it cannot
+ * be weakened without its own record. Such a diff must carry a ratification
+ * artifact under the ratifications directory with `verdict: ratified`, valid
+ * per the ratification-artifact contract.
  *
  * Every kernel diff is gated, not only the authority-EXPANDING ones.
  * ADR-268 § 4 makes the artifact required for authority-expanding edits. Which
@@ -122,6 +126,67 @@ export const ANCHOR_PATHS: readonly string[] = [
 /** Governance hooks: the blocking PreToolUse guards. */
 const GOVERNANCE_HOOK_RE = /^src\/scripts\/hooks\/block_[a-z0-9_]+\.ts$/;
 
+/**
+ * Hook-plumbing SOURCES — the files that decide which concern runs, on which
+ * host, under which budget.
+ *
+ * `road-to-a-kernel-that-guards-its-plumbing` 1.1. The nine kernel rules were
+ * governed and the plumbing that decides whether a guard runs at all was not,
+ * so a diff deleting `block-no-verify` from the manifest carried no record
+ * while a typo in the rule it enforces carried one. The asymmetry was the
+ * defect: a concern removed from `hook_manifest.yaml` is a refusal that stops
+ * happening, which is the same authority change as loosening the rule behind
+ * it, reached one file earlier.
+ *
+ * This is the ADR-268 § 4 mechanism EXTENDED, not a second deny. Nothing new
+ * refuses a tool call here; the same CI gate simply reads a wider path set,
+ * and every property the gate already had — base-revision code, in-repo quorum
+ * policy, the whole diff as its unit — carries over unchanged.
+ *
+ * `dist/hooks/dispatch.js` and `hooks/hooks.json` are BUILD OUTPUTS that no
+ * reader in this repository opens — they exist only inside an installed
+ * consumer tree — and they have no legitimate hand edit at all, so they are
+ * refused at tool-call time by `block_plumbing_writes.ts` rather than ratified
+ * here: a record for a file whose every hand edit is illegitimate would be a
+ * record of a mistake.
+ *
+ * road-to-blocking-severities 2.1 WIDENS this from "sources only" to
+ * "everything the dispatcher serves at runtime", and the distinction above is
+ * why the two compiled tables land here while the two build outputs do not.
+ * `src/scripts/hook_manifest.json` and `src/scripts/hooks/host_lowering.json`
+ * are committed in THIS tree and are READ IN PREFERENCE to the YAML they were
+ * compiled from — `dispatch_hook._load_yaml` and `host_lowering.resolveTable`
+ * both serve the compiled body whenever its fingerprint matches. A diff that
+ * edits only the JSON therefore changes what every host is told about which
+ * concern runs and which slot can refuse, while the gated YAML beside it is
+ * untouched. That is the same authority change as editing the source, reached
+ * one file later, and before this step it carried no record.
+ *
+ * Two further files join for the same reason rather than by analogy:
+ *
+ *   - `src/scripts/hooks/dispatch_hook.ts` is the dispatcher itself. Every
+ *     concern's verdict passes through it, so an edit here can suppress a
+ *     refusal without touching the manifest that declares it.
+ *   - `src/scripts/_lib/kernel_rules.ts` is the list of the nine kernel rules.
+ *     THIS GATE resolves `is_kernel_rule` through it, so a diff removing a name
+ *     from that list removes a rule from this gate's own reach — the one edit
+ *     that could quietly narrow the gate while every other path kept working.
+ *
+ * Both are also denied at tool-call time, `dispatch_hook.ts` through the
+ * plumbing guard's source set and `kernel_rules.ts` through the kernel-rule
+ * write guard, so the pairing of deny-plus-record matches what the YAML sources
+ * already had.
+ *
+ * The compiled tables are REGENERATED, not hand-edited, by
+ * `./scripts-run src/scripts/compile_hook_manifest --table manifest|host-lowering`,
+ * which runs as a script rather than as an edit tool call and so is not what
+ * either mechanism refuses. A regeneration lands in the same diff as the YAML
+ * change that caused it, which already requires a record; the case this closes
+ * is the diff where only the JSON moves.
+ */
+const PLUMBING_SOURCE_RE =
+    /^(?:src\/scripts\/hook_manifest\.(?:yaml|json)|src\/scripts\/hooks\/host_lowering\.(?:yaml|json)|src\/scripts\/hooks\/dispatch_hook\.ts|src\/scripts\/_lib\/kernel_rules\.ts|src\/scripts\/hooks\/[a-z0-9-]+-dispatcher\.sh|src\/config\/hook-(?:token|latency)-budget\.json)$/;
+
 /**
  * A kernel rule, in the source tree or in any projection.
  *
@@ -141,6 +206,8 @@ const KERNEL_RULE_PATH_RE = /(?:^|\/)rules\/([a-z0-9-]+)\.md$/;
 export interface GatedPaths {
     kernelRules: string[];
     governanceHooks: string[];
+    /** Hook-plumbing sources — manifest, host lowering, dispatchers, budgets. */
+    plumbing: string[];
     self: boolean;
 }
 
@@ -148,6 +215,7 @@ export interface GatedPaths {
 export function classifyPaths(files: readonly string[]): GatedPaths {
     const kernelRules: string[] = [];
     const governanceHooks: string[] = [];
+    const plumbing: string[] = [];
     let self = false;
     for (const raw of files) {
         const p = raw.replace(/\\/g, '/').trim();
@@ -171,14 +239,23 @@ export function classifyPaths(files: readonly string[]): GatedPaths {
         }
         if (GOVERNANCE_HOOK_RE.test(p)) {
             governanceHooks.push(p);
+            continue;
+        }
+        if (PLUMBING_SOURCE_RE.test(p)) {
+            plumbing.push(p);
         }
     }
-    return { kernelRules, governanceHooks, self };
+    return { kernelRules, governanceHooks, plumbing, self };
 }
 
 /** True when anything in the diff requires a ratification artifact. */
 export function requiresRatification(gated: GatedPaths): boolean {
-    return gated.kernelRules.length > 0 || gated.governanceHooks.length > 0 || gated.self;
+    return (
+        gated.kernelRules.length > 0 ||
+        gated.governanceHooks.length > 0 ||
+        gated.plumbing.length > 0 ||
+        gated.self
+    );
 }
 
 /** Ratification artifacts present in the diff, as repo-relative paths. */
@@ -253,6 +330,7 @@ export function evaluate(
     const gatedSet = new Set<string>([
         ...gated.kernelRules,
         ...gated.governanceHooks,
+        ...gated.plumbing,
         ...(gated.self ? [SELF_PATH] : []),
     ]);
     const artifactSet = new Set(ratificationArtifactsIn(files));
@@ -286,7 +364,8 @@ export function evaluate(
 
     if (!requiresRatification(gated)) {
         lines.push(
-            '✅  no kernel rule, governance hook or self edit in the diff — nothing to ratify',
+            '✅  no kernel rule, governance hook, hook-plumbing source or self edit in the ' +
+                'diff — nothing to ratify',
         );
         close(true);
         return { exitCode: 0, lines, scanned };
@@ -295,6 +374,7 @@ export function evaluate(
     const touched = [
         ...gated.kernelRules.map((p) => `kernel rule ${p}`),
         ...gated.governanceHooks.map((p) => `governance hook ${p}`),
+        ...gated.plumbing.map((p) => `hook-plumbing source ${p}`),
         ...(gated.self ? ['the ratification mechanism itself (gate, reader, policy or workflow)'] : []),
     ];
     lines.push(`Gated surfaces in this diff (${touched.length}):`);
@@ -446,8 +526,8 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         roots: ['<the diff against the base ref>'],
         allowEmpty:
             'EMPTY_VALID: the corpus is one diff. A commit range that changed nothing is a ' +
-            'real state, and there is then no kernel rule, governance hook or mechanism file ' +
-            'to ratify — the gate has read everything there was.',
+            'real state, and there is then no kernel rule, governance hook, plumbing source or ' +
+            'mechanism file to ratify — the gate has read everything there was.',
     });
     if (!quiet || result.exitCode !== 0) {
         for (const l of result.lines) {