@event4u/agent-config 9.6.0 → 9.7.0

package/src/scripts/bench_adversarial_council.ts

@@ -0,0 +1,292 @@
+/**
+ * Two-stage residual-detection benchmark runner for the adversarial-council
+ * finding-coverage claim (ADR-122, road-to-adversarial-council-benchmark,
+ * design: docs/design/adversarial-council-eval.md).
+ *
+ * Protocol (documented here so the verdict is reproducible; 2 working providers
+ * — anthropic + openai — so the design is adapted to isolate panel VALUE without
+ * a structural-zero artifact):
+ *
+ *   Stage 1 — define the residual. BOTH providers review the 12 defect fixtures
+ *   under a NEUTRAL review prompt. Residual R = defects that NEITHER neutral pass
+ *   caught (the judge-survivable pool: it survived a strong 2-vendor first read).
+ *
+ *   Stage 2 — single skeptic vs cross-vendor panel, on R + the clean controls,
+ *   under an ADVERSARIAL SKEPTIC prompt (the shipped Mode-9 posture):
+ *     - single_judge  = anthropic-skeptic alone.
+ *     - panel         = reconciled union of {anthropic, openai} skeptics.
+ *   Because panel ⊇ single, lift ≥ 0 and measures the MARGINAL value the
+ *   second vendor adds at a fixed skeptic posture — exactly "does a cross-vendor
+ *   panel out-find a single skeptic on the residual, at no-worse FP".
+ *
+ *   evaluateCouncilBench applies the LOCKED dual threshold → backed | honest-null.
+ *
+ * Limitation (recorded honestly): with 2 vendors this isolates the 2nd-vendor
+ * marginal contribution, not an N-vendor scaling curve. gemini/xai are stubbed
+ * or disabled in this CLI build.
+ *
+ * `--mock` runs the whole pipeline on canned responses (no spend) to pre-validate
+ * parsing + residual + scoring + gate in BOTH directions. `--run` fires the real
+ * paid cross-vendor calls (maintainer spend-gated).
+ */
+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 { evaluateCouncilBench, type CouncilBenchInputs } from './_lib/adversarial_council_gate.js';
+import {
+    caughtDefect,
+    isFalsePositive,
+    recall,
+    fpRate,
+    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');
+const SINGLE_SKEPTIC = 'anthropic'; // the single-judge baseline in stage 2
+
+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 JSON_SHAPE =
+    '{"findings":[{"file":"<file path>","category":"<defect category>","confidence":"high|medium|low","summary":"<one line>"}]}';
+function neutralPrompt(item: CorpusItem): string {
+    return [
+        'You are a senior code reviewer. Review the TypeScript below for REAL defects and report only genuine bugs you are confident about. If it is correct, report an empty findings array — do not invent problems.',
+        `Respond with STRICT JSON only, exactly: ${JSON_SHAPE}`,
+        '',
+        codeBlock(item),
+    ].join('\n');
+}
+function skepticPrompt(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: ${JSON_SHAPE}`,
+        '',
+        codeBlock(item),
+    ].join('\n');
+}
+
+function parseFindings(text: string): Finding[] {
+    if (!text) return [];
+    const start = text.indexOf('{');
+    if (start < 0) return [];
+    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 [];
+    try {
+        const obj = JSON.parse(text.slice(start, end + 1)) as { findings?: unknown };
+        const arr = Array.isArray(obj.findings) ? obj.findings : [];
+        return 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);
+    } catch {
+        return [];
+    }
+}
+
+type Reviews = Record<string, Record<string, Finding[]>>; // fixtureId → member → findings
+
+// Direct, INDEPENDENT client calls — NOT council_cli. The council `run`/`debate`
+// transport imposes multi-round peer-review with cross-member visibility and
+// returns prose ("## Round 2 … Reviewer A"), which (a) violates the claim's
+// independent-skeptic requirement and (b) defeats JSON parsing. We call each
+// provider's client once, in isolation, with a strict-JSON system prompt.
+const SYSTEM_JSON =
+    'You are a code reviewer. Output ONLY one JSON object — no prose, no markdown, no code fences. ' +
+    'Shape exactly: {"findings":[{"file":"<path>","category":"<category>","confidence":"high|medium|low","summary":"<one line>"}]}. ' +
+    'If the code is correct, output {"findings":[]}. Do not include any text before or after the JSON object.';
+
+let _clients: Record<string, ExternalAIClient> | null = null;
+function getClients(): Record<string, 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 directReview(item: CorpusItem, userPrompt: string): Promise<Record<string, Finding[]>> {
+    const cs = getClients();
+    const out: Record<string, Finding[]> = {};
+    for (const [name, client] of Object.entries(cs)) {
+        let text = '';
+        try {
+            const resp = await client.ask(SYSTEM_JSON, userPrompt, 1200);
+            text = resp.text ?? '';
+        } catch (e) {
+            process.stderr.write(`  ${name} error on ${item.id}: ${(e as Error).message}\n`);
+        }
+        out[name] = parseFindings(text);
+    }
+    return out;
+}
+
+interface Passes {
+    neutral: Reviews; // defect fixtures only
+    skeptic: Reviews; // residual + controls
+    residualIds: string[];
+}
+
+async function realPasses(items: CorpusItem[]): Promise<Passes> {
+    const defects = items.filter((i) => !i.is_clean);
+    const controls = items.filter((i) => i.is_clean);
+    const neutral: Reviews = {};
+    process.stderr.write('stage 1 (neutral, independent per vendor) over 12 defects…\n');
+    for (const d of defects) {
+        neutral[d.id] = await directReview(d, neutralPrompt(d));
+        process.stderr.write(`  neutral ${d.id}: ${Object.entries(neutral[d.id] ?? {}).map(([m, f]) => `${m}=${f.length}`).join(' ')}\n`);
+    }
+    const residual = defects.filter((d) => !Object.values(neutral[d.id] ?? {}).flat().some((f) => caughtDefect(groundTruth(d), [f])));
+    process.stderr.write(`residual (missed by BOTH neutral passes): ${residual.map((r) => r.id).join(', ') || '(none)'}\n`);
+    const skeptic: Reviews = {};
+    process.stderr.write('stage 2 (adversarial skeptic, independent per vendor) over residual + controls…\n');
+    for (const item of [...residual, ...controls]) {
+        skeptic[item.id] = await directReview(item, skepticPrompt(item));
+        process.stderr.write(`  skeptic ${item.id}: ${Object.entries(skeptic[item.id] ?? {}).map(([m, f]) => `${m}=${f.length}`).join(' ')}\n`);
+    }
+    return { neutral, skeptic, residualIds: residual.map((r) => r.id) };
+}
+
+function mockPasses(items: CorpusItem[]): Passes {
+    // Deterministic proof that the pipeline discriminates: neutral 2-vendor pass
+    // catches the "easier" defects; a hard residual survives; the skeptic panel
+    // then recovers more of the residual than a single skeptic, at controlled FP.
+    const defects = items.filter((i) => !i.is_clean);
+    const controls = items.filter((i) => i.is_clean);
+    const neutralCatch = new Set(['sec-01', 'sec-02', 'inv-01', 'inv-02', 'state-03', 'mfi-01']); // 6 caught neutrally
+    // residual = the other 6: sec-03, inv-03, state-01, state-02, mfi-02, mfi-03
+    const anthropicSkepticCatch = new Set(['sec-03', 'state-01']); // single skeptic recovers 2/6
+    const openaiSkepticExtra = new Set(['inv-03', 'mfi-02', 'mfi-03']); // openai adds 3 more → panel 5/6
+    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 neutral: Reviews = {};
+    for (const d of defects) neutral[d.id] = { anthropic: neutralCatch.has(d.id) ? hit(d) : [], openai: [] };
+    const skeptic: Reviews = {};
+    const residual = defects.filter((d) => !neutralCatch.has(d.id));
+    for (const d of residual) {
+        skeptic[d.id] = {
+            anthropic: anthropicSkepticCatch.has(d.id) ? hit(d) : [],
+            openai: openaiSkepticExtra.has(d.id) ? hit(d) : [],
+        };
+    }
+    for (const c of controls)
+        skeptic[c.id] = { anthropic: [], openai: c.id === 'clean-02' ? [{ file: c.files[0]?.path ?? '', category: 'correctness', confidence: 'high' }] : [] };
+    return { neutral, skeptic, residualIds: residual.map((r) => r.id) };
+}
+
+function scorePasses(items: CorpusItem[], p: Passes): { inputs: CouncilBenchInputs; detail: Record<string, unknown> } {
+    const byId = new Map(items.map((i) => [i.id, i]));
+    const residual = p.residualIds.map((id) => byId.get(id)!);
+    const controls = items.filter((i) => i.is_clean);
+
+    const singleCaught: Record<string, boolean> = {};
+    const panelCaught: Record<string, boolean> = {};
+    for (const d of residual) {
+        const gt = groundTruth(d);
+        singleCaught[d.id] = caughtDefect(gt, p.skeptic[d.id]?.[SINGLE_SKEPTIC] ?? []);
+        panelCaught[d.id] = caughtDefect(gt, Object.values(p.skeptic[d.id] ?? {}).flat());
+    }
+    const singleFp: Record<string, boolean> = {};
+    const panelFp: Record<string, boolean> = {};
+    for (const c of controls) {
+        const gt = groundTruth(c);
+        singleFp[c.id] = isFalsePositive(gt, p.skeptic[c.id]?.[SINGLE_SKEPTIC] ?? []);
+        panelFp[c.id] = isFalsePositive(gt, Object.values(p.skeptic[c.id] ?? {}).flat());
+    }
+    const inputs: CouncilBenchInputs = {
+        single_judge_residual_recall: recall(singleCaught),
+        panel_residual_recall: recall(panelCaught),
+        single_judge_fp_rate: fpRate(singleFp),
+        panel_fp_rate: fpRate(panelFp),
+        fp_noise_margin: 1 / 3,
+    };
+    const detail = {
+        total_defects: items.filter((i) => !i.is_clean).length,
+        residual_ids: p.residualIds,
+        residual_size: residual.length,
+        single_skeptic: SINGLE_SKEPTIC,
+        single_residual_caught: Object.entries(singleCaught).filter(([, v]) => v).map(([k]) => k),
+        panel_residual_caught: Object.entries(panelCaught).filter(([, v]) => v).map(([k]) => k),
+        single_fp: Object.entries(singleFp).filter(([, v]) => v).map(([k]) => k),
+        panel_fp: Object.entries(panelFp).filter(([, v]) => v).map(([k]) => k),
+    };
+    return { inputs, detail };
+}
+
+async function main(argv: string[]): Promise<number> {
+    const mock = argv.includes('--mock');
+    const run = argv.includes('--run');
+    if (!mock && !run) {
+        process.stderr.write('usage: bench_adversarial_council (--mock | --run)\n');
+        return 2;
+    }
+    const items = loadCorpus();
+    const passes = mock ? mockPasses(items) : await realPasses(items);
+    const { inputs, detail } = scorePasses(items, passes);
+    const verdict = evaluateCouncilBench(inputs);
+    const report = {
+        mode: mock ? 'mock' : 'run',
+        corpus: 'internal/bench/adversarial-council/corpus.json',
+        protocol:
+            'stage1 2-vendor neutral → residual (missed by both); stage2 single skeptic (anthropic) vs cross-vendor panel union on residual; FP on clean controls',
+        inputs,
+        detail,
+        verdict,
+    };
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    return 0;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+    void main(process.argv.slice(2)).then((code) => process.exit(code));
+}
+
+export { parseFindings, scorePasses, main };

package/src/scripts/check_no_new_legacy_path.ts

@@ -24,6 +24,7 @@
  *   - src/scripts/_lib/agent_src.py        (the LEGACY_SRC constant)
  *   - src/scripts/check_references.py       (forbidden-substring detector)
  *   - src/scripts/check_condensed_paths.py  (forbidden-substring detector)
+ *   - src/scripts/check_source_pointer_freshness.ts (forbidden-substring detector)
  *
  * Faithful-twin rule (Python→TypeScript migration): a `*.ts` file is also
  * exempt when a same-stem `*.py` sibling exists AND already contains the
@@ -50,6 +51,7 @@ const EXEMPT: ReadonlySet<string> = new Set([
     'src/scripts/check_references.py',
     'src/scripts/check_condensed_paths.py',
     'src/scripts/check_no_new_legacy_path.py', // this file documents the literal
+    'src/scripts/check_source_pointer_freshness.ts', // forbidden-substring detector for the legacy tree
 ]);
 
 type TwinCheck = (curFile: string) => boolean;

package/src/scripts/check_source_pointer_freshness.ts

@@ -0,0 +1,165 @@
+#!/usr/bin/env tsx
+/**
+ * check_source_pointer_freshness — fail when an AUTHORING artifact asserts a
+ * RETIRED source-of-truth pointer as the current one.
+ *
+ * The doc-follows-code discipline (rule: downstream-changes § Doc-Impact;
+ * skill: agent-docs-writing § Doc-Impact) is a behavioral obligation. This is
+ * its deterministic backstop for the one drift class a plain script CAN catch
+ * without semantics: a doc that still names the retired `.agent-src.uncondensed/`
+ * tree as the source of truth after the source moved to `src/` (ADR-051).
+ *
+ * Scope is deliberately narrow (council 2026-07-21, do-not-build list): an
+ * explicit allowlist of the authoring files that MAKE a source-of-truth claim,
+ * not a whole-tree sweep — a gate that fires on every commit and gets
+ * routinely overridden is worse than none. Historical mentions (ADRs under
+ * docs/decisions/, archived roadmaps) are out of scope by construction; a
+ * genuinely-historical line inside an allowlisted file is exempted with an
+ * inline `<!-- pointer-freshness: historical -->` marker.
+ *
+ * Extend AUTHORING_FILES as the broader `.agent-src.uncondensed` cleanup lands
+ * (186 files still carry the token; see road-to-doc-follows-code Phase 4/5
+ * follow-up).
+ *
+ * Exit codes: 0 = clean, 1 = a retired pointer in an allowlisted authoring
+ * file, 2 = usage / self-test failure.
+ *
+ * Usage:
+ *     tsx src/scripts/check_source_pointer_freshness.ts [--json] [--selftest]
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+// parents[2] of src/scripts/<file> is the repo root.
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+// Authoring files that assert WHERE the source of truth lives. Each must NOT
+// name the retired `.agent-src.uncondensed/` tree as current. Extend as the
+// broader cleanup lands.
+const AUTHORING_FILES: readonly string[] = [
+    'src/agent-src/README.md',
+    'src/skills/agents-md-thin-root/SKILL.md',
+];
+
+// Retired source-of-truth pointer. Matches both the bare token and the older
+// monorepo-prefixed form `packages/core/.agent-src.uncondensed/`.
+const RETIRED_POINTER = /\.agent-src\.uncondensed\//;
+
+// A line carrying this marker is a deliberate historical reference — exempt.
+const HISTORICAL_MARKER = '<!-- pointer-freshness: historical -->';
+
+interface Hit {
+    file: string;
+    line: number;
+    text: string;
+}
+
+function _scanFile(rel: string): Hit[] {
+    const abs = path.join(ROOT, rel);
+    let text: string;
+    try {
+        if (!fs.statSync(abs).isFile()) {
+            return [];
+        }
+        text = fs.readFileSync(abs, 'utf-8');
+    } catch {
+        // A missing allowlisted file is a config drift in itself — surface it.
+        return [{ file: rel, line: 0, text: '(allowlisted authoring file not found)' }];
+    }
+    const hits: Hit[] = [];
+    const lines = text.split('\n');
+    for (let idx = 0; idx < lines.length; idx += 1) {
+        const line = lines[idx] as string;
+        if (line.includes(HISTORICAL_MARKER)) {
+            continue;
+        }
+        if (RETIRED_POINTER.test(line)) {
+            hits.push({ file: rel, line: idx + 1, text: line.trim().slice(0, 160) });
+        }
+    }
+    return hits;
+}
+
+/** Deterministic self-check of the matcher — no filesystem, no network. */
+function _selftest(): number {
+    const stale = 'The source of truth is `.agent-src.uncondensed/`. Edit there.';
+    const monorepo = 'Editing `packages/core/.agent-src.uncondensed/templates/AGENTS.md`.';
+    const clean = 'The source of truth is `src/`. Edit there, then run `task sync`.';
+    const historical = `Retired path \`.agent-src.uncondensed/\` ${HISTORICAL_MARKER}`;
+    const cases: Array<[string, boolean]> = [
+        [stale, true],
+        [monorepo, true],
+        [clean, false],
+        [historical, false], // marker suppresses the match at scan time
+    ];
+    let ok = true;
+    for (const [sample, shouldMatch] of cases) {
+        const exempt = sample.includes(HISTORICAL_MARKER);
+        const matched = !exempt && RETIRED_POINTER.test(sample);
+        if (matched !== shouldMatch) {
+            process.stderr.write(`selftest FAIL: ${JSON.stringify(sample)} expected match=${shouldMatch}, got ${matched}\n`);
+            ok = false;
+        }
+    }
+    if (ok) {
+        process.stdout.write('✅  check_source_pointer_freshness selftest passed (4/4).\n');
+        return 0;
+    }
+    return 2;
+}
+
+function main(argv: readonly string[]): number {
+    if (argv.includes('--selftest')) {
+        return _selftest();
+    }
+    const asJson = argv.includes('--json');
+    const hits: Hit[] = [];
+    for (const rel of AUTHORING_FILES) {
+        hits.push(..._scanFile(rel));
+    }
+
+    if (asJson) {
+        process.stdout.write(JSON.stringify({ ok: hits.length === 0, hits }, null, 2) + '\n');
+    } else if (hits.length > 0) {
+        process.stdout.write(`❌  ${hits.length} retired source-of-truth pointer(s) in authoring files:\n\n`);
+        for (const h of hits) {
+            process.stdout.write(`  ${h.file}:${h.line}  ${h.text}\n`);
+        }
+        process.stdout.write(
+            '\nThese name the retired `.agent-src.uncondensed/` tree as the source of\n' +
+                'truth. The source of truth is `src/` (ADR-051, rule: source-of-truth).\n' +
+                'Fix the pointer, or mark a genuinely-historical line with\n' +
+                `\`${HISTORICAL_MARKER}\`. See rule: downstream-changes § Doc-Impact.\n`,
+        );
+    } else {
+        process.stdout.write('✅  No retired source-of-truth pointers in authoring files.\n');
+    }
+    return hits.length > 0 ? 1 : 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main(process.argv.slice(2)));
+}
+
+export { main, _scanFile, _selftest, AUTHORING_FILES, RETIRED_POINTER, HISTORICAL_MARKER };

package/src/scripts/hooks/dispatch_hook.ts

@@ -35,6 +35,7 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { parse as parseYaml } from "yaml";
 
+import { hardenedSpawnEnv } from "../_lib/spawn_env.js";
 import {
   atomic_write_json,
   feedback_dir,
@@ -500,7 +501,10 @@ function _run_concern(concern: ConcernDef, envelope: JsonObject): RunResult {
   // Pass the package root so concerns can locate package-shipped
   // distributed content (ADR-020 global-only consumers carry no
   // project-local copy). REPO_ROOT is the dispatcher's own resolved root.
-  const concern_env = { ...process.env, AGENT_CONFIG_PACKAGE_ROOT: REPO_ROOT };
+  // Consumer-runtime concern dispatch: scrub code-execution-injection env
+  // vectors (loader / git-config / NODE_OPTIONS / …) before spawning each
+  // concern, then set the package-root marker as an explicit override.
+  const concern_env = hardenedSpawnEnv({ AGENT_CONFIG_PACKAGE_ROOT: REPO_ROOT });
 
   const started = performance.now();
   const { command, args: spawnArgs } = _resolve_tsx_invocation(script, cmd.slice(1));

package/src/scripts/lint_readme_serial_comma.ts

@@ -0,0 +1,169 @@
+#!/usr/bin/env tsx
+/**
+ * CI guard for the no-serial-comma house style in README.md prose.
+ *
+ * House style: prose never puts a comma directly before a final "and" / "or"
+ * (no Oxford / serial comma). `skills, commands and rules` — NOT
+ * `skills, commands, and rules`. README.md is the public claim surface for a
+ * package whose whole pitch is "every headline claim is machine-checked", so a
+ * drifting comma style in the copy is the same class of defect as a drifting
+ * number: this guard turns a one-off copy fix into a permanent build gate.
+ *
+ * Prose only. Fenced code, inline `backtick` spans, HTML comments (claim
+ * markers), URLs, and Markdown table rows are masked before matching so the
+ * guard never trips on code, data, or link syntax.
+ *
+ * Exit codes: 0 clean · 1 violation found / README missing.
+ */
+
+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 README = 'README.md';
+
+// A comma, whitespace, then a final coordinating conjunction as a whole word.
+const SERIAL_COMMA = /,[ \t]+(and|or)\b/gi;
+
+/** Python str.splitlines() — drops the trailing empty element. */
+function _splitlines(text: string): string[] {
+    if (text === '') {
+        return [];
+    }
+    const normalised = text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    const parts = normalised.split('\n');
+    if (parts[parts.length - 1] === '') {
+        parts.pop();
+    }
+    return parts;
+}
+
+/**
+ * Return per-line content with everything that is not prose masked out.
+ *
+ * Order matters: HTML comments and fenced regions blank the whole line; on a
+ * surviving prose line we then blank inline backtick spans, URLs, and — for a
+ * Markdown table row — the whole line, so a `, and` inside code, a link, or a
+ * data cell never counts as a style violation.
+ */
+function _stripNoise(lines: string[]): string[] {
+    const urlRe = /https?:\/\/\S+|\(\.[\w./-]+\)/g;
+    const backtickRe = /`[^`]*`/g;
+    const cleaned: string[] = [];
+    let inFence = false;
+    let inHtml = false;
+    for (const raw of lines) {
+        const line = raw;
+        if (line.includes('<!--') && !line.includes('-->')) {
+            inHtml = true;
+        }
+        if (inHtml) {
+            cleaned.push('');
+            if (line.includes('-->')) {
+                inHtml = false;
+            }
+            continue;
+        }
+        const stripped = line.trim();
+        if (stripped.startsWith('```')) {
+            inFence = !inFence;
+            cleaned.push('');
+            continue;
+        }
+        if (inFence) {
+            cleaned.push('');
+            continue;
+        }
+        // Single-line HTML comment (e.g. a claim marker) — blank it.
+        let content = line.replace(/<!--[\s\S]*?-->/g, ' ');
+        // Markdown table row — data, not prose.
+        if (content.trim().startsWith('|')) {
+            cleaned.push('');
+            continue;
+        }
+        // Mask code spans / URLs with a word-char placeholder (not a space):
+        // a space would let a `code`-span sitting between a list comma and the
+        // final "and" / "or" collapse into a phantom ", or" (the first list
+        // comma is legitimate — only a comma *directly* before and/or counts).
+        content = content.replace(backtickRe, 'x').replace(urlRe, 'x');
+        cleaned.push(content);
+    }
+    return cleaned;
+}
+
+interface Hit {
+    line: number;
+    match: string;
+}
+
+function collect_hits(text: string): Hit[] {
+    const lines = _stripNoise(_splitlines(text));
+    const hits: Hit[] = [];
+    lines.forEach((content, idx) => {
+        SERIAL_COMMA.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = SERIAL_COMMA.exec(content)) !== null) {
+            hits.push({ line: idx + 1, match: m[0].trim() });
+            if (m.index === SERIAL_COMMA.lastIndex) {
+                SERIAL_COMMA.lastIndex += 1;
+            }
+        }
+    });
+    return hits;
+}
+
+function main(): number {
+    const quiet = process.argv.slice(2).includes('--quiet');
+    if (!fs.existsSync(README)) {
+        process.stderr.write(`error: ${README} not found\n`);
+        return 1;
+    }
+
+    const hits = collect_hits(fs.readFileSync(README, 'utf-8'));
+
+    if (hits.length > 0) {
+        process.stdout.write(
+            `FAIL  ${README}: ${hits.length} serial-comma violation(s) in prose ` +
+                `(house style: no comma before a final "and" / "or").\n`,
+        );
+        for (const { line, match } of hits) {
+            const lineStr = String(line).padStart(4, ' ');
+            process.stdout.write(`  L${lineStr}  -> "${match}"\n`);
+        }
+        process.stdout.write('\nFix: drop the comma before the final "and" / "or".\n');
+        return 1;
+    }
+
+    if (!quiet) {
+        process.stdout.write(`OK    ${README}: no serial-comma violations in prose.\n`);
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (installed `.augment/` projection, or macOS
+    // /var → /private/var temp dirs) makes the raw URLs differ. Compare
+    // realpaths so the entry guard still fires under a symlink.
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export { README, SERIAL_COMMA, collect_hits, main };