@event4u/agent-config 14.10.0 → 14.11.0

package/src/scripts/derive_playbooks.ts

@@ -0,0 +1,406 @@
+/**
+ * derive_playbooks — propose Playbook contexts (ADR-244) from a repository's own
+ * configuration, and refuse to claim more than the tree shows.
+ *
+ * The `grade` field is the whole point. `configured` asserts that every step invokes
+ * something PRESENT IN THE TREE AND SEEN, so this script may only write it when it has
+ * actually resolved the invoked id to a file or a declared task. When it cannot, it
+ * writes `observed` and says which id went unresolved — never `configured` with a
+ * plausible-looking `invokes` list. That is the Class-A rule of `standards-from-config`
+ * applied to procedure: the config IS the standard, and an unresolvable id is not config.
+ *
+ * Scope of the first release, decided in ADR-244 § What a playbook is and not re-litigated
+ * here: THREE resolvable kinds — `package.json#scripts`, `turbo.json` tasks, and
+ * `turbo gen` templates under `turbo/generators/`. Nx generators and Plop are deliberately
+ * out: discovering them needs a consumer binary (`nx list`, `plop --help`), and the
+ * Phase-3 staleness check must run without one. A repo carrying them is reported, so the
+ * omission is visible to its maintainer rather than silent.
+ *
+ * Usage:
+ *   derive_playbooks --root <repo>            # propose, print, write nothing
+ *   derive_playbooks --root <repo> --write    # write into the playbook home
+ *   derive_playbooks --root <repo> --home <d> # override the home
+ *   derive_playbooks --self-test
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * The playbook home. ADR-244 decided a playbook IS a context type, so this is the
+ * contexts home rather than a new directory — the path is not a fresh decision, and the
+ * `--home` flag exists because the ADR calls placement the part of the decision least
+ * likely to survive contact with a consumer.
+ */
+export const DEFAULT_HOME = path.join('agents', 'settings', 'contexts');
+
+export type Grade = 'configured' | 'observed';
+
+export interface PlaybookStep {
+    readonly title: string;
+    /** The id this step invokes — a script name, a turbo task, or `turbo gen <t>`. */
+    readonly invokes: string;
+    /** Where the id was RESOLVED, or null when it could not be. */
+    readonly source_of_truth: string | null;
+    readonly verify: string;
+}
+
+export interface Playbook {
+    readonly slug: string;
+    readonly task: string;
+    readonly scope: string;
+    readonly grade: Grade;
+    readonly steps: readonly PlaybookStep[];
+    /** Ids that could not be resolved. Non-empty forces `observed`. */
+    readonly unresolved: readonly string[];
+}
+
+export interface DeriveReport {
+    readonly playbooks: readonly Playbook[];
+    /** Kinds seen in the tree that this release cannot resolve — reported, never guessed. */
+    readonly out_of_scope: readonly string[];
+}
+
+const readJson = (p: string): Record<string, unknown> | null => {
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8')) as Record<string, unknown>;
+    } catch {
+        return null;
+    }
+};
+
+const asRecord = (v: unknown): Record<string, unknown> =>
+    v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+
+/** Turbo generator templates present in the tree, as `turbo gen <name>` ids. */
+export const discoverTurboGenerators = (root: string): Map<string, string> => {
+    const out = new Map<string, string>();
+    const dir = path.join(root, 'turbo', 'generators');
+    if (!fs.existsSync(dir)) return out;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.set(`turbo gen ${entry.name}`, path.relative(root, full));
+            continue;
+        }
+        // A config file declares generators BY NAME, so read the names it registers
+        // rather than assuming the filename is the generator id. `@turbo/gen` wraps Plop
+        // and the registering call is `plop.setGenerator('component', …)`; `addGenerator`
+        // is accepted too because Plop's own API carries both spellings and a config
+        // written against either must resolve.
+        const text = fs.readFileSync(full, 'utf8');
+        for (const m of text.matchAll(/\.(?:set|add)Generator\(\s*['"]([A-Za-z0-9_-]+)['"]/g)) {
+            out.set(`turbo gen ${m[1]}`, `${path.relative(root, full)} (setGenerator)`);
+        }
+    }
+    return out;
+};
+
+/** Every workspace directory that carries its own `package.json`. */
+export const discoverWorkspaces = (root: string): string[] => {
+    const pkg = readJson(path.join(root, 'package.json'));
+    const globs = Array.isArray(pkg?.workspaces) ? (pkg.workspaces as string[]) : [];
+    const found: string[] = [];
+    for (const g of globs) {
+        if (!g.endsWith('/*')) continue;
+        const base = path.join(root, g.slice(0, -2));
+        if (!fs.existsSync(base)) continue;
+        for (const e of fs.readdirSync(base, { withFileTypes: true })) {
+            if (!e.isDirectory()) continue;
+            const rel = path.join(g.slice(0, -2), e.name);
+            if (fs.existsSync(path.join(root, rel, 'package.json'))) found.push(rel);
+        }
+    }
+    return found.sort();
+};
+
+/**
+ * Resolve one invoked id against the tree. Returns the place it was SEEN, or null.
+ * Null is what forces `observed`, so this function is the honesty gate of the script.
+ */
+export const resolveInvoked = (
+    root: string,
+    id: string,
+    generators: Map<string, string>,
+): string | null => {
+    if (generators.has(id)) return generators.get(id) ?? null;
+
+    const turbo = readJson(path.join(root, 'turbo.json'));
+    if (turbo && Object.prototype.hasOwnProperty.call(asRecord(turbo.tasks), id)) {
+        return 'turbo.json#tasks';
+    }
+    const pkg = readJson(path.join(root, 'package.json'));
+    if (pkg && Object.prototype.hasOwnProperty.call(asRecord(pkg.scripts), id)) {
+        return 'package.json#scripts';
+    }
+    return null;
+};
+
+/** Kinds this release does not resolve, reported so the gap is visible. */
+export const detectOutOfScope = (root: string): string[] => {
+    const out: string[] = [];
+    if (fs.existsSync(path.join(root, 'nx.json'))) out.push('nx generators (needs `nx list`)');
+    for (const n of ['plopfile.js', 'plopfile.mjs', 'plopfile.ts', 'plopfile.cjs']) {
+        if (fs.existsSync(path.join(root, n))) {
+            out.push('plop generators (needs `plop --help`)');
+            break;
+        }
+    }
+    return out;
+};
+
+const scriptBody = (root: string, name: string): string =>
+    String(asRecord(readJson(path.join(root, 'package.json'))?.scripts)[name] ?? '');
+
+/**
+ * A script whose body is a thin wrapper (`turbo gen component`) is a POINTER at the real
+ * procedure, so the playbook must invoke what it points at — otherwise a renamed
+ * generator leaves the playbook green while the procedure is broken, which is exactly the
+ * drift Phase 3 gates.
+ */
+export const unwrapScript = (body: string): string | null => {
+    const m = /^\s*turbo\s+gen\s+([A-Za-z0-9_-]+)/.exec(body);
+    return m ? `turbo gen ${m[1]}` : null;
+};
+
+export const derive = (root: string): DeriveReport => {
+    const generators = discoverTurboGenerators(root);
+    const workspaces = discoverWorkspaces(root);
+    const pkg = readJson(path.join(root, 'package.json'));
+    const scripts = asRecord(pkg?.scripts);
+    const playbooks: Playbook[] = [];
+
+    for (const name of Object.keys(scripts).sort()) {
+        // Only creation-shaped scripts become playbooks. `build` and `test` are one
+        // command each — a playbook for them would be a rename of the script, not a
+        // procedure, and the estate does not need one file per npm script.
+        const noun = /^(?:new|gen|generate|create|scaffold|add)[:-]?(.*)$/.exec(name);
+        if (!noun) continue;
+
+        const wrapped = unwrapScript(scriptBody(root, name));
+        const invoked = wrapped ?? name;
+        const where = resolveInvoked(root, invoked, generators);
+        const subject = (noun[1] || 'artefact').replace(/[^A-Za-z0-9]+/g, '-');
+
+        // `scope` prefers a real workspace whose name matches the subject, so a component
+        // playbook lands on packages/ui rather than claiming the whole repo.
+        const ws = workspaces.find((w) => path.basename(w) === subject) ?? null;
+        const scope =
+            ws ??
+            workspaces.find((w) => subject === 'component' && path.basename(w) === 'ui') ??
+            'repo';
+
+        const step: PlaybookStep = {
+            title: `Run the repository's own generator`,
+            invokes: invoked,
+            source_of_truth: where,
+            verify: where
+                ? `the generator's output appears under \`${scope}\` and the package builds`
+                : `UNRESOLVED — confirm \`${invoked}\` exists before trusting this step`,
+        };
+
+        // The slug carries the workspace when the playbook is workspace-scoped. Two
+        // workspaces may each own a `component` procedure with different conventions, and
+        // one file per subject would silently collapse them into whichever ran last.
+        const noun_slug = subject === 'artefact' ? name.replace(/[^a-z0-9]+/gi, '-') : subject;
+        const slug = scope === 'repo' ? `add-${noun_slug}` : `add-${path.basename(scope)}-${noun_slug}`;
+
+        playbooks.push({
+            slug,
+            task: `Add a new ${subject.replace(/-/g, ' ')} to this repository`,
+            scope,
+            grade: where ? 'configured' : 'observed',
+            steps: [step],
+            unresolved: where ? [] : [invoked],
+        });
+    }
+
+    return { playbooks, out_of_scope: detectOutOfScope(root) };
+};
+
+export const renderPlaybook = (p: Playbook): string => {
+    const lines: string[] = [
+        '---',
+        `task: "${p.task}"`,
+        `scope: "${p.scope}"`,
+        `grade: "${p.grade}"`,
+        'invokes:',
+        ...p.steps.map((s) => `  - "${s.invokes}"`),
+        '---',
+        '',
+        `# Playbook: ${p.task}`,
+        '',
+        '> **This is THIS repository\'s answer, and it outranks a shipped skill.** A shipped',
+        '> skill is a generic answer to a generic question; this file encodes decisions this',
+        '> repository already made.',
+        '',
+        `Grade \`${p.grade}\` — ${
+            p.grade === 'configured'
+                ? 'every step below invokes something seen in the tree, cited per step.'
+                : 'at least one invoked id could NOT be resolved in the tree, so the steps are a hypothesis to confirm, not a procedure to trust.'
+        }`,
+        '',
+        '## Steps',
+        '',
+    ];
+    p.steps.forEach((s, i) => {
+        lines.push(
+            `${i + 1}. **${s.title}** — \`${s.invokes}\``,
+            `   - **Source of truth:** ${s.source_of_truth ?? '**unresolved** — nothing in the tree declares this id'}`,
+            `   - **Verify:** ${s.verify}`,
+            '',
+        );
+    });
+    if (p.unresolved.length > 0) {
+        lines.push(
+            '## Why this is not `configured`',
+            '',
+            `Unresolved: ${p.unresolved.map((u) => `\`${u}\``).join(', ')}. A \`configured\``,
+            'grade asserts every step was seen in the tree; this one was not, and downgrading is',
+            'the honest outcome rather than writing the stronger claim and hoping.',
+            '',
+        );
+    }
+    return lines.join('\n');
+};
+
+// ---------------------------------------------------------------------------
+// Restatement detection — for the per-workspace AGENTS.md contract (1.3).
+//
+// A `packages/<n>/AGENTS.md` is allowed and its primary content is a POINTER LIST to the
+// playbooks scoped to that workspace. The failure it must not become is a second copy of
+// the steps: two files then disagree the first time one is edited, and a reader has no way
+// to tell which one the repository actually follows. So the detector below looks for a
+// playbook step's own text appearing verbatim in a workspace file, and deliberately does
+// NOT flag a pointer AT the playbook — naming the file is the behaviour the contract wants.
+// ---------------------------------------------------------------------------
+
+export interface Restatement {
+    readonly file: string;
+    readonly playbook: string;
+    /** The step text found verbatim in `file`. */
+    readonly step: string;
+}
+
+/** Normalise for comparison: collapse whitespace, drop markdown emphasis and list markers. */
+const normalise = (line: string): string =>
+    line
+        .replace(/^\s*(?:[-*+]|\d+\.)\s+/, '')
+        .replace(/[*_`>]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+
+/** A line that merely POINTS at a playbook — a link, or a path mention. Never a restatement. */
+export const isPointerLine = (line: string): boolean =>
+    /\[[^\]]+\]\([^)]*\.md[^)]*\)/.test(line) || /`[^`]*\.md`/.test(line);
+
+/**
+ * Steps of a playbook that a workspace file restates verbatim.
+ *
+ * The needle is the step's **invoked id**, not its title. Titles are generic by
+ * construction — every generator step in this repository's own fixture is called "Run the
+ * repository's own generator" — so a title match reports the same prose line once per
+ * playbook and tells the reader nothing about WHICH procedure was duplicated. The id is
+ * what makes a line actionable, and duplicating the actionable half is the failure.
+ *
+ * Short lines are skipped: a three-word step and a three-word sentence collide by accident,
+ * and a detector that fires on coincidence teaches its readers to ignore it.
+ */
+export const findRestatedSteps = (
+    playbooks: readonly { readonly slug: string; readonly steps: readonly PlaybookStep[] }[],
+    file: string,
+    text: string,
+    minChars = 12,
+): Restatement[] => {
+    const lines = text.split('\n');
+    const found: Restatement[] = [];
+    for (const p of playbooks) {
+        for (const st of p.steps) {
+            const needle = normalise(st.invokes);
+            if (needle.length < minChars) continue;
+            for (const line of lines) {
+                if (isPointerLine(line)) continue;
+                if (normalise(line).includes(needle)) {
+                    found.push({ file, playbook: p.slug, step: st.title });
+                    break;
+                }
+            }
+        }
+    }
+    return found;
+};
+
+const selfTest = (): number => {
+    let failed = 0;
+    const check = (name: string, cond: boolean): void => {
+        if (!cond) {
+            console.error(`❌  ${name}`);
+            failed += 1;
+        }
+    };
+
+    check('a thin wrapper unwraps to the generator it points at', unwrapScript('turbo gen component') === 'turbo gen component');
+    check('an unrelated script body does not unwrap', unwrapScript('vite build') === null);
+    check('a wrapper with flags still unwraps', unwrapScript('turbo gen workspace --type package') === 'turbo gen workspace');
+
+    check(
+        'a pointer at a playbook is not a restatement',
+        isPointerLine('- See [add a component](../../agents/settings/contexts/add-ui-component.md)'),
+    );
+    check('a prose line is not a pointer', !isPointerLine('Run the repository own generator first'));
+
+    const fixture = path.join('tests', 'fixtures', 'playbooks', 'mono-with-generator');
+    if (fs.existsSync(fixture)) {
+        const r = derive(fixture);
+        const comp = r.playbooks.find((p) => p.slug === 'add-ui-component');
+        check('the fixture yields a component playbook', comp !== undefined);
+        check('it is graded configured', comp?.grade === 'configured');
+        check('it invokes the generator, not the wrapper script', comp?.steps[0]?.invokes === 'turbo gen component');
+        check('its scope is the workspace, not the repo', comp?.scope === path.join('packages', 'ui'));
+        check('build and test produced no playbook', !r.playbooks.some((p) => /build|test/.test(p.slug)));
+    }
+
+    process.stdout.write(
+        failed === 0
+            ? '✅  derive_playbooks: self-test passed\n'
+            : `❌  derive_playbooks: ${failed} failure(s)\n`,
+    );
+    return failed === 0 ? 0 : 1;
+};
+
+const main = (): number => {
+    const argv = process.argv.slice(2);
+    if (argv.includes('--self-test')) return selfTest();
+
+    const arg = (flag: string): string | null => {
+        const i = argv.indexOf(flag);
+        return i >= 0 && i + 1 < argv.length ? String(argv[i + 1]) : null;
+    };
+    const root = arg('--root') ?? '.';
+    const home = arg('--home') ?? path.join(root, DEFAULT_HOME);
+    const write = argv.includes('--write');
+
+    const report = derive(root);
+    if (report.playbooks.length === 0) {
+        process.stdout.write('derive_playbooks: no creation-shaped procedure found — nothing proposed.\n');
+    }
+    for (const p of report.playbooks) {
+        const target = path.join(home, `${p.slug}.md`);
+        process.stdout.write(
+            `${p.grade === 'configured' ? '✅' : '⚠️ '} ${target}  grade=${p.grade}  invokes=[${p.steps.map((s) => s.invokes).join(', ')}]\n`,
+        );
+        if (!write) continue;
+        fs.mkdirSync(home, { recursive: true });
+        fs.writeFileSync(target, renderPlaybook(p), 'utf8');
+    }
+    for (const o of report.out_of_scope) {
+        process.stdout.write(`ℹ️  out of scope for this release: ${o} — reported, not guessed at (ADR-244)\n`);
+    }
+    process.stdout.write(`scanned: ${report.playbooks.length}\n`);
+    return 0;
+};
+
+if (process.argv[1] && /derive_playbooks/.test(process.argv[1])) {
+    process.exit(main());
+}

package/src/scripts/design_slop_rules.test.ts

@@ -93,6 +93,13 @@ const FIXTURES: Record<string, { ext: string; positive: string; negative: string
     positive: "We streamline and empower your robust, world-class workflow.",
     negative: "We cut page load by 40% and remove three steps from checkout.",
   },
+  "slop-cp6-generic-art-direction": {
+    ext: "md",
+    positive: "Build a Three.js hero with floating abstract shapes and a gradient mesh.",
+    negative:
+      "Build a Three.js hero: the assembled chassis rotates, one component " +
+      "highlighted per beat, ending on the price panel.",
+  },
   "slop-cp5-emoji-ui": {
     ext: "html",
     positive: '<h1>🚀 Get Started</h1><button>✅ Track progress</button>',

package/src/scripts/design_slop_rules.ts

@@ -175,6 +175,35 @@ const BUZZWORDS = [
   "leverage",
 ];
 
+/**
+ * Stock render subjects — the default thing an image or 3D model becomes when
+ * nobody decided what it should be about.
+ *
+ * Same mechanism as `BUZZWORDS` (CP2), applied to art direction instead of
+ * prose: each entry names a *visual* that carries no subject matter. The
+ * delete-test is the same one — swap the phrase for the product's actual
+ * subject and the brief says more, which is the proof it said nothing.
+ *
+ * On the `copy` engine deliberately. A CSS engine cannot see subject matter:
+ * `transform: translateZ()` looks identical whether it moves a product or a
+ * glowing orb. The only detectable surface is the brief's own wording.
+ */
+const STOCK_RENDER_SUBJECTS = [
+  "floating abstract shapes",
+  "abstract floating shapes",
+  "gradient mesh",
+  "glowing orb",
+  "glowing orbs",
+  "floating particles",
+  "particle field",
+  "abstract 3d shape",
+  "abstract 3d shapes",
+  "futuristic hud",
+  "digital landscape",
+  "flowing ribbons",
+  "liquid metal blob",
+];
+
 // ---------------------------------------------------------------------------
 // The registry
 // ---------------------------------------------------------------------------
@@ -314,9 +343,15 @@ export const SLOP_RULES: SlopRule[] = [
     catalogId: "T7",
     severity: "P2",
     engines: ["css"],
-    description: "Default AI font (Inter/Roboto/DM Sans/Geist/Space Grotesk/Instrument Serif) without a brand reason",
+    description: "Default AI font (Inter/Roboto/DM Sans/Geist/Space Grotesk/Instrument Serif) without a stated reason",
+    // Register-scoped by the catalog, NOT by this matcher: a CSS text pass carries
+    // no register signal, so the scope lives in the rebuttal rather than in the
+    // gate. `design-modes.md` sanctions a single reliable family in the PRODUCT
+    // register, which makes "product register" a complete reason on its own — the
+    // message names it so a product surface knows the rebuttal without reading two
+    // guidelines. P2 is a rebuttable presumption (see the header), never a block.
     message:
-      "This is a default AI-coding-tool font pick. Declare it in DESIGN.md with a reason, or choose deliberately (T7).",
+      "This is a default AI-coding-tool font pick. Declare it with a reason (T7) — in the product register, \"single reliable family\" IS the reason; state it in DESIGN.md or the surface brief.",
     gated: (ctx) => DEFAULT_FONTS.some((f) => ctx.has(f)),
     detect: ({ lines }) =>
       lines.flatMap((l, i) => {
@@ -416,6 +451,25 @@ export const SLOP_RULES: SlopRule[] = [
       return [];
     },
   },
+  {
+    id: "slop-cp6-generic-art-direction",
+    catalogId: "CP6",
+    severity: "P2",
+    engines: ["copy"],
+    description: "Stock render subject named in a brief instead of the product's own subject matter",
+    message:
+      "This names a default visual, not a subject — swap it for what the product " +
+      "actually shows and the brief says more (CP6).",
+    detect: ({ content, ext }) => {
+      const text = visibleText(content, ext);
+      const lower = text.toLowerCase();
+      const hits = STOCK_RENDER_SUBJECTS.filter((s) => lower.includes(s));
+      if (hits.length === 0) {
+        return [];
+      }
+      return [{ line: 1, snippet: hits.slice(0, 3).join(", ") }];
+    },
+  },
   {
     id: "slop-cp5-emoji-ui",
     catalogId: "CP5",

package/src/scripts/dispatch_r2_reviewer.ts

@@ -39,6 +39,7 @@
  * (bad ref, unreadable file, crash).
  */
 
+import { independenceFields } from './_lib/review_independence.js';
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
@@ -872,6 +873,21 @@ function findingsSkeleton(args: {
     return [
         `# Findings: ${args.slug}`,
         `<!-- completion-review: v1 | reviewed: ${args.reviewedDate} | scope: ${args.scopeHash} | diff: ${args.headSha} | reviewer: r2-fresh-subagent-${args.slug} | prompt_hash: ${args.promptHash} -->`,
+        // SECOND PRODUCER of the independence record — step 2.2 of
+        // road-to-review-independence. Until this line, `self_review_gate.ts` was the
+        // only producer, which is why `check_review_schema` reported `scanned: 1`: a
+        // schema gate with one producer checks that one producer agrees with itself.
+        //
+        // The values are derived, never chosen. `single-member` because this dispatch
+        // has exactly one reviewer; `fresh` because a fresh subagent is what this file
+        // dispatches and is the property the whole artifact exists to carry (the
+        // `reviewer:` field above already says so in prose). Both axes go in, and the
+        // derived pair follows: single-member + fresh is `provisional` / `single-pass`.
+        //
+        // Recording `provisional` on a fresh reviewer is not a downgrade — it is the
+        // honest reading. One reviewer is one reviewer, however uncontaminated; the
+        // family axis is what `accepted` needs and one member cannot supply it.
+        `<!-- ${JSON.stringify({ 'review-independence': independenceFields([`r2-fresh-subagent-${args.slug}`], 'fresh') })} -->`,
         // Set at CREATION, never inferred later: an inferred type reads filename
         // and location, which are exactly the signals that already fail to
         // distinguish an input from a binding. This artifact binds a scope from

package/src/scripts/frontend_corpus_hash.ts

@@ -0,0 +1,116 @@
+/**
+ * frontend_corpus_hash — freeze and verify the frontend benchmark corpus.
+ *
+ * Step 0.2 of `road-to-frontend-power` registers a labelled frontend population
+ * and requires its hash to be committed BEFORE any commit that moves the
+ * detector engine. Risk 6 of that roadmap names the failure the hash guards
+ * against: "One effort ships both the engine and the corpus that scores it."
+ *
+ * The hash is the weaker half of that mitigation and this header says so
+ * plainly: it pins the population against LATER edits, so a number published
+ * against `<digest>` cannot be re-scored on a quietly-different corpus. It says
+ * nothing about who authored the corpus in the first place. The authorship
+ * caveat — and the resulting rule that no detector row may be promoted to
+ * `backed` against this population — lives in
+ * `tests/eval/frontend-corpus/README.md` and is not restated here.
+ *
+ * Determinism: files are enumerated depth-first with a sorted directory walk,
+ * paths are emitted POSIX-style relative to the corpus root, and content is
+ * hashed as raw bytes. `CORPUS.sha256` itself is excluded, so `--write`
+ * followed by `--check` is stable.
+ *
+ * Not a CI gate, deliberately. `tests/eval/frontend-corpus.test.ts` runs the
+ * `--check` path, which is the enforcement surface; a fourth ratchet-tripping
+ * gate script for a manifest one test can assert would cost more than it buys.
+ *
+ * Exit 0 = manifest matches (or was written). Exit 1 = drift.
+ */
+
+import * as crypto from 'node:crypto';
+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 = path.resolve(path.dirname(_HERE), '..', '..');
+export const CORPUS_ROOT = path.join(REPO, 'tests', 'eval', 'frontend-corpus');
+export const MANIFEST_NAME = 'CORPUS.sha256';
+/** Subtrees carrying corpus content. Anything else at the root is prose. */
+const CONTENT_DIRS = ['cases', 'near-miss'] as const;
+
+/** Depth-first, sorted, POSIX-relative file list under `root`. */
+export function walk(root: string, rel = ''): string[] {
+    const abs = rel ? path.join(root, rel) : root;
+    if (!fs.existsSync(abs)) return [];
+    const out: string[] = [];
+    for (const name of fs.readdirSync(abs).sort()) {
+        const childRel = rel ? `${rel}/${name}` : name;
+        if (fs.statSync(path.join(root, childRel)).isDirectory()) out.push(...walk(root, childRel));
+        else if (childRel !== MANIFEST_NAME) out.push(childRel);
+    }
+    return out;
+}
+
+/**
+ * Pure core: the manifest text for a set of (path, bytes) pairs. Pure so the
+ * ordering guarantee is testable without a corpus on disk.
+ */
+export function manifestText(entries: ReadonlyArray<readonly [string, Buffer]>): string {
+    const lines = entries.map(
+        ([p, bytes]) => `${crypto.createHash('sha256').update(bytes).digest('hex')}  ${p}`,
+    );
+    const roll = crypto.createHash('sha256').update(lines.join('\n')).digest('hex');
+    return [
+        '# frontend benchmark corpus — sha256 manifest',
+        '# Produced by src/scripts/frontend_corpus_hash.ts. Do not hand-edit.',
+        `# files: ${lines.length}`,
+        `# corpus: ${roll}`,
+        ...lines,
+        '',
+    ].join('\n');
+}
+
+export function buildManifest(root: string = CORPUS_ROOT): string {
+    const files = CONTENT_DIRS.flatMap((d) => walk(root, d));
+    return manifestText(files.map((p) => [p, fs.readFileSync(path.join(root, p))] as const));
+}
+
+/** The rolling `# corpus:` digest — the value a published number cites. */
+export function corpusDigest(text: string): string | null {
+    return /^# corpus: ([0-9a-f]{64})$/m.exec(text)?.[1] ?? null;
+}
+
+function main(argv: readonly string[]): number {
+    const manifestPath = path.join(CORPUS_ROOT, MANIFEST_NAME);
+    const built = buildManifest();
+    const digest = corpusDigest(built);
+
+    if (argv.includes('--write')) {
+        fs.writeFileSync(manifestPath, built);
+        process.stdout.write(`✅  wrote ${MANIFEST_NAME} — corpus ${digest}\n`);
+        return 0;
+    }
+    if (argv.includes('--check')) {
+        if (!fs.existsSync(manifestPath)) {
+            console.error(`❌  ${MANIFEST_NAME} is missing — run with --write`);
+            return 1;
+        }
+        const onDisk = fs.readFileSync(manifestPath, 'utf8');
+        if (onDisk !== built) {
+            console.error(
+                `❌  corpus drift — manifest says ${corpusDigest(onDisk)}, tree hashes to ${digest}.\n` +
+                    '    A case changed without a rehash. Rerun with --write, and re-publish any\n' +
+                    '    number that cited the old digest rather than carrying it over.',
+            );
+            return 1;
+        }
+        process.stdout.write(`✅  corpus matches manifest — ${digest}\n`);
+        return 0;
+    }
+    process.stdout.write(built);
+    return 0;
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+    process.exit(main(process.argv.slice(2)));
+}