@event4u/agent-config 16.1.0 → 16.2.0

package/src/scripts/check_argument_hint.ts

@@ -0,0 +1,287 @@
+#!/usr/bin/env tsx
+/**
+ * Where an artifact declares `inputs:`, its `argument-hint` is DERIVED from
+ * that declaration — and a hand-written hint on the same artifact is a
+ * conflict, not a merge.
+ *
+ * road-to-an-invocation-contract-that-reaches-the-wire 3.1.
+ *
+ * WHY A CONFLICT RATHER THAN A MERGE
+ *
+ * The tree already answers "what does this take?" in prose, through
+ * `argument-hint`, which nothing validates. Adding a structured declaration
+ * beside it creates a SECOND authority for the same question, and two surfaces
+ * that can answer one question drift — which is the failure this whole roadmap
+ * exists to make unrepresentable (Risk 1). Making the derived direction
+ * one-way, and a disagreement a build failure, is what keeps the second
+ * authority from forming. Merging the two would BE the second authority.
+ *
+ * An artifact with no declaration is untouched: its hand-written hint stays
+ * exactly as it is, because there is nothing to derive from and no conflict to
+ * have. That is why the 43 hintless commands are a generation gap that closes
+ * as declarations land, rather than 43 prose edits nobody reviewed.
+ *
+ * THE FORM, AND WHY IT ROUND-TRIPS
+ *
+ * `<name>` required · `[name]` optional · `:a|b` appended for an enum. The
+ * corpus already writes `[path]` and `[--force]` in exactly this shape, so the
+ * generated hint is not a new dialect. {@link parseHint} recovers the name,
+ * requiredness and enum from the rendered string, and the round-trip is
+ * asserted rather than assumed — a generator whose output its own parser cannot
+ * read would make the conflict check unfalsifiable.
+ *
+ * Exit codes: 0 in sync · 1 a conflict or a missing derived hint · 2 unreadable.
+ */
+
+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';
+
+const _HERE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export const GATE = 'check_argument_hint';
+
+export interface InputDecl {
+    readonly name: string;
+    readonly type: string;
+    readonly required?: boolean;
+    readonly enum?: readonly string[];
+}
+
+/** Render the canonical hint for a declaration. */
+export function hintFor(inputs: readonly InputDecl[]): string {
+    return inputs
+        .map((i) => {
+            const body = i.enum && i.enum.length > 0 ? `${i.name}:${i.enum.join('|')}` : i.name;
+            return i.required === true ? `<${body}>` : `[${body}]`;
+        })
+        .join(' ');
+}
+
+export interface ParsedHint {
+    readonly name: string;
+    readonly required: boolean;
+    readonly enum?: readonly string[];
+}
+
+/** Recover declarations from a rendered hint. The inverse of {@link hintFor}. */
+export function parseHint(hint: string): ParsedHint[] {
+    const out: ParsedHint[] = [];
+    for (const m of hint.matchAll(/([<[])([a-z][a-z0-9_]*)(?::([^\]>]+))?([\]>])/g)) {
+        const open = m[1]!;
+        const close = m[4]!;
+        if ((open === '<') !== (close === '>')) continue;
+        const parsed: ParsedHint = {
+            name: m[2]!,
+            required: open === '<',
+            ...(m[3] === undefined ? {} : { enum: m[3].split('|') }),
+        };
+        out.push(parsed);
+    }
+    return out;
+}
+
+/** Frontmatter of one artifact, or `null` when it has none or it is malformed. */
+function frontmatter(text: string): Record<string, unknown> | null {
+    const m = /^---\n([\s\S]*?)\n---/.exec(text);
+    if (m === null) return null;
+    try {
+        const fm = yaml.load(m[1]!);
+        return fm !== null && typeof fm === 'object' ? (fm as Record<string, unknown>) : null;
+    } catch {
+        return null;
+    }
+}
+
+export function declaredInputs(fm: Record<string, unknown> | null): InputDecl[] | null {
+    if (fm === null) return null;
+    const raw = fm['inputs'];
+    if (!Array.isArray(raw)) return null;
+    const out: InputDecl[] = [];
+    for (const item of raw) {
+        if (item === null || typeof item !== 'object') continue;
+        const r = item as Record<string, unknown>;
+        if (typeof r['name'] !== 'string' || typeof r['type'] !== 'string') continue;
+        out.push({
+            name: r['name'],
+            type: r['type'],
+            ...(typeof r['required'] === 'boolean' ? { required: r['required'] } : {}),
+            ...(Array.isArray(r['enum'])
+                ? { enum: r['enum'].filter((x): x is string => typeof x === 'string') }
+                : {}),
+        });
+    }
+    return out;
+}
+
+export type FindingKind = 'conflict' | 'missing';
+
+export interface Finding {
+    readonly file: string;
+    readonly kind: FindingKind;
+    readonly derived: string;
+    /** The hand-written hint, for a conflict. */
+    readonly written?: string;
+}
+
+/** Compare one artifact's declaration against its hint. */
+export function checkArtifact(text: string, file: string): Finding | null {
+    const fm = frontmatter(text);
+    const inputs = declaredInputs(fm);
+    if (inputs === null || inputs.length === 0) return null;
+    const derived = hintFor(inputs);
+    const written = fm?.['argument-hint'];
+    if (typeof written !== 'string') return { file, kind: 'missing', derived };
+    if (written.trim() !== derived) return { file, kind: 'conflict', derived, written };
+    return null;
+}
+
+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;
+}
+
+/**
+ * COMMANDS ONLY, and the reason is structural rather than a scoping preference:
+ * `argument-hint` is a key of `command.schema.json` and of no other schema. A
+ * skill cannot carry one, so reporting a skill that declares `inputs:` as
+ * "missing its hint" would demand a field the schema forbids. Skills still get
+ * their declaration onto the wire — that is `to_mcp_prompt_meta`'s job (3.2),
+ * which reads the declaration directly and needs no hint at all.
+ */
+export function scan(root: string): { findings: Finding[]; scanned: number; declaring: number } {
+    const files = walk(path.join(root, 'src', 'domains'), (n) => n === 'command.md').sort();
+
+    const findings: Finding[] = [];
+    let declaring = 0;
+    for (const f of files) {
+        const text = fs.readFileSync(f, 'utf8');
+        const inputs = declaredInputs(frontmatter(text));
+        if (inputs !== null && inputs.length > 0) declaring += 1;
+        const finding = checkArtifact(text, path.relative(root, f));
+        if (finding !== null) findings.push(finding);
+    }
+    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));
+    for (const f of findings) ledger.fail(f.file, f.kind);
+
+    // 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'] });
+
+    reportScanned({
+        gate: GATE,
+        scanned,
+        units: 'artifact(s)',
+        roots: ['src/domains'],
+    });
+    ledger.report();
+
+    if (findings.length > 0) {
+        for (const f of findings) {
+            if (f.kind === 'conflict') {
+                process.stdout.write(
+                    `❌  ${GATE}: ${f.file} has a hand-written \`argument-hint\` that contradicts ` +
+                        `its declaration.\n      written: ${f.written ?? ''}\n      derived: ${f.derived}\n`,
+                );
+            } else {
+                process.stdout.write(
+                    `❌  ${GATE}: ${f.file} declares \`inputs:\` but carries no \`argument-hint\`.\n` +
+                        `      derived: ${f.derived}\n`,
+                );
+            }
+        }
+        process.stdout.write(
+            '\nWhere a declaration exists the hint is derived from it, one way. Fix the ' +
+                'declaration, or delete the hand-written hint — never reconcile the two by ' +
+                'hand, which is the second authority this check exists to prevent.\n',
+        );
+        return 1;
+    }
+
+    process.stdout.write(
+        `✅  ${GATE}: every derived \`argument-hint\` matches its declaration ` +
+            `(${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, fm: string): string => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), `arg-hint-${name}-`));
+        const cmd = path.join(dir, 'src', 'domains', 'probe-pack', 'probe');
+        fs.mkdirSync(cmd, { recursive: true });
+        fs.writeFileSync(path.join(cmd, 'command.md'), `---\nname: probe\n${fm}---\n\nbody\n`, 'utf-8');
+        return dir;
+    };
+
+    const run = (root: string): number =>
+        runGateCli(ROOT, path.join('src', 'scripts', 'check_argument_hint.ts'), ['--root', root], ROOT);
+
+    return runSelfTest({
+        gate: GATE,
+        minCases: 5,
+        minRejectCases: 3,
+        cases: [
+            {
+                name: 'an empty corpus is refused, not certified green',
+                expect: 'reject',
+                run: () => run(fs.mkdtempSync(path.join(os.tmpdir(), 'arg-hint-empty-'))),
+            },
+            {
+                name: 'a hint matching its declaration passes',
+                expect: 'accept',
+                run: () =>
+                    run(plant('match', 'argument-hint: "<a>"\ninputs:\n  - name: a\n    type: string\n    required: true\n')),
+            },
+            {
+                name: 'a hand-written hint contradicting the declaration fails',
+                expect: 'reject',
+                run: () =>
+                    run(plant('conflict', 'argument-hint: "[other]"\ninputs:\n  - name: a\n    type: string\n    required: true\n')),
+            },
+            {
+                name: 'a declaration with no hint at all fails',
+                expect: 'reject',
+                run: () => run(plant('missing', 'inputs:\n  - name: a\n    type: string\n')),
+            },
+            {
+                name: 'an artifact with no declaration keeps its free-text hint',
+                expect: 'accept',
+                run: () => run(plant('nodecl', 'argument-hint: "[free text]"\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_claims.ts

@@ -208,9 +208,76 @@ const SELF_COUNT = new RegExp(
     'i',
 );
 
+/**
+ * Byte-unit metric ids, read from `src/config/metric-registry.yml`.
+ *
+ * WHY THE IDS AND NOT THE WORD `bytes`. A detector keyed on a number near the
+ * word would red on ordinary documentation — a file size in a README, a payload
+ * example in a contract — and the cheapest repair for a gate that reds on
+ * correct prose is to weaken it until it finds nothing. Keyed on the DECLARED
+ * ids, only a figure claiming a registered metric is checked, and a line that
+ * merely mentions bytes is not a claim about this package at all.
+ *
+ * `MAGNITUDE` already covers `KB|MB|GB`, so this is not the first byte-shaped
+ * figure the gate sees; what it adds is the id-bearing form, which is how
+ * `road-to-a-bytes-row-that-exists` made a byte statement expressible in the
+ * first place.
+ *
+ * Parsed with a line scanner rather than a YAML dependency: the shape read is
+ * two adjacent keys at a fixed indent, and an unreadable registry yields an
+ * EMPTY id list, which makes the detector inert rather than throwing inside a
+ * gate whose job is to report other people's problems.
+ */
+export function parse_byte_metric_ids(raw: string): string[] {
+    const out: string[] = [];
+    let current: string | null = null;
+    for (const line of raw.split('\n')) {
+        const id = /^\s*-\s+id:\s*([A-Za-z0-9._-]+)\s*$/.exec(line);
+        if (id?.[1] !== undefined) {
+            current = id[1];
+            continue;
+        }
+        const unit = /^\s*unit:\s*(\S+)\s*$/.exec(line);
+        if (unit?.[1] !== undefined && current !== null && /^bytes/.test(unit[1])) {
+            out.push(current);
+            current = null;
+        }
+    }
+    return out;
+}
+
+const METRIC_REGISTRY_REL = 'src/config/metric-registry.yml';
+let _byteMetricIds: string[] | null = null;
+
+function byteMetricIds(): string[] {
+    if (_byteMetricIds === null) {
+        try {
+            _byteMetricIds = parse_byte_metric_ids(
+                fs.readFileSync(path.join(REPO, METRIC_REGISTRY_REL), 'utf-8'),
+            );
+        } catch {
+            _byteMetricIds = [];
+        }
+    }
+    return _byteMetricIds;
+}
+
+/**
+ * A line naming a declared byte metric AND carrying a figure.
+ *
+ * Both halves are required. The id alone is prose about the metric — the
+ * registry entry itself says what it is for, and that is not a claim. A number
+ * alone is every other line in the tree.
+ */
+export function is_byte_metric_claim(line: string, ids: string[] = byteMetricIds()): boolean {
+    if (ids.length === 0) return false;
+    if (!/\b\d[\d,._]*\b/.test(line)) return false;
+    return ids.some((id) => new RegExp(String.raw`\b${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\b`).test(line));
+}
+
 /** True when a line carries any figure shape that must bind to a claim. */
 export function is_quantified_claim(line: string): boolean {
-    return RATIO.test(line) || MAGNITUDE.test(line) || SELF_COUNT.test(line);
+    return RATIO.test(line) || MAGNITUDE.test(line) || SELF_COUNT.test(line) || is_byte_metric_claim(line);
 }
 
 class ExitCode extends Error {
@@ -1041,6 +1108,17 @@ function selfTest(): number {
 
     const CLEAN_README = '# Agent Config\n\nGoverned skills, rules and commands.\n';
 
+    /** A registry carrying exactly one byte-unit metric, for the 4.1 cases. */
+    const BYTE_REGISTRY = [
+        'metrics:',
+        '  - id: tool-raw-bytes',
+        '    unit: bytes',
+        '    basis: measured',
+        '  - id: some-token-metric',
+        '    unit: tokens',
+        '',
+    ].join('\n');
+
     const cases: SelfTestCase[] = [
         {
             name: 'a retired phrasing absent from every publish surface → accept',
@@ -1071,6 +1149,52 @@ function selfTest(): number {
             expect: 'reject',
             run: () => fixture({ 'docs/CLAIMS.md': closed('daemon'), 'README.md': CLEAN_README }),
         },
+
+        // road-to-a-bytes-row-that-exists 4.1 — both directions, because a
+        // one-directional fixture cannot tell a working detector from one that
+        // reds on everything. The registry file is part of the fixture: the
+        // gate reads it relative to its own location, so the copied script in
+        // the temp root reads the copied registry.
+        {
+            name: 'a byte figure naming a metric with no ledger entry → reject',
+            expect: 'reject',
+            run: () =>
+                fixture({
+                    'docs/CLAIMS.md': closed(null),
+                    'src/config/metric-registry.yml': BYTE_REGISTRY,
+                    'README.md': `${CLEAN_README}\nEach dispatch records 2048 tool-raw-bytes.\n`,
+                }),
+        },
+        {
+            name: 'the same figure once a markered ledger entry backs it → accept',
+            expect: 'accept',
+            run: () =>
+                fixture({
+                    'docs/CLAIMS.md': [
+                        closed(null),
+                        '### claim: tool-raw-bytes-observed',
+                        '- claim: Each dispatch records 2048 tool-raw-bytes.',
+                        '- kind: quant',
+                        '- evidence: docs/evidence.md#ANCHOR',
+                        '- status: backed',
+                        '- last_verified: 2026-09-29',
+                        '',
+                    ].join('\n'),
+                    'src/config/metric-registry.yml': BYTE_REGISTRY,
+                    'README.md':
+                        `${CLEAN_README}\nEach dispatch records 2048 tool-raw-bytes. <!-- claim:tool-raw-bytes-observed -->\n`,
+                }),
+        },
+        {
+            name: 'ordinary prose carrying a byte size but no declared id → accept',
+            expect: 'accept',
+            run: () =>
+                fixture({
+                    'docs/CLAIMS.md': closed(null),
+                    'src/config/metric-registry.yml': BYTE_REGISTRY,
+                    'README.md': `${CLEAN_README}\nThe example payload below is 2048 bytes long.\n`,
+                }),
+        },
         {
             name: 'the never-published sentinel with a stated reason → accept',
             expect: 'accept',

package/src/scripts/check_enforcement_coverage.ts

@@ -260,13 +260,22 @@ function load_corpus(dirs: readonly string[], files: readonly string[] = []): st
  * whether or not anyone chooses to. Conflating the two is how a package ends up
  * believing an on-demand tool is a gate.
  */
-function reachable_scripts(wiring: string): Set<string> {
-    const scripts_dir = path.join(REPO_ROOT, 'src', 'scripts');
+/**
+ * Transitive closure of the scripts a wiring surface reaches.
+ *
+ * `roots` is a seam, not a feature: it defaults to the real tree, and a test
+ * passes a synthetic one. Without it the only way to exercise the fixed point
+ * is over ~650 real files, where a chain deep enough to catch a broken worklist
+ * cannot be constructed on purpose.
+ */
+export function reachable_scripts(wiring: string, roots?: { dir: string; base: string }): Set<string> {
+    const scripts_dir = roots?.dir ?? path.join(REPO_ROOT, 'src', 'scripts');
+    const base_dir = roots?.base ?? REPO_ROOT;
     const all: string[] = fs.existsSync(scripts_dir)
         ? walk(scripts_dir).filter((p) => p.endsWith('.ts'))
         : [];
 
-    const rel = (abs: string): string => path.relative(REPO_ROOT, abs);
+    const rel = (abs: string): string => path.relative(base_dir, abs);
     const stem = (abs: string): string => path.basename(abs).replace(/\.ts$/, '');
 
     const reached = new Set<string>();
@@ -274,24 +283,44 @@ function reachable_scripts(wiring: string): Set<string> {
         if (wiring.includes(rel(abs)) || wiring.includes(stem(abs))) reached.add(rel(abs));
     }
 
-    let grew = true;
-    while (grew) {
-        grew = false;
-        const frontier = [...reached];
+    // WORKLIST, not a re-scan of everything reached so far.
+    //
+    // The previous shape rebuilt `bodies` from EVERY reached file on every
+    // iteration and re-tested every unreached file against the whole thing. The
+    // corpus is ~650 scripts, `mentions_as_code` compiles and runs two regexes
+    // per candidate, and the concatenated body grows into the megabytes — so the
+    // cost was iterations x unreached x |all bodies so far|, with each iteration
+    // re-doing every comparison the previous ones had already made.
+    //
+    // Measured, because this was found by profile rather than by reading:
+    // `build_proof.render()` -- which calls this transitively -- took 241 s on a
+    // developer machine under plain `tsx`, and the CPU profile attributed
+    // essentially all of it to this function's regex sweep, spread over hundreds
+    // of per-name `RegExp` frames. The file's own header had recorded ~54 s.
+    //
+    // Re-testing an old body is provably redundant: a file that did not match a
+    // body in the iteration that body was added cannot match it later, because
+    // neither the body nor the test changes. So each round searches ONLY the
+    // bodies admitted in the previous round. Same fixed point, same result --
+    // the loop still runs until nothing new is reached.
+    let frontier = [...reached];
+    while (frontier.length > 0) {
         const bodies = frontier
             .map((r) => {
-                const abs = path.join(REPO_ROOT, r);
+                const abs = path.join(base_dir, r);
                 return fs.existsSync(abs) ? strip_comments(fs.readFileSync(abs, 'utf-8')) : '';
             })
             .join('\n');
+        const next: string[] = [];
         for (const abs of all) {
             const r = rel(abs);
             if (reached.has(r)) continue;
             if (mentions_as_code(bodies, path.basename(abs), stem(abs))) {
                 reached.add(r);
-                grew = true;
+                next.push(r);
             }
         }
+        frontier = next;
     }
     return reached;
 }