@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/report_consumer_gate_reach.ts

@@ -0,0 +1,233 @@
+#!/usr/bin/env tsx
+/**
+ * How many of this package's gates run on a CONSUMER's machine.
+ *
+ * A gate here is a top-level `src/scripts/` module named `check_*`, `lint_*` or
+ * `audit_*` — the same prefix census `ls src/scripts | grep -cE` returns, minus
+ * the allowlist data files and test files that census also counts. Most of them
+ * run only in this repository's CI. This report names the ones a consumer's
+ * install can actually execute, so a figure about "consumer-path gates" is a
+ * reading rather than a recollection.
+ *
+ * REACHABLE means statically reachable from an entry point a consumer runs:
+ *
+ *   - the hook dispatcher entry and every `script:` the hook manifest binds;
+ *   - the node CLI entry, every delegated `src/scripts/_cli/cmd_*.ts` verb, the
+ *     installer and the MCP server;
+ *   - every `src/**` `.ts` path the bash dispatcher names literally.
+ *
+ * Edges are relative value imports (static and dynamic) plus a literal
+ * `src/scripts/<gate>.ts` string inside a reached module, which is how a module
+ * spawns a gate as a child process. Type-only imports are not edges: they are
+ * erased before anything runs.
+ *
+ * What this does NOT see: a gate a consumer runs by typing its path by hand, and
+ * a spawn whose path is assembled at runtime. Both make the figure a LOWER bound
+ * on reach through a supported surface, never a census of what a determined
+ * consumer could execute. Named `report_` because it publishes a reading and
+ * gates nothing — whether the figure becomes a ratchet is the open
+ * `consumer-gate-denominator` blocker, not this script's decision.
+ *
+ * Inputs:  --root DIR (default: this repository) · --json
+ * Exit 0 with a reading; 1 when an entry point the reading depends on is absent,
+ * because a count over a tree with no dispatcher is not a reading.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import * as YAML from 'yaml';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+
+export const GATE_PREFIX_RE = /^(check_|lint_|audit_)/;
+export const HOOK_MANIFEST = 'src/scripts/hook_manifest.yaml';
+export const BASH_DISPATCHER = 'src/scripts/_dispatch.bash';
+
+/** Entry points that must exist for the reading to mean anything. */
+export const FIXED_ENTRIES: readonly string[] = [
+    'src/scripts/hooks/dispatch_entry.ts',
+    'src/cli/agent-config.ts',
+    'src/scripts/install.ts',
+    'src/scripts/mcp_server/__main__.ts',
+];
+const REQUIRED_ENTRIES: readonly string[] = ['src/scripts/hooks/dispatch_entry.ts', HOOK_MANIFEST];
+
+export interface Reading {
+    /** Every top-level `src/scripts/` entry with a gate prefix, data files included. */
+    prefixEntries: number;
+    /** Gate modules: `.ts`, not a test. */
+    gates: string[];
+    /** Gate modules statically reachable from a consumer entry point. */
+    reachable: string[];
+    /** Entry points the walk started from, repo-relative. */
+    entries: string[];
+}
+
+function strip(source: string): string {
+    return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:'"`])\/\/.*$/gm, '$1');
+}
+
+/** Relative VALUE specifiers: static imports, re-exports, side-effect and dynamic imports. */
+export function valueSpecifiers(source: string): string[] {
+    const s = strip(source);
+    const out: string[] = [];
+    const staticRe = /\b(?:import|export)\s+(?!type\b)(?:[\s\S]*?\bfrom\s*)?['"](\.{1,2}\/[^'"]+)['"]/g;
+    const dynamicRe = /\bimport\(\s*['"](\.{1,2}\/[^'"]+)['"]\s*\)/g;
+    for (const re of [staticRe, dynamicRe]) {
+        let m: RegExpExecArray | null;
+        while ((m = re.exec(s)) !== null) {
+            if (m[1] !== undefined) out.push(m[1]);
+        }
+    }
+    return out;
+}
+
+/** Literal `src/scripts/<gate>.ts` paths — the spawn edge. */
+export function spawnedGatePaths(source: string): string[] {
+    const out: string[] = [];
+    const re = /src\/scripts\/((?:check|lint|audit)_[A-Za-z0-9_]+)(?:\.ts)?\b/g;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(source)) !== null) out.push(`src/scripts/${m[1] as string}.ts`);
+    return out;
+}
+
+function resolveSpec(root: string, fromRel: string, spec: string): string | null {
+    const base = path.posix.join(path.posix.dirname(fromRel), spec);
+    for (const c of [base.replace(/\.js$/, '.ts'), base, `${base}.ts`, `${base}/index.ts`]) {
+        const norm = path.posix.normalize(c);
+        const abs = path.join(root, norm);
+        if (norm.endsWith('.ts') && fs.existsSync(abs) && fs.statSync(abs).isFile()) return norm;
+    }
+    return null;
+}
+
+function manifestScripts(root: string): string[] {
+    const doc = YAML.parse(fs.readFileSync(path.join(root, HOOK_MANIFEST), 'utf8')) as unknown;
+    const out = new Set<string>();
+    const visit = (v: unknown): void => {
+        if (Array.isArray(v)) {
+            v.forEach(visit);
+        } else if (v !== null && typeof v === 'object') {
+            for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+                if (k === 'script' && typeof val === 'string' && val.endsWith('.ts')) out.add(val);
+                else visit(val);
+            }
+        }
+    };
+    visit(doc);
+    return [...out].sort();
+}
+
+function bashNamedSources(root: string): string[] {
+    const abs = path.join(root, BASH_DISPATCHER);
+    if (!fs.existsSync(abs)) return [];
+    const text = fs.readFileSync(abs, 'utf8');
+    return [...new Set(text.match(/\bsrc\/[A-Za-z0-9_/.-]+\.ts\b/g) ?? [])].sort();
+}
+
+function delegatedVerbs(root: string): string[] {
+    const dir = path.join(root, 'src/scripts/_cli');
+    if (!fs.existsSync(dir)) return [];
+    return fs
+        .readdirSync(dir)
+        .filter((f) => /^cmd_.*\.ts$/.test(f) && !f.endsWith('.test.ts'))
+        .map((f) => `src/scripts/_cli/${f}`)
+        .sort();
+}
+
+export function listGates(root: string): { prefixEntries: number; gates: string[] } {
+    const names = fs.readdirSync(path.join(root, 'src/scripts')).filter((n) => GATE_PREFIX_RE.test(n));
+    const gates = names
+        .filter((n) => n.endsWith('.ts') && !n.endsWith('.test.ts'))
+        .map((n) => `src/scripts/${n}`)
+        .sort();
+    return { prefixEntries: names.length, gates };
+}
+
+export function read(root: string): Reading {
+    for (const req of REQUIRED_ENTRIES) {
+        if (!fs.existsSync(path.join(root, req))) {
+            throw new Error(`no ${req} under ${root}`);
+        }
+    }
+    const entries = [
+        ...new Set([
+            ...FIXED_ENTRIES,
+            ...manifestScripts(root),
+            ...delegatedVerbs(root),
+            ...bashNamedSources(root),
+        ]),
+    ]
+        .filter((e) => fs.existsSync(path.join(root, e)))
+        .sort();
+    const { prefixEntries, gates } = listGates(root);
+    const gateSet = new Set(gates);
+    const visited = new Set<string>();
+    const queue = [...entries];
+    while (queue.length > 0) {
+        const rel = queue.shift() as string;
+        if (visited.has(rel)) continue;
+        visited.add(rel);
+        const source = fs.readFileSync(path.join(root, rel), 'utf8');
+        for (const spec of valueSpecifiers(source)) {
+            const target = resolveSpec(root, rel, spec);
+            if (target !== null && !visited.has(target)) queue.push(target);
+        }
+        for (const g of spawnedGatePaths(strip(source))) {
+            if (gateSet.has(g) && !visited.has(g)) queue.push(g);
+        }
+    }
+    return { prefixEntries, gates, reachable: gates.filter((g) => visited.has(g)), entries };
+}
+
+export function render(r: Reading): string[] {
+    const lines = [
+        `prefix entries under src/scripts/: ${r.prefixEntries}`,
+        `gate modules (.ts, not a test):    ${r.gates.length}`,
+        `reachable from a consumer entry:   ${r.reachable.length} (${r.entries.length} entry point(s) walked)`,
+        '',
+    ];
+    for (const g of r.reachable) lines.push(`  ${g}`);
+    return lines;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let root = REPO;
+    let json = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === '--root') {
+            root = path.resolve(argv[i + 1] ?? root);
+            i += 1;
+        } else if (argv[i] === '--json') {
+            json = true;
+        }
+    }
+    let reading: Reading;
+    try {
+        reading = read(root);
+    } catch (e) {
+        process.stderr.write(`report_consumer_gate_reach: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+    const out = json
+        ? JSON.stringify(
+              {
+                  prefix_entries: reading.prefixEntries,
+                  gates: reading.gates.length,
+                  reachable: reading.reachable,
+                  entries: reading.entries.length,
+              },
+              null,
+              2,
+          )
+        : render(reading).join('\n');
+    process.stdout.write(`${out}\n`);
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main());
+}

package/src/scripts/report_merge_gate_load.ts

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+/**
+ * How much the merge danger gate puts on the owner — a reader, not a gate.
+ *
+ *   report_merge_gate_load --pin REV --since ISO [--root DIR] [--out FILE]
+ *                          [--named REV …] [--stdout]
+ *
+ * Replays this checkout's `classify_merge_risk` over every first-parent commit
+ * of `--pin` committed at or after `--since`, each commit judged as the range
+ * `C^..C`, and tallies the merge clearances committed at the pin by outcome.
+ * It writes one markdown table set: commits per verdict, commits per trigger,
+ * the per-day median and maximum for `needs-council` and `needs-owner` over the
+ * days that had a merge, and the hand-offs to the owner by cause.
+ *
+ * Two properties are the point:
+ *
+ *   - **Reproducible.** The output names the resolved pin, the window, the
+ *     command and the classifier's revision, and carries no wall-clock time, so
+ *     a re-run at the same pin, timestamp and classifier revision is
+ *     byte-identical. Days are cut in the offset `--since` names.
+ *   - **Counts and names only.** It reads commit ids, subjects and paths, and
+ *     the clearance records' derived fields; never a prompt or a reply.
+ *
+ * Its caveat, printed in the output: the classifier's path sets are this
+ * checkout's, applied to the whole window — a commit from before a trigger
+ * existed is classed as if it had.
+ *
+ * Exit: 0 always once it ran, 2 on a usage error or an unresolvable pin.
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { CLEARANCE_DIR, parseClearance, type Outcome } from './_lib/merge_clearance_record.js';
+import { readRequiredProviders } from './_lib/ratification_artifact.js';
+import { classifyTarget, type Verdict } from './classify_merge_risk.js';
+
+export const DEFAULT_OUT = 'agents/evidence/analysis/merge-gate-load-2026-10.md';
+
+/** The two pull requests the roadmap names as rows: #2251 and #2256. */
+export const DEFAULT_NAMED = ['82a131feb', 'edd18fea6'];
+
+const POLICY_PATH = 'src/config/ratification-policy.json';
+
+export interface Row {
+    sha: string;
+    day: string;
+    subject: string;
+    verdict: Verdict;
+    triggers: string[];
+}
+
+export interface ClearanceTally {
+    cleared: number;
+    'not-cleared': number;
+    dangerous: number;
+    split: number;
+    unreadable: number;
+}
+
+function git(root: string, args: readonly string[]): { ok: boolean; out: string } {
+    const r = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+    return { ok: r.status === 0, out: typeof r.stdout === 'string' ? r.stdout : '' };
+}
+
+/**
+ * The revision of the checkout the classifier runs from — its path sets are
+ * module code, not read at `--pin` — marked `-dirty` when its source differs.
+ */
+export function classifierRevision(): string {
+    const file = fileURLToPath(new URL('./classify_merge_risk.ts', import.meta.url));
+    const dir = path.dirname(file);
+    const head = git(dir, ['rev-parse', 'HEAD']);
+    if (!head.ok) return 'unknown';
+    const dirty = git(dir, ['status', '--porcelain', '--', file]).out.trim() !== '';
+    return `${head.out.trim()}${dirty ? '-dirty' : ''}`;
+}
+
+/** `+02:00` → 120; `Z` or no offset → 0. */
+export function offsetMinutes(iso: string): number {
+    const m = /([+-])(\d{2}):(\d{2})$/u.exec(iso);
+    if (m === null) return 0;
+    const v = Number(m[2]) * 60 + Number(m[3]);
+    return m[1] === '-' ? -v : v;
+}
+
+/** The calendar day of an instant in a fixed offset. */
+export function dayIn(instantIso: string, offset: number): string {
+    return new Date(Date.parse(instantIso) + offset * 60_000).toISOString().slice(0, 10);
+}
+
+export function median(values: readonly number[]): number {
+    if (values.length === 0) return 0;
+    const s = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(s.length / 2);
+    return s.length % 2 === 1 ? (s[mid] as number) : ((s[mid - 1] as number) + (s[mid] as number)) / 2;
+}
+
+export function replay(root: string, pin: string, since: string): Row[] {
+    const offset = offsetMinutes(since);
+    const log = git(root, ['log', '--first-parent', '--format=%H%x09%P%x09%cI%x09%s', `--since=${since}`, pin]);
+    const rows: Row[] = [];
+    for (const line of log.out.split('\n')) {
+        if (line.trim() === '') continue;
+        const [sha = '', parents = '', when = '', ...rest] = line.split('\t');
+        if (parents.trim() === '') continue;
+        const c = classifyTarget(root, { range: `${sha}^..${sha}` });
+        rows.push({
+            sha,
+            day: dayIn(when, offset),
+            subject: rest.join('\t'),
+            verdict: c.verdict,
+            triggers: [...new Set(c.triggers.map((t) => t.id))].sort(),
+        });
+    }
+    return rows;
+}
+
+/** The clearance records committed at the pin, by derived outcome. */
+export function tallyClearances(root: string, pin: string): ClearanceTally {
+    const tally: ClearanceTally = { cleared: 0, 'not-cleared': 0, dangerous: 0, split: 0, unreadable: 0 };
+    const listed = git(root, ['ls-tree', '--name-only', `${pin}:${CLEARANCE_DIR}`]);
+    if (!listed.ok) return tally;
+    const policy = git(root, ['show', `${pin}:${POLICY_PATH}`]);
+    const required = policy.ok ? readRequiredProviders(policy.out) : null;
+    for (const name of listed.out.split('\n').filter((n) => n.endsWith('.md')).sort()) {
+        const text = git(root, ['show', `${pin}:${CLEARANCE_DIR}/${name}`]);
+        const parsed = text.ok && required !== null ? parseClearance(text.out, required) : ['unreadable'];
+        if (Array.isArray(parsed)) {
+            tally.unreadable += 1;
+            continue;
+        }
+        tally[parsed.outcome as Outcome] += 1;
+        if (parsed.outcome === 'not-cleared' && parsed.seats.some((s) => s.reading === 'clear')) {
+            tally.split += 1;
+        }
+    }
+    return tally;
+}
+
+function cell(s: string): string {
+    return s.replace(/\|/gu, '\\|');
+}
+
+export function render(opts: {
+    pin: string;
+    since: string;
+    rows: readonly Row[];
+    clearances: ClearanceTally;
+    named: readonly string[];
+    command: string;
+    classifier: string;
+}): string {
+    const { pin, since, rows, clearances, named, command, classifier } = opts;
+    const verdicts: Verdict[] = ['routine', 'needs-council', 'needs-owner'];
+    const byVerdict = new Map(verdicts.map((v) => [v, rows.filter((r) => r.verdict === v).length]));
+    const byTrigger = new Map<string, number>();
+    for (const r of rows) for (const t of r.triggers) byTrigger.set(t, (byTrigger.get(t) ?? 0) + 1);
+    const days = [...new Set(rows.map((r) => r.day))].sort();
+    const perDay = (v: Verdict): number[] => days.map((d) => rows.filter((r) => r.day === d && r.verdict === v).length);
+    const council = perDay('needs-council');
+    const owner = perDay('needs-owner');
+    const councilWithoutRecord = Math.max(0, (byVerdict.get('needs-council') ?? 0) - (clearances.cleared + clearances['not-cleared'] + clearances.dangerous));
+    const out: string[] = [
+        '<!-- evidence-type: analysis -->',
+        '',
+        '# Merge danger gate — the owner\'s load',
+        '',
+        `Pin \`${pin}\`, window from \`${since}\`, first-parent history. Produced by`,
+        '',
+        '```bash',
+        command,
+        '```',
+        '',
+        `Classifier revision \`${classifier}\`. A re-run of that command at the same pin, timestamp`,
+        'and classifier revision is byte-identical.',
+        '',
+        '**Caveat.** The classifier is this checkout\'s, so its path sets are applied to',
+        'the whole window: a commit from before a trigger existed is classed as if it',
+        'had. The figures say what the gate *would* hand over today, not what it did.',
+        '',
+        '## Commits per verdict',
+        '',
+        '| Verdict | Commits |',
+        '|---|---|',
+        ...verdicts.map((v) => `| \`${v}\` | ${String(byVerdict.get(v) ?? 0)} |`),
+        `| total | ${String(rows.length)} |`,
+        '',
+        '## Commits per trigger',
+        '',
+        'A commit with several triggers is counted under each.',
+        '',
+        '| Trigger | Commits |',
+        '|---|---|',
+        ...[...byTrigger.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([t, n]) => `| \`${t}\` | ${String(n)} |`),
+        '',
+        '## Per day with a merge',
+        '',
+        `${String(days.length)} day(s) with a first-parent commit, cut in the offset of \`${since}\`.`,
+        '',
+        '| Verdict | Median per day | Maximum | Days with none |',
+        '|---|---|---|---|',
+        `| \`needs-council\` | ${String(median(council))} | ${String(Math.max(0, ...council))} | ${String(council.filter((n) => n === 0).length)} |`,
+        `| \`needs-owner\` | ${String(median(owner))} | ${String(Math.max(0, ...owner))} | ${String(owner.filter((n) => n === 0).length)} |`,
+        '',
+        '## Hand-offs to the owner, by cause',
+        '',
+        '| Cause | Count | Source |',
+        '|---|---|---|',
+        `| \`needs-owner\` | ${String(byVerdict.get('needs-owner') ?? 0)} | replay |`,
+        `| a \`dangerous\` seat | ${String(clearances.dangerous)} | clearance records at the pin |`,
+        `| a split — not cleared with at least one clearing seat | ${String(clearances.split)} | clearance records at the pin |`,
+        `| not cleared, no clearing seat (degraded or no quorum) | ${String(clearances['not-cleared'] - clearances.split)} | clearance records at the pin |`,
+        `| \`needs-council\` with no clearance record — no council on record | ${String(councilWithoutRecord)} | replay minus records |`,
+        '',
+        `Clearance records at the pin: ${String(clearances.cleared)} cleared, ${String(clearances['not-cleared'])} not cleared, ` +
+            `${String(clearances.dangerous)} dangerous, ${String(clearances.unreadable)} unreadable. A \`needs-council\` commit`,
+        'with no record either predates the record (the gate merged on free prose, or',
+        'the owner merged it himself) or was handed over; the replay cannot tell which.',
+        '',
+        '## Named rows',
+        '',
+        '| Commit | Day | Verdict | Triggers | Subject |',
+        '|---|---|---|---|---|',
+    ];
+    for (const n of named) {
+        const r = rows.find((x) => x.sha.startsWith(n));
+        out.push(
+            r === undefined
+                ? `| \`${n}\` | — | not in the window | — | — |`
+                : `| \`${r.sha.slice(0, 9)}\` | ${r.day} | \`${r.verdict}\` | ${r.triggers.map((t) => `\`${t}\``).join(', ') || '—'} | ${cell(r.subject)} |`,
+        );
+    }
+    out.push('');
+    return out.join('\n');
+}
+
+function argValues(argv: readonly string[], flag: string): string[] {
+    const out: string[] = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === flag && argv[i + 1] !== undefined && !(argv[i + 1] as string).startsWith('--')) {
+            out.push(argv[i + 1] as string);
+        }
+    }
+    return out;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2), write: (l: string) => void = (l) => process.stdout.write(`${l}\n`)): number {
+    const pinArg = argValues(argv, '--pin')[0];
+    const since = argValues(argv, '--since')[0];
+    const root = path.resolve(argValues(argv, '--root')[0] ?? process.cwd());
+    const outRel = argValues(argv, '--out')[0] ?? DEFAULT_OUT;
+    const namedArg = argValues(argv, '--named');
+    const named = namedArg.length > 0 ? namedArg : DEFAULT_NAMED;
+    if (pinArg === undefined || since === undefined || Number.isNaN(Date.parse(since))) {
+        write('usage: report_merge_gate_load --pin REV --since ISO [--root DIR] [--out FILE] [--named REV …] [--stdout]');
+        return 2;
+    }
+    const resolved = git(root, ['rev-parse', '--verify', `${pinArg}^{commit}`]);
+    if (!resolved.ok) {
+        write(`report_merge_gate_load: cannot resolve --pin ${pinArg}`);
+        return 2;
+    }
+    const pin = resolved.out.trim();
+    const rows = replay(root, pin, since);
+    const command =
+        `./scripts-run src/scripts/report_merge_gate_load --pin ${pin} --since ${since}` +
+        (namedArg.length > 0 ? namedArg.map((n) => ` --named ${n}`).join('') : '');
+    const body = render({ pin, since, rows, clearances: tallyClearances(root, pin), named, command, classifier: classifierRevision() });
+    if (argv.includes('--stdout')) {
+        process.stdout.write(body);
+        return 0;
+    }
+    const target = path.resolve(root, outRel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, body, 'utf8');
+    write(`report_merge_gate_load: wrote ${outRel} — ${String(rows.length)} commit(s)`);
+    return 0;
+}
+
+function isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/report_project_contract.ts

@@ -0,0 +1,123 @@
+#!/usr/bin/env tsx
+/**
+ * Which of the four contract sections a consumer `AGENTS.md` carries.
+ *
+ * `road-to-a-project-contract-written-down` step 1.3. `/agents:init` asks for
+ * a goal and for no-gos, and an empty answer omits the section rather than
+ * filling it. This is what reports the result: `N of 4`, with the missing ones
+ * named.
+ *
+ * ```
+ * READ-ONLY. IT INFERS NOTHING.
+ * A GOAL THE AGENT COULD GUESS FROM THE DESCRIPTION IS STILL A GOAL NOBODY WROTE.
+ * ```
+ *
+ * That is the whole design constraint. A reader that recognised "our goal is
+ * …" in prose would report a contract the file does not carry, and the count
+ * would become a statement about the reader instead of about the file.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/report_project_contract [AGENTS.md]
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+
+/** Presence of each contract section. Four booleans, never a score. */
+export interface Contract {
+    goal: boolean;
+    noGos: boolean;
+    architecture: boolean;
+    conventions: boolean;
+}
+
+/**
+ * Accepted `##` headings per section — the spellings the consumer guide and
+ * the filled template actually produce, and no others. Matched whole, at
+ * level two only: `### Goal` is a subsection of something else and `## Goals`
+ * is a different word.
+ */
+const HEADINGS: Record<keyof Contract, readonly string[]> = {
+    goal: ['goal'],
+    noGos: ['no-gos', 'no-gos (never do this)'],
+    architecture: ['architecture', 'architecture style', 'architecture & conventions'],
+    conventions: ['conventions', 'coding conventions', 'architecture & conventions'],
+};
+
+/**
+ * The `##` headings of a markdown body, lower-cased, skipping fenced blocks.
+ *
+ * The fence skip is load-bearing rather than tidy: the consumer guide ships
+ * every one of these headings INSIDE a ```markdown fence as copy-in material,
+ * so a reader without it reports the guide as a complete contract.
+ */
+function level2Headings(body: string): string[] {
+    const out: string[] = [];
+    let fence: string | null = null;
+    for (const raw of body.split('\n')) {
+        const line = raw.trimEnd();
+        const open = /^\s*(```+|~~~+)/.exec(line);
+        if (open !== null) {
+            const marker = open[1] as string;
+            if (fence === null) fence = marker[0] as string;
+            else if (marker.startsWith(fence)) fence = null;
+            continue;
+        }
+        if (fence !== null) continue;
+        const m = /^##[ \t]+(.+?)[ \t]*#*$/.exec(line);
+        if (m !== null) out.push((m[1] as string).trim().toLowerCase());
+    }
+    return out;
+}
+
+export function readContract(file: string): Contract {
+    if (!fs.existsSync(file)) throw new Error(`report_project_contract: ${file} not found`);
+    const headings = new Set(level2Headings(fs.readFileSync(file, 'utf8')));
+    const has = (key: keyof Contract): boolean => HEADINGS[key].some((h) => headings.has(h));
+    return { goal: has('goal'), noGos: has('noGos'), architecture: has('architecture'), conventions: has('conventions') };
+}
+
+const LABEL: Record<keyof Contract, string> = {
+    goal: 'goal',
+    noGos: 'no-gos',
+    architecture: 'architecture',
+    conventions: 'conventions',
+};
+
+export function renderReport(c: Contract): string {
+    const keys = Object.keys(LABEL) as (keyof Contract)[];
+    const present = keys.filter((k) => c[k]);
+    const missing = keys.filter((k) => !c[k]);
+    const head = `project contract: ${String(present.length)} of 4`;
+    if (missing.length === 0) return `${head} — goal, no-gos, architecture, conventions.\n`;
+    return (
+        `${head} — missing: ${missing.map((k) => LABEL[k]).join(', ')}.\n` +
+        'Nothing was inferred: a section the file does not carry is reported missing\n' +
+        'rather than guessed from other prose. The copy-in shapes are in\n' +
+        '`consumer-agents-md-guide.md`.\n'
+    );
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    if (argv.includes('-h') || argv.includes('--help')) {
+        process.stdout.write('usage: report_project_contract [AGENTS.md]\n\nRead-only. Prints N of 4.\n');
+        return 0;
+    }
+    const file = path.resolve(argv.find((a) => !a.startsWith('-')) ?? 'AGENTS.md');
+    let contract: Contract;
+    try {
+        contract = readContract(file);
+    } catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    process.stdout.write(renderReport(contract));
+    // Exit 0 whatever the count: this REPORTS, it does not gate. A consumer
+    // who deliberately writes no no-gos has not failed anything.
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === `file://${process.argv[1]}`) {
+    process.exit(main());
+}