@event4u/agent-config 9.14.0 → 9.15.0

package/src/scripts/check_augment_description_cap.ts

@@ -91,11 +91,32 @@ function _globMdSorted(dir: string): string[] {
     return out;
 }
 
-export function main(): number {
+/**
+ * Injection seam for tests: `--root <dir>` overrides the scan root.
+ *
+ * Additive — no flag means the CI-identical bare call scans `RULES_DIR`, so the
+ * pinned CLI contract is unchanged. Without a seam the only way to exercise a
+ * real over-cap violation was to tamper with a committed rule, which is why this
+ * gate shipped with tests that never called `main()` at all.
+ */
+function _resolve_root(argv: readonly string[]): string {
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        if (a === '--root') {
+            const v = argv[i + 1];
+            if (v !== undefined) return path.resolve(v);
+        } else if (a.startsWith('--root=')) {
+            return path.resolve(a.slice('--root='.length));
+        }
+    }
+    return RULES_DIR;
+}
+
+export function main(argv: readonly string[] = []): number {
     const failures: Array<[string, number, string]> = [];
     let checked = 0;
 
-    for (const p of _globMdSorted(RULES_DIR)) {
+    for (const p of _globMdSorted(_resolve_root(argv))) {
         const text = fs.readFileSync(p, 'utf-8');
         const fm = parse_frontmatter(text);
         if (fm['type'] !== 'auto') {
@@ -157,7 +178,7 @@ function _isCliEntry(): boolean {
 }
 
 if (_isCliEntry() || process.argv[1] === _HERE) {
-    process.exit(main());
+    process.exit(main(process.argv.slice(2)));
 }
 
 export { REPO_ROOT, RULES_DIR, DESC_CAP };

package/src/scripts/check_ci_strict_superset.ts

@@ -0,0 +1,150 @@
+#!/usr/bin/env tsx
+/**
+ * Assert `ci-strict` is a superset of `ci` BY CONSTRUCTION.
+ *
+ * WHY THIS EXISTS (road-to-renewal-foundation Phase 1, council 2026-08-02
+ * decision A1, 2/2):
+ *
+ * `Taskfile.yml` used to carry `ci` (202 gate entries) and `ci-strict` (197)
+ * as two independently maintained literal lists. They drifted, and nothing
+ * detected it — `check_ci_local_parity.ts` deliberately scopes itself to
+ * `LOCAL_ROOTS = ['ci', 'consistency']`, so `ci-strict` was outside every
+ * assertion in the repo. Six gates ran in `ci` with no counterpart in
+ * `ci-strict` at all:
+ *
+ *   preflight (fans out to 11 scripts, incl. check_no_new_legacy_path and
+ *   check_kernel_rule_bundle), check-ci-local-parity,
+ *   check-gitignore-freshness, check-generator-output-coverage,
+ *   check-tracked-but-ignored, check-generated-artefact-headers
+ *
+ * — so the "release-tag gate" was strictly WEAKER than the everyday gate on
+ * ~16 concrete script runs. A stricter tier that checks less is the worst
+ * possible shape for a release gate: it is trusted more and proves less.
+ *
+ * The fix was structural, not a bigger checker: `ci-strict` now delegates to
+ * `ci` and adds only strict-only entries on top, so the superset property is
+ * tautological. This gate guards the ONE invariant that keeps it tautological
+ * — the first gate entry of `ci-strict` is `- task: ci`.
+ *
+ * It deliberately does NOT re-parse and diff both lists. That would recreate
+ * the very "maintain a second model of the same thing" problem the delegation
+ * removed, and it would pass happily on a re-forked pair of lists that merely
+ * happened to match on the day it ran.
+ *
+ * Exit codes: 0 ok · 1 invariant violated · 2 usage / environment error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const TASKFILE = path.join(REPO_ROOT, 'Taskfile.yml');
+
+/** The delegation entry that makes the superset property tautological. */
+const DELEGATION = '- task: ci';
+
+/**
+ * Extract the `cmds:` entries of a top-level task, in order.
+ *
+ * Minimal line scan rather than a YAML dependency: the shape is fixed
+ * (`  <name>:` at two-space indent, `    cmds:` at four, `      - ...` at
+ * six) and the repo has no YAML anchors anywhere, so a parser buys nothing
+ * here and adds an import to a gate that must stay cheap.
+ */
+function taskCmds(source: string, taskName: string): string[] | null {
+    const lines = source.split('\n');
+    const header = `  ${taskName}:`;
+    let i = lines.findIndex((l) => l === header);
+    if (i === -1) {
+        return null;
+    }
+    const out: string[] = [];
+    let inCmds = false;
+    for (i += 1; i < lines.length; i++) {
+        const line = lines[i]!;
+        if (line.trim() === '') {
+            continue;
+        }
+        // Any line at two-space indent that is not deeper ends this task.
+        if (/^ {2}\S/.test(line)) {
+            break;
+        }
+        if (/^ {4}cmds:\s*$/.test(line)) {
+            inCmds = true;
+            continue;
+        }
+        if (!inCmds) {
+            continue;
+        }
+        const m = /^ {6}(- .*)$/.exec(line);
+        if (m) {
+            out.push(m[1]!.trim());
+        }
+    }
+    return out;
+}
+
+export function main(): number {
+    let source: string;
+    try {
+        source = fs.readFileSync(TASKFILE, 'utf-8');
+    } catch (err) {
+        process.stderr.write(`❌  check_ci_strict_superset: cannot read ${TASKFILE}: ${String(err)}\n`);
+        return 2;
+    }
+
+    const strict = taskCmds(source, 'ci-strict');
+    if (strict === null) {
+        process.stderr.write(
+            '❌  check_ci_strict_superset: no `ci-strict:` task found in Taskfile.yml.\n' +
+                '    The gate cannot verify an invariant on a task that does not exist.\n',
+        );
+        return 2;
+    }
+    if (taskCmds(source, 'ci') === null) {
+        process.stderr.write(
+            '❌  check_ci_strict_superset: no `ci:` task found in Taskfile.yml.\n',
+        );
+        return 2;
+    }
+
+    // Skip the internal timing wrappers; they carry no gate semantics and
+    // `ci-strict` intentionally does not repeat them (`ci` already brackets
+    // the run, so the duration line prints once).
+    const gateEntries = strict.filter(
+        (e) => !e.startsWith('- defer:') && e !== '- task: _ci-start' && e !== '- task: _ci-end',
+    );
+
+    if (gateEntries.length === 0) {
+        process.stderr.write('❌  check_ci_strict_superset: `ci-strict` has no gate entries.\n');
+        return 1;
+    }
+
+    if (gateEntries[0] !== DELEGATION) {
+        process.stderr.write(
+            '❌  check_ci_strict_superset: `ci-strict` no longer delegates to `ci`.\n' +
+                `    expected first gate entry: \`${DELEGATION}\`\n` +
+                `    found:                    \`${gateEntries[0]}\`\n\n` +
+                '    `ci-strict` must run every `ci` gate plus strict-only extras. It used\n' +
+                '    to be an independently maintained copy of the list and silently drifted\n' +
+                '    to SIX fewer gates than `ci` — a release gate that proved less than the\n' +
+                '    everyday gate. Delegation is what makes the superset property structural\n' +
+                '    instead of asserted. If you need a strict variant of a gate, add the\n' +
+                '    `-strict` task AFTER the delegation entry; never re-inline the list.\n',
+        );
+        return 1;
+    }
+
+    const extras = gateEntries.slice(1);
+    process.stdout.write(
+        `✅  ci-strict ⊇ ci by construction (delegates to \`ci\`, plus ${extras.length} strict-only ` +
+            `entr${extras.length === 1 ? 'y' : 'ies'}).\n`,
+    );
+    return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exit(main());
+}

package/src/scripts/check_cluster_patterns.ts

@@ -18,6 +18,19 @@
  * must document the bare-invocation behaviour (menu / default route /
  * detection fallback) per command-clusters.md § Bare invocation.
  *
+ * Filesystem-enumeration addition (road-to-renewal-leverage, 2026-08-02): the
+ * checks above all read the CONTRACT and ask "does what it names exist?".
+ * Nothing asked the inverse — "does what exists get named?" — so a
+ * sub-command could sit on disk while appearing in neither its hub's
+ * `## Sub-commands` table nor its `routes_to:`, invisibly. Two instances were
+ * live when this was added (`/roadmap:materialize`, `/memory:learn-low-impact`)
+ * plus incomplete `routes_to` on 12 of 25 dispatch clusters.
+ * `check_completeness` closes that direction: for a `type: orchestrator`
+ * dispatcher, every on-disk `<sub>/command.md` sibling directory must be named
+ * in the table and listed in `routes_to`. Scoped to orchestrators on purpose —
+ * a few contract rows point at full working commands that merely happen to
+ * carry one nested sub-command, and those own no dispatch table.
+ *
  * Exit codes: 0 = clean, 1 = pattern violations, 3 = internal error.
  */
 
@@ -170,6 +183,90 @@ function _repr(v: string | undefined): string {
     return `'${v.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 }
 
+/** Parse a `routes_to: [a, b]` frontmatter value into its entries. */
+export function parse_routes_to(raw: string | undefined): string[] {
+    if (raw === undefined) {
+        return [];
+    }
+    const m = /^\[(.*)\]$/.exec(raw.trim());
+    if (!m) {
+        return [];
+    }
+    return (m[1] as string)
+        .split(',')
+        .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+        .filter((s) => s.length > 0);
+}
+
+/** Sub-command directory names that carry a `command.md`, sorted. */
+export function on_disk_subs(dispatcher_path: string): string[] {
+    const dir = path.dirname(dispatcher_path);
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isDirectory() && _isFile(path.join(dir, e.name, 'command.md')))
+        .map((e) => e.name)
+        .sort();
+}
+
+/**
+ * Does the body name `<sub>` as a sub-command of `<cluster>`?
+ *
+ * Both `` `/cluster:sub` `` and `` `/cluster sub` `` count — command-clusters.md
+ * § 157 makes the space form a first-class equivalent of the colon form, so
+ * requiring one of them would be inventing a rule the contract does not carry.
+ * The trailing class allows a row that decorates the name inside the same
+ * backticks (`` `/team review [--background]` ``).
+ */
+export function names_sub(body: string, cluster: string, sub: string): boolean {
+    const re = new RegExp('`/' + cluster + '[: ]' + sub + '(?![a-z0-9-])');
+    return re.test(body);
+}
+
+/**
+ * Every on-disk sub-command of an orchestrator must be named in its
+ * `## Sub-commands` table and listed in `routes_to:`.
+ *
+ * Non-orchestrator dispatchers are skipped: a handful of contract rows point
+ * at full working commands that merely happen to carry a nested sub-command,
+ * and those own no dispatch table to be complete against.
+ */
+export function check_completeness(
+    cluster: string,
+    dispatcher_path: string,
+    fm: Record<string, string>,
+    body: string,
+): string[] {
+    if (fm['type'] !== 'orchestrator') {
+        return [];
+    }
+    const subs = on_disk_subs(dispatcher_path);
+    if (subs.length === 0) {
+        return [];
+    }
+    const errors: string[] = [];
+    const routes = parse_routes_to(fm['routes_to']);
+    for (const sub of subs) {
+        if (!names_sub(body, cluster, sub)) {
+            errors.push(
+                `sub-command \`${sub}\` exists on disk but is not named in the ` +
+                    '`## Sub-commands` table',
+            );
+        }
+        if (!routes.includes(`${cluster}-${sub}`) && !routes.includes(sub)) {
+            errors.push(
+                `sub-command \`${sub}\` exists on disk but is missing from ` +
+                    '`routes_to:`',
+            );
+        }
+    }
+    return errors;
+}
+
 export function check_dispatcher(cluster: string, slug_map: Map<string, string>): FileReport {
     const p = _resolve_command(cluster, slug_map);
     if (p === null) {
@@ -241,6 +338,9 @@ export function check_dispatcher(cluster: string, slug_map: Map<string, string>)
         }
     }
 
+    // Completeness (2026-08-02): every sub-command that EXISTS must be named.
+    rep.errors.push(...check_completeness(cluster, p, fm, body));
+
     // Bare-invocation story (Phase 4 / ADR-115): the Dispatch section must say
     // what a bare `/<cluster>` does — a menu, a default route, or detection.
     const dispatchIdx = body.indexOf('## Dispatch');

package/src/scripts/check_consumer_scope_flip.ts

@@ -63,7 +63,7 @@ export interface FlipVerdict {
 
 export function verify_flip(repoRoot = '.'): FlipVerdict {
     const template = parseYaml(fs.readFileSync(path.join(repoRoot, TEMPLATE), 'utf-8')) as Record<string, unknown>;
-    const scope = ruleScopeFromSettings(template);
+    const scope = ruleScopeFromSettings(template, repoRoot);
     if (scope.workspaces === null) {
         throw new Error('template rule_workspaces is empty — nothing flipped, nothing to verify');
     }
@@ -149,8 +149,26 @@ async function main(): Promise<number> {
         },
         pass: v.pass,
     };
-    fs.mkdirSync(path.dirname(REPORT), { recursive: true });
-    fs.writeFileSync(REPORT, `${JSON.stringify(report, null, 1)}\n`);
+    // WRITE IS OPT-IN (road-to-renewal-foundation Phase 1). This used to write
+    // unconditionally, which made a `check_*` script mutate a TRACKED, DATED
+    // artifact as a side effect of merely being executed. Two concrete costs,
+    // both hit in one session:
+    //
+    //   * Any sweep that runs "every gate" — a coverage census, a timing pass,
+    //     or the pooled umbrella runner this roadmap proposes — silently dirties
+    //     the tree, and the next `task consistency` then reports derived-output
+    //     drift that has nothing to do with the diff under test.
+    //   * A dated report is a RECORD of a past measurement. Rewriting it in
+    //     place with today's numbers destroys the thing its filename claims.
+    //
+    // Verification is unchanged and still runs on every invocation; only the
+    // persistence is gated. `--write` reproduces the old behaviour for a
+    // deliberate re-measure.
+    const wrote = process.argv.includes('--write');
+    if (wrote) {
+        fs.mkdirSync(path.dirname(REPORT), { recursive: true });
+        fs.writeFileSync(REPORT, `${JSON.stringify(report, null, 1)}\n`);
+    }
     process.stdout.write(`excluded ${v.excluded.length} rules under scope [${v.scope.join(', ')}]\n`);
     if (v.violations.length > 0) {
         process.stdout.write(`❌  NON-MAINTAINER rules would drop: ${v.violations.join(' · ')}\n`);
@@ -162,7 +180,11 @@ async function main(): Promise<number> {
         `legacy-all ${legacyRules} rules / ${legacyTok} tok → scoped ${scopedRules} rules / ${scopedTok} tok `
         + `(−${legacyTok - scopedTok} tok, −${report.delta.tokens_pct}%)\n`,
     );
-    process.stdout.write(v.pass ? `✅  flip verified — wrote ${REPORT}\n` : '❌  flip NOT verified\n');
+    process.stdout.write(
+        v.pass
+            ? `✅  flip verified${wrote ? ` — wrote ${REPORT}` : ' (read-only; pass --write to persist the report)'}\n`
+            : '❌  flip NOT verified\n',
+    );
     return v.pass ? 0 : 1;
 }
 

package/src/scripts/check_evaluator_budgets.ts

@@ -3,17 +3,38 @@
  * check_evaluator_budgets — enforce the outside-in evaluator budgets
  * (road-to-credible-install Phase 6) against a measurements JSON.
  *
- * Two failure modes per metric:
+ * Three failure modes per metric:
  *   1. absolute:   measured > budgets[metric].max
  *   2. regression: measured > last_measured * (1 + regression_pct/100)
  *      — fails EVEN WHEN still under the absolute budget (the >10%
  *      creep rule), so slow rot cannot hide under a generous cap.
+ *   3. drift:      a DETERMINISTIC metric disagrees with the committed
+ *      measurement record the nightly publishes. `cli_help_command_count`
+ *      drifted 74 → 80 against a value frozen at 79 with nobody seeing it;
+ *      the record makes the day a number moves the day it shows in a diff
+ *      (road-to-gates-that-can-fail Phase 5).
+ *
+ * ## Posture — warn on main, fail on release
+ *
+ * A hard fail on `main` turns every legitimate command addition into a
+ * blocked merge, which is how budgets get quietly raised with a cushion
+ * instead of consciously. So budget / regression / drift findings are
+ * ADVISORY outside a release context and BLOCKING inside one. This is not a
+ * weakening: before the Phase-4 path triggers, the umbrella ran on release
+ * PRs and the nightly only — the surfaces that now warn never saw the gate
+ * at all. The posture IS the delivery route the council adopted for nightly
+ * visibility, not a second mechanism beside it.
+ *
+ * Structural findings (a metric with NO measurement supplied) are ALWAYS
+ * blocking, in either posture: that is a harness reporting green on nothing,
+ * which is the whole class this roadmap exists to end.
  *
  * Usage:
  *   ./scripts-run src/scripts/check_evaluator_budgets --measurements <file.json>
+ *       [--recorded <file.json>] [--posture warn|fail]
  *   (measurements: flat { metric: number } — produced by evaluator_umbrella.sh)
  *
- * Exit codes: 0 green · 1 budget/regression exceeded · 2 internal error.
+ * Exit codes: 0 green (or advisory findings only) · 1 blocking finding · 2 internal error.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -22,6 +43,9 @@ import { fileURLToPath } from 'node:url';
 const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 const BUDGETS_PATH = path.join(REPO_ROOT, 'src', 'config', 'evaluator-budgets.json');
 
+/** Committed measurement record the nightly refreshes (Phase 5 step 1). */
+export const RECORD_REL = path.join('agents', 'evidence', 'metrics', 'evaluator-measurements.json');
+
 interface BudgetEntry {
     max: number;
     last_measured: number;
@@ -30,51 +54,174 @@ interface BudgetEntry {
      * (absolute cap is their real gate); sizes/counts keep the tight
      * global default. */
     regression_pct?: number;
+    /** `false` for wall-clock metrics: they cannot be compared run-to-run,
+     * so they are excluded from the drift check. Missing = deterministic. */
+    deterministic?: boolean;
 }
 interface BudgetsDoc {
     regression_pct: number;
     budgets: Record<string, BudgetEntry>;
 }
 
-export function evaluate(
+/** Shape of the committed measurement record. */
+export interface MeasurementRecord {
+    schema_version: number;
+    recorded_at: string;
+    git_sha?: string;
+    run_url?: string;
+    conditions?: string;
+    measurements: Record<string, number | string>;
+}
+
+export type Severity =
+    /** Always blocks — the harness itself is broken. */
+    | 'structural'
+    /** Blocks only under the `fail` posture. */
+    | 'advisory';
+
+export interface Finding {
+    metric: string;
+    severity: Severity;
+    message: string;
+}
+
+export function evaluateFindings(
     budgetsDoc: BudgetsDoc,
     measurements: Record<string, number>,
-): string[] {
-    const errors: string[] = [];
+): Finding[] {
+    const findings: Finding[] = [];
     for (const [metric, entry] of Object.entries(budgetsDoc.budgets)) {
         const measured = measurements[metric];
         if (measured === undefined || Number.isNaN(measured)) {
-            errors.push(`${metric}: no measurement supplied (method: ${entry.method})`);
+            findings.push({
+                metric,
+                severity: 'structural',
+                message: `${metric}: no measurement supplied (method: ${entry.method})`,
+            });
             continue;
         }
         if (measured > entry.max) {
-            errors.push(`${metric}: measured ${measured} exceeds budget ${entry.max}`);
+            findings.push({
+                metric,
+                severity: 'advisory',
+                message: `${metric}: measured ${measured} exceeds budget ${entry.max}`,
+            });
             continue;
         }
         const pct = entry.regression_pct ?? budgetsDoc.regression_pct;
         const ceiling = entry.last_measured * (1 + pct / 100);
         if (entry.last_measured > 0 && measured > ceiling) {
-            errors.push(
-                `${metric}: measured ${measured} regressed >${pct}% vs ` +
+            findings.push({
+                metric,
+                severity: 'advisory',
+                message:
+                    `${metric}: measured ${measured} regressed >${pct}% vs ` +
                     `last_measured ${entry.last_measured} (ceiling ${ceiling.toFixed(2)}) — ` +
                     'fails even under the absolute budget',
-            );
+            });
         }
     }
-    return errors;
+    return findings;
+}
+
+/**
+ * Back-compat surface: the flat message list. Kept because the budget shape
+ * and the per-metric rules are pinned by tests through this function.
+ */
+export function evaluate(budgetsDoc: BudgetsDoc, measurements: Record<string, number>): string[] {
+    return evaluateFindings(budgetsDoc, measurements).map((f) => f.message);
+}
+
+/**
+ * Compare a fresh measurement set against the committed record.
+ *
+ * Only DETERMINISTIC metrics participate: comparing wall-clock timings
+ * run-to-run produces noise, and a noisy comparison gets ignored — which
+ * reproduces the failure the record exists to fix. A metric absent from
+ * either side is skipped (a missing measurement is already a structural
+ * finding above; a metric absent from the record is simply not recorded yet).
+ */
+export function driftFindings(
+    budgetsDoc: BudgetsDoc,
+    measurements: Record<string, number>,
+    record: MeasurementRecord | null,
+): Finding[] {
+    if (record === null) return [];
+    const findings: Finding[] = [];
+    for (const [metric, entry] of Object.entries(budgetsDoc.budgets)) {
+        if (entry.deterministic === false) continue;
+        const fresh = measurements[metric];
+        const recorded = record.measurements[metric];
+        if (fresh === undefined || recorded === undefined) continue;
+        if (typeof recorded !== 'number') continue;
+        if (fresh === recorded) continue;
+        findings.push({
+            metric,
+            severity: 'advisory',
+            message:
+                `${metric}: measured ${fresh} but the committed record says ${recorded} ` +
+                `(recorded ${record.recorded_at}` +
+                `${record.git_sha ? ` @ ${record.git_sha.slice(0, 8)}` : ''}) — refresh ` +
+                `${RECORD_REL} in the PR that moves the number, or explain the move`,
+        });
+    }
+    return findings;
+}
+
+export type Posture = 'warn' | 'fail';
+
+/**
+ * Where are we, and does a budget finding block?
+ *
+ * Release context → `fail`. Local (no CI env) → `fail`, deliberately: a
+ * maintainer running this by hand — including `release.ts` — wants the strict
+ * answer, and a local run blocks nobody else. Everything else (main, the
+ * nightly, a feature PR) → `warn`.
+ */
+export function detectPosture(
+    env: NodeJS.ProcessEnv = process.env,
+    override?: string,
+): { posture: Posture; reason: string } {
+    if (override === 'warn' || override === 'fail') {
+        return { posture: override, reason: `--posture ${override}` };
+    }
+    const head = env['GITHUB_HEAD_REF'] ?? '';
+    const base = env['GITHUB_BASE_REF'] ?? '';
+    const ref = env['GITHUB_REF'] ?? '';
+    if (head.startsWith('release/')) {
+        return { posture: 'fail', reason: `release PR (head ${head})` };
+    }
+    if (base.startsWith('release/')) {
+        return { posture: 'fail', reason: `PR into a release branch (base ${base})` };
+    }
+    if (ref.startsWith('refs/heads/release/') || ref.startsWith('refs/tags/')) {
+        return { posture: 'fail', reason: `release ref (${ref})` };
+    }
+    if (!env['GITHUB_ACTIONS']) {
+        return { posture: 'fail', reason: 'local run (no CI env) — strict by default' };
+    }
+    return { posture: 'warn', reason: `non-release CI context (${ref || 'unknown ref'})` };
+}
+
+function argValue(argv: string[], flag: string): string | undefined {
+    const i = argv.indexOf(flag);
+    return i >= 0 ? argv[i + 1] : undefined;
 }
 
 export function main(argv: string[] = process.argv.slice(2)): number {
-    const idx = argv.indexOf('--measurements');
-    if (idx < 0 || argv[idx + 1] === undefined) {
-        process.stderr.write('usage: check_evaluator_budgets --measurements <file.json>\n');
+    const measurementsPath = argValue(argv, '--measurements');
+    if (measurementsPath === undefined) {
+        process.stderr.write(
+            'usage: check_evaluator_budgets --measurements <file.json> ' +
+                '[--recorded <file.json>] [--posture warn|fail]\n',
+        );
         return 2;
     }
     let budgetsDoc: BudgetsDoc;
     let measurements: Record<string, number>;
     try {
         budgetsDoc = JSON.parse(fs.readFileSync(BUDGETS_PATH, 'utf-8')) as BudgetsDoc;
-        measurements = JSON.parse(fs.readFileSync(argv[idx + 1] as string, 'utf-8')) as Record<
+        measurements = JSON.parse(fs.readFileSync(measurementsPath, 'utf-8')) as Record<
             string,
             number
         >;
@@ -82,13 +229,45 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         process.stderr.write(`check_evaluator_budgets: ${(e as Error).message}\n`);
         return 2;
     }
-    const errors = evaluate(budgetsDoc, measurements);
-    if (errors.length > 0) {
-        for (const e of errors) process.stderr.write(`❌  evaluator budget: ${e}\n`);
+
+    // The committed record is optional: a fresh checkout before the first
+    // nightly has none, and a missing record must not fake a green drift check.
+    const recordPath = argValue(argv, '--recorded') ?? path.join(REPO_ROOT, RECORD_REL);
+    let record: MeasurementRecord | null = null;
+    try {
+        record = JSON.parse(fs.readFileSync(recordPath, 'utf-8')) as MeasurementRecord;
+    } catch {
+        process.stdout.write(
+            `ℹ️  no measurement record at ${recordPath} — drift check skipped ` +
+                '(the nightly publishes it)\n',
+        );
+    }
+
+    const { posture, reason } = detectPosture(process.env, argValue(argv, '--posture'));
+    const findings = [
+        ...evaluateFindings(budgetsDoc, measurements),
+        ...driftFindings(budgetsDoc, measurements, record),
+    ];
+    const blocking = findings.filter((f) => f.severity === 'structural' || posture === 'fail');
+    const advisory = findings.filter((f) => !blocking.includes(f));
+
+    for (const f of advisory) {
+        process.stderr.write(`⚠️  evaluator budget (advisory, posture=${posture}): ${f.message}\n`);
+    }
+    for (const f of blocking) {
+        process.stderr.write(`❌  evaluator budget: ${f.message}\n`);
+    }
+    if (blocking.length > 0) {
+        process.stderr.write(
+            `check_evaluator_budgets: ${blocking.length} blocking finding(s) — ` +
+                `posture ${posture} (${reason})\n`,
+        );
         return 1;
     }
     process.stdout.write(
-        `✅  evaluator budgets met (${Object.keys(budgetsDoc.budgets).length} metrics)\n`,
+        `✅  evaluator budgets met (${Object.keys(budgetsDoc.budgets).length} metrics` +
+            `${advisory.length > 0 ? `, ${advisory.length} advisory finding(s)` : ''}) — ` +
+            `posture ${posture} (${reason})\n`,
     );
     return 0;
 }