@event4u/agent-config 9.27.0 → 9.29.0

package/src/scripts/bench_critic_protocol.ts

@@ -0,0 +1,396 @@
+/**
+ * Critic-protocol A/B runner (road-to-judgment-and-forensic-evidence Phase 2).
+ *
+ * Measures the `load_bearing` critic protocol against the shipped `legacy`
+ * adversarial-skeptic posture on the frozen corpus
+ * (internal/bench/adversarial-council/corpus.json) — the corpus on which the
+ * legacy posture scored a measured 100% false-positive rate on the 3
+ * controversial-but-correct clean controls (run 2026-07-21).
+ *
+ * Protocol (pre-registered in docs/CLAIMS.md `critic-protocol-load-bearing-ab`
+ * BEFORE any paid run; thresholds, prompts, and scorer semantics frozen there):
+ *
+ *   Both arms run as ONE independent single-shot review per vendor
+ *   (anthropic + openai, direct client calls — NEVER council_cli transport)
+ *   over all 15 corpus items (12 defect fixtures + 3 clean controls).
+ *
+ *   PER VENDOR, the load_bearing arm promotes iff BOTH:
+ *     (1) FP rate on the 3 clean controls < 50%, AND
+ *     (2) TP count on the 12 defect fixtures >= 80% of the legacy arm's
+ *         TP count in the same run.
+ *
+ *   Scoring is the existing deterministic scorer applied IDENTICALLY to both
+ *   arms on findings only (caughtDefect / isFalsePositive). The protocol's
+ *   `verdict` field is a secondary published signal; "flawed" with empty
+ *   findings counts as `incoherent` (2026-08-09 council design pass) — never
+ *   as a catch, never as an FP.
+ *
+ * `--mock` validates the pipeline in BOTH directions with zero spend (a
+ * passing arm must read PASS, a failing arm must read FAIL) — the roadmap's
+ * pre-spend tripwire. `--run` fires the paid cross-vendor calls
+ * (maintainer spend-gated). `--out <file>` writes the report JSON.
+ *
+ * The `legacy` default and the `critic_protocol` config key live in
+ * scripts/ai_council/config.ts; this runner takes the arms from the corpus
+ * loop directly (an A/B needs both regardless of the configured value).
+ */
+// ledger-exempt: bench runner, not a CI gate — spend-gated on-demand measurement
+// with a fixed 15-item corpus; the report itself carries the full denominator.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import {
+    AnthropicClient,
+    OpenAIClient,
+    load_anthropic_key,
+    load_openai_key,
+    type ExternalAIClient,
+} from './ai_council/clients.js';
+import {
+    caughtDefect,
+    isFalsePositive,
+    categoryFamily,
+    type Finding,
+    type GroundTruth,
+} from './_lib/adversarial_bench_score.js';
+
+const REPO_ROOT = process.cwd();
+const CORPUS_PATH = path.join(REPO_ROOT, 'internal/bench/adversarial-council/corpus.json');
+
+/** Pre-registered thresholds — frozen with the CLAIMS entry, never adjusted. */
+const FP_CEILING = 0.5; // strict: FP rate must be < 0.5 on the 3 controls
+const TP_RETENTION_FLOOR = 0.8; // load_bearing TP >= 0.8 × legacy TP, per vendor
+
+interface CorpusItem {
+    id: string;
+    class: string;
+    defect_category: string;
+    is_clean: boolean;
+    files: { path: string; content: string }[];
+    ground_truth: { defect_files: string[]; defect_summary: string };
+}
+
+function loadCorpus(): CorpusItem[] {
+    return JSON.parse(fs.readFileSync(CORPUS_PATH, 'utf8')).items as CorpusItem[];
+}
+function groundTruth(item: CorpusItem): GroundTruth {
+    return {
+        id: item.id,
+        is_clean: item.is_clean,
+        defect_files: item.ground_truth.defect_files,
+        defect_category: item.is_clean ? 'none' : categoryFamily(item.defect_category),
+    };
+}
+function codeBlock(item: CorpusItem): string {
+    return item.files.map((f) => `FILE: ${f.path}\n\`\`\`ts\n${f.content}\`\`\``).join('\n\n');
+}
+
+const FINDINGS_SHAPE =
+    '{"findings":[{"file":"<file path>","category":"<defect category>","confidence":"high|medium|low","summary":"<one line>"}]}';
+
+/**
+ * LEGACY arm — byte-identical to the prompt that produced the measured 100%
+ * FP on the clean controls (bench_adversarial_council.ts skepticPrompt).
+ */
+function legacyPrompt(item: CorpusItem): string {
+    return [
+        'You are an adversarial security/correctness skeptic. Assume this code may hide a subtle, non-obvious defect that a normal review missed — a masked access-control/SSRF/traversal flaw, a boundary/logic inversion, a concurrency or resource-leak edge, a cross-file contract mismatch. Hunt for it. Report only defects you can concretely justify; if after hard scrutiny it is genuinely correct, report an empty array (do not fabricate).',
+        `Respond with STRICT JSON only, exactly: ${FINDINGS_SHAPE}`,
+        '',
+        codeBlock(item),
+    ].join('\n');
+}
+
+const PROTOCOL_SHAPE =
+    '{"invariant":"<one sentence>","load_bearing_assumption":"<one sentence, names file+function>","failure_scenario_if_broken":"<one sentence>","cost_of_avoidance":"<one sentence>","succeeded_would_do":"<one sentence or \'nothing\'>","verdict":"holds|flawed","findings":[{"file":"<file path>","category":"<defect category>","confidence":"high|medium|low","summary":"<one line>"}]}';
+
+/**
+ * LOAD_BEARING arm — the fixed protocol. Design integrated the 2026-08-09
+ * council convergence: the assumption must be tied to a named file+function
+ * (no platitudes), a concrete failure scenario forces the assumption to be
+ * load-bearing, and "holds" is an explicitly permitted, completed review.
+ */
+function loadBearingPrompt(item: CorpusItem): string {
+    return [
+        'You are a rigorous correctness critic running a fixed protocol. Do not free-associate defects. Work strictly in this order:',
+        '1. State the invariant this code must maintain to be correct, then name the SINGLE load-bearing assumption it rests on — the one whose failure would break that invariant. Tie it to a named file and function; a platitude ("inputs are valid") is not an assumption.',
+        '2. State the concrete failure scenario if that assumption broke: which input or state leads to which wrong behaviour. If you cannot state one, the assumption is not load-bearing — pick again.',
+        '3. State the cost of what this code is avoiding: what failure mode or complexity does its current shape avert?',
+        "4. State what someone who has already built a comparable thing successfully would do differently here, if anything ('nothing' is acceptable).",
+        '5. Now inspect the assumption against the code. If it survives inspection and the failure scenario is unreachable, your verdict is "holds" and findings is []. A defensible "holds" with the assumption and scenario stated is a completed review, not a refusal. If the assumption breaks, or the failure scenario is reachable, or you find another concrete defect you can justify against specific lines, your verdict is "flawed" and findings lists each one.',
+        `Respond with STRICT JSON only, exactly: ${PROTOCOL_SHAPE}`,
+        '',
+        codeBlock(item),
+    ].join('\n');
+}
+
+const SYSTEM_JSON =
+    'You are a code reviewer. Output ONLY one JSON object — no prose, no markdown, no code fences. ' +
+    'If the code is correct, the "findings" array is empty. Do not include any text before or after the JSON object.';
+
+interface ArmResponse {
+    findings: Finding[];
+    verdict: 'holds' | 'flawed' | null; // null for the legacy arm (no verdict field)
+}
+
+function extractJsonObject(text: string): Record<string, unknown> | null {
+    if (!text) return null;
+    const start = text.indexOf('{');
+    if (start < 0) return null;
+    let depth = 0;
+    let end = -1;
+    for (let i = start; i < text.length; i++) {
+        if (text[i] === '{') depth++;
+        else if (text[i] === '}' && --depth === 0) {
+            end = i;
+            break;
+        }
+    }
+    if (end < 0) return null;
+    try {
+        return JSON.parse(text.slice(start, end + 1)) as Record<string, unknown>;
+    } catch {
+        return null;
+    }
+}
+
+function parseArmResponse(text: string): ArmResponse {
+    const obj = extractJsonObject(text);
+    if (!obj) return { findings: [], verdict: null };
+    const arr = Array.isArray(obj.findings) ? obj.findings : [];
+    const findings = arr
+        .filter((f): f is Record<string, unknown> => typeof f === 'object' && f !== null)
+        .map((f) => ({
+            file: String(f.file ?? ''),
+            category: String(f.category ?? ''),
+            confidence: (['high', 'medium', 'low'].includes(String(f.confidence))
+                ? String(f.confidence)
+                : 'high') as 'high' | 'medium' | 'low',
+        }))
+        .filter((f) => f.file.length > 0);
+    const verdict = obj.verdict === 'holds' || obj.verdict === 'flawed' ? obj.verdict : null;
+    return { findings, verdict };
+}
+
+type Arm = 'legacy' | 'load_bearing';
+type Vendor = 'anthropic' | 'openai';
+const ARMS: readonly Arm[] = ['legacy', 'load_bearing'];
+const VENDORS: readonly Vendor[] = ['anthropic', 'openai'];
+
+/** fixtureId → arm → vendor → response */
+type Reviews = Record<string, Record<Arm, Record<Vendor, ArmResponse>>>;
+
+let _clients: Record<Vendor, ExternalAIClient> | null = null;
+function getClients(): Record<Vendor, ExternalAIClient> {
+    if (!_clients) {
+        _clients = {
+            anthropic: new AnthropicClient({ model: 'claude-sonnet-4-5', api_key: load_anthropic_key() }),
+            openai: new OpenAIClient({ model: 'gpt-4o', api_key: load_openai_key() }),
+        };
+    }
+    return _clients;
+}
+
+async function realReviews(items: CorpusItem[]): Promise<Reviews> {
+    const cs = getClients();
+    const out: Reviews = {};
+    for (const item of items) {
+        const perArm = { legacy: {}, load_bearing: {} } as Reviews[string];
+        out[item.id] = perArm;
+        for (const arm of ARMS) {
+            const prompt = arm === 'legacy' ? legacyPrompt(item) : loadBearingPrompt(item);
+            for (const vendor of VENDORS) {
+                let text = '';
+                try {
+                    const resp = await cs[vendor].ask(SYSTEM_JSON, prompt, 1600);
+                    text = resp.text ?? '';
+                } catch (e) {
+                    process.stderr.write(`  ${vendor} error on ${item.id}/${arm}: ${(e as Error).message}\n`);
+                }
+                const r = parseArmResponse(text);
+                perArm[arm][vendor] = r;
+                process.stderr.write(
+                    `  ${arm} ${item.id} ${vendor}: findings=${String(r.findings.length)} verdict=${r.verdict ?? '-'}\n`,
+                );
+            }
+        }
+    }
+    return out;
+}
+
+/**
+ * Mock reviews for pipeline validation in a chosen direction.
+ * `direction: 'pass'` — load_bearing keeps TP parity with legacy and stays
+ * silent on the controls. `direction: 'fail'` — load_bearing rubber-stamps
+ * (misses defects below the retention floor) so the verdict must read FAIL.
+ */
+function mockReviews(items: CorpusItem[], direction: 'pass' | 'fail'): Reviews {
+    const hit = (i: CorpusItem): Finding[] => [
+        {
+            file: i.ground_truth.defect_files[0] ?? i.files[0]?.path ?? '',
+            category: i.defect_category,
+            confidence: 'high' as const,
+        },
+    ];
+    const fpHit = (i: CorpusItem): Finding[] => [
+        { file: i.files[0]?.path ?? '', category: 'correctness', confidence: 'high' as const },
+    ];
+    const out: Reviews = {};
+    const defects = items.filter((i) => !i.is_clean);
+    const keepIds = new Set(
+        // In 'fail' direction the load_bearing arm catches only half the
+        // defects legacy catches — below the 0.8 retention floor.
+        defects.filter((_, idx) => idx % 2 === 0).map((d) => d.id),
+    );
+    for (const item of items) {
+        const legacyResp: ArmResponse = item.is_clean
+            ? { findings: fpHit(item), verdict: null } // legacy FPs every control (the measured defect)
+            : { findings: hit(item), verdict: null };
+        const lbCatches = item.is_clean ? false : direction === 'pass' || keepIds.has(item.id);
+        const lbResp: ArmResponse = item.is_clean
+            ? { findings: [], verdict: 'holds' }
+            : lbCatches
+              ? { findings: hit(item), verdict: 'flawed' }
+              : { findings: [], verdict: 'holds' };
+        out[item.id] = {
+            legacy: { anthropic: legacyResp, openai: legacyResp },
+            load_bearing: { anthropic: lbResp, openai: lbResp },
+        };
+    }
+    return out;
+}
+
+interface VendorArmScore {
+    tp: number;
+    fp: number;
+    fp_rate: number;
+    incoherent: number;
+    holds_on_clean: number;
+    caught_ids: string[];
+    fp_ids: string[];
+}
+
+interface VendorVerdict {
+    legacy: VendorArmScore;
+    load_bearing: VendorArmScore;
+    tp_retention: number | null;
+    fp_pass: boolean;
+    tp_pass: boolean;
+    promotes: boolean;
+}
+
+function scoreVendor(items: CorpusItem[], reviews: Reviews, vendor: Vendor): VendorVerdict {
+    const defects = items.filter((i) => !i.is_clean);
+    const controls = items.filter((i) => i.is_clean);
+    const armScore = (arm: Arm): VendorArmScore => {
+        const caught: string[] = [];
+        let incoherent = 0;
+        let holdsOnClean = 0;
+        for (const d of defects) {
+            const r = reviews[d.id]?.[arm]?.[vendor] ?? { findings: [], verdict: null };
+            if (caughtDefect(groundTruth(d), r.findings)) caught.push(d.id);
+            if (r.verdict === 'flawed' && r.findings.length === 0) incoherent++;
+        }
+        const fpIds: string[] = [];
+        for (const c of controls) {
+            const r = reviews[c.id]?.[arm]?.[vendor] ?? { findings: [], verdict: null };
+            if (isFalsePositive(groundTruth(c), r.findings)) fpIds.push(c.id);
+            if (r.verdict === 'flawed' && r.findings.length === 0) incoherent++;
+            if (r.verdict === 'holds') holdsOnClean++;
+        }
+        return {
+            tp: caught.length,
+            fp: fpIds.length,
+            fp_rate: controls.length ? fpIds.length / controls.length : 0,
+            incoherent,
+            holds_on_clean: holdsOnClean,
+            caught_ids: caught,
+            fp_ids: fpIds,
+        };
+    };
+    const legacy = armScore('legacy');
+    const load_bearing = armScore('load_bearing');
+    const tp_retention = legacy.tp > 0 ? load_bearing.tp / legacy.tp : null;
+    const fp_pass = load_bearing.fp_rate < FP_CEILING;
+    // A legacy TP of 0 leaves retention undefined. NOT part of the frozen
+    // registration (which is silent on a zero baseline) — a conservative
+    // in-code rule, unexercised in the recorded run (legacy TP was 10 and 5):
+    // retention unshowable against a zero baseline → tp_pass false.
+    const tp_pass = tp_retention !== null && tp_retention >= TP_RETENTION_FLOOR;
+    return { legacy, load_bearing, tp_retention, fp_pass, tp_pass, promotes: fp_pass && tp_pass };
+}
+
+function buildReport(items: CorpusItem[], reviews: Reviews, mode: string): Record<string, unknown> {
+    const perVendor: Record<string, VendorVerdict> = {};
+    for (const vendor of VENDORS) perVendor[vendor] = scoreVendor(items, reviews, vendor);
+    const promotes = VENDORS.every((v) => perVendor[v]?.promotes === true);
+    const detail: Record<string, unknown> = {};
+    for (const item of items) {
+        const perItem: Record<string, unknown> = { is_clean: item.is_clean };
+        for (const arm of ARMS) {
+            for (const vendor of VENDORS) {
+                const r = reviews[item.id]?.[arm]?.[vendor];
+                perItem[`${arm}_${vendor}`] = r
+                    ? { findings: r.findings.length, verdict: r.verdict }
+                    : null;
+            }
+        }
+        detail[item.id] = perItem;
+    }
+    return {
+        mode,
+        corpus: 'internal/bench/adversarial-council/corpus.json',
+        claim: 'critic-protocol-load-bearing-ab (docs/CLAIMS.md, pre-registered 2026-08-09)',
+        protocol:
+            'both arms single-shot per vendor over all 15 items; FP on findings only, identical scorer both arms; verdict secondary; flawed+empty findings = incoherent',
+        thresholds: { fp_ceiling: FP_CEILING, tp_retention_floor: TP_RETENTION_FLOOR },
+        per_vendor: perVendor,
+        verdict: {
+            promotes,
+            direction: promotes ? 'both thresholds met per vendor' : 'at least one threshold missed',
+            default_unchanged: 'legacy stays the default regardless (config critic_protocol)',
+        },
+        detail,
+    };
+}
+
+async function main(argv: string[]): Promise<number> {
+    const mock = argv.includes('--mock');
+    const run = argv.includes('--run');
+    const outIdx = argv.indexOf('--out');
+    const outFile = outIdx >= 0 ? argv[outIdx + 1] : null;
+    if (!mock && !run) {
+        process.stderr.write('usage: bench_critic_protocol (--mock | --run) [--out <file>]\n');
+        return 2;
+    }
+    const items = loadCorpus();
+    if (mock) {
+        // Tripwire (roadmap pre-mortem): the pipeline must discriminate in BOTH
+        // directions before any paid call.
+        const passReport = buildReport(items, mockReviews(items, 'pass'), 'mock-pass');
+        const failReport = buildReport(items, mockReviews(items, 'fail'), 'mock-fail');
+        const passOk = (passReport.verdict as { promotes: boolean }).promotes === true;
+        const failOk = (failReport.verdict as { promotes: boolean }).promotes === false;
+        process.stdout.write(JSON.stringify({ mock_pass: passReport, mock_fail: failReport }, null, 2) + '\n');
+        if (!passOk || !failOk) {
+            process.stderr.write(
+                `mock discrimination FAILED: pass-direction promotes=${String(passOk)}, fail-direction rejects=${String(failOk)} — do NOT run paid calls.\n`,
+            );
+            return 1;
+        }
+        process.stderr.write('mock discrimination OK in both directions.\n');
+        return 0;
+    }
+    const reviews = await realReviews(items);
+    const report = buildReport(items, reviews, 'run');
+    const json = JSON.stringify(report, null, 2) + '\n';
+    if (outFile) fs.writeFileSync(outFile, json);
+    process.stdout.write(json);
+    return 0;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+    void main(process.argv.slice(2)).then((code) => process.exit(code));
+}
+
+export { parseArmResponse, scoreVendor, buildReport, mockReviews, legacyPrompt, loadBearingPrompt };

package/src/scripts/check_branch_freshness.ts

@@ -0,0 +1,255 @@
+#!/usr/bin/env tsx
+/**
+ * Fail when this branch is behind the base it will be merged into — asked of
+ * the REMOTE, not of the local tracking ref.
+ *
+ * WHY THIS EXISTS — measured, not hypothetical.
+ *
+ * `feedback-update-branch-before-push` says: behind target → merge the base in
+ * and re-run the gates, before the push. On 2026-08-08 that obligation was
+ * satisfied in form and missed in substance. The run opened with
+ * `git fetch origin --prune`, branched from `origin/main` at `c0a3630eb`,
+ * worked for roughly ninety minutes, and pushed without fetching again. Two PRs
+ * merged inside that window, one of them shipping the same roadmap phase the
+ * branch was implementing. The PR opened `CONFLICTING`, and a concurrent branch
+ * had already published a different number for the same census.
+ *
+ * The failure is not a forgotten rule. It is a live-state fact read once and
+ * then carried: `direct-answers` Iron Law 2 forbids exactly that for branch and
+ * sync state, and a ninety-minute-old reading is memory, not a check. Nothing
+ * caught it, because nothing looked — `/roadmap:next` screens the remote before
+ * SELECTION, `task preflight` reads the tree, and the session register is
+ * advisory. The obligation was model-carried at the one point where its input
+ * decays fastest.
+ *
+ * THIS GATE ASKS THE REMOTE. A version that compared HEAD against the local
+ * `origin/main` ref would reproduce the very defect it exists to catch: that
+ * ref is exactly the stale reading that caused the incident. So it runs
+ * `git ls-remote`, one network round trip, and compares against the SHA the
+ * server reports right now.
+ *
+ * It never fetches, merges, or rebases for you. Choosing how to catch up is a
+ * git-history decision (`git-history-discipline`), and a gate that rewrites
+ * history to make itself pass is a worse failure than the one it reports.
+ */
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { runGateCli, runSelfTest, type SelfTestCase } from "./_lib/gate_self_test.js";
+import { reportScanned } from "./_lib/scan_scope.js";
+
+const DEFAULT_BASE = "main";
+const SELF_TEST_MIN_CASES = 3;
+const SELF_TEST_MIN_REJECT = 1;
+const SCRIPT_REL = "src/scripts/check_branch_freshness.ts";
+
+function git(args: string[]): string | null {
+  try {
+    return execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/** The SHA the server reports for `<base>` right now — never a tracking ref. */
+export function remoteHead(base: string, remote = "origin"): string | null {
+  const out = git(["ls-remote", "--heads", remote, base]);
+  if (out === null || out === "") {
+    return null;
+  }
+  const sha = out.split(/\s+/)[0];
+  return sha !== undefined && /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+}
+
+/**
+ * Is `sha` already contained in HEAD?
+ *
+ * `merge-base --is-ancestor` needs the object locally. A SHA the server just
+ * reported may not be here yet, which is itself the answer — the branch cannot
+ * contain a commit it has never seen.
+ */
+export function containsCommit(sha: string): boolean | null {
+  if (git(["cat-file", "-e", `${sha}^{commit}`]) === null) {
+    return false;
+  }
+  try {
+    execFileSync("git", ["merge-base", "--is-ancestor", sha, "HEAD"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build a throwaway origin + working clone, and optionally let a SECOND clone
+ * push so the working clone's tracking ref goes stale without it noticing.
+ *
+ * The stale-tracking-ref case is the whole point. A fixture that only advances
+ * the remote via the same clone would leave `origin/main` correct locally, and a
+ * gate reading the tracking ref would pass it — which is exactly the false green
+ * this gate exists to remove.
+ */
+function buildFixture(root: string, opts: { advanceRemote: boolean }): string {
+  const origin = path.join(root, "origin.git");
+  const work = path.join(root, "work");
+  fs.mkdirSync(origin, { recursive: true });
+  const g = (args: string[], at: string): void => {
+    execFileSync("git", args, { cwd: at, stdio: "ignore" });
+  };
+  const write = (at: string, name: string, body: string): void => {
+    fs.writeFileSync(path.join(at, name), body);
+    g(["add", "-A"], at);
+    g(["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-m", name], at);
+  };
+  g(["init", "--bare", "-b", DEFAULT_BASE], origin);
+  g(["init", "-b", DEFAULT_BASE, work], root);
+  g(["remote", "add", "origin", origin], work);
+  write(work, "a.txt", "one");
+  g(["push", "-u", "origin", DEFAULT_BASE], work);
+  g(["checkout", "-b", "feat/x"], work);
+  write(work, "b.txt", "two");
+  if (opts.advanceRemote) {
+    const other = path.join(root, "other");
+    g(["clone", origin, other], root);
+    write(other, "c.txt", "three");
+    g(["push"], other);
+  }
+  return work;
+}
+
+export function selfTest(repoRoot: string): number {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "cbf-selftest-"));
+  const run = (advanceRemote: boolean, onBase: boolean): number => {
+    const dir = fs.mkdtempSync(path.join(root, "case-"));
+    const work = buildFixture(dir, { advanceRemote });
+    if (onBase) {
+      execFileSync("git", ["checkout", DEFAULT_BASE], { cwd: work, stdio: "ignore" });
+    }
+    // The child must not inherit a CI flag, or every case would no-op green.
+    delete process.env["CI"];
+    delete process.env["GITHUB_ACTIONS"];
+    return runGateCli(repoRoot, SCRIPT_REL, ["--quiet"], work);
+  };
+  const cases: SelfTestCase[] = [
+    {
+      name: "a branch whose tracking ref is stale while the remote has moved is REFUSED",
+      expect: "reject",
+      run: () => run(true, false),
+    },
+    {
+      name: "a branch containing the remote base passes",
+      expect: "accept",
+      run: () => run(false, false),
+    },
+    {
+      name: "standing on the base branch itself is a no-op, not a refusal",
+      expect: "accept",
+      run: () => run(false, true),
+    },
+  ];
+  try {
+    return runSelfTest({
+      gate: "check_branch_freshness",
+      cases,
+      minCases: SELF_TEST_MIN_CASES,
+      minRejectCases: SELF_TEST_MIN_REJECT,
+    });
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Publish the scan scope: how many remote base refs this run actually resolved.
+ *
+ * One when the server answered, zero on every path that legitimately has
+ * nothing to ask — each with its reason, because a gate reporting success over
+ * an empty scope is the false green this repo keeps finding, and "there was
+ * nothing to check" and "I checked and it was fine" must not print the same.
+ */
+function scanReport(scanned: number, allowEmpty?: string): void {
+  reportScanned({
+    gate: "check_branch_freshness",
+    scanned,
+    units: "remote base ref(s)",
+    roots: ["origin"],
+    ...(allowEmpty === undefined ? {} : { allowEmpty }),
+  });
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+  if (argv.includes("--self-test")) {
+    return selfTest(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", ".."));
+  }
+  const quiet = argv.includes("--quiet");
+  const baseArg = argv.indexOf("--base");
+  const base = baseArg >= 0 ? (argv[baseArg + 1] ?? DEFAULT_BASE) : DEFAULT_BASE;
+
+  // CI merges or refuses on the server; a second opinion here would be noise.
+  if (process.env["CI"] === "true" || process.env["GITHUB_ACTIONS"] === "true") {
+    scanReport(0, "no-op in CI — the forge owns mergeability, and a second opinion here is noise");
+    return 0;
+  }
+
+  const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]);
+  if (branch === null || branch === "HEAD") {
+    scanReport(0, "detached HEAD — there is no branch whose freshness could be asked");
+    return 0;
+  }
+  if (branch === base) {
+    scanReport(0, `standing on ${base} itself — a branch cannot be behind itself`);
+    return 0;
+  }
+
+  const sha = remoteHead(base);
+  if (sha === null) {
+    // Loud, not silent. An offline run has not verified the invariant, and a
+    // gate that passes on an invariant it never evaluated is the false green
+    // this repo keeps finding.
+    scanReport(0, `origin/${base} unreachable — reported NOT VERIFIED rather than green`);
+    process.stdout.write(
+      `check_branch_freshness: could not reach origin/${base} — NOT VERIFIED (offline?). ` +
+        "Re-run before pushing.\n",
+    );
+    return 0;
+  }
+
+  scanReport(1);
+  if (containsCommit(sha) === true) {
+    if (!quiet) {
+      process.stdout.write(`✅  branch is current with origin/${base} (${sha.slice(0, 9)})` + "\n");
+    }
+    return 0;
+  }
+
+  console.error(`❌  branch is BEHIND origin/${base} — the remote is at ${sha.slice(0, 9)}.`);
+  console.error("");
+  console.error("    Pushing now opens a PR that may conflict, and worse: another branch");
+  console.error("    may already have shipped what this one is implementing.");
+  console.error("");
+  console.error(`    git fetch origin && git merge origin/${base}`);
+  console.error("    then re-run the gates before pushing.");
+  console.error("");
+  console.error(
+    "    This gate asks the REMOTE, not your tracking ref — a fetch from earlier in",
+  );
+  console.error("    the session is a memory, not a check (direct-answers Iron Law 2).");
+  return 1;
+}
+
+const invokedDirectly = ((): boolean => {
+  const entry = process.argv[1];
+  if (entry === undefined) return false;
+  try {
+    return fs.realpathSync(path.resolve(entry)) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+
+if (invokedDirectly) {
+  process.exit(main());
+}