@event4u/agent-config 16.1.0 → 16.2.0

package/src/scripts/report_obligation_writer_split.ts

@@ -0,0 +1,236 @@
+#!/usr/bin/env tsx
+/**
+ * report_obligation_writer_split — which kind of tree wrote the obligation rows.
+ *
+ * WHAT QUESTION THIS ANSWERS, AND WHY IT NEEDED A TOOL.
+ * `obligation-settle-shadow-bar` is pre-registered against the shadow rows under
+ * `agents/runtime/state/obligations/`, and its own clause (7) says that corpus is
+ * one machine's runtime state. Until the rows carried a writer, that sentence was
+ * the ONLY place the fact lived: a reader holding the ledgers could count rows and
+ * could not separate them, so a reading that cleared the floor would have been
+ * quotable as evidence about a population nobody had measured. This prints the
+ * separation, from the rows themselves.
+ *
+ * IT REACHES NO VERDICT, AND THAT IS THE DESIGN. A split is an input to the corpus
+ * decision held in `road-to-an-obligation-row-that-names-its-writer`, not the
+ * decision — the three options there (accept the one-machine corpus and amend the
+ * bar, widen it deliberately, or file the window `resolved-null`) are owner-
+ * reserved, and all three name arming as owner-reserved too. So this exits 0 on
+ * every path, prints counts, and says nothing about whether anything may be armed.
+ * A reporter that graded the corpus would be handing the arming discussion a
+ * verdict wearing a number's clothes.
+ *
+ * `absent` IS REPORTED APART FROM `unknown`, and the distinction is load-bearing.
+ * `unknown` is a row whose writer WAS resolved and came back unresolvable; `absent`
+ * is a row written before the field existed. Folding them together would let the
+ * whole pre-field corpus read as "we looked and could not tell", which is a
+ * stronger claim than "we had not started looking". The ledger's own `parseRows`
+ * maps both to `unknown` — correct for a consumer that only needs a role — so this
+ * reads the JSON directly rather than through it, and uses `isWriterRole` for the
+ * vocabulary so the two cannot drift.
+ *
+ * PRIVACY, at the precision the code holds. Output is counts, plus the SCAN ROOT,
+ * which the caller supplied and which is the one thing a reader needs in order to
+ * know what was measured. Nothing else crosses: no session id, no ledger filename,
+ * no rule id, no timestamp. The scan reads those and keeps none of them.
+ *
+ * WRITES NOTHING. It opens files for reading and creates no directory, not even
+ * the ledger directory it looks for. A missing directory is a reported state, not
+ * a thing to fix.
+ *
+ * Exit: 0 always, except a usage error (1). Advisory — it gates nothing.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { OBLIGATION_STATE_DIR, WRITER_ROLES, isWriterRole } from './_lib/obligations.js';
+
+/** The reported classes: the closed vocabulary, plus the pre-field case. */
+export const REPORTED_CLASSES = [...WRITER_ROLES, 'absent'] as const;
+export type ReportedClass = (typeof REPORTED_CLASSES)[number];
+
+/** The three row arrays a ledger carries, named as the file names them. */
+export const ROW_ARRAYS = ['delivered', 'discharged', 'shadow'] as const;
+export type RowArray = (typeof ROW_ARRAYS)[number];
+
+export type Tally = Record<ReportedClass, number>;
+
+export interface WriterSplit {
+    /** The directory scanned, echoed so a reader knows what was measured. */
+    readonly store: string;
+    /** `false` when the ledger directory does not exist at all. */
+    readonly storeExists: boolean;
+    /** Ledger files opened and parsed. */
+    readonly ledgers: number;
+    /** Files present but unreadable or unparseable — reported, never silently dropped. */
+    readonly unreadable: number;
+    /** Per row array, the split by writer class. */
+    readonly byArray: Record<RowArray, Tally>;
+    /** Every array folded together. */
+    readonly total: Tally;
+}
+
+function emptyTally(): Tally {
+    return { package: 0, consumer: 0, unknown: 0, absent: 0 };
+}
+
+/**
+ * Classify one row's writer field.
+ *
+ * A field that is missing entirely is `absent`. A field that is present but
+ * outside the closed vocabulary is `unknown`, matching `parseRows`: a corrupt
+ * provenance label degrades, it never deletes the record of a real row.
+ */
+export function classifyRow(row: unknown): ReportedClass {
+    if (typeof row !== 'object' || row === null) return 'absent';
+    if (!('writer' in row)) return 'absent';
+    const writer = (row as { writer: unknown }).writer;
+    return isWriterRole(writer) ? writer : 'unknown';
+}
+
+/** Tally one ledger's arrays into an accumulator. */
+function tallyLedger(doc: unknown, into: Record<RowArray, Tally>): void {
+    if (typeof doc !== 'object' || doc === null) return;
+    for (const name of ROW_ARRAYS) {
+        const rows = (doc as Record<string, unknown>)[name];
+        if (!Array.isArray(rows)) continue;
+        for (const row of rows) into[name][classifyRow(row)] += 1;
+    }
+}
+
+/**
+ * Read every ledger under `root` and split its rows by writer class.
+ *
+ * Opens files for reading only. A file that will not parse increments
+ * `unreadable` rather than being skipped in silence — a corpus with unreadable
+ * members is a different corpus from a clean one, and a reader deciding whether
+ * a sample floor is met needs to know which they have.
+ */
+export function readWriterSplit(root: string): WriterSplit {
+    const store = path.join(root, OBLIGATION_STATE_DIR);
+    const byArray: Record<RowArray, Tally> = {
+        delivered: emptyTally(),
+        discharged: emptyTally(),
+        shadow: emptyTally(),
+    };
+
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(store).filter((f) => f.endsWith('.json'));
+    } catch {
+        return { store, storeExists: false, ledgers: 0, unreadable: 0, byArray, total: emptyTally() };
+    }
+
+    let ledgers = 0;
+    let unreadable = 0;
+    for (const entry of entries) {
+        let doc: unknown;
+        try {
+            doc = JSON.parse(fs.readFileSync(path.join(store, entry), 'utf-8'));
+        } catch {
+            unreadable += 1;
+            continue;
+        }
+        ledgers += 1;
+        tallyLedger(doc, byArray);
+    }
+
+    const total = emptyTally();
+    for (const name of ROW_ARRAYS) {
+        for (const cls of REPORTED_CLASSES) total[cls] += byArray[name][cls];
+    }
+    return { store, storeExists: true, ledgers, unreadable, byArray, total };
+}
+
+const sum = (t: Tally): number => REPORTED_CLASSES.reduce((n, c) => n + t[c], 0);
+
+/**
+ * Render the split as text.
+ *
+ * The line a reader is most likely to quote is the shadow row, so it is named
+ * rather than left to be inferred from a table: the pre-registered bar counts
+ * shadow rows and nothing else, and a split over `delivered` answers a question
+ * the bar did not ask.
+ */
+export function render(split: WriterSplit): string {
+    const out: string[] = [];
+    out.push(`scanned: ${split.store}`);
+    if (!split.storeExists) {
+        out.push('  the ledger directory does not exist — nothing was measured.');
+        out.push('  This is not a reading of zero. It is the absence of a corpus.');
+        return `${out.join('\n')}\n`;
+    }
+    out.push(`  ledgers: ${split.ledgers}${split.unreadable > 0 ? `, unreadable: ${split.unreadable}` : ''}`);
+    if (split.ledgers === 0) {
+        out.push('  no ledger files — the directory exists and holds nothing.');
+        return `${out.join('\n')}\n`;
+    }
+
+    const width = Math.max(...ROW_ARRAYS.map((n) => n.length));
+    out.push('');
+    out.push(`${'rows'.padEnd(width)}  ${REPORTED_CLASSES.map((c) => c.padStart(9)).join('')}    total`);
+    for (const name of ROW_ARRAYS) {
+        const t = split.byArray[name];
+        const cells = REPORTED_CLASSES.map((c) => String(t[c]).padStart(9)).join('');
+        out.push(`${name.padEnd(width)}  ${cells}  ${String(sum(t)).padStart(7)}`);
+    }
+    const cells = REPORTED_CLASSES.map((c) => String(split.total[c]).padStart(9)).join('');
+    out.push(`${'all'.padEnd(width)}  ${cells}  ${String(sum(split.total)).padStart(7)}`);
+
+    out.push('');
+    out.push(
+        `shadow rows — the only array the pre-registered bar counts: ${sum(split.byArray.shadow)}`,
+    );
+    out.push(
+        '`absent` is a row written before the writer field existed; `unknown` is a row whose',
+    );
+    out.push('writer was resolved and came back unresolvable. They are not the same reading.');
+    out.push('');
+    out.push('This is a split, not a verdict. Whether the corpus is fit to read the bar off,');
+    out.push('and what follows for the detector, are owner decisions this tool does not make.');
+    return `${out.join('\n')}\n`;
+}
+
+/**
+ * Read one flag's value, refusing a flag whose value is missing.
+ *
+ * A flag present as the last argv element must be a usage error and never a
+ * silent fall back to the default. The same slip in a sibling reporter measured
+ * the DEFAULT corpus while printing what read as a settled number — a confident
+ * figure from a tree nobody asked for is worse than no figure at all.
+ */
+function argValue(argv: string[], flag: string, fallback: string): string {
+    const i = argv.indexOf(flag);
+    if (i === -1) return fallback;
+    const value = argv[i + 1];
+    if (value === undefined || value.startsWith('--')) {
+        process.stderr.write(`report_obligation_writer_split: ${flag} needs a value\n`);
+        process.exit(1);
+    }
+    return value;
+}
+
+export function main(argv: string[]): number {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        process.stdout.write(
+            'usage: report_obligation_writer_split [--root <dir>] [--json]\n\n' +
+                '  --root <dir>  tree whose agents/runtime/state/obligations/ to read (default: cwd)\n' +
+                '  --json        emit the split as JSON instead of text\n\n' +
+                'Read-only. Writes nothing, gates nothing, exits 0.\n',
+        );
+        return 0;
+    }
+    const root = argValue(argv, '--root', process.cwd());
+    const split = readWriterSplit(root);
+    process.stdout.write(argv.includes('--json') ? `${JSON.stringify(split, null, 2)}\n` : render(split));
+    return 0;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(_HERE)) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/report_skill_menu_census.ts

@@ -53,8 +53,21 @@
  * `command-only` and `flow-only` name a CANDIDATE for `user-invocable: false`,
  * never a decision — see the sole-entry limit above.
  *
+ * THE PER-PROFILE MENU, added by `road-to-a-menu-whose-precision-is-measured`
+ * 4.1. `--profile minimal|balanced|full|all` prints the menu byte count each
+ * shipped install profile delivers. Each profile's preset is read from its own
+ * file, and the answer is that all three are equal: no shipped preset declares
+ * a key that selects skills, so each one ships the whole menu.
+ *
+ * The equality note is WITHHELD when any profile carries a key listed in
+ * {@link SKILL_SELECTING_INI_KEYS}, and the key is named instead. That is the
+ * whole falsifiability claim, stated no wider than it holds: the byte count
+ * would not move — nothing here knows what such a key means — but the report
+ * stops asserting a conclusion whose premise has changed.
+ *
  * Usage:
  *     ./scripts-run src/scripts/report_skill_menu_census                # stdout summary
+ *     ./scripts-run src/scripts/report_skill_menu_census --profile all
  *     ./scripts-run src/scripts/report_skill_menu_census --emit         # write the artifact
  *     ./scripts-run src/scripts/report_skill_menu_census --emit --pin <sha>
  *
@@ -313,8 +326,203 @@ function headSha(root: string): string {
     return execFileSync('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf-8' }).trim();
 }
 
+// ── per-profile menu bytes (road-to-a-menu-whose-precision-is-measured 4.1) ──
+
+/** The shipped install presets, mirroring `install.ts` SUPPORTED_PROFILES. */
+export const PROFILES = ['minimal', 'balanced', 'full'] as const;
+export type Profile = (typeof PROFILES)[number];
+
+/**
+ * Preset keys that would narrow the skill menu.
+ *
+ * EMPTY, and the emptiness is the finding rather than a stub. A preset selects
+ * `rule_loading_tier`, `discipline_profile` and `chat_history_frequency`; which
+ * SKILLS are written is decided by `packs:` frontmatter against the active pack
+ * set, which no preset names.
+ *
+ * It is a TRIPWIRE, not a selector, and the distinction is worth stating
+ * plainly because the first version of this comment overclaimed it. Nothing
+ * here knows what such a key would MEAN, so nothing here can apply one: the
+ * byte count would not move. What the list buys is that a preset carrying a
+ * listed key is NAMED in the output and the equality note is withheld — so the
+ * report stops asserting a conclusion whose premise has changed, instead of
+ * printing the same prose over a different tree.
+ */
+export const SKILL_SELECTING_INI_KEYS: readonly string[] = [];
+
+/** Flat `key=value` read of a profile preset; `;` comments and blanks dropped. */
+export function readProfileIni(root: string, profile: Profile): Record<string, string> {
+    const p = path.join(root, 'src', 'config', 'profiles', `${profile}.ini`);
+    const out: Record<string, string> = {};
+    for (const raw of fs.readFileSync(p, 'utf-8').split('\n')) {
+        const line = raw.trim();
+        if (line === '' || line.startsWith(';') || line.startsWith('#') || line.startsWith('[')) continue;
+        const eq = line.indexOf('=');
+        if (eq === -1) continue;
+        out[line.slice(0, eq).trim()] = line.slice(eq + 1).trim();
+    }
+    return out;
+}
+
+export interface ProfileMenu {
+    readonly profile: Profile;
+    /** Skills this profile writes onto the model menu. */
+    readonly menuSkills: number;
+    /** Bytes of `- <name>: <description>\n`, the shape `censusSkillsCatalog` sums. */
+    readonly menuBytes: number;
+    /** chars/4, the estimator the payload budget uses. */
+    readonly tokensEstimate: number;
+    /** `declared_skill_catalogue_tokens` from the preset, or null when absent. */
+    readonly declaredCatalogueTokens: number | null;
+    /** Preset keys found that would narrow the menu. Empty today, by measurement. */
+    readonly selectingKeys: readonly string[];
+}
+
+/**
+ * One profile's menu, computed from its preset plus the skill tree.
+ *
+ * The catalogue LINE is the same shape `preamble_byte_census.censusSkillsCatalog`
+ * sums — `- <name>: <description>\n`. The POPULATION deliberately is not, and the
+ * difference is stated rather than smoothed over: that census sums every
+ * `SKILL.md`, because the payload bucket it feeds is about what the host lists;
+ * this one drops a skill carrying `user-invocable: false` or
+ * `disable-model-invocation: true`, because a menu is what the MODEL may pick
+ * from. Two skills carry such a flag today, so over the same tree and the same
+ * line shape this report reads 311 B below the full-population sum. Expect the
+ * two to differ; a reader who finds them equal has found a defect in one.
+ */
+export function menuForProfile(root: string, profile: Profile): ProfileMenu {
+    const ini = readProfileIni(root, profile);
+    const selectingKeys = SKILL_SELECTING_INI_KEYS.filter((k) => k in ini);
+    const skillsDir = path.join(root, 'src', 'skills');
+    let menuSkills = 0;
+    let menuBytes = 0;
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const skillMd = path.join(skillsDir, entry.name, 'SKILL.md');
+        if (!fs.existsSync(skillMd)) continue;
+        const text = fs.readFileSync(skillMd, 'utf-8');
+        const flags = menuFlags(text);
+        if (flags.userInvocable === false || flags.disableModel === true) continue;
+        const name = /^name:\s*(\S.*?)\s*$/mu.exec(text.slice(0, 4000))?.[1] ?? entry.name;
+        const description = frontmatterDescription(text);
+        menuSkills += 1;
+        menuBytes += `- ${name}: ${description}\n`.length;
+    }
+    const declared = ini['declared_skill_catalogue_tokens'];
+    return {
+        profile,
+        menuSkills,
+        menuBytes,
+        tokensEstimate: Math.round(menuBytes / 4),
+        declaredCatalogueTokens: declared === undefined ? null : Number(declared),
+        selectingKeys,
+    };
+}
+
+/**
+ * The `description:` value, folded lines included.
+ *
+ * A `[^\n]+` capture was measured 17.1 % low elsewhere in this tree because it
+ * truncates every folded multi-line description; this reads to the next
+ * top-level key instead.
+ *
+ * A double-quoted value has its escapes DECODED. Leaving them encoded counted
+ * `\"` as two characters and over-reported the menu by 56 B across 13 skills —
+ * small, but the same class of defect as the 17.1 % one above, and a function
+ * whose docstring cites that fix should not carry a second instance of it.
+ */
+export function frontmatterDescription(text: string): string {
+    if (!text.startsWith('---')) return '';
+    const end = text.indexOf('\n---', 3);
+    if (end === -1) return '';
+    const lines = text.slice(3, end).split('\n');
+    const at = lines.findIndex((l) => /^description:/u.test(l));
+    if (at === -1) return '';
+    const parts = [(lines[at] as string).replace(/^description:\s*/u, '')];
+    for (let i = at + 1; i < lines.length; i += 1) {
+        const l = lines[i] as string;
+        if (/^\S/u.test(l)) break;
+        parts.push(l.trim());
+    }
+    const joined = parts.join(' ').trim();
+    if (joined.length >= 2 && joined.startsWith('"') && joined.endsWith('"')) {
+        return joined.slice(1, -1).replace(/\\(["\\])/gu, '$1');
+    }
+    if (joined.length >= 2 && joined.startsWith("'") && joined.endsWith("'")) {
+        return joined.slice(1, -1).replace(/''/gu, "'");
+    }
+    return joined;
+}
+
+/** Render the per-profile menu table. Returns the lines, so tests read them. */
+export function renderProfileMenus(menus: readonly ProfileMenu[]): string[] {
+    const L: string[] = [];
+    L.push('menu bytes per install profile (name + description, the catalogue shape):');
+    L.push('  profile    skills   menu_bytes   ~tokens   declared');
+    for (const m of menus) {
+        L.push(
+            `  ${m.profile.padEnd(10)} ${String(m.menuSkills).padStart(6)} ` +
+                `${String(m.menuBytes).padStart(12)} ${String(m.tokensEstimate).padStart(9)} ` +
+                `${(m.declaredCatalogueTokens === null ? '—' : String(m.declaredCatalogueTokens)).padStart(10)}`,
+        );
+    }
+    const flagged = menus.filter((m) => m.selectingKeys.length > 0);
+    if (flagged.length > 0) {
+        L.push('');
+        L.push('  A preset declares a key that could select skills, so the equality below is NOT');
+        L.push('  asserted — the premise it rested on has changed. Keys found:');
+        for (const m of flagged) L.push(`    ${m.profile}: ${m.selectingKeys.join(', ')}`);
+        return L;
+    }
+    const distinct = new Set(menus.map((m) => m.menuBytes));
+    if (menus.length > 1 && distinct.size === 1) {
+        L.push('');
+        L.push(
+            '  All profiles report the SAME menu_bytes, and that is a measurement, not a',
+        );
+        L.push(
+            '  placeholder: no preset declares a key that selects skills, so each ships the',
+        );
+        L.push(
+            '  whole menu. The preset chooses which RULES activate; which SKILLS are written',
+        );
+        L.push(
+            '  is decided by `packs:` frontmatter against the active pack set. A menu-bytes',
+        );
+        L.push(
+            '  lever therefore has to move packs or the menu flags — changing profile does',
+        );
+        L.push('  nothing. The three presets already record this in their own comments.');
+    }
+    return L;
+}
+
 export function main(argv: readonly string[]): number {
     const root = REPO_ROOT;
+    const profIdx = argv.indexOf('--profile');
+    if (profIdx !== -1) {
+        const want = argv[profIdx + 1] ?? 'all';
+        const chosen: Profile[] =
+            want === 'all' ? [...PROFILES] : PROFILES.includes(want as Profile) ? [want as Profile] : [];
+        if (chosen.length === 0) {
+            process.stderr.write(
+                `report_skill_menu_census: --profile expects ${PROFILES.join(' | ')} | all, got ${want}\n`,
+            );
+            return 2;
+        }
+        if (argv.includes('--emit')) {
+            // Refused rather than ignored: `--emit` writes the census artifact,
+            // `--profile` prints a table and writes nothing, and silently doing
+            // the second when the caller asked for both is how an artifact goes
+            // un-refreshed without anyone noticing.
+            process.stderr.write('report_skill_menu_census: --profile and --emit are separate runs\n');
+            return 2;
+        }
+        const menus = chosen.map((p) => menuForProfile(root, p));
+        process.stdout.write(`${renderProfileMenus(menus).join('\n')}\n`);
+        return 0;
+    }
     const emit = argv.includes('--emit');
     const pinIdx = argv.indexOf('--pin');
     const pin = pinIdx !== -1 && pinIdx + 1 < argv.length ? (argv[pinIdx + 1] as string) : headSha(root);

package/src/scripts/report_standing_payload_by_host.ts

@@ -156,7 +156,7 @@ export const HOST_SURFACES: readonly HostSurface[] = [
     },
     {
         host: 'codex', surface: '.codex/agent-config.md', perRuleTree: false,
-        writer: 'src/scripts/install.ts:1432',
+        writer: 'src/scripts/install.ts:1431',
         // Scoped to `.codex` rather than the bare filename: nine other lines in
         // `install.ts` write an `agent-config.md` for some other host, so the
         // unscoped anchor would have accepted a drift onto any of them — the

package/src/scripts/roadmap_verify_share.ts

@@ -0,0 +1,213 @@
+#!/usr/bin/env tsx
+/**
+ * The runnable share of `verify:` clauses, per roadmap.
+ *
+ * A `verify:` clause names a command and never names what the command must
+ * produce, so a step can be flipped on a command that cannot fail. Two numbers
+ * say how bad that is, and neither had a producing command before this script:
+ * how many clauses name a COMMAND at all (the runnable share), and how many
+ * name an EXPECTATION (the falsifiable share).
+ *
+ * THIS IS A READER, NOT A GATE. It exits 0 on every corpus, including one where
+ * both shares are zero. That is a property of the reader, not a description of
+ * the tree: measured 2026-09-29, the tree carried 230 clauses, 93 naming a
+ * command and 6 naming an expectation — neither share is zero, and the
+ * commissioning roadmap's claim that the second one was is the first thing this
+ * script refuted. A ratchet needs a false-positive rate and two readings a
+ * quarter apart; it has neither, and a gate that reds all but a handful of
+ * roadmaps at once gets weakened until it finds nothing. What it buys instead
+ * is that the NEXT reading is a delta rather than a re-derivation.
+ *
+ * THE UNIT, stated because the figure is meaningless without it. One unit is
+ * one STEP BLOCK (`- [ ]`, `- [x]`, `- [~]`, `- [-]`, plus its continuation
+ * lines) that carries a `verify:` clause. Not one line: a clause wraps, and a
+ * line count would double-count a wrapped clause and count prose that merely
+ * mentions the token. Step blocks come from `closure_scan`'s own `units()`, so
+ * the two instruments agree on what a step is; that also inherits its
+ * exclusions — fenced code, and the `## Decisions` / `## Blockers` /
+ * `## Kill register` / `## Risk Register` discharge sections, where a mention
+ * of `verify:` is commentary rather than a step's oracle.
+ *
+ * Closed steps are counted. A `[x]` flipped on a clause that could not fail is
+ * the defect in its completed form, and excluding them would report the
+ * backlog as smaller every time someone closed one.
+ *
+ * CLI:
+ *   ./scripts-run src/scripts/roadmap_verify_share
+ *   ./scripts-run src/scripts/roadmap_verify_share --json
+ *   ./scripts-run src/scripts/roadmap_verify_share --root <dir> [--recursive]
+ *
+ * Exit codes: 0 always, except 2 for bad argv or a dead scan root.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { units } from './closure_scan.js';
+import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
+import { parseVerifyClause } from './_lib/verify_clause.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const _PROG = 'roadmap_verify_share';
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const DEFAULT_ROOT = 'agents/roadmaps';
+
+export interface FileShare {
+    readonly file: string;
+    /** Step blocks carrying a `verify:` clause. */
+    readonly clauses: number;
+    /** Of those, the ones naming a command — the runnable share. */
+    readonly withCommand: number;
+    /** Of those, the ones naming an expectation — the falsifiable share. */
+    readonly withExpectation: number;
+}
+
+export interface ShareReport {
+    readonly root: string;
+    readonly files: number;
+    readonly clauses: number;
+    readonly withCommand: number;
+    readonly withExpectation: number;
+    readonly perFile: readonly FileShare[];
+}
+
+/** Count the clauses in one roadmap's text. */
+export function shareOf(file: string, text: string): FileShare {
+    let clauses = 0;
+    let withCommand = 0;
+    let withExpectation = 0;
+    for (const u of units(text.split('\n'))) {
+        if (!u.hasVerify) continue;
+        const clause = parseVerifyClause(u.blockText);
+        if (clause === null) continue;
+        clauses += 1;
+        if (clause.command !== null) withCommand += 1;
+        if (clause.expect !== null) withExpectation += 1;
+    }
+    return { file, clauses, withCommand, withExpectation };
+}
+
+function markdownFiles(root: string, recursive: boolean): string[] {
+    const out: string[] = [];
+    const walk = (dir: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (recursive) walk(full);
+                continue;
+            }
+            if (e.name.endsWith('.md')) out.push(full);
+        }
+    };
+    walk(root);
+    return out.sort();
+}
+
+export function report(rootAbs: string, rootLabel: string, recursive: boolean): ShareReport {
+    const files = markdownFiles(rootAbs, recursive);
+    // A root that resolved to nothing is blindness, not cleanliness: the share
+    // would read as a clean 0/0 and the reader would believe it.
+    assertScanned({ gate: _PROG, scanned: files.length, units: 'roadmap(s)', roots: [rootLabel] });
+    const perFile = files
+        .map((f) => shareOf(path.relative(REPO_ROOT, f), fs.readFileSync(f, 'utf-8')))
+        .filter((s) => s.clauses > 0);
+    return {
+        root: rootLabel,
+        files: files.length,
+        clauses: perFile.reduce((n, s) => n + s.clauses, 0),
+        withCommand: perFile.reduce((n, s) => n + s.withCommand, 0),
+        withExpectation: perFile.reduce((n, s) => n + s.withExpectation, 0),
+        perFile,
+    };
+}
+
+function pct(n: number, of: number): string {
+    return of === 0 ? 'n/a' : `${((n / of) * 100).toFixed(1)}%`;
+}
+
+export function render(r: ShareReport): string {
+    const lines: string[] = [];
+    lines.push(`root: ${r.root}`);
+    lines.push(`roadmaps scanned: ${String(r.files)}`);
+    lines.push(`verify clauses: ${String(r.clauses)}`);
+    lines.push(`  naming a command:     ${String(r.withCommand)} (${pct(r.withCommand, r.clauses)})`);
+    lines.push(`  naming an expectation: ${String(r.withExpectation)} (${pct(r.withExpectation, r.clauses)})`);
+    lines.push('');
+    lines.push('| roadmap | clauses | command | expectation |');
+    lines.push('|---|---:|---:|---:|');
+    for (const s of r.perFile) {
+        lines.push(
+            `| \`${path.basename(s.file)}\` | ${String(s.clauses)} | ${String(s.withCommand)} | ${String(s.withExpectation)} |`,
+        );
+    }
+    return lines.join('\n') + '\n';
+}
+
+function _usage(): string {
+    return (
+        `usage: ${_PROG} [-h] [--json] [--root <dir>] [--recursive]\n\n` +
+        `Report the runnable and falsifiable share of \`verify:\` clauses. Gates nothing.\n`
+    );
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    let json = false;
+    let recursive = false;
+    let root = DEFAULT_ROOT;
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i] as string;
+        if (a === '-h' || a === '--help') {
+            process.stdout.write(_usage());
+            return 0;
+        } else if (a === '--json') json = true;
+        else if (a === '--recursive') recursive = true;
+        else if (a === '--root') {
+            const next = args[i + 1];
+            if (next === undefined) {
+                process.stderr.write(`${_usage()}${_PROG}: error: --root needs a directory\n`);
+                return 2;
+            }
+            root = next;
+            i += 1;
+        } else {
+            process.stderr.write(`${_usage()}${_PROG}: error: unrecognized arguments: ${a}\n`);
+            return 2;
+        }
+    }
+
+    const rootAbs = path.isAbsolute(root) ? root : path.join(REPO_ROOT, root);
+    let r: ShareReport;
+    try {
+        r = report(rootAbs, root, recursive);
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
+
+    process.stdout.write(json ? JSON.stringify(r, null, 2) + '\n' : render(r));
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (!process.argv[1]) return false;
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exitCode = main();
+}