@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/check_finding_dispositions.ts

@@ -8,8 +8,8 @@
  *
  * The record is a COMMITTED ledger — `agents/evidence/release-findings/
  * <version>.json` — never the PR comment (council 2026-08-03: a comment is
- * mutable and unaudited; it is transport, not a record). Every blocking/high
- * finding in the ledger must carry a complete disposition
+ * mutable and unaudited; it is transport, not a record). Every blocking
+ * finding in the ledger (see `isBlocking`) must carry a complete disposition
  * `{status: fixed|false_positive|accepted_risk, commit (when fixed),
  * rationale, verified_by}`; the release workflow is red while one does not.
  *
@@ -75,6 +75,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+import { coverageLabel } from './_lib/review_coverage.js';
 import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -84,6 +85,26 @@ export const LEDGER_DIR = 'agents/evidence/release-findings';
 export const DISPOSITION_STATUSES = ['fixed', 'false_positive', 'accepted_risk'] as const;
 export type DispositionStatus = (typeof DISPOSITION_STATUSES)[number];
 
+/**
+ * Every status that means a human re-read the finding and decided.
+ *
+ * `still_open` is the fourth, and it exists so that "give every row a terminal
+ * status" does not read as "close every finding". A row re-checked against the
+ * merged head and found to be a real, unfixed issue is adjudicated; writing
+ * `accepted_risk` over it to make a count reach zero would be the cheapest way
+ * to satisfy the requirement and the one that destroys it.
+ *
+ * It is deliberately NOT in {@link DISPOSITION_STATUSES}: a BLOCKING row may
+ * never pass on it. `missing_dispositions` reports a blocking finding marked
+ * `still_open` with its own message and the gate stays red — which is the
+ * behaviour a blocking finding that is still open should have.
+ *
+ * `open` from the schema is absent on purpose. The schema documents it as the
+ * INITIAL state, so counting it would make the tally reachable without anyone
+ * re-reading a finding.
+ */
+export const TERMINAL_STATUSES = [...DISPOSITION_STATUSES, 'still_open'] as const;
+
 export interface LedgerFinding {
     finding_id: string;
     severity: 'critical' | 'high' | 'medium' | 'low';
@@ -120,6 +141,12 @@ export interface Ledger {
     assurance?: string;
     reviewers?: string[];
     coverage?: unknown;
+    /**
+     * Per-run count of findings quoting a supplied fact, written by
+     * `self_review_gate` under `--findings-out`. Declared here because ingest
+     * now carries it; see {@link INTEGRITY_FIELDS}.
+     */
+    fact_claims?: unknown;
 }
 
 /**
@@ -139,7 +166,7 @@ export interface Ledger {
  * consumer inferring it from the findings would be inventing the integrity
  * claim the fields exist to record.
  */
-export const INTEGRITY_FIELDS = [
+const SCHEMA_INTEGRITY_FIELDS = [
     'review_independence',
     'context_relation',
     'acceptance_status',
@@ -148,6 +175,24 @@ export const INTEGRITY_FIELDS = [
     'coverage',
 ] as const;
 
+/**
+ * The carried set: the six above plus `fact_claims`.
+ *
+ * `fact_claims` is written by `self_review_gate.ts` at `--findings-out` time and
+ * was dropped by every ingest, because this list predates it. The field is the
+ * falsifier for the supplied-facts change — a count over the next cut — and a
+ * falsifier that never reaches the record is not one. It is carried rather than
+ * recomputed for the same reason the other six are: only the producing run knows
+ * what it quoted.
+ *
+ * It is NOT in {@link SCHEMA_INTEGRITY_FIELDS}, which is the set the ingest
+ * warning names. That warning tells a writer that `check_review_schema` derives
+ * `acceptance_status` and `assurance` from `review_independence` and will red on
+ * a ledger declaring neither — a sentence that is simply untrue of `fact_claims`,
+ * and naming it there would make the warning wrong to buy one shorter list.
+ */
+export const INTEGRITY_FIELDS = [...SCHEMA_INTEGRITY_FIELDS, 'fact_claims'] 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
@@ -226,21 +271,74 @@ function _clean_review_reason(artifact: Record<string, unknown>): string {
     );
 }
 
+export const MEDIUM_SECURITY_BLOCKS_AFTER = '16.3.0';
+
+function semverParts(v: string): [number, number, number] | null {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/** True unless `release` parses and is at or before the cutoff. */
+export function mediumSecurityBinds(release: string | null): boolean {
+    if (release === null) return true;
+    const r = semverParts(release);
+    const cut = semverParts(MEDIUM_SECURITY_BLOCKS_AFTER) as [number, number, number];
+    if (r === null) return true;
+    for (let i = 0; i < 3; i++) {
+        const a = r[i] as number;
+        const b = cut[i] as number;
+        if (a !== b) return a > b;
+    }
+    return false;
+}
+
 /**
- * Mirrors self_review_gate.classifyBlocking — security/claim × critical/high,
- * MINUS anything the tree disproved.
- *
- * The `contradicted` clause is not a second policy; it is the same one, and
- * the mirror has to carry it or the two gates disagree: the review would stop
- * counting a disproved deletion claim as blocking while the release kept
- * demanding a disposition for it. A `contradicted` value is written only by
- * `annotateContradicted`, which checks the claim against
- * `git diff --name-status base...HEAD` AND the working tree.
+ * self_review_gate.classifyBlocking (security/claim × critical/high) PLUS
+ * security × medium, MINUS anything the tree disproved.
+ *
+ * Deliberately STRICTER than the merge gate, and the asymmetry is load-bearing
+ * rather than drift — do not re-mirror it. The merge gate asks whether a change
+ * may enter trunk while work is still integrating; this gate asks whether a
+ * known risk may ship to users without an accountable decision. 16.3.0 shipped
+ * a medium security finding that had already been open in 16.2.0 with nobody
+ * required to decide it, so a medium security finding needs a disposition here
+ * while it stays advisory at merge. `accepted_risk` with a rationale satisfies
+ * it; `still_open` does not. `claim × medium` stays advisory in both.
+ * Council 2026-10-07 (claude-sonnet-4-5 + codex, 2/2 concluded, option a,
+ * release gate only). Revisit if medium security findings routinely receive
+ * formulaic `accepted_risk` over three consecutive releases, or exceed about
+ * ten per release.
+ *
+ * The widening is prospective: it binds releases after
+ * {@link MEDIUM_SECURITY_BLOCKS_AFTER}, the last one published before the
+ * decision. A release already shipped cannot be made to wait, and re-gating it
+ * would leave exactly two outcomes for a medium security row that is genuinely
+ * still open — a red trunk, or an `accepted_risk` written only to turn it
+ * green, which is the relabelling this gate exists to refuse. Without a release
+ * (a reported finding, a test) the wider rule applies.
+ *
+ * The cutoff orders by version, not by publication date: a maintenance release
+ * on an older line (a 16.2.x cut after the decision) sits at or before the
+ * cutoff and is exempt. The council ratified the prospective cutoff and this
+ * documented exemption on 2026-10-07 (2/2); cutting a maintenance line is the
+ * condition that reopens it.
+ *
+ * The `contradicted` clause is shared with the merge gate, and has to be or the
+ * two disagree: the review would stop counting a disproved deletion claim as
+ * blocking while the release kept demanding a disposition for it. A
+ * `contradicted` value is written only by `annotateContradicted`, which checks
+ * the claim against `git diff --name-status base...HEAD` AND the working tree.
  */
-export function isBlocking(f: Pick<LedgerFinding, 'kind' | 'severity' | 'contradicted'>): boolean {
+export function isBlocking(
+    f: Pick<LedgerFinding, 'kind' | 'severity' | 'contradicted'>,
+    release: string | null = null,
+): boolean {
     if ((f.contradicted ?? '').trim() !== '') {
         return false;
     }
+    if (f.kind === 'security' && f.severity === 'medium' && mediumSecurityBinds(release)) {
+        return true;
+    }
     return (
         (f.kind === 'security' || f.kind === 'claim') &&
         (f.severity === 'critical' || f.severity === 'high')
@@ -253,10 +351,13 @@ export function isBlocking(f: Pick<LedgerFinding, 'kind' | 'severity' | 'contrad
  * Empty rationale / verified_by is a hygiene violation (waiver precedent:
  * "empty string = hygiene violation"); status `fixed` requires a commit.
  */
-export function missing_dispositions(findings: readonly LedgerFinding[]): string[] {
+export function missing_dispositions(
+    findings: readonly LedgerFinding[],
+    release: string | null = null,
+): string[] {
     const problems: string[] = [];
     for (const f of findings) {
-        if (!isBlocking(f)) {
+        if (!isBlocking(f, release)) {
             continue;
         }
         const label = `${f.finding_id} (${f.severity} ${f.kind}: ${f.title})`;
@@ -265,6 +366,10 @@ export function missing_dispositions(findings: readonly LedgerFinding[]): string
             problems.push(`${label}: no disposition status`);
             continue;
         }
+        if (status === 'still_open') {
+            problems.push(`${label}: still_open does not satisfy a blocking finding — fix it, disprove it, or accept the risk with a reason`);
+            continue;
+        }
         if (!(DISPOSITION_STATUSES as readonly string[]).includes(status)) {
             problems.push(`${label}: unknown status ${JSON.stringify(status)}`);
             continue;
@@ -282,6 +387,69 @@ export function missing_dispositions(findings: readonly LedgerFinding[]): string
     return problems;
 }
 
+/** What the success line reports, counted over the two populations apart. */
+export interface DispositionTally {
+    /** Rows `isBlocking` admits. */
+    readonly blockingTotal: number;
+    /** Of those, the ones `missing_dispositions` finds nothing wrong with. */
+    readonly blockingDispositioned: number;
+    /** Every other row. The gate cannot fail on these; it can still count them. */
+    readonly nonBlockingTotal: number;
+    /** Of those, the ones carrying a {@link TERMINAL_STATUSES} value. */
+    readonly nonBlockingTerminal: number;
+}
+
+/**
+ * Count what the gate checked, split by what it can actually require.
+ *
+ * The recorded failure this exists for: `--release 16.2.0` printed "all 20
+ * recorded finding(s) for 16.2.0 dispositioned (blocking ones completely)" over
+ * a ledger carrying a `status` on 2 of 20 rows. Both halves of that sentence are
+ * individually defensible — the gate did require the blocking ones, and it did
+ * complete — and together they say the opposite of the truth, because nobody
+ * reads a parenthetical as a retraction of the word in front of it. Eighteen
+ * findings had never been adjudicated and the record said they had.
+ *
+ * The fix is a count, not a new refusal. Exit semantics are untouched: a
+ * non-blocking row still cannot fail the gate. What changes is that the line
+ * stops claiming the rows it never looked at.
+ *
+ * An unrecognised status counts as NOT terminal, which is the conservative
+ * direction: a typo surfaces as a row the line says is unadjudicated, rather
+ * than disappearing into a count that reads as finished.
+ */
+export function disposition_tally(
+    findings: readonly LedgerFinding[],
+    release: string | null = null,
+): DispositionTally {
+    let blockingTotal = 0;
+    let blockingDispositioned = 0;
+    let nonBlockingTotal = 0;
+    let nonBlockingTerminal = 0;
+    for (const f of findings) {
+        if (isBlocking(f, release)) {
+            blockingTotal++;
+            if (missing_dispositions([f], release).length === 0) {
+                blockingDispositioned++;
+            }
+            continue;
+        }
+        nonBlockingTotal++;
+        if ((TERMINAL_STATUSES as readonly string[]).includes((f.status ?? '').trim())) {
+            nonBlockingTerminal++;
+        }
+    }
+    return { blockingTotal, blockingDispositioned, nonBlockingTotal, nonBlockingTerminal };
+}
+
+/** The tally as the success line renders it. Never the word "all". */
+export function disposition_summary(t: DispositionTally): string {
+    return (
+        `blocking ${String(t.blockingDispositioned)}/${String(t.blockingTotal)} dispositioned · ` +
+        `non-blocking ${String(t.nonBlockingTerminal)}/${String(t.nonBlockingTotal)} carry a terminal status`
+    );
+}
+
 /**
  * An empty finding set must say why it is empty.
  *
@@ -434,10 +602,11 @@ export function resolve_release_status(release: string): ReleaseStatus {
 export function unrecorded_findings(
     reported: ReadonlyArray<Pick<LedgerFinding, 'finding_id' | 'severity' | 'kind' | 'title' | 'contradicted'>>,
     ledger: readonly LedgerFinding[],
+    release: string | null = null,
 ): string[] {
     const known = new Set(ledger.map((f) => f.finding_id));
     return reported
-        .filter((f) => isBlocking(f) && !known.has(f.finding_id))
+        .filter((f) => isBlocking(f, release) && !known.has(f.finding_id))
         .map((f) => `${f.finding_id} (${f.severity} ${f.kind}: ${f.title}) reported by the self-review but not in the ledger`);
 }
 
@@ -577,7 +746,7 @@ function main(argv: readonly string[]): number {
                     'ledger is a result rather than an absence\n',
             );
         }
-        const absent = INTEGRITY_FIELDS.filter((k) => ledger[k] === undefined);
+        const absent = SCHEMA_INTEGRITY_FIELDS.filter((k) => ledger[k] === undefined);
         if (absent.length > 0) {
             process.stdout.write(
                 `⚠️   artifact carried no ${absent.join(', ')} — ` +
@@ -667,18 +836,24 @@ function main(argv: readonly string[]): number {
         throw exc;
     }
 
-    const problems = missing_dispositions(ledger.findings);
+    const problems = missing_dispositions(ledger.findings, release);
     if (pr) {
         const reported = parse_comment_findings(_gh_comment_bodies(pr));
-        problems.push(...unrecorded_findings(reported, ledger.findings));
+        problems.push(...unrecorded_findings(reported, ledger.findings, release));
     }
 
     if (problems.length === 0) {
         const n = ledger.findings.length;
+        // The label is appended to BOTH lines, including the zero-findings one:
+        // a review that read 65 of 678 files and reported nothing is the case
+        // where "no findings" is least informative on its own.
+        const partial = coverageLabel(ledger.coverage);
+        const suffix = partial === null ? '' : ` — ${partial}`;
         process.stdout.write(
             n === 0
-                ? `✅  no recorded findings for ${release} (ledger ${fs.existsSync(ledgerPath) ? 'empty' : 'absent'})\n`
-                : `✅  all ${n} recorded finding(s) for ${release} dispositioned (blocking ones completely)\n`,
+                ? `✅  no recorded findings for ${release} (ledger ${fs.existsSync(ledgerPath) ? 'empty' : 'absent'})${suffix}\n`
+                : `✅  ${String(n)} recorded finding(s) for ${release} — ` +
+                      `${disposition_summary(disposition_tally(ledger.findings, release))}${suffix}\n`,
         );
         return 0;
     }

package/src/scripts/check_gate_coverage.ts

@@ -30,7 +30,8 @@
  * definition. It runs the same contract as the review-side canary in
  * `docs/contracts/adversarial-review-protocol.md` § 6 (rotating class, sealed
  * record, NEVER SHIPS) and is deliberately kept OFF the default CI path: it
- * mutates the tree, so it is an operator-invoked biannual experiment, not a
+ * mutates the tree, so it is a scheduled experiment (`.github/workflows/gate-canary.yml`,
+ * monthly, ledger uploaded as a run artifact) or an operator run, never a
  * per-PR gate. Every plant is reverted in a `finally`.
  *
  * CLI:
@@ -415,8 +416,8 @@ function report_negative_control_inventory(specs: readonly GateSpec[]): void {
   // The arithmetic is the guard against skimming: two numbers that reconcile
   // against the enforced total cannot be read as "all of them checked".
   process.stdout.write(
-    `  ⚠️  declared, not run — the mutating --canary path is operator-invoked and off the per-PR workflow, ` +
-      `so no negative control ran here.\n`,
+    `  ⚠️  declared, not run — the mutating --canary path is off the per-PR workflow (it runs monthly ` +
+      `in .github/workflows/gate-canary.yml), so no negative control ran here.\n`,
   );
   for (const s of without) {
     process.stdout.write(`  · ${s.id}: ${s.no_canary_reason ?? '(no reason recorded)'}\n`);

package/src/scripts/check_gate_reachability.ts

@@ -42,6 +42,7 @@ import {
     resetSourceCache,
     type InventoryVerdict,
 } from './_lib/loop_surfaces.js';
+import { analyseModuleReach, groupCounts } from './_lib/module_reach.js';
 
 const REPO_ROOT = process.cwd();
 const TASKFILES_DIR = 'taskfiles';
@@ -312,6 +313,10 @@ function runGate(root: string): number {
         units: 'exemption row(s) + unreachable target(s) + declared loop instrument(s)',
         roots: [EXEMPTIONS_REL, INVENTORY_REL, ROOT_TASKFILE, TASKFILES_DIR],
     });
+    // Phase 3.1 of road-to-modules-that-something-calls.md: five numbers beside
+    // this gate's existing verdicts, printed whether the gate passes or fails —
+    // reported, enforcing nothing, the way the estate gate prints its draft count.
+    process.stdout.write(moduleReachLine(moduleReachSummary(root)));
     const inventoryClean = inv.shape.length === 0 && inv.reach.length === 0;
     if (v.unreasoned.length === 0 && v.stale.length === 0 && inventoryClean) {
         process.stdout.write(
@@ -506,13 +511,54 @@ function selfTest(): number {
     }
 }
 
+export interface ModuleReachSummary {
+    /** The four group counts — the roadmap's "four group counts", over the unreferenced-by-name set only. */
+    groups: Record<'contract-test' | 'open-or-deferred-step' | 'named-outside-open-step' | 'named-in-none', number>;
+    /** "the total of modules reached by nothing" (import edges + run-by-path) — the fifth number. */
+    reachedByNothing: number;
+    /**
+     * Not one of the five — the size of the unreferenced-by-name set the four
+     * groups partition. Kept on the summary because it is a free cross-check
+     * (it must equal the sum of `groups`); never printed as a sixth number.
+     */
+    unreferencedTotal: number;
+}
+
+/**
+ * The five module-reach numbers (road-to-modules-that-something-calls.md
+ * Phase 3.1) — reported beside this gate's own verdicts, the way the estate
+ * gate prints its draft-roadmap count: a number that moves in a change's own
+ * gate output, enforcing nothing.
+ */
+export function moduleReachSummary(root: string): ModuleReachSummary {
+    const { modules } = analyseModuleReach(root);
+    const unreferenced = modules.filter((m) => !m.namedByProduction);
+    return {
+        groups: groupCounts(unreferenced),
+        reachedByNothing: modules.filter((m) => !m.reachedByImportOrPath).length,
+        unreferencedTotal: unreferenced.length,
+    };
+}
+
+export function moduleReachLine(s: ModuleReachSummary): string {
+    return (
+        `module reach (reported, not gated), src/scripts/_lib: ` +
+        `contract-test ${String(s.groups['contract-test'])} · ` +
+        `open-or-deferred-step ${String(s.groups['open-or-deferred-step'])} · ` +
+        `named-outside-open-step ${String(s.groups['named-outside-open-step'])} · ` +
+        `named-in-none ${String(s.groups['named-in-none'])} · ` +
+        `REACHED-BY-NOTHING total ${String(s.reachedByNothing)}\n`
+    );
+}
+
 export function main(argv: string[] = process.argv.slice(2), root = REPO_ROOT): number {
     if (argv.includes('--self-test')) return selfTest();
     if (argv.includes('--gate')) return runGate(root);
     const r = analyse(root);
     const inv = inventoryVerdict(root);
+    const moduleReach = moduleReachSummary(root);
     if (argv.includes('--json')) {
-        process.stdout.write(`${JSON.stringify({ ...r, inventory: inv }, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify({ ...r, inventory: inv, moduleReach }, null, 2)}\n`);
         return 0;
     }
     // Emitted on the DEFAULT invocation too, not only under `--gate`: the
@@ -538,6 +584,7 @@ export function main(argv: string[] = process.argv.slice(2), root = REPO_ROOT):
             `prose-bound surfaces ${String(inv.proseBound.length)}\n`,
     );
     for (const f of inv.reach) process.stdout.write(`  · ${f.id} — ${f.detail}\n`);
+    process.stdout.write(moduleReachLine(moduleReach));
     return 0;
 }
 

package/src/scripts/check_generator_sync.ts

@@ -546,11 +546,59 @@ const HOST_LOWERING_TRIPLE: Triple = {
     },
 };
 
+const GRAMMAR_REFERENCE = 'src/skills/git-workflow/references/commit-subject.md';
+const GRAMMAR_GENERATOR = 'src/scripts/generate_git_convention_grammar.ts';
+
+/**
+ * The commit-subject reference is the fallback a command reads when the
+ * `agent-config` binary cannot run, so its grammar block has to be the grammar
+ * the binary runs. The page itself is a source too: a hand edit to the block is
+ * the drift this row exists to catch.
+ */
+const GIT_CONVENTION_GRAMMAR_TRIPLE: Triple = {
+    id: 'git-convention-grammar',
+    output: GRAMMAR_REFERENCE,
+    remedy: './scripts-run src/scripts/generate_git_convention_grammar',
+    why: 'the reference carries a grammar and measurement block rendered from the modules the git:convention verb runs',
+    sourcesOf() {
+        return {
+            ok: true,
+            sources: [
+                { kind: 'file', value: 'src/scripts/_lib/git_convention_grammar.ts' },
+                { kind: 'file', value: 'src/scripts/_lib/git_convention_measure.ts' },
+                { kind: 'file', value: GRAMMAR_GENERATOR },
+                { kind: 'file', value: GRAMMAR_REFERENCE },
+            ],
+        };
+    },
+    regenerate(root, workDir) {
+        const outFile = path.join(workDir, 'commit-subject.md');
+        const tsx = path.join(root, 'node_modules', '.bin', process.platform === 'win32' ? 'tsx.cmd' : 'tsx');
+        if (!fs.existsSync(tsx)) {
+            return { ok: false, reason: `no tsx at ${path.relative(root, tsx)} — run \`npm ci\` before this gate` };
+        }
+        const res = spawnSync(tsx, [path.join(root, GRAMMAR_GENERATOR), '--out', outFile], {
+            cwd: root,
+            encoding: 'utf8',
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        if (res.status !== 0) {
+            return { ok: false, reason: `generate_git_convention_grammar exited ${String(res.status)}: ${(res.stderr ?? '').trim()}` };
+        }
+        try {
+            return { ok: true, text: fs.readFileSync(outFile, 'utf8') };
+        } catch (e) {
+            return { ok: false, reason: `generate_git_convention_grammar reported success but wrote no readable file (${String(e)})` };
+        }
+    },
+};
+
 export const REGISTRY: readonly Triple[] = [
     CENSUS_TRIPLE,
     INSTALL_BUNDLE_TRIPLE,
     HOOK_MANIFEST_TRIPLE,
     HOST_LOWERING_TRIPLE,
+    GIT_CONVENTION_GRAMMAR_TRIPLE,
 ];
 
 // ---------------------------------------------------------------------------