@event4u/agent-config 15.0.0 → 16.1.0

package/src/scripts/check_finding_dispositions.ts

@@ -103,6 +103,121 @@ export interface Ledger {
     findings: LedgerFinding[];
     /** Why the finding set is empty. Required when it is; see empty_ledger_problem. */
     no_findings_reason?: string;
+    // The six integrity fields, declared rather than swept into an index
+    // signature. An index signature would hold them, and would also disable
+    // excess-property and typo detection on the whole type for every consumer:
+    // under `--strict`, `l.findigs` type-checks against a Ledger carrying one.
+    // The set is known and finite, so it costs six lines to keep the type.
+    review_independence?: string;
+    context_relation?: string;
+    acceptance_status?: string;
+    assurance?: string;
+    reviewers?: string[];
+    coverage?: unknown;
+}
+
+/**
+ * Fields the self-review artifact carries that say how much a ledger's silence
+ * is worth, and which `--ingest` used to drop on the floor.
+ *
+ * `check_review_schema` derives `acceptance_status` and `assurance` from
+ * `review_independence` and fails a ledger whose declarations disagree — so an
+ * ingested ledger missing all three was not merely thinner than a hand-written
+ * one, it could not satisfy the gate that reads it. Every committed ledger from
+ * 14.19.0 onward carries the full set; only the ingest path produced files
+ * without it, which is one of the two reasons nobody could run the ingest and
+ * get a green tree.
+ *
+ * Carried rather than recomputed: the producing run is the only thing that
+ * knows how many reviewers answered and how much of the diff they saw, and a
+ * consumer inferring it from the findings would be inventing the integrity
+ * claim the fields exist to record.
+ */
+export const INTEGRITY_FIELDS = [
+    'review_independence',
+    'context_relation',
+    'acceptance_status',
+    'assurance',
+    'reviewers',
+    'coverage',
+] as const;
+
+/**
+ * Merge a self-review artifact into a ledger: new findings by id, the integrity
+ * fields on first write, and — when the review found nothing — the reason that
+ * makes an empty ledger legible.
+ *
+ * MUTATES AND RETURNS THE SAME OBJECT. Callers must use the returned `ledger`
+ * rather than relying on the mutation; the two are the same reference today and
+ * the signature is what a later reader will trust.
+ *
+ * The integrity fields are written only when the ledger does not already carry
+ * them. A second ingest into a ledger a human has since adjudicated must not
+ * silently restate what the earlier run claimed about independence — the first
+ * producing run is the one whose claim the dispositions were filled against.
+ *
+ * The empty-findings case is the one that used to deadlock a release. A clean
+ * review produces `findings: []`, `empty_ledger_problem` refuses an empty
+ * ledger with no `no_findings_reason`, and the release then stopped demanding
+ * dispositions for zero findings — an instruction nobody can follow. An ingest
+ * knows exactly what a clean review means and writes it, with the coverage
+ * numbers as the checkable part rather than a bare assurance.
+ */
+export function merge_ingest(
+    ledger: Ledger,
+    artifact: Record<string, unknown>,
+): { ledger: Ledger; added: number; carried: string[]; reasoned: boolean } {
+    const known = new Set(ledger.findings.map((f) => f.finding_id));
+    let added = 0;
+    for (const f of (artifact['findings'] as LedgerFinding[] | undefined) ?? []) {
+        if (!known.has(f.finding_id)) {
+            ledger.findings.push(f);
+            added++;
+        }
+    }
+    // Assigned through one `unknown` view rather than per field: the six are a
+    // closed set the type declares, and spelling out six near-identical
+    // if-blocks to satisfy the checker would make the set harder to extend than
+    // the type is to read. The view is local to this loop.
+    const carried: string[] = [];
+    const sink = ledger as unknown as Record<string, unknown>;
+    for (const key of INTEGRITY_FIELDS) {
+        if (sink[key] === undefined && artifact[key] !== undefined) {
+            sink[key] = artifact[key];
+            carried.push(key);
+        }
+    }
+    // Only on an artifact that actually SAYS it found nothing. Without the key
+    // check, any JSON object without a `findings` key reads as an empty finding
+    // set, and the sentence below would assert a review that never happened —
+    // into the permanent record, which is worse than the deadlock it replaces.
+    let reasoned = false;
+    const declaresFindings = Array.isArray(artifact['findings']);
+    if (
+        declaresFindings &&
+        ledger.findings.length === 0 &&
+        (ledger.no_findings_reason ?? '').trim() === ''
+    ) {
+        ledger.no_findings_reason = _clean_review_reason(artifact);
+        reasoned = true;
+    }
+    return { ledger, added, carried, reasoned };
+}
+
+/** The `no_findings_reason` an ingest of a zero-findings artifact writes. */
+function _clean_review_reason(artifact: Record<string, unknown>): string {
+    const cov = artifact['coverage'] as Record<string, unknown> | undefined;
+    const reviewed = cov?.['filesReviewed'];
+    const total = cov?.['filesTotal'];
+    const scope =
+        typeof reviewed === 'number' && typeof total === 'number'
+            ? ` over ${reviewed} of ${total} changed file(s)`
+            : '';
+    return (
+        `The self-review ran and reported no findings${scope}; ingested from its own ` +
+        'artifact by the release, so the empty set is a result rather than an absence. ' +
+        'Check it against the coverage block above and the run that produced it.'
+    );
 }
 
 /** Mirrors self_review_gate.classifyBlocking — security/claim × critical/high. */
@@ -389,32 +504,68 @@ function main(argv: readonly string[]): number {
     const ledgerPath = _ledger_path(dir, release);
 
     if (ingest) {
-        const incoming = parse_ledger(
-            JSON.stringify({
-                schema_version: 1,
-                release,
-                findings: (JSON.parse(fs.readFileSync(ingest, 'utf-8')) as { findings: LedgerFinding[] }).findings,
-            }),
-            ingest,
-        );
+        // Guarded: a truncated or corrupt artifact otherwise exits the child on
+        // an uncaught exception, and the release reports only "command failed"
+        // with no indication that the artifact is the problem.
+        let artifact: Record<string, unknown>;
+        try {
+            artifact = JSON.parse(fs.readFileSync(ingest, 'utf-8')) as Record<string, unknown>;
+        } catch (e) {
+            process.stderr.write(
+                `❌  ${ingest}: not readable as JSON (${e instanceof Error ? e.message : String(e)})\n`,
+            );
+            return 2;
+        }
+        // Run the incoming findings through the parser the committed ledger goes
+        // through, and keep the RESULT rather than discarding it. What that buys
+        // is narrow and worth stating: the parser checks the envelope and that
+        // every entry has a non-empty `finding_id`. It does NOT check severity,
+        // kind or title, so an entry with a bad severity still lands — the
+        // schema gate is what reads those, on the committed file.
+        let incoming: Ledger;
+        try {
+            incoming = parse_ledger(
+                JSON.stringify({
+                    schema_version: 1,
+                    release,
+                    findings: (artifact['findings'] as LedgerFinding[] | undefined) ?? [],
+                }),
+                ingest,
+            );
+        } catch (e) {
+            process.stderr.write(`❌  ${e instanceof Error ? e.message : String(e)}\n`);
+            return 2;
+        }
         let ledger: Ledger = { schema_version: 1, release, findings: [] };
         if (fs.existsSync(ledgerPath)) {
             ledger = parse_ledger(fs.readFileSync(ledgerPath, 'utf-8'), ledgerPath);
         }
-        const known = new Set(ledger.findings.map((f) => f.finding_id));
-        let added = 0;
-        for (const f of incoming.findings) {
-            if (!known.has(f.finding_id)) {
-                ledger.findings.push(f);
-                added++;
-            }
-        }
+        const merged = merge_ingest(ledger, { ...artifact, findings: incoming.findings });
+        ledger = merged.ledger;
+        const { added, carried, reasoned } = merged;
         fs.mkdirSync(path.dirname(ledgerPath), { recursive: true });
         fs.writeFileSync(ledgerPath, JSON.stringify(ledger, null, 2) + '\n');
         process.stdout.write(
             `📥  ingested ${added} new finding(s) into ${path.relative(REPO_ROOT, ledgerPath)} — ` +
                 'fill dispositions before the release validation goes green\n',
         );
+        if (carried.length > 0) {
+            process.stdout.write(`    carried integrity fields: ${carried.join(', ')}\n`);
+        }
+        if (reasoned) {
+            process.stdout.write(
+                '    the review reported nothing — wrote no_findings_reason so the empty ' +
+                    'ledger is a result rather than an absence\n',
+            );
+        }
+        const absent = INTEGRITY_FIELDS.filter((k) => ledger[k] === undefined);
+        if (absent.length > 0) {
+            process.stdout.write(
+                `⚠️   artifact carried no ${absent.join(', ')} — ` +
+                    'check_review_schema derives acceptance_status and assurance from ' +
+                    'review_independence and will red on a ledger that declares neither\n',
+            );
+        }
         return 0;
     }
 

package/src/scripts/check_gate_reachability.ts

@@ -36,6 +36,12 @@ import * as os from 'node:os';
 
 import { reportScanned } from './_lib/scan_scope.js';
 import { runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
+import {
+    INVENTORY_REL,
+    inventoryVerdict,
+    resetSourceCache,
+    type InventoryVerdict,
+} from './_lib/loop_surfaces.js';
 
 const REPO_ROOT = process.cwd();
 const TASKFILES_DIR = 'taskfiles';
@@ -238,6 +244,23 @@ export interface GateVerdict {
     unreasoned: string[];
     /** Recorded exemptions that are no longer unreachable — stale rows. */
     stale: string[];
+    /**
+     * The `_lib-export-reach` axis: a declared loop instrument nothing calls.
+     *
+     * A second axis in this one script rather than a second gate, because it
+     * asks the same question one layer down. The first axis asks whether CI
+     * reaches a gate TARGET; this asks whether production code reaches a
+     * declared INSTRUMENT. A separate gate would need its own registration,
+     * its own coverage row and its own wiring — and would then be the thing
+     * this family exists to detect if any of that were missed.
+     *
+     * Deliberately scoped to the instruments named in `loop-surfaces.yaml`
+     * rather than to every `_lib` export. Measured on `loop_guards.ts`, the
+     * unscoped version reports nine of fourteen exports dead; a gate whose
+     * signal is a minority of its own output gets allowlisted rather than
+     * answered.
+     */
+    inventory: InventoryVerdict;
 }
 
 /**
@@ -255,25 +278,51 @@ export function gateVerdict(root = REPO_ROOT): GateVerdict {
     return {
         unreasoned: r.unreachable.filter((n) => !exempt.has(n)).sort(),
         stale: [...exempt.keys()].filter((n) => !unreachable.has(n)).sort(),
+        inventory: inventoryVerdict(root),
     };
 }
 
+/** The `_lib-export-reach` half of the verdict, written to stderr. */
+function reportInventory(inv: InventoryVerdict): void {
+    for (const f of inv.shape) {
+        process.stderr.write(
+            `❌  ${INVENTORY_REL}: surface \`${f.id}\` — ${f.detail} (${f.reason}). Every surface ` +
+                'carries every field, and a bound resolves to something that exists.\n',
+        );
+    }
+    for (const f of inv.reach) {
+        const fix =
+            f.reason === 'dead'
+                ? 'Give it a production consumer, declare it `status: experimental` with a future ' +
+                  '`expires:`, or delete it. A built instrument nothing calls is not built.'
+                : 'An exemption is a dated deferral, not a label. Decide it, or move the date and ' +
+                  'say why in `note:`.';
+        process.stderr.write(`❌  ${f.id} (${f.file}) — ${f.detail}. ${fix}\n`);
+    }
+}
+
 function runGate(root: string): number {
     const v = gateVerdict(root);
     const exempt = readExemptions(root);
+    const inv = v.inventory;
+    const declared = inv.live.length + inv.exempt.length + inv.reach.length;
     reportScanned({
         gate: 'check_gate_reachability',
-        scanned: exempt.size + analyse(root).unreachable.length,
-        units: 'exemption row(s) + unreachable target(s)',
-        roots: [EXEMPTIONS_REL, ROOT_TASKFILE, TASKFILES_DIR],
+        scanned: exempt.size + analyse(root).unreachable.length + declared,
+        units: 'exemption row(s) + unreachable target(s) + declared loop instrument(s)',
+        roots: [EXEMPTIONS_REL, INVENTORY_REL, ROOT_TASKFILE, TASKFILES_DIR],
     });
-    if (v.unreasoned.length === 0 && v.stale.length === 0) {
+    const inventoryClean = inv.shape.length === 0 && inv.reach.length === 0;
+    if (v.unreasoned.length === 0 && v.stale.length === 0 && inventoryClean) {
         process.stdout.write(
             `✅  check_gate_reachability: every unreachable gate target carries a recorded reason ` +
-                `(${String(exempt.size)} exempt).\n`,
+                `(${String(exempt.size)} exempt); every declared loop instrument is called or ` +
+                `dated (${String(inv.live.length)} live, ${String(inv.exempt.length)} experimental` +
+                `${inv.proseBound.length > 0 ? `, ${String(inv.proseBound.length)} prose-bound surface(s)` : ''}).\n`,
         );
         return 0;
     }
+    reportInventory(inv);
     for (const n of v.unreasoned) {
         process.stderr.write(
             `❌  ${n} is gate-shaped, unreachable from \`task ci\` and every workflow, and carries ` +
@@ -320,6 +369,58 @@ function selfTest(): number {
         return v.unreasoned.length === 0 && v.stale.length === 0 ? 0 : 1;
     };
 
+    /**
+     * A throwaway tree for the `_lib-export-reach` axis.
+     *
+     * `surface` and `instrument` are written verbatim into the inventory, so a
+     * case can plant a malformed row without the builder silently repairing
+     * it — which is the whole point of a planted failure.
+     */
+    const inventoryFixture = (opts: { surface: string; instrument: string; calls: boolean }): number => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gr-inv-'));
+        roots.push(dir);
+        fs.mkdirSync(path.join(dir, 'src', 'config'), { recursive: true });
+        fs.mkdirSync(path.join(dir, 'src', 'lib'), { recursive: true });
+        fs.writeFileSync(
+            path.join(dir, 'src', 'lib', 'thing.ts'),
+            [
+                'export const CEILING = 3;',
+                'export function stalled(): boolean { return false; }',
+                'export function helper(): number { return CEILING; }',
+                ...(opts.calls ? ['export const used = helper();'] : []),
+            ].join('\n'),
+            'utf-8',
+        );
+        fs.writeFileSync(
+            path.join(dir, 'src', 'config', 'loop-surfaces.yaml'),
+            `surfaces:\n${opts.surface}\ninstruments:\n${opts.instrument}\n`,
+            'utf-8',
+        );
+        resetSourceCache();
+        const v = inventoryVerdict(dir);
+        resetSourceCache();
+        return v.shape.length === 0 && v.reach.length === 0 ? 0 : 1;
+    };
+
+    const wholeSurface = [
+        '  s:',
+        '    kind: code',
+        '    bound_kind: code',
+        '    cap: src/lib/thing.ts:CEILING',
+        '    no_progress: src/lib/thing.ts:stalled',
+        '    success_stop: a stated stop',
+        '    checker: a stated checker',
+        '    human_gate: none',
+        '    terminal_vocabulary: none',
+        '    production_consumers: [src/lib/thing.ts]',
+    ].join('\n');
+    // Identical but for the one missing field — so a red can only be the cap.
+    const cappedSurface = wholeSurface
+        .split('\n')
+        .filter((l) => !l.includes('cap:'))
+        .join('\n');
+    const plainInstrument = ['  helper:', '    file: src/lib/thing.ts', '    role: a stated role'].join('\n');
+
     const cases: SelfTestCase[] = [
         {
             name: 'a wired gate target → accept',
@@ -343,9 +444,63 @@ function selfTest(): number {
             expect: 'reject',
             run: () => fixture({ target: 'check-x', wired: true, exempt: { 'check-x': 'stale' } }),
         },
+        // The `_lib-export-reach` axis. The accept case comes first so a
+        // builder that reds on everything is caught before the three planted
+        // failures can be read as the axis working.
+        {
+            name: 'a whole surface and a called instrument → accept',
+            expect: 'accept',
+            run: () =>
+                inventoryFixture({ surface: wholeSurface, instrument: plainInstrument, calls: true }),
+        },
+        {
+            name: 'a surface with no `cap` → reject',
+            expect: 'reject',
+            run: () =>
+                inventoryFixture({ surface: cappedSurface, instrument: plainInstrument, calls: true }),
+        },
+        {
+            name: 'an instrument with no consumer → reject',
+            expect: 'reject',
+            run: () =>
+                inventoryFixture({ surface: wholeSurface, instrument: plainInstrument, calls: false }),
+        },
+        {
+            // The reason `expires:` is a required field rather than a nicety:
+            // a declared-inactive instrument with no deadline is the same dead
+            // code wearing a label.
+            name: 'an exception whose `expires:` has passed → reject',
+            expect: 'reject',
+            run: () =>
+                inventoryFixture({
+                    surface: wholeSurface,
+                    instrument: `${plainInstrument}\n    status: experimental\n    expires: '2020-01-01'`,
+                    calls: false,
+                }),
+        },
+        {
+            name: 'an `experimental` exception with no `expires:` → reject',
+            expect: 'reject',
+            run: () =>
+                inventoryFixture({
+                    surface: wholeSurface,
+                    instrument: `${plainInstrument}\n    status: experimental`,
+                    calls: false,
+                }),
+        },
+        {
+            name: 'an unexpired `experimental` exception on a dead instrument → accept',
+            expect: 'accept',
+            run: () =>
+                inventoryFixture({
+                    surface: wholeSurface,
+                    instrument: `${plainInstrument}\n    status: experimental\n    expires: '2099-01-01'`,
+                    calls: false,
+                }),
+        },
     ];
     try {
-        return runSelfTest({ gate: 'check_gate_reachability', cases, minCases: 4, minRejectCases: 2 });
+        return runSelfTest({ gate: 'check_gate_reachability', cases, minCases: 10, minRejectCases: 6 });
     } finally {
         for (const d of roots) fs.rmSync(d, { recursive: true, force: true });
     }
@@ -355,18 +510,20 @@ export function main(argv: string[] = process.argv.slice(2), root = REPO_ROOT):
     if (argv.includes('--self-test')) return selfTest();
     if (argv.includes('--gate')) return runGate(root);
     const r = analyse(root);
+    const inv = inventoryVerdict(root);
     if (argv.includes('--json')) {
-        process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify({ ...r, inventory: inv }, null, 2)}\n`);
         return 0;
     }
     // Emitted on the DEFAULT invocation too, not only under `--gate`: the
     // coverage gate reads a bare run, and a gate that reports what it inspected
     // only in one mode is a gate that reports nothing in the other.
+    const declared = inv.live.length + inv.exempt.length + inv.reach.length;
     reportScanned({
         gate: 'check_gate_reachability',
-        scanned: readExemptions(root).size + r.unreachable.length,
-        units: 'exemption row(s) + unreachable target(s)',
-        roots: [EXEMPTIONS_REL, ROOT_TASKFILE, TASKFILES_DIR],
+        scanned: readExemptions(root).size + r.unreachable.length + declared,
+        units: 'exemption row(s) + unreachable target(s) + declared loop instrument(s)',
+        roots: [EXEMPTIONS_REL, INVENTORY_REL, ROOT_TASKFILE, TASKFILES_DIR],
     });
     const total = r.reachable.length + r.scriptInWorkflow.length + r.unreachable.length;
     process.stdout.write(
@@ -375,6 +532,12 @@ export function main(argv: string[] = process.argv.slice(2), root = REPO_ROOT):
             `UNREACHABLE ${String(r.unreachable.length)}\n`,
     );
     for (const n of r.unreachable) process.stdout.write(`  · ${n}\n`);
+    process.stdout.write(
+        `declared loop instruments: ${String(declared)} · live ${String(inv.live.length)} · ` +
+            `experimental ${String(inv.exempt.length)} · DEAD ${String(inv.reach.length)} · ` +
+            `prose-bound surfaces ${String(inv.proseBound.length)}\n`,
+    );
+    for (const f of inv.reach) process.stdout.write(`  · ${f.id} — ${f.detail}\n`);
     return 0;
 }