@event4u/agent-config 16.0.0 → 16.2.0

package/src/scripts/_lib/host_env_write.ts

@@ -0,0 +1,111 @@
+/**
+ * The only host environment variables this package will ever write.
+ *
+ * WHY ITS OWN MODULE. One place owns the question "which host variable may this
+ * package write", and the answer is a two-row allow table rather than a rule
+ * applied at a call site. `install.ts` imports it; nothing else writes host env.
+ * The move out of `install.ts` also keeps that file, already far over its size
+ * cap, from paying for this feature — the same reason the doctor's
+ * network-posture block moved into its own module.
+ *
+ * THE GUARANTEE IS THE SHAPE, not a check. Both traffic variables —
+ * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` and `DISABLE_AUTOUPDATER` — reach
+ * the host's update-disabled resolver, the blanket one as its THIRD RUNG
+ * (measured on Claude Code 2.1.284, `docs/setup/host-traffic-environment.md`).
+ * A writer able to express either could disable a consumer's security updates.
+ * Owner-decided 2026-09-30 that it never may, and an allow table of two holds
+ * that where a deny list of two would have to stay complete as the host grows
+ * more variables.
+ *
+ * Both writable entries are request SIZE caps. Neither suppresses a call, an
+ * update check or a download — they bound how big a request is, never how many.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import * as YAML from 'yaml';
+
+/** The allow table. Two rows, and adding a third is a governance change. */
+export const WRITABLE_HOST_ENV: readonly { readonly variable: string; readonly settingsKey: string }[] = [
+    { variable: 'BASH_MAX_OUTPUT_LENGTH', settingsKey: 'bash_max_output_length' },
+    { variable: 'MAX_MCP_OUTPUT_TOKENS', settingsKey: 'max_mcp_output_tokens' },
+];
+
+/** Where a project's settings document lives, canonical first. */
+const SETTINGS_CANDIDATES: readonly string[][] = [
+    ['agents', 'settings', '.agent-settings.yml'],
+    ['.agent-settings.yml'],
+];
+
+/**
+ * The project settings document, or `null` when there is none to read.
+ *
+ * `null` on an absent or unparseable file rather than `{}`: the caller reads a
+ * key whose ABSENCE means "write nothing", and collapsing an unreadable file to
+ * an empty object would give the same answer as a readable file with the key
+ * unset. Both write nothing, but only one of them is a fact.
+ */
+export function readSettingsDoc(projectRoot: string): unknown | null {
+    for (const parts of SETTINGS_CANDIDATES) {
+        const p = path.join(projectRoot, ...parts);
+        let text: string;
+        try {
+            text = fs.readFileSync(p, 'utf-8');
+        } catch {
+            continue;
+        }
+        let doc: unknown;
+        try {
+            doc = YAML.parse(text, { version: '1.1' });
+        } catch {
+            return null;
+        }
+        return doc === null || doc === undefined || typeof doc !== 'object' ? null : doc;
+    }
+    return null;
+}
+
+/**
+ * The `env` block for the host settings file, or `null` when nothing is set.
+ *
+ * `null` rather than `{}`: an empty object would still be merged into the
+ * consumer's file, leaving an `env: {}` nobody asked for and making "this
+ * package wrote nothing" indistinguishable from "this package wrote a blank".
+ *
+ * A non-integer or non-positive value is IGNORED rather than written. The schema
+ * already refuses it; this branch is for a hand-edited settings file, where
+ * writing a value the host would silently reinterpret is worse than writing none.
+ */
+export function hostEnvBlock(settings: unknown): Record<string, string> | null {
+    const root = settings as Record<string, unknown> | null | undefined;
+    const he = root?.['host_environment'] as Record<string, unknown> | undefined;
+    const caps = he?.['request_size_caps'] as Record<string, unknown> | undefined;
+    if (caps === undefined) return null;
+    const out: Record<string, string> = {};
+    for (const { variable, settingsKey } of WRITABLE_HOST_ENV) {
+        const v = caps[settingsKey];
+        if (typeof v === 'number' && Number.isInteger(v) && v > 0) out[variable] = String(v);
+    }
+    return Object.keys(out).length === 0 ? null : out;
+}
+
+/**
+ * The host bridge object with the `env` block merged in, if there is one.
+ *
+ * Takes the bridge and returns it rather than being called for its side effect,
+ * so the caller is one expression and `install.ts` — already far over its size
+ * cap — pays one line for this feature instead of six. `announce` is injected
+ * rather than imported: this module has no opinion about how a caller reports,
+ * and importing the installer's logger would make a leaf depend on its consumer.
+ */
+export function withHostEnv(
+    bridge: Record<string, unknown>,
+    projectRoot: string,
+    announce: (msg: string) => void,
+): Record<string, unknown> {
+    const env = hostEnvBlock(readSettingsDoc(projectRoot));
+    if (env === null) return bridge;
+    announce(`.claude/settings.json: wrote ${Object.keys(env).join(', ')} (request-size caps)`);
+    return { ...bridge, env };
+}

package/src/scripts/_lib/json_python_parity.ts

@@ -0,0 +1,127 @@
+/**
+ * `json.dumps` byte-parity helpers — the emit half of the ADR-200 port.
+ *
+ * The retired Python installer wrote every JSON artefact through
+ * `json.dumps(..., ensure_ascii=False)`, and the port's contract is
+ * byte-identical output, not merely equivalent JSON. `JSON.stringify` does not
+ * satisfy it: it escapes nothing above `\u001f` the same way, renders `NaN` /
+ * `Infinity` as `null` rather than as Python's bare tokens, and offers no
+ * separator control for the compact NDJSON form. So the three dump shapes the
+ * installer needs are written out here, mirroring CPython's encoder:
+ *
+ * - {@link jsonDumpsIndent} — `json.dumps(data, indent=N, ensure_ascii=False)`
+ *   with `sort_keys=False` (insertion order preserved, as JS object key order
+ *   already matches Python dict order for our string keys);
+ * - {@link jsonDumpsCompact} — `json.dumps(obj, separators=(",", ":"))`;
+ * - {@link jsonStrNoAscii} — the string encoder both build on.
+ *
+ * Sibling of `src/scripts/install.ts`, which is its only caller. It lives here
+ * rather than inline because the dump shapes are pure, total functions of their
+ * input with no installer state — and because `install.ts` is far over the
+ * 1,500-line source ceiling (`check_source_size_budget`), so a self-contained
+ * unit belongs outside it.
+ *
+ * This module is in the installer's bundled import closure
+ * (`npm run build:install-bundle`), so it carries no module-level side effect
+ * and no `process.exit` — see `check_installer_import_purity`.
+ */
+
+export function jsonStrNoAscii(s: string): string {
+    // json.dumps(ensure_ascii=False): escape control chars + " + \, keep >=0x20
+    let out = '"';
+    for (const ch of s) {
+        const code = ch.codePointAt(0) as number;
+        switch (ch) {
+            case '"':
+                out += '\\"';
+                break;
+            case '\\':
+                out += '\\\\';
+                break;
+            case '\n':
+                out += '\\n';
+                break;
+            case '\r':
+                out += '\\r';
+                break;
+            case '\t':
+                out += '\\t';
+                break;
+            case '\b':
+                out += '\\b';
+                break;
+            case '\f':
+                out += '\\f';
+                break;
+            default:
+                if (code < 0x20) {
+                    out += '\\u' + code.toString(16).padStart(4, '0');
+                } else {
+                    out += ch;
+                }
+        }
+    }
+    return out + '"';
+}
+
+function _jsonScalar(value: unknown): string | null {
+    if (value === null || value === undefined) return 'null';
+    if (typeof value === 'boolean') return value ? 'true' : 'false';
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            if (Number.isNaN(value)) return 'NaN';
+            return value > 0 ? 'Infinity' : '-Infinity';
+        }
+        // Our payloads carry only integers; render as-is.
+        return String(value);
+    }
+    if (typeof value === 'string') return jsonStrNoAscii(value);
+    return null;
+}
+
+function _dumpIndent(value: unknown, indent: number, depth: number): string {
+    const scalar = _jsonScalar(value);
+    if (scalar !== null) return scalar;
+    const pad = ' '.repeat(indent * (depth + 1));
+    const closePad = ' '.repeat(indent * depth);
+    if (Array.isArray(value)) {
+        if (value.length === 0) return '[]';
+        const items = value.map((v) => pad + _dumpIndent(v, indent, depth + 1));
+        return `[\n${items.join(',\n')}\n${closePad}]`;
+    }
+    if (typeof value === 'object' && value !== null) {
+        const obj = value as Record<string, unknown>;
+        const keys = Object.keys(obj);
+        if (keys.length === 0) return '{}';
+        const items = keys.map(
+            (k) => `${pad}${jsonStrNoAscii(k)}: ${_dumpIndent(obj[k], indent, depth + 1)}`,
+        );
+        return `{\n${items.join(',\n')}\n${closePad}}`;
+    }
+    return jsonStrNoAscii(String(value));
+}
+
+/** `json.dumps(data, indent=N, ensure_ascii=False)` (sort_keys=False). */
+export function jsonDumpsIndent(value: unknown, indent: number): string {
+    return _dumpIndent(value, indent, 0);
+}
+
+/** `json.dumps(obj, separators=(",", ":"))` — compact, ensure_ascii=False here. */
+export function jsonDumpsCompact(value: unknown): string {
+    const scalar = _jsonScalar(value);
+    if (scalar !== null) return scalar;
+    if (Array.isArray(value)) {
+        return '[' + value.map((v) => jsonDumpsCompact(v)).join(',') + ']';
+    }
+    if (typeof value === 'object' && value !== null) {
+        const obj = value as Record<string, unknown>;
+        return (
+            '{' +
+            Object.keys(obj)
+                .map((k) => `${jsonStrNoAscii(k)}:${jsonDumpsCompact(obj[k])}`)
+                .join(',') +
+            '}'
+        );
+    }
+    return jsonStrNoAscii(String(value));
+}

package/src/scripts/_lib/lean_projection_mode.ts

@@ -11,11 +11,22 @@
  *
  * So each side supplies the raw string from its own reader and this module
  * decides what it means. Anything unrecognised — absent key, typo, `null`,
- * a non-string — is `eager-all`, today's shipped behaviour: a mode nobody can
- * spell must never silently thin the standing corpus.
+ * a non-string — is `eager-all`: the parser fallback, which is NOT the value
+ * the template ships (see the type below), because a mode nobody can spell
+ * must never silently thin the standing corpus.
  */
 
-/** The three projection shapes. `eager-all` is the shipped default. */
+/**
+ * The three projection shapes, and the two different defaults they answer to.
+ *
+ * The TEMPLATE default — what a consumer is given — is `delivery` with
+ * `hosts: [claude-code]`, shipped in `src/config/agent-settings.template.yml`
+ * since ADR-267, so on that one host a normal read resolves to `delivery`.
+ * The PARSER FALLBACK — what applies when no value resolves from any layer —
+ * is `eager-all` (`DEFAULT_LEAN_PROJECTION_MODE` below), deliberately not
+ * flipped with the template per ADR-267 decision 4: the template says what was
+ * chosen, the constant says what happens when nothing could be read.
+ */
 export type LeanProjectionMode = 'eager-all' | 'thin' | 'delivery';
 
 export const DEFAULT_LEAN_PROJECTION_MODE: LeanProjectionMode = 'eager-all';

package/src/scripts/_lib/llm_proposer_transport.ts

@@ -37,6 +37,7 @@
  */
 
 import { load_anthropic_key } from '../ai_council/clients.js';
+import { sanitize_text } from './retrieval_sanitize.js';
 import type {
     GenerationRequest,
     GenerationResult,
@@ -140,10 +141,19 @@ export function anthropicGenerator(keyPath: string | null = null): TextGenerator
             );
         }
         const data = (await resp.json()) as AnthropicResponse;
-        const text = (data.content ?? [])
-            .filter((b) => b.type === 'text')
-            .map((b) => b.text ?? '')
-            .join('');
+        // Sanitize AT THE TRANSPORT, which is the choke point and one call site.
+        // A flag every caller has to remember is the instruction-only
+        // enforcement this package diagnoses in itself, and a partially
+        // sanitized world — some callers filtered, some not — is worse than
+        // either end state. The floor is a no-op on ordinary text, so what
+        // changes here is only a response that carries a hidden-instruction
+        // vector; see `docs/contracts/retrieval-read-surfaces.md`.
+        const text = sanitize_text(
+            (data.content ?? [])
+                .filter((b) => b.type === 'text')
+                .map((b) => b.text ?? '')
+                .join(''),
+        );
         // An empty body is returned AS an empty body rather than repaired here.
         // The arm's own output contract refuses it and classifies the refusal;
         // repairing it in the transport would move a decision into the layer

package/src/scripts/_lib/loop_surfaces.ts

@@ -0,0 +1,382 @@
+/**
+ * The loop-surface inventory, and the reach question it exists to answer.
+ *
+ * Why an inventory at all.
+ *
+ * `archive/road-to-wired-instruments.md` closed four instances of one defect —
+ * an instrument this repository built, tested, and then connected to nothing —
+ * one instance at a time, and shipped five hand-written `grep` acceptance
+ * criteria instead of a detector. Two further instances were open the whole
+ * time and nothing in the tree could notice them. This module is the reader
+ * half of the fix: a declared list of loop surfaces and the exported helpers
+ * they are supposed to call, plus the one predicate that says whether a
+ * declared helper is called by anything at all.
+ *
+ * What it is NOT.
+ *
+ * Reader input. Nothing executes from it, no surface changes behaviour because
+ * of it, and there is no runner. That is Risk 3 of the roadmap that introduced
+ * it, stated as a constraint rather than a hope: the moment something
+ * dispatches off this file it has become the loop engine a recorded decision
+ * forbids.
+ *
+ * The reach predicate, and the correction that shaped it.
+ *
+ * The obvious predicate — "no file other than its own imports this export" —
+ * was measured against `loop_guards.ts` and calls nine of its fourteen exports
+ * dead. Most of those are wrong: a helper used by its own neighbours in the
+ * same file is reached every time that file is. So the criterion is
+ * occurrence-based and counts the declaration itself:
+ *
+ *     an export is DEAD when it appears in `src/` exactly once,
+ *     including its own declaration.
+ *
+ * Two is enough, deliberately. A second occurrence anywhere in `src/` means
+ * some production line names it; whether that line sits in the same file or
+ * another one is not a difference this predicate needs to resolve, and
+ * resolving it would mean writing a second import resolver.
+ *
+ * `tests/` is outside `src/` and therefore outside the count by construction —
+ * which is the point. A test-only caller is exactly the state both open
+ * instances are in.
+ *
+ * Why `cap` accepts a markdown anchor as well as a symbol.
+ *
+ * The roadmap step that specified this file asked for `file:symbol` and
+ * "never prose". Reproduced against the tree on 2026-09-13, that is
+ * unsatisfiable for two of the five surfaces and a category error for both:
+ * `verify-repair-loop` and `experiment-loop` are SKILLS, and a skill's bound
+ * is a documented knob, not a TypeScript constant. `grep -rn max_attempts
+ * src/` returns hits only inside the skill's own directory.
+ *
+ * The property that requirement was reaching for is preserved exactly:
+ * a bound must resolve to something that demonstrably EXISTS. So a `.ts`
+ * target must be a defined symbol, a `.md` target must be a literal token
+ * present in that file, and a markdown-bound row must additionally declare
+ * `bound_kind: prose` — the prose-ness is recorded rather than inferred, and
+ * `inventoryVerdict` reports those surfaces as a named set so a prose bound
+ * can never be read as equal to a code one.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { parse as parseYaml } from 'yaml';
+
+export const INVENTORY_REL = 'src/config/loop-surfaces.yaml';
+
+/** Fields every surface row must carry. Order is the order they are reported in. */
+export const SURFACE_FIELDS = [
+    'cap',
+    'no_progress',
+    'success_stop',
+    'checker',
+    'human_gate',
+    'terminal_vocabulary',
+    'production_consumers',
+] as const;
+
+export type SurfaceField = (typeof SURFACE_FIELDS)[number];
+
+/** A loop surface — a thing that iterates under a bound. */
+export interface LoopSurface {
+    id: string;
+    /** `code` or `prose` — which kind of artefact the surface itself is. */
+    kind: string;
+    /** `code` when `cap`/`no_progress` name symbols, `prose` when they name doc anchors. */
+    bound_kind: string;
+    cap: string;
+    no_progress: string;
+    success_stop: string;
+    checker: string;
+    human_gate: string;
+    terminal_vocabulary: string;
+    production_consumers: string[];
+}
+
+/**
+ * An exported helper a surface is meant to call.
+ *
+ * Separated from surfaces because the reach question only applies here: a
+ * surface is reached by being bound (a hook slot, a skill invocation), an
+ * instrument is reached by being called, and only the second is answerable by
+ * counting occurrences of a symbol.
+ */
+export interface LoopInstrument {
+    id: string;
+    file: string;
+    role: string;
+    /** `experimental` exempts it from the reach requirement — with a deadline. */
+    status?: string | undefined;
+    /** ISO `YYYY-MM-DD`. Required under `status: experimental`; a past date reds. */
+    expires?: string | undefined;
+    note?: string | undefined;
+}
+
+export interface Inventory {
+    surfaces: LoopSurface[];
+    instruments: LoopInstrument[];
+}
+
+/** `path/to/file.ts:SYMBOL` or `path/to/file.md:ANCHOR`. */
+const BOUND_TARGET = /^([A-Za-z0-9_./-]+\.(?:ts|js|md)):([A-Za-z_$][A-Za-z0-9_$-]*)$/;
+
+function str(row: Record<string, unknown>, key: string): string {
+    const v = row[key];
+    return v === undefined || v === null ? '' : String(v);
+}
+
+export function readInventory(root: string): Inventory | null {
+    const p = path.join(root, INVENTORY_REL);
+    if (!fs.existsSync(p)) return null;
+    const doc = parseYaml(fs.readFileSync(p, 'utf-8')) as {
+        surfaces?: Record<string, Record<string, unknown>>;
+        instruments?: Record<string, Record<string, unknown>>;
+    } | null;
+
+    const surfaces: LoopSurface[] = [];
+    for (const [id, row] of Object.entries(doc?.surfaces ?? {})) {
+        surfaces.push({
+            id,
+            kind: str(row, 'kind'),
+            bound_kind: str(row, 'bound_kind'),
+            cap: str(row, 'cap'),
+            no_progress: str(row, 'no_progress'),
+            success_stop: str(row, 'success_stop'),
+            checker: str(row, 'checker'),
+            human_gate: str(row, 'human_gate'),
+            terminal_vocabulary: str(row, 'terminal_vocabulary'),
+            production_consumers: Array.isArray(row['production_consumers'])
+                ? (row['production_consumers'] as unknown[]).map(String)
+                : [],
+        });
+    }
+
+    const instruments: LoopInstrument[] = [];
+    for (const [id, row] of Object.entries(doc?.instruments ?? {})) {
+        instruments.push({
+            id,
+            file: str(row, 'file'),
+            role: str(row, 'role'),
+            status: row['status'] === undefined ? undefined : String(row['status']),
+            expires: row['expires'] === undefined ? undefined : String(row['expires']),
+            note: row['note'] === undefined ? undefined : String(row['note']),
+        });
+    }
+
+    surfaces.sort((a, b) => a.id.localeCompare(b.id));
+    instruments.sort((a, b) => a.id.localeCompare(b.id));
+    return { surfaces, instruments };
+}
+
+/** Every `.ts` / `.js` file under `src/`, sorted. Cached per root. */
+const sourceCache = new Map<string, string[]>();
+
+export function sourceFiles(root: string): string[] {
+    const hit = sourceCache.get(root);
+    if (hit !== undefined) return hit;
+    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.sort((a, b) => a.name.localeCompare(b.name))) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (e.name === 'node_modules') continue;
+                walk(full);
+            } else if (e.name.endsWith('.ts') || e.name.endsWith('.js')) {
+                out.push(full);
+            }
+        }
+    };
+    walk(path.join(root, 'src'));
+    sourceCache.set(root, out);
+    return out;
+}
+
+/** Drop the file-list cache. The self-test builds throwaway trees. */
+export function resetSourceCache(): void {
+    sourceCache.clear();
+}
+
+function escapeRe(s: string): string {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * How many times `symbol` occurs anywhere under `src/`, declaration included.
+ *
+ * Word-bounded, so `stallSignal` does not match `stallSignalled`. Deliberately
+ * text-level: a symbol resolver would have to model re-exports, barrel files
+ * and type-only imports to beat this, and would then be a second
+ * implementation of the compiler. The loose version's failure mode is a count
+ * that is too HIGH — reporting a dead export as live, which is the quiet
+ * direction. It never manufactures an accusation.
+ */
+export function occurrences(root: string, symbol: string): number {
+    if (symbol === '') return 0;
+    const re = new RegExp(`\\b${escapeRe(symbol)}\\b`, 'g');
+    let n = 0;
+    for (const f of sourceFiles(root)) {
+        n += (fs.readFileSync(f, 'utf-8').match(re) ?? []).length;
+    }
+    return n;
+}
+
+/** Does `file` DEFINE `symbol` (a `.ts` target) or merely contain it (a `.md` anchor)? */
+export function resolvesTarget(root: string, file: string, token: string): boolean {
+    const p = path.join(root, file);
+    if (!fs.existsSync(p)) return false;
+    const text = fs.readFileSync(p, 'utf-8');
+    const esc = escapeRe(token);
+    if (file.endsWith('.md')) return new RegExp(`\\b${esc}\\b`).test(text);
+    const decl = new RegExp(`\\b(?:const|let|var|function|interface|type|class|enum)\\s+${esc}\\b`);
+    if (decl.test(text)) return true;
+    // Object keys, union members and class fields: `TOKEN:` / `TOKEN(` at line start.
+    return new RegExp(`^\\s*(?:readonly\\s+)?${esc}\\s*[:(]`, 'm').test(text);
+}
+
+export interface ReachFinding {
+    id: string;
+    file: string;
+    /** `dead` · `expired` · `no-expiry` · `bad-status` — why it reds. */
+    reason: string;
+    detail: string;
+}
+
+export interface ShapeFinding {
+    id: string;
+    reason: string;
+    detail: string;
+}
+
+export interface InventoryVerdict {
+    /** Surfaces with a missing field, or a bound that resolves to nothing. */
+    shape: ShapeFinding[];
+    /** Declared instruments with no production consumer and no valid exemption. */
+    reach: ReachFinding[];
+    /** Instruments reported live — the does-not-over-fire evidence. */
+    live: string[];
+    /** Instruments held by a valid, unexpired `experimental` exemption. */
+    exempt: string[];
+    /** Surfaces whose bound is documented prose, not a code symbol. Reported, never red. */
+    proseBound: string[];
+}
+
+/** An instrument is reached when it occurs more than once in `src/`. */
+export const REACH_MINIMUM_OCCURRENCES = 2;
+
+const BOUND_FIELDS = ['cap', 'no_progress'] as const;
+
+function checkSurface(root: string, s: LoopSurface, shape: ShapeFinding[]): void {
+    for (const f of SURFACE_FIELDS) {
+        const v = s[f];
+        const empty = Array.isArray(v) ? v.length === 0 : String(v).trim() === '';
+        if (empty) shape.push({ id: s.id, reason: 'missing-field', detail: `\`${f}\` is empty` });
+    }
+    if (s.bound_kind !== 'code' && s.bound_kind !== 'prose') {
+        shape.push({
+            id: s.id,
+            reason: 'bad-bound-kind',
+            detail: `\`bound_kind: ${s.bound_kind}\` — must be \`code\` or \`prose\``,
+        });
+    }
+    for (const f of BOUND_FIELDS) {
+        const raw = String(s[f]).trim();
+        if (raw === '') continue;
+        const m = BOUND_TARGET.exec(raw);
+        if (m === null) {
+            shape.push({
+                id: s.id,
+                reason: 'not-a-target',
+                detail: `\`${f}: ${raw}\` is not \`path/to/file.{ts,js,md}:TOKEN\``,
+            });
+            continue;
+        }
+        const [, file, token] = m as unknown as [string, string, string];
+        // A markdown bound must SAY it is prose. Undeclared, it would read as a
+        // code bound in every report that aggregates this file.
+        if (file.endsWith('.md') && s.bound_kind !== 'prose') {
+            shape.push({
+                id: s.id,
+                reason: 'undeclared-prose-bound',
+                detail: `\`${f}\` points into ${file} but the row is \`bound_kind: ${s.bound_kind}\``,
+            });
+        }
+        if (!resolvesTarget(root, file, token)) {
+            shape.push({
+                id: s.id,
+                reason: 'unresolved-target',
+                detail: `\`${f}\` names ${token} in ${file}, which does not carry it`,
+            });
+        }
+    }
+}
+
+function checkInstrument(root: string, i: LoopInstrument, day: string, v: InventoryVerdict): void {
+    if (i.status !== undefined && i.status !== 'experimental') {
+        v.reach.push({
+            id: i.id,
+            file: i.file,
+            reason: 'bad-status',
+            detail: `\`status: ${i.status}\` is not a recognised exemption (only \`experimental\`)`,
+        });
+        return;
+    }
+    if (i.status === 'experimental') {
+        const exp = (i.expires ?? '').trim();
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(exp)) {
+            v.reach.push({
+                id: i.id,
+                file: i.file,
+                reason: 'no-expiry',
+                detail: 'an `experimental` exemption needs `expires: YYYY-MM-DD`',
+            });
+            return;
+        }
+        if (exp <= day) {
+            v.reach.push({
+                id: i.id,
+                file: i.file,
+                reason: 'expired',
+                detail: `the \`experimental\` exemption lapsed on ${exp} — decide, or move the date with a reason`,
+            });
+            return;
+        }
+        v.exempt.push(i.id);
+        return;
+    }
+    const n = occurrences(root, i.id);
+    if (n < REACH_MINIMUM_OCCURRENCES) {
+        v.reach.push({
+            id: i.id,
+            file: i.file,
+            reason: 'dead',
+            detail: `occurs ${String(n)}× in src/ (own declaration included) — nothing calls it`,
+        });
+    } else {
+        v.live.push(i.id);
+    }
+}
+
+export function inventoryVerdict(root: string, today = new Date()): InventoryVerdict {
+    const v: InventoryVerdict = { shape: [], reach: [], live: [], exempt: [], proseBound: [] };
+    const inv = readInventory(root);
+    if (inv === null) return v;
+
+    for (const s of inv.surfaces) {
+        checkSurface(root, s, v.shape);
+        if (s.bound_kind === 'prose') v.proseBound.push(s.id);
+    }
+    const day = today.toISOString().slice(0, 10);
+    for (const i of inv.instruments) checkInstrument(root, i, day, v);
+
+    v.live.sort();
+    v.exempt.sort();
+    v.proseBound.sort();
+    return v;
+}