@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/bench_touched_file_quality.ts

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * bench_touched_file_quality — what the shadow quality pass costs at stop.
+ *
+ * `road-to-touched-files-that-pass-their-own-tools` 1.4: record the `shadow`
+ * variant's p95 over a five-file TypeScript fixture BEFORE any default moves.
+ * Risk 1 of that roadmap is that a quality pass makes stop the slowest hook in
+ * the chain, and 2.3 defers the `shadow → warn` flip to the owner. Neither
+ * decision should be taken on an estimate.
+ *
+ * CORRECTED FROM REPRODUCTION — the step's premise was wrong, and the
+ * correction is why this is a file rather than a patch.
+ *
+ * The step reads "the per-concern bench already measures `verify-before-complete`
+ * at default". It does not. `bench_hook_latency.perConcernRows` is fed by
+ * `blockingConcerns()`, which filters `hook_manifest.yaml` to
+ * `severity: blocking`; `verify-before-complete` is declared `severity: advisory`
+ * (manifest line ~122), so it has never had a per-concern row and there was no
+ * `default` reading to add a `shadow` variant beside. Adding the concern to that
+ * filter would have changed what "blocking" means in a report whose consumer
+ * (step 3.3 of the kernel-plumbing roadmap) derives per-concern TIMEOUTS from it
+ * — a timeout for an advisory concern is a different decision, and smuggling it
+ * in through a measurement would have been the wrong place to take it.
+ *
+ * So this measures the pass directly, which is also the number the two open
+ * decisions actually need: the slot p95 in `docs/hook-latency.json` is dominated
+ * by spawn + bundle load, and what 1.4 asks about is the DELTA the pass adds.
+ *
+ * METHOD, pinned so the number reproduces:
+ *   - A throwaway consumer-shaped project: `package.json` declaring `typescript`
+ *     and `eslint`, five TypeScript files, a flat ESLint config, `git init`, and
+ *     a `minimal-safe-diff.json` naming all five as this turn's touched files.
+ *   - `node_modules` is SYMLINKED to this repository's, so `npx eslint` resolves
+ *     a real, installed linter and runs offline. The measurement is therefore of
+ *     a real tool over real files, not of a stub.
+ *   - N iterations (default 20, `--runs N`) of `collectTouchedFileQuality` — the
+ *     exact function the stop path calls — measured with `performance.now()`.
+ *     That covers the recorder read, `git status`, `resolve_toolchain`, and every
+ *     spawn the plan produced.
+ *   - The `off` baseline is measured too, by the same loop with the pass skipped,
+ *     so the row reports a DELTA rather than an absolute whose floor is unknown.
+ *
+ * WHAT THE NUMBER IS NOT. It is one machine's reading, and the dominant term is
+ * whichever tools the fixture's resolver happens to emit — a consumer whose
+ * toolchain resolves `phpstan` over a large tree will measure something else
+ * entirely. It bounds the decision for THIS shape; it is not a budget.
+ *
+ * Exit codes: 0 measured · 2 the fixture could not be built.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { collectTouchedFileQuality } from './before_complete_hook.js';
+
+const REPO_ROOT = path.resolve(path.dirname(path.resolve(fileURLToPath(import.meta.url))), '..', '..');
+
+/** Files in the fixture. Five, per the step. */
+export const FIXTURE_FILE_COUNT = 5;
+
+const SESSION = 'bench-touched-file-quality';
+
+export function percentile(samples: readonly number[], p: number): number {
+    if (samples.length === 0) return 0;
+    const sorted = [...samples].sort((a, b) => a - b);
+    const idx = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+    return sorted[Math.max(0, idx)] as number;
+}
+
+/**
+ * Build the throwaway consumer project and return its root.
+ *
+ * Deliberately NOT inside the repository: a fixture under `src/` or `agents/`
+ * would be picked up by the tree's own gates, and one that `git init`s inside an
+ * existing worktree would report the repository's status rather than its own.
+ */
+export function buildFixture(): string {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'tfq-bench-'));
+
+    fs.writeFileSync(
+        path.join(root, 'package.json'),
+        JSON.stringify(
+            { name: 'tfq-bench-fixture', private: true, devDependencies: { typescript: '*', eslint: '*' } },
+            null,
+            2,
+        ),
+        'utf-8',
+    );
+    // A flat config with no rules: eslint still parses every file, which is the
+    // cost being measured, without a rule set that would make the number a
+    // statement about this repository's lint configuration.
+    fs.writeFileSync(path.join(root, 'eslint.config.mjs'), 'export default [];\n', 'utf-8');
+
+    for (let i = 0; i < FIXTURE_FILE_COUNT; i += 1) {
+        fs.writeFileSync(
+            path.join(root, `mod${String(i)}.ts`),
+            `export interface Row${String(i)} { id: number; name: string }\n` +
+                `export function build${String(i)}(n: number): Row${String(i)}[] {\n` +
+                `    return Array.from({ length: n }, (_, j) => ({ id: j, name: 'r' + String(j) }));\n` +
+                `}\n`,
+            'utf-8',
+        );
+    }
+
+    try {
+        fs.symlinkSync(path.join(REPO_ROOT, 'node_modules'), path.join(root, 'node_modules'), 'dir');
+    } catch {
+        // Left absent on a platform that refuses the link: `npx eslint` then
+        // resolves to nothing and the pass records `skipped: absent`, which the
+        // report states rather than hides.
+    }
+
+    spawnSync('git', ['init', '-q'], { cwd: root });
+
+    fs.mkdirSync(path.join(root, 'agents', 'state'), { recursive: true });
+    fs.writeFileSync(
+        path.join(root, 'agents', 'state', 'minimal-safe-diff.json'),
+        JSON.stringify({
+            session_id: SESSION,
+            files_touched_this_turn: Array.from(
+                { length: FIXTURE_FILE_COUNT },
+                (_, i) => `mod${String(i)}.ts`,
+            ),
+        }),
+        'utf-8',
+    );
+
+    return root;
+}
+
+export interface BenchRow {
+    readonly concern: string;
+    readonly mode: 'off' | 'shadow';
+    readonly runs: number;
+    readonly p50_ms: number;
+    readonly p95_ms: number;
+    readonly max_ms: number;
+    /** What the pass actually did, so a row of zeros is never mistaken for speed. */
+    readonly commands: readonly string[];
+    readonly skipped: readonly string[];
+}
+
+export function measure(root: string, iterations: number): { off: BenchRow; shadow: BenchRow } {
+    const offSamples: number[] = [];
+    const shadowSamples: number[] = [];
+    let commands: string[] = [];
+    let skipped: string[] = [];
+
+    // One warm-up outside the samples: the first `npx` resolution pays a cost no
+    // subsequent stop pays, and reporting it inside the p95 would describe a
+    // session's first stop as if it were every stop.
+    collectTouchedFileQuality(root, SESSION);
+
+    for (let i = 0; i < iterations; i += 1) {
+        const t0 = performance.now();
+        const result = collectTouchedFileQuality(root, SESSION);
+        shadowSamples.push(performance.now() - t0);
+        if (i === 0 && result !== null) {
+            commands = result.runs.filter((r) => r.skipped === null).map((r) => r.command);
+            skipped = result.runs
+                .filter((r) => r.skipped !== null)
+                .map((r) => `${r.source_command} → ${String(r.skipped)}`);
+        }
+
+        // `off` is not "the same loop with a flag" — on the off path the stop
+        // handler never reaches this function at all, so the baseline is the
+        // empty interval, measured to keep the harness's own overhead visible.
+        const t1 = performance.now();
+        offSamples.push(performance.now() - t1);
+    }
+
+    const row = (mode: 'off' | 'shadow', xs: number[]): BenchRow => ({
+        concern: 'verify-before-complete',
+        mode,
+        runs: xs.length,
+        p50_ms: Math.round(percentile(xs, 50) * 1000) / 1000,
+        p95_ms: Math.round(percentile(xs, 95) * 1000) / 1000,
+        max_ms: Math.round(Math.max(...xs, 0) * 1000) / 1000,
+        commands: mode === 'shadow' ? commands : [],
+        skipped: mode === 'shadow' ? skipped : [],
+    });
+
+    return { off: row('off', offSamples), shadow: row('shadow', shadowSamples) };
+}
+
+export function render(rows: { off: BenchRow; shadow: BenchRow }): string {
+    const line = (r: BenchRow): string =>
+        `| ${r.concern} | ${r.mode} | ${String(r.runs)} | ${r.p50_ms.toFixed(3)} | ` +
+        `${r.p95_ms.toFixed(3)} | ${r.max_ms.toFixed(3)} |`;
+    const out: string[] = [
+        '',
+        `fixture: ${String(FIXTURE_FILE_COUNT)} TypeScript files, consumer-shaped project`,
+        '',
+        '| concern | mode | runs | p50_ms | p95_ms | max_ms |',
+        '|---|---|---|---|---|---|',
+        line(rows.off),
+        line(rows.shadow),
+        '',
+        `delta p95 (shadow − off): ${(rows.shadow.p95_ms - rows.off.p95_ms).toFixed(3)} ms`,
+        '',
+        `commands executed: ${rows.shadow.commands.length === 0 ? '(none)' : rows.shadow.commands.join(' · ')}`,
+        `skipped: ${rows.shadow.skipped.length === 0 ? '(none)' : rows.shadow.skipped.join(' · ')}`,
+        '',
+    ];
+    return out.join('\n');
+}
+
+export function main(argv: readonly string[]): number {
+    const runsIdx = argv.indexOf('--runs');
+    const parsed = runsIdx === -1 ? NaN : Number(argv[runsIdx + 1]);
+    const iterations = Number.isFinite(parsed) && parsed > 0 ? Math.trunc(parsed) : 20;
+    const asJson = argv.includes('--json');
+
+    let root: string;
+    try {
+        root = buildFixture();
+    } catch (err) {
+        process.stderr.write(`bench_touched_file_quality: could not build the fixture — ${String(err)}\n`);
+        return 2;
+    }
+
+    const rows = measure(root, iterations);
+    process.stdout.write(asJson ? `${JSON.stringify(rows, null, 2)}\n` : render(rows));
+
+    try {
+        fs.rmSync(root, { recursive: true, force: true });
+    } catch {
+        // A leftover temp directory is not a failed measurement.
+    }
+    return 0;
+}
+
+const _entry = process.argv[1];
+if (_entry !== undefined && path.resolve(_entry) === path.resolve(fileURLToPath(import.meta.url))) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/cache_realization_report.ts

@@ -44,6 +44,10 @@ import {
     DEFAULT_PROJECTS_ROOT,
     projectStoreSlug,
     scanTranscripts,
+    measureBytesPerToken,
+    derivedBytes,
+    type BytesPerToken,
+    type DerivedBytes,
     type BucketAggregate,
     type TranscriptBucket,
     type TranscriptRecord,
@@ -764,11 +768,38 @@ export interface Report {
     council_mispricing: CouncilMispricingResult;
     worktree_fragmentation: WorktreeFragmentationResult;
     prefix_stability: PrefixStabilityResult;
+    /**
+     * Provider bytes per bucket — DERIVED, and labelled so on every value
+     * (`road-to-a-bytes-row-that-exists` Phase 2, metric
+     * `provider-bytes-per-call`).
+     *
+     * `null` when this corpus supplies no bytes-per-token factor. That is the
+     * honest outcome and it is emitted as `null` rather than as a figure from
+     * some other corpus: the factor is a property of the content it was
+     * measured on, and no constant lives in this file or in
+     * `_lib/cc_transcript.ts` for it to fall back to.
+     *
+     * LIMIT, stated where the number is rather than only in the registry: the
+     * factor is measured over ASSISTANT OUTPUT content, which is the only text
+     * a transcript carries. The request's system prompt, tool definitions and
+     * prior turns are not in the transcript at all (the same limitation
+     * `preamble_byte_census` records), so the factor is an output-side ratio
+     * applied to an input-side token count. That is why the value is `derived`
+     * and not `measured`, and why it must never be quoted as a wire figure.
+     */
+    provider_bytes: {
+        factor: BytesPerToken | null;
+        main: DerivedBytes | null;
+        subagent: DerivedBytes | null;
+    };
     claims: Claim[];
 }
 
 export function buildReport(opts: Options): Report {
-    const scan = scanTranscripts({ root: opts.root, maxAgeDays: opts.maxAgeDays });
+    // `measureBytes` is the only change to this scan: the token columns below
+    // are computed from the same `usage` blocks as before and are unaffected.
+    const scan = scanTranscripts({ root: opts.root, maxAgeDays: opts.maxAgeDays, measureBytes: true });
+    const bytesFactor = measureBytesPerToken(scan.records);
     const buckets = aggregateByBucket(scan.records);
     const subagentColdStart = computeColdStarts(scan.records);
     const byAgent = aggregateByAgent(scan.records);
@@ -822,6 +853,11 @@ export function buildReport(opts: Options): Report {
         council_mispricing: councilMispricing,
         worktree_fragmentation: worktreeFragmentation,
         prefix_stability: prefixStability,
+        provider_bytes: {
+            factor: bytesFactor,
+            main: derivedBytes(billableInputTokens(buckets.main), bytesFactor),
+            subagent: derivedBytes(billableInputTokens(buckets.subagent), bytesFactor),
+        },
         claims,
     };
 }
@@ -851,6 +887,30 @@ export function renderText(r: Report): string {
     out.push(`  ${ps.reason}`);
     out.push('');
 
+    const pb = r.provider_bytes;
+    out.push('Provider bytes (DERIVED - never a counted wire figure):');
+    if (pb.factor === null) {
+        out.push('  basis: unavailable - this corpus supplied no bytes-per-token factor');
+        out.push('  no figure is emitted; a ratio from another corpus would not be this one');
+    } else {
+        out.push(
+            `  factor: ${pb.factor.bytes_per_token.toFixed(4)} bytes/token (basis: ${pb.factor.basis},`
+                + ` ${pb.factor.content_bytes} content bytes / ${pb.factor.output_tokens} output tokens`
+                + ` over ${pb.factor.records} records)`,
+        );
+        for (const bucket of ['main', 'subagent'] as const) {
+            const d = pb[bucket];
+            out.push(
+                d === null
+                    ? `  ${bucket}: basis: unavailable`
+                    : `  ${bucket}: ${d.bytes} bytes (basis: ${d.basis}, from ${d.tokens} billable input tokens)`,
+            );
+        }
+        out.push('  the factor is measured over assistant OUTPUT content; the request payload is');
+        out.push('  not in any transcript, so this is an estimate of volume, not a wire measurement');
+    }
+    out.push('');
+
     out.push('By bucket:');
     for (const bucket of ['main', 'subagent'] as const) {
         const b = r.buckets[bucket];

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)));
+}