@event4u/agent-config 16.3.0 → 16.5.0

package/src/scripts/check_standing_rule_delivery.ts

@@ -71,6 +71,7 @@
  * converts into the other.
  */
 
+import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -80,6 +81,8 @@ import { fileURLToPath } from 'node:url';
 import { assertScanned, DeadScopeError, reportScanned } from './_lib/scan_scope.js';
 import { measure, method_note } from './_lib/token_count.js';
 import * as rule_layer_overlap from './_lib/rule_layer_overlap.js';
+import { lawText, ruleBody } from './_lib/rule_law_section.js';
+import { is_thin_entry, lawDigest, STUB_LAW_OPEN } from './_lib/thin_rules.js';
 
 const PROG = 'check_standing_rule_delivery';
 const _HERE = fileURLToPath(import.meta.url);
@@ -205,6 +208,80 @@ export function measureStandingDelivery(
     };
 }
 
+/** One installed rule, compared against the source it was installed from. */
+export interface ReinstallRow {
+    readonly layer: string;
+    readonly id: string;
+    /** What the two digests are of — named, so a reader knows what "differs" means. */
+    readonly compared: 'body' | 'law' | 'none';
+    readonly installed: string;
+    readonly source: string;
+    readonly status: 'current' | 'pending reinstall' | 'no source';
+}
+
+function bodyDigest(text: string): string {
+    return createHash('sha256').update(ruleBody(text), 'utf-8').digest('hex').slice(0, 16);
+}
+
+/**
+ * Per installed rule: its digest against the CURRENT source digest
+ * (`road-to-a-default-install-served-once` step 1.2).
+ *
+ * The cap above measures installed directories only, by design, so a source
+ * rule that got smaller is invisible until a reinstall. This names every rule
+ * whose installed copy no longer matches its source as `pending reinstall`.
+ * It REPORTS and fails nothing — every source edit makes an older install
+ * differ, and that is a state to act on, not an error.
+ *
+ * What is compared depends on the installed form, and the row says which:
+ *
+ * - **body** — a full-bodied copy: sha256 of the body after the frontmatter
+ *   and comment strip, because the installer rewrites the frontmatter into
+ *   host form and the body is what the host reads.
+ * - **law** — a stub carrying a copied law: the digest the stub recorded
+ *   against the digest of the source's law section today.
+ * - **none** — a stub with no copied text: its body is read from the package
+ *   at delivery, so nothing installed can go stale.
+ */
+export function reinstallRows(
+    layer: string,
+    installed_dir: string,
+    source_dir: string,
+): ReinstallRow[] {
+    const l = rule_layer_overlap.readRuleLayer(installed_dir);
+    if (l === null) return [];
+    const rows: ReinstallRow[] = [];
+    for (const [name, text] of l.files) {
+        const id = name.replace(/\.md$/, '');
+        let src: string | null;
+        try {
+            src = fs.readFileSync(path.join(source_dir, name), 'utf-8');
+        } catch {
+            src = null;
+        }
+        let compared: ReinstallRow['compared'] = 'body';
+        let installed = bodyDigest(text);
+        let source = src === null ? '-' : bodyDigest(src);
+        if (is_thin_entry(text)) {
+            const at = text.indexOf(STUB_LAW_OPEN);
+            if (at === -1) {
+                compared = 'none';
+                installed = '-';
+                source = '-';
+            } else {
+                compared = 'law';
+                installed = text.slice(at + STUB_LAW_OPEN.length).split(' ')[0] ?? '';
+                const law = src === null ? null : lawText(ruleBody(src));
+                source = law === null ? '-' : lawDigest(law);
+            }
+        }
+        const status: ReinstallRow['status'] =
+            src === null ? 'no source' : installed === source ? 'current' : 'pending reinstall';
+        rows.push({ layer, id, compared, installed, source, status });
+    }
+    return rows;
+}
+
 /**
  * Where the loaded-instruction record would live if the host wrote one.
  *
@@ -331,6 +408,25 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         );
     }
 
+    // Step 1.2 — the installed copy against the current source, per rule.
+    // Reported, never failed: see `reinstallRows`.
+    const source_dir = path.join(REPO_ROOT, 'dist', 'agent-src', 'rules');
+    const rows = [
+        ...reinstallRows('global', path.join(os.homedir(), '.claude', 'rules'), source_dir),
+        ...reinstallRows('project', path.join(REPO_ROOT, '.claude', 'rules'), source_dir),
+    ];
+    const pending = rows.filter((r) => r.status === 'pending reinstall');
+    out(
+        `  reinstall ${pending.length} of ${rows.length} installed rule(s) differ from `
+            + `${path.relative(REPO_ROOT, source_dir)} (installed digest vs current source digest)\n`,
+    );
+    for (const r of rows) {
+        out(
+            `    ${r.layer.padEnd(8)} ${r.id.padEnd(40)} ${r.compared.padEnd(5)} `
+                + `${r.installed.padEnd(16)} ${r.source.padEnd(16)} ${r.status}\n`,
+        );
+    }
+
     const pct = total / budget.total_cap_tokens;
     out(
         `  TOTAL    ${String(total).padStart(13)} tok / ${budget.total_cap_tokens} cap `

package/src/scripts/check_suppression_hygiene.ts

@@ -264,11 +264,8 @@ export const SUPPRESSION_INVENTORY: readonly SuppressionSpec[] = [
         file: 'src/config/conformance-claim-baseline.json',
         listKey: 'undeclared',
         tier: 'string_list',
-        // Absent at the base ref because this change introduces it. Remove the
-        // flag on the next change once the introducing commit is an ancestor of
-        // main — the scan below fails while it is set and the file resolves,
-        // so the flag closes itself rather than needing to be remembered.
-        newInThisChange: true,
+        // `newInThisChange` removed: the baseline resolves at the base ref since
+        // 9a013fac5, and the scan reported the stale flag as designed.
         what: 'skill and rule artefacts carrying a standard-conformance claim with no enforced_by declaration',
     },
 ];

package/src/scripts/ci_settle.ts

@@ -64,7 +64,7 @@ export const FOREGROUND_CEILING_MIN = 9;
 /** What one poll told us. `unreadable` is deliberately not a verdict. */
 export type PollState =
     | { kind: 'unreadable'; reason: string }
-    | { kind: 'pending'; total: number; done: number }
+    | { kind: 'pending'; total: number; done: number; pendingNames?: string[] }
     | { kind: 'settled'; failing: string[]; total: number };
 
 /**
@@ -234,7 +234,8 @@ export function classifyPoll(stdout: string, stderr: string, status: number | nu
         typeof r.conclusion === 'string' && r.conclusion.length > 0;
     const done = rows.filter(terminal).length;
     if (done < rows.length) {
-        return { kind: 'pending', total: rows.length, done };
+        const pendingNames = rows.filter((r) => !terminal(r)).map((r) => String(r.name ?? '?'));
+        return { kind: 'pending', total: rows.length, done, pendingNames };
     }
     const bad = new Set(['FAILURE', 'TIMED_OUT', 'CANCELLED', 'ACTION_REQUIRED', 'STARTUP_FAILURE']);
     // A concurrency group that supersedes its own earlier run leaves TWO rows
@@ -264,6 +265,44 @@ export function classifyPoll(stdout: string, stderr: string, status: number | nu
     return { kind: 'settled', failing, total: rows.length };
 }
 
+const MAX_NAMED = 8;
+const MAX_NAME_CHARS = 80;
+
+/**
+ * The lines an expired wait prints, the `DID NOT SETTLE` line LAST because the
+ * last line is the one a caller reads as the outcome.
+ *
+ * WHY IT SAYS MORE THAN IT USED TO (`road-to-blocking-time-by-cause` 3.3,
+ * claim `turnaround-blocking-by-cause-targets`): in the 2026-10 reading 20 of
+ * 44 CI waits ended here and were re-run in the FOREGROUND, 184 of 261 ci-wait
+ * minutes. Naming what is still pending and that the next wait belongs in the
+ * background shortens the caller's blocking time without skipping a check: the
+ * forge still runs every one, and the verdict still comes from this waiter.
+ *
+ * Check names come from the forge and are DATA: control characters are
+ * stripped, each name is capped, and the list is bounded, so a name cannot
+ * forge a second `next wait:` line or a terminal escape.
+ */
+export function renderNoSettle(timeoutMin: number, last: PollState | null): string[] {
+    const lines: string[] = [];
+    let next = '';
+    if (last !== null && last.kind === 'pending' && last.total > 0) {
+        const names = (last.pendingNames ?? [])
+            .map((n) => n.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, ' ').trim().slice(0, MAX_NAME_CHARS))
+            .filter((n) => n !== '');
+        const shown = names.slice(0, MAX_NAMED).join(', ');
+        const more = names.length > MAX_NAMED ? ` (+${String(names.length - MAX_NAMED)} more)` : '';
+        lines.push(
+            `ci_settle: ${String(last.done)}/${String(last.total)} settled; still pending: ${shown}${more}`,
+        );
+        next =
+            ' Checks are still running, so next wait: background — re-run this waiter with the host\'s ' +
+            'background primitive; a second foreground wait repeats this one.';
+    }
+    lines.push(`ci_settle: DID NOT SETTLE within ${String(timeoutMin)} min — no verdict is claimed.${next}`);
+    return lines;
+}
+
 function poll(pr: string): PollState {
     const r = spawnSync('gh', ['pr', 'view', pr, '--json', 'statusCheckRollup'], {
         encoding: 'utf-8',
@@ -519,9 +558,7 @@ export function main(argv: readonly string[]): number {
             );
         }
         if (Date.now() >= deadline) {
-            process.stdout.write(
-                `ci_settle: DID NOT SETTLE within ${String(timeoutMin)} min — no verdict is claimed.\n`,
-            );
+            for (const line of renderNoSettle(timeoutMin, state)) process.stdout.write(`${line}\n`);
             return 2;
         }
         sleepSync(intervalSec);

package/src/scripts/classify_merge_risk.ts

@@ -0,0 +1,320 @@
+#!/usr/bin/env tsx
+/**
+ * classify_merge_risk — ADR-282's danger gate in front of an authorized
+ * auto-merge.
+ *
+ * Says `routine` or `needs-council` for a diff, plus the triggers that fired.
+ * `routine` merges on the owner's auto-merge instruction with no review;
+ * `needs-council` sends the diff to the AI council first. The classifier is
+ * advisory to that flow and grants nothing on its own.
+ *
+ * Every trigger is lifted from a rule that already exists, never invented here:
+ *
+ *   - `non-destructive-by-default` Hard-Floor rows: bulk deletion (a removed
+ *     directory, or DELETION_THRESHOLD deleted files), infrastructure config,
+ *     production data and migrations, deploy and release paths.
+ *   - `security-sensitive-stop` surfaces: auth, authz, tenancy, billing,
+ *     secrets, uploads, webhooks, route files (public endpoints).
+ *   - The ratification surfaces, read through `check_kernel_edit_ratified`'s own
+ *     `classifyPaths` — a second list would drift from the first.
+ *   - Any CI workflow: `process-full` makes a disabled required check the thing
+ *     delivery-ready must refuse, and a green rollup on a weakened workflow is
+ *     exactly what a no-review merge would trust.
+ *   - Its own surface — this file and the two commands that call it — for the
+ *     reason the ratification gate watches itself: a routine-class PR must not
+ *     be able to loosen the gate that classed it.
+ *
+ * Prose files (`.md`, `.mdx`, `.txt`, `.rst`) are exempt from the security,
+ * infra and migration token checks: a skill ABOUT secrets is not a secret
+ * surface. They stay subject to deletion, governance and self-surface checks.
+ *
+ * Fails closed: a diff that cannot be read is `needs-council`, never `routine`,
+ * and never an internal-error exit a caller might read as "nothing found".
+ *
+ * Inputs (one of):
+ *   <pr-number>           PR mode: base and head read via `gh`, head fetched
+ *   --range BASE..HEAD    range mode (`...` also accepted)
+ * Options:
+ *   --root DIR            repository to read (default: cwd)
+ *   --json                one JSON object instead of text
+ *
+ * Exit codes: 0 = routine · 1 = needs-council (including fail-closed).
+ * The LAST output line is the verdict.
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { classifyPaths, requiresRatification } from './check_kernel_edit_ratified.js';
+
+export const DELETION_THRESHOLD = 5;
+
+export interface ChangeEntry {
+    status: string;
+    path: string;
+    oldPath?: string;
+}
+
+export interface Trigger {
+    id: string;
+    rule: string;
+    paths: string[];
+}
+
+export interface Classification {
+    verdict: 'routine' | 'needs-council';
+    triggers: Trigger[];
+}
+
+export interface ClassifyOptions {
+    /** Does `dir` still exist in the head tree? Decides a removed directory. */
+    dirExistsInHead: (dir: string) => boolean;
+}
+
+const PROSE_EXT = new Set(['.md', '.mdx', '.txt', '.rst']);
+
+const SECURITY_TOKENS = new Set([
+    'auth', 'authn', 'authz', 'authenticate', 'authentication', 'authorization', 'authorize',
+    'login', 'logout', 'oauth', 'sso', 'saml', 'mfa', '2fa', 'password', 'passwords', 'passwd', 'jwt',
+    'permission', 'permissions', 'rbac', 'acl', 'policy', 'policies',
+    'tenant', 'tenants', 'tenancy', 'multitenancy',
+    'billing', 'payment', 'payments', 'invoice', 'invoices', 'subscription', 'subscriptions',
+    'refund', 'refunds', 'charge', 'charges',
+    'secret', 'secrets', 'credential', 'credentials', 'vault', 'kms', 'env',
+    'upload', 'uploads', 'webhook', 'webhooks', 'routes',
+]);
+
+const INFRA_SEGMENTS = new Set([
+    'terraform', 'terragrunt', 'pulumi', 'k8s', 'kubernetes', 'helm', 'charts', 'ansible',
+    'cloudformation', 'cdk', 'infra', 'infrastructure',
+]);
+const INFRA_EXT = new Set(['.tf', '.tfvars', '.hcl']);
+const INFRA_BASENAME_RE = /^(?:Pulumi(?:\.[\w-]+)?\.ya?ml|Chart\.ya?ml|kustomization\.ya?ml|serverless\.ya?ml)$/;
+
+const PROD_TOKENS = new Set(['prod', 'production']);
+const MIGRATION_SEGMENTS = new Set(['migrations', 'migration', 'migrate']);
+const DEPLOY_TOKENS = new Set(['deploy', 'deployment', 'deployments', 'release', 'releases', 'publish']);
+
+const SELF_SURFACE_RE =
+    /(?:^|\/)(?:scripts\/classify_merge_risk\.ts|domains\/git\/pr\/merge\/command\.md|domains\/product-basic\/roadmap\/process-full\/command\.md)$|^docs\/decisions\/ADR-282-[^/]+\.md$/;
+
+/** Lower-cased word tokens of a path: split on separators and camelCase. */
+function tokens(p: string): string[] {
+    return p
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/[\/._\-\s]+/)
+        .filter((t) => t !== '');
+}
+
+function segments(p: string): string[] {
+    return p.toLowerCase().split('/');
+}
+
+function isProse(p: string): boolean {
+    return PROSE_EXT.has(path.posix.extname(p).toLowerCase());
+}
+
+function isSecurity(p: string): boolean {
+    if (isProse(p)) {
+        return false;
+    }
+    const base = path.posix.basename(p);
+    if (base === '.env' || base.startsWith('.env.')) {
+        return true;
+    }
+    return tokens(p).some((t) => SECURITY_TOKENS.has(t));
+}
+
+function isInfra(p: string): boolean {
+    if (INFRA_EXT.has(path.posix.extname(p).toLowerCase()) || INFRA_BASENAME_RE.test(path.posix.basename(p))) {
+        return true;
+    }
+    return !isProse(p) && segments(p).slice(0, -1).some((s) => INFRA_SEGMENTS.has(s));
+}
+
+function isProdOrMigration(p: string): boolean {
+    if (path.posix.extname(p).toLowerCase() === '.sql') {
+        return true;
+    }
+    if (isProse(p)) {
+        return false;
+    }
+    return segments(p).some((s) => MIGRATION_SEGMENTS.has(s)) || tokens(p).some((t) => PROD_TOKENS.has(t));
+}
+
+function isDeployOrRelease(p: string): boolean {
+    return !isProse(p) && tokens(p).some((t) => DEPLOY_TOKENS.has(t));
+}
+
+function isWorkflow(p: string): boolean {
+    return p.startsWith('.github/workflows/');
+}
+
+/** Every path a change touches — both sides of a rename or copy. */
+function touched(entries: readonly ChangeEntry[]): string[] {
+    const out = new Set<string>();
+    for (const e of entries) {
+        out.add(e.path);
+        if (e.oldPath !== undefined) {
+            out.add(e.oldPath);
+        }
+    }
+    return [...out];
+}
+
+export function classifyChanges(entries: readonly ChangeEntry[], opts: ClassifyOptions): Classification {
+    const triggers: Trigger[] = [];
+    const add = (id: string, rule: string, paths: string[]): void => {
+        if (paths.length > 0) {
+            triggers.push({ id, rule, paths: [...paths].sort() });
+        }
+    };
+    const all = touched(entries);
+    const deleted = entries.filter((e) => e.status === 'D').map((e) => e.path);
+
+    if (deleted.length >= DELETION_THRESHOLD) {
+        add('bulk-deletion', `non-destructive-by-default — ${deleted.length} deleted files (≥ ${DELETION_THRESHOLD})`, deleted);
+    }
+    const goneDirs = [...new Set(deleted.map((p) => path.posix.dirname(p)).filter((d) => d !== '.'))].filter(
+        (d) => !opts.dirExistsInHead(d),
+    );
+    add(
+        'removed-directory',
+        'non-destructive-by-default — a directory no longer exists in the head',
+        deleted.filter((p) => goneDirs.includes(path.posix.dirname(p))),
+    );
+    add('infra-config', 'non-destructive-by-default — Terraform / Pulumi / k8s / Ansible / cloud config', all.filter(isInfra));
+    add('prod-data-or-migration', 'non-destructive-by-default — production data or a migration', all.filter(isProdOrMigration));
+    add('deploy-or-release', 'non-destructive-by-default — deploy or release path', all.filter(isDeployOrRelease));
+    add('ci-workflow', 'process-full — a disabled required check cannot reach delivery-ready', all.filter(isWorkflow));
+    add('security-surface', 'security-sensitive-stop — auth, authz, tenancy, billing, secrets, uploads, webhooks, routes', all.filter(isSecurity));
+
+    const gated = classifyPaths(all);
+    if (requiresRatification(gated)) {
+        const gatedPaths = [...gated.kernelRules, ...gated.governanceHooks, ...gated.plumbing];
+        add(
+            'governance-surface',
+            'check_kernel_edit_ratified — kernel rule, governance hook, hook plumbing or the ratification mechanism',
+            gatedPaths.length > 0 ? gatedPaths : all.filter((p) => classifyPaths([p]).self),
+        );
+    }
+    add('merge-authority-surface', 'ADR-282 — the danger gate and the commands that call it', all.filter((p) => SELF_SURFACE_RE.test(p)));
+
+    return { verdict: triggers.length > 0 ? 'needs-council' : 'routine', triggers };
+}
+
+/** Parse `git diff --name-status` output. Throws on a line it cannot read. */
+export function parseNameStatus(text: string): ChangeEntry[] {
+    const out: ChangeEntry[] = [];
+    for (const line of text.split('\n')) {
+        if (line.trim() === '') {
+            continue;
+        }
+        const parts = line.split('\t');
+        const status = (parts[0] ?? '').charAt(0);
+        if (parts.length < 2 || !/^[AMDRCTU]$/.test(status)) {
+            throw new Error(`unreadable name-status line: ${JSON.stringify(line)}`);
+        }
+        if ((status === 'R' || status === 'C') && parts.length >= 3) {
+            out.push({ status, oldPath: parts[1] ?? '', path: parts[2] ?? '' });
+        } else {
+            out.push({ status, path: parts[1] ?? '' });
+        }
+    }
+    return out;
+}
+
+function git(root: string, args: string[]): { ok: boolean; out: string } {
+    const r = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+    return { ok: r.status === 0, out: r.stdout ?? '' };
+}
+
+interface Resolved {
+    base: string;
+    head: string;
+}
+
+function resolvePr(root: string, pr: string): Resolved | null {
+    const v = spawnSync('gh', ['pr', 'view', pr, '--json', 'baseRefName,headRefOid'], { cwd: root, encoding: 'utf8' });
+    if (v.status !== 0) {
+        return null;
+    }
+    const meta = JSON.parse(v.stdout) as { baseRefName?: string; headRefOid?: string };
+    if (meta.baseRefName === undefined || meta.headRefOid === undefined) {
+        return null;
+    }
+    git(root, ['fetch', '-q', 'origin', meta.baseRefName, `pull/${pr}/head`]);
+    return { base: `origin/${meta.baseRefName}`, head: meta.headRefOid };
+}
+
+function resolveRange(range: string): Resolved | null {
+    const m = /^(.+?)\.\.\.?(.+)$/.exec(range);
+    return m === null ? null : { base: m[1] ?? '', head: m[2] ?? '' };
+}
+
+function failClosed(reason: string): Classification {
+    return { verdict: 'needs-council', triggers: [{ id: 'diff-unreadable', rule: 'fail closed — ADR-282', paths: [reason] }] };
+}
+
+export function classifyTarget(root: string, target: { pr?: string | undefined; range?: string | undefined }): Classification {
+    const resolved = target.pr !== undefined ? resolvePr(root, target.pr) : resolveRange(target.range ?? '');
+    if (resolved === null) {
+        return failClosed('could not resolve base and head');
+    }
+    const diff = git(root, ['diff', '--name-status', '-M', `${resolved.base}...${resolved.head}`]);
+    if (!diff.ok) {
+        return failClosed(`git diff ${resolved.base}...${resolved.head} failed`);
+    }
+    let entries: ChangeEntry[];
+    try {
+        entries = parseNameStatus(diff.out);
+    } catch (e) {
+        return failClosed((e as Error).message);
+    }
+    return classifyChanges(entries, {
+        dirExistsInHead: (dir) => git(root, ['cat-file', '-e', `${resolved.head}:${dir}`]).ok,
+    });
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2), write: (l: string) => void = (l) => process.stdout.write(`${l}\n`)): number {
+    let root = process.cwd();
+    let range: string | undefined;
+    let pr: string | undefined;
+    let json = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? '';
+        if (a === '--root') {
+            root = argv[++i] ?? root;
+        } else if (a === '--range') {
+            range = argv[++i];
+        } else if (a === '--json') {
+            json = true;
+        } else if (/^\d+$/.test(a)) {
+            pr = a;
+        }
+    }
+    const result =
+        pr === undefined && range === undefined ? failClosed('no PR number and no --range given') : classifyTarget(root, { pr, range });
+    if (json) {
+        write(JSON.stringify(result));
+    } else {
+        for (const t of result.triggers) {
+            write(`trigger ${t.id} — ${t.rule}`);
+            for (const p of t.paths) {
+                write(`  ${p}`);
+            }
+        }
+        write(
+            result.verdict === 'routine'
+                ? 'verdict: routine'
+                : `verdict: needs-council (${result.triggers.length} trigger(s): ${result.triggers.map((t) => t.id).join(', ')})`,
+        );
+    }
+    return result.verdict === 'routine' ? 0 : 1;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+    process.exit(main());
+}

package/src/scripts/closure_scan.ts

@@ -130,7 +130,12 @@ export const NON_BLOCKING_KINDS: ReadonlySet<Kind> = new Set<Kind>(['unfalsifiab
  * on the CONTENT a step asserts. Anything whose exit code already tracks the
  * claim — `grep` (1 on no match), a linter, a test runner — is absent on
  * purpose: including it would turn this listing into a census of every verify
- * line in the tree, which is step 2.2's instrument, not this one.
+ * line in the tree, which is step 2.2's instrument, not this one. One case
+ * reads titles and runs nothing: a name-filtered test run
+ * (`vitest run <target> -t <name>`) whose target exists carries its own
+ * failure mode a plain exit-code read cannot see — `-t` with no matching
+ * title skips every test and still exits 0 — so that one shape is read for
+ * content, never executed, in `_nameFilterHasNoMatch` below.
  */
 const FIXED_OUTPUT_HEADS: ReadonlySet<string> = new Set(['echo', 'true', 'printf', 'cat', 'ls', 'pwd', 'date']);
 
@@ -149,6 +154,87 @@ const FIXED_OUTPUT_HEADS: ReadonlySet<string> = new Set(['echo', 'true', 'printf
  * remainder as clean, which is the same mistake as reporting a share off a
  * corpus nobody scanned.
  */
+// `vitest run <target> -t <name>` (optionally `npx`-prefixed); `<name>` may
+// be bare, single-quoted or double-quoted. The target is captured
+// non-greedily up to the first whitespace or quote.
+const VITEST_NAME_FILTER_RE = /(?:^|\s)vitest\s+run\s+(\S+)\s+-t\s+(?:'([^']+)'|"([^"]+)"|(\S+))/;
+
+// `describe(`, `it(`, `test(`, and their `.only`/`.skip`/`.each`/`.todo`
+// modifiers, each with a quoted first argument — the title vitest matches
+// `-t` against (concatenated with its ancestor `describe` titles at
+// run time; this reads each title string standalone, which is sufficient to
+// prove a filter CAN match something — the question this function asks).
+const TEST_TITLE_RE = /\b(?:describe|it|test)(?:\.\w+)?\s*\(\s*(['"`])((?:(?!\1).)*)\1/g;
+
+function _collectTestFiles(target: string): string[] {
+    let stat: fs.Stats;
+    try {
+        stat = fs.statSync(target);
+    } catch {
+        return [];
+    }
+    if (stat.isFile()) return [target];
+    if (!stat.isDirectory()) return [];
+    const out: string[] = [];
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(target, { recursive: true }) as string[];
+    } catch {
+        return [];
+    }
+    for (const rel of entries) {
+        if (!/\.(?:test|spec)\.tsx?$/.test(rel)) continue;
+        out.push(path.join(target, rel));
+    }
+    return out;
+}
+
+function _extractTitles(file: string): string[] {
+    let text: string;
+    try {
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return [];
+    }
+    const titles: string[] = [];
+    const re = new RegExp(TEST_TITLE_RE.source, TEST_TITLE_RE.flags);
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(text)) !== null) {
+        titles.push(m[2] ?? '');
+    }
+    return titles;
+}
+
+/**
+ * A name-filtered vitest run whose target exists but carries no test title
+ * containing the filter — the oracle exits 0 on every test skipped, which a
+ * plain exit-code read cannot distinguish from every test passing.
+ *
+ * `null` whenever the shape does not match, the target cannot be resolved
+ * (nothing to read), or no title could be extracted at all (a parse miss,
+ * not evidence of absence) — in every one of those the finding would be a
+ * guess, and this function only reports what it read.
+ */
+function _nameFilterHasNoMatch(command: string): string | null {
+    const m = VITEST_NAME_FILTER_RE.exec(command);
+    if (m === null) return null;
+    const targetRaw = m[1] as string;
+    const name = (m[2] ?? m[3] ?? m[4] ?? '').trim();
+    if (name === '') return null;
+    const target = path.resolve(process.cwd(), targetRaw);
+    const files = _collectTestFiles(target);
+    if (files.length === 0) return null;
+    let sawAnyTitle = false;
+    for (const file of files) {
+        for (const title of _extractTitles(file)) {
+            sawAnyTitle = true;
+            if (title.includes(name)) return null;
+        }
+    }
+    if (!sawAnyTitle) return null;
+    return `\`-t ${name}\` matches no test title under ${targetRaw}: the run exits 0 with every test skipped`;
+}
+
 export function unfalsifiableReason(clause: VerifyClause): string | null {
     if (clause.command === null) {
         // A MANUAL clause asserting a QUANTITY nothing produced. Narrowed to a
@@ -176,6 +262,10 @@ export function unfalsifiableReason(clause: VerifyClause): string | null {
             // An expectation that cannot compile never became one upstream.
         }
     }
+
+    const nameFilterReason = _nameFilterHasNoMatch(clause.command);
+    if (nameFilterReason !== null) return nameFilterReason;
+
     return null;
 }