@event4u/agent-config 13.0.0 → 14.1.0

package/src/scripts/ai_council/qualification_wiring.ts

@@ -0,0 +1,243 @@
+/**
+ * Where provider qualification meets the CLI (road-to-release-review-p0
+ * Phase 3).
+ *
+ * `qualification.ts` classifies and `probe_store.ts` observes; both are pure of
+ * the council's own plumbing. This module is the seam: it turns a resolved
+ * transport plus a stored observation into a verdict, decides what that verdict
+ * does to attendance, and renders it for the two surfaces that show it.
+ *
+ * **It exists as its own file because the size ratchet said so, and the ratchet
+ * was right.** All of this first landed inside `council_cli.ts`, which was
+ * already 4,058 lines — over the 1,500-line ceiling — so 253 lines of wiring
+ * scored 253 against `check_source_size_budget`, whose metric is
+ * `Σ max(0, lines(f) − CEILING)`. The four new modules the same change added
+ * scored zero, being well under. That asymmetry is the gate working: it does
+ * not object to new code, it objects to new code in the file that is already
+ * too big to read. Extracting here costs one import and leaves the seam
+ * testable on its own terms.
+ *
+ * ## The injection contract
+ *
+ * `build_members` evaluates qualification ONLY when its caller supplies a
+ * `probe_store`. Omission is the safe default here rather than the unsafe one,
+ * and the reason is determinism, not timidity: the store lives under
+ * `agents/runtime/`, which is gitignored, so a `build_members` that read it
+ * implicitly would give a different answer on a machine that had run a council
+ * pass than on one that had not — the exact per-machine flakiness the
+ * `environment_report` injection point already exists to keep out of that
+ * function. Every production entry point supplies it; a unit test supplies a
+ * fixture or nothing.
+ *
+ * The matching out-param, `qualification_out`, is empty when no store was
+ * passed. Empty means **not evaluated**, which is a different statement from
+ * "every seat qualified" and must never be read as the latter.
+ *
+ * ## What the status surface consulted, and what it did not
+ *
+ * Reading the store means `cmd_status` now touches a path under the project
+ * root. Its ADR-104 claim — that the project tree is never consulted — is
+ * therefore scoped to CONFIG resolution, and the probe path is published
+ * beside it rather than folded into a hedge.
+ */
+
+import {
+    formatQualificationLine,
+    isCountableForQuorum,
+    qualifyMember,
+    type MemberQualification,
+} from './qualification.js';
+import { probeFor, recordProbes, type ProbeEntry, type ProbeStore } from './probe_store.js';
+import type { AbsentReason, CliFailureClass, Transport } from './transport_resolver.js';
+
+/** The slice of a resolved transport the ladder consumes. */
+export interface ResolvedSlice {
+    readonly available: boolean;
+    readonly transport: Transport | null;
+    readonly reason: string | null;
+    readonly absentReason: AbsentReason | null;
+}
+
+/**
+ * Qualify one enabled member against the store.
+ *
+ * Called from the member loop BEFORE any branch decides how the seat is built:
+ * the branches differ in construction, not in what would qualify, and a
+ * per-branch call is how the `manual` path would silently stop being qualified.
+ */
+export function qualifySeat(
+    name: string,
+    resolved: ResolvedSlice,
+    modelId: string | null,
+    store: ProbeStore,
+): MemberQualification {
+    return qualifyMember({
+        name,
+        transport: {
+            available: resolved.available,
+            transport: resolved.transport,
+            reason: resolved.reason,
+            absentReason: resolved.absentReason,
+        },
+        modelId,
+        lastProbe: probeFor(store, name),
+    });
+}
+
+export interface AttendanceGate {
+    /** Seats to record absent — already-absent names excluded, so no double count. */
+    readonly toRecordAbsent: readonly MemberQualification[];
+    /** ONE line for the whole roster, or null when every seat is countable. */
+    readonly noticeLine: string | null;
+}
+
+/**
+ * Which qualified seats may not be counted present, and the one line that says
+ * so.
+ *
+ * Two properties this encodes, both of which were review findings:
+ *
+ *  - **A seat already recorded absent is excluded**, so it is not subtracted
+ *    twice — the caller routes the rest through its own `record_absent`, which
+ *    keeps the pre-run event's `total - present == absent.length` invariant.
+ *  - **One line, not one per seat.** A fresh machine has no store, so every
+ *    seat reads `unknown` and the per-seat form printed the full roster on
+ *    every invocation, spend-free previews included.
+ */
+export function attendanceGate(
+    qualifications: readonly MemberQualification[],
+    alreadyAbsent: ReadonlySet<string>,
+): AttendanceGate {
+    const blocked = qualifications.filter(
+        (q) => !alreadyAbsent.has(q.name) && !isCountableForQuorum(q.verdict),
+    );
+    if (blocked.length === 0) {
+        return { toRecordAbsent: [], noticeLine: null };
+    }
+    return {
+        toRecordAbsent: blocked,
+        noticeLine:
+            `[council] ${String(blocked.length)} seat(s) not counted toward attendance — ` +
+            `${blocked.map(formatQualificationLine).join(' · ')}`,
+    };
+}
+
+/**
+ * The `QuorumAbsentReason` an unqualified seat is recorded under.
+ *
+ * `unavailable` for BOTH `unavailable` and `unknown`, deliberately: that enum
+ * is closed and carries no `unqualified` member, and minting one would be a
+ * contract change on an event other instruments parse — to express a
+ * distinction the absence `detail` carries losslessly on the same row.
+ */
+export function absenceReasonFor(_q: MemberQualification): 'unavailable' {
+    return 'unavailable';
+}
+
+/** The `qualification` block a status payload publishes. */
+export function qualificationJson(
+    qualifications: readonly MemberQualification[],
+): Record<string, unknown> {
+    return Object.fromEntries(
+        qualifications.map((q) => [
+            q.name,
+            {
+                verdict: q.verdict,
+                decided_by: q.decidedBy,
+                countable_for_quorum: isCountableForQuorum(q.verdict),
+                checks: q.checks.map((c) => ({ id: c.id, status: c.status, detail: c.detail })),
+            },
+        ]),
+    );
+}
+
+/**
+ * The human status lines: one per seat, then the advice.
+ *
+ * TWO warnings, not one. A single "run a pass and it resolves itself" was
+ * emitted for every uncountable seat including `unavailable` ones, where it is
+ * false — and it sent the operator to re-run instead of to the actual fault.
+ */
+export function qualificationStatusLines(
+    qualifications: readonly MemberQualification[],
+): string[] {
+    const lines = qualifications.map((q) => `  qualification    ${formatQualificationLine(q)}`);
+    const total = String(qualifications.length);
+    const unknown = qualifications.filter((q) => q.verdict === 'unknown').length;
+    const unavailable = qualifications.filter((q) => q.verdict === 'unavailable').length;
+    if (unknown > 0) {
+        lines.push(
+            `  ⚠️  ${String(unknown)} of ${total} seat(s) have no recorded exchange and read \`unknown\`, so they are`,
+            '     not counted toward a quorum. Run a council pass and this resolves itself.',
+        );
+    }
+    if (unavailable > 0) {
+        lines.push(
+            `  ❌  ${String(unavailable)} of ${total} seat(s) are \`unavailable\` — a pass will NOT fix these.`,
+            '     Read the deciding check on each line above and repair that.',
+        );
+    }
+    return lines;
+}
+
+/** How many seats a status surface may count toward a quorum. */
+export function countableSeats(qualifications: readonly MemberQualification[]): number {
+    return qualifications.filter((q) => isCountableForQuorum(q.verdict)).length;
+}
+
+/**
+ * Per-member observations from one index-aligned round of responses.
+ *
+ * ONE definition, used by the run path and the debate path both. A second copy
+ * is how the two would drift on what counts as an answer — and "non-empty text,
+ * not merely the absence of an error" is a distinction this repository already
+ * paid for once, when a 290 s timeout returned an empty body with no error set
+ * and the banner printed full attendance.
+ *
+ * Typed structurally rather than against the client classes on purpose: this
+ * module has no business importing the transport layer to read two fields, and
+ * the looser signature is what lets it be tested without constructing a client.
+ */
+export function probesFromRound(
+    members: readonly { readonly name: string }[],
+    responses: readonly ({ readonly error?: unknown; readonly text: string } | undefined)[],
+    classify: (raw: string) => CliFailureClass,
+    at: string,
+): ProbeEntry[] {
+    const probes: ProbeEntry[] = [];
+    for (let i = 0; i < members.length; i++) {
+        const m = members[i] as { readonly name: string };
+        const r = responses[i];
+        if (r !== undefined && !r.error && r.text.trim() !== '') {
+            probes.push({ name: m.name, outcome: 'ok', at });
+            continue;
+        }
+        const raw =
+            (r?.error as string | undefined) ??
+            (r !== undefined && r.text.trim() === '' ? 'empty response body' : 'no response');
+        probes.push({ name: m.name, outcome: classify(String(raw)), at });
+    }
+    return probes;
+}
+
+/** Today, as the store records it. Extracted so a test can pin the date. */
+export function observationDate(now: Date = new Date()): string {
+    return now.toISOString().slice(0, 10);
+}
+
+/**
+ * Record one round's observations into the store — the whole side effect, at
+ * one call site per path.
+ *
+ * Unguarded by any success check on purpose: a pass that errored is as
+ * informative an observation as one that answered, and `recordProbes` is
+ * best-effort by construction, so a write failure cannot break the run.
+ */
+export function recordRoundObservations(
+    root: string,
+    members: readonly { readonly name: string }[],
+    responses: readonly ({ readonly error?: unknown; readonly text: string } | undefined)[],
+    classify: (raw: string) => CliFailureClass,
+): void {
+    recordProbes(root, probesFromRound(members, responses, classify, observationDate()));
+}

package/src/scripts/ai_council/quorum_wiring.ts

@@ -0,0 +1,211 @@
+/**
+ * The quorum seam between `quorum.ts` and the council CLI.
+ *
+ * `quorum.ts` is pure arithmetic: given n, present and a setting, it answers
+ * whether a pass concluded. Everything here is the plumbing around that answer
+ * — reading the setting out of a possibly hand-built config dict, re-deriving
+ * presence from a round of responses, emitting the attendance event, and
+ * rendering the operator-facing banner.
+ *
+ * **Extracted for the same reason its sibling `qualification_wiring.ts` was,
+ * and the reason is worth stating rather than implying.** Adding provider
+ * qualification to `council_cli.ts` pushed that file from 4,058 to 4,311
+ * lines, and `check_source_size_budget` scores `Σ max(0, lines(f) − 1500)` —
+ * so every added line in a file already 2,500 over the ceiling counts against
+ * the ratchet, while the new modules beside it count zero. Moving the
+ * qualification seam out recovered 164 of those lines; the residual 89 was
+ * call-site wiring that cannot leave `council_cli.ts`. This module is the
+ * operator's answer to that residual: pull the quorum plumbing — the same
+ * layer, and the code the qualification change already reaches into — into a
+ * file whose subject it actually is.
+ *
+ * That makes the extraction a real boundary rather than budget accounting. The
+ * discriminator: every function here is about a k-of-n verdict and its
+ * reporting, and none of them is about parsing argv, constructing clients, or
+ * writing an output payload — which is what `council_cli.ts` is for.
+ *
+ * `Dict` is redeclared locally rather than imported: it is `Record<string,
+ * unknown>` in the CLI too, and importing a type alias that shallow would
+ * couple this module to the file it was just separated from.
+ */
+
+import type { CouncilResponse, ExternalAIClient } from './clients.js';
+import type { QuorumSetting } from './config.js';
+import {
+    appendQuorumEvent,
+    type QuorumAbsence,
+    type QuorumCommand,
+    type QuorumDispatch,
+    type QuorumEventPhase,
+} from './events_log.js';
+import { evaluateQuorum, SOLO_FLOOR_MIN_PRESENT, type QuorumResult } from './quorum.js';
+import { absentReasonFromCliFailure, classifyCliFailure } from './transport_resolver.js';
+
+type Dict = Record<string, unknown>;
+
+/**
+ * `ai['quorum']` as forwarded by `_synthesize_ai_council_block` (already
+ * validated by `config.ts::_build_quorum` on that path) — or, for a caller
+ * that hands `build_members` a hand-built dict bypassing the loader
+ * entirely, a defensive re-check that fails soft to `'majority'` rather
+ * than throwing. `build_members` is not the config-validation layer;
+ * `evaluateQuorum` degrades an unrecognisable setting toward
+ * `inconclusive`, never toward a false `concluded`, so failing soft here
+ * costs nothing on the safety side.
+ */
+export function _quorum_setting_from(ai: Dict): QuorumSetting {
+    const raw = ai['quorum'];
+    if (raw === 'majority') {
+        return 'majority';
+    }
+    if (typeof raw === 'number' && Number.isInteger(raw) && raw >= 1) {
+        return raw;
+    }
+    return 'majority';
+}
+
+/**
+ * `ai['quorum_min_present']` with the same fail-soft posture as
+ * `_quorum_setting_from`: the loader has already validated it on the normal
+ * path, and a hand-built dict that bypasses the loader falls back to the
+ * ADR-224 default rather than throwing.
+ *
+ * Failing soft costs nothing on the safety side here, and less than it does
+ * for `quorum`: this value feeds a counterfactual boolean that no gate reads,
+ * so the worst outcome of a wrong fallback is one mis-recorded telemetry line,
+ * never a pass that concluded when it should not have.
+ */
+export function _quorum_min_present_from(ai: Dict): number {
+    const raw = ai['quorum_min_present'];
+    if (typeof raw === 'number' && Number.isInteger(raw) && raw >= 1) {
+        return raw;
+    }
+    return SOLO_FLOOR_MIN_PRESENT;
+}
+
+/**
+ * Emit one `quorum_result` line for a resolved quorum.
+ *
+ * Both `evaluateQuorum` call sites route through here, tagged by `phase`, so
+ * a solo-concluded pass is distinguishable from a full-attendance one in the
+ * event log — the gap `road-to-always-on-orchestration`'s Risk 6 asserted was
+ * already closed and was not.
+ *
+ * The emit sits at the call sites rather than inside `_postRunQuorum` on
+ * purpose: that function is exported and unit-tested as a pure derivation,
+ * and a write buried in it would make every test of it a log writer.
+ *
+ * `absent` entries arrive as the CLI's own `{member, reason, detail}` dicts;
+ * `detail` is dropped by `appendQuorumEvent`'s input type, which cannot carry
+ * free-form text at all.
+ */
+export function _emitQuorumEvent(
+    phase: QuorumEventPhase,
+    quorum: QuorumResult,
+    absent: readonly Dict[],
+    ctx: {
+        command: QuorumCommand;
+        dispatch?: QuorumDispatch;
+        /** Enabled members before `--single` filtering; defaults to the roster that ran. */
+        configuredTotal?: number;
+        lens?: string;
+        invocation?: string;
+        /**
+         * The ADR-224 shadow floor for this pass. `gateClass` is deliberately
+         * NOT in this context object: no CLI path declares itself gate-class,
+         * so a parameter here would be one no caller ever sets, and its
+         * absence is what the `false` on every line honestly records.
+         */
+        minPresent?: number;
+    },
+): void {
+    appendQuorumEvent({
+        lens: ctx.lens ?? '',
+        invocation: ctx.invocation ?? '',
+        phase,
+        command: ctx.command,
+        dispatch: ctx.dispatch ?? 'full',
+        configuredTotal: ctx.configuredTotal ?? quorum.total,
+        result: quorum,
+        ...(ctx.minPresent !== undefined ? { minPresent: ctx.minPresent } : {}),
+        absent: absent.map(
+            (a): QuorumAbsence => ({
+                member: String(a['member'] ?? ''),
+                reason: (a['reason'] as QuorumAbsence['reason']) ?? 'unavailable',
+            }),
+        ),
+    });
+}
+
+/**
+ * Re-derive quorum AFTER the provider calls, over what was actually USABLE —
+ * never what merely CONSTRUCTED (M3, independent-review finding). `members`
+ * and `responses` must be index-aligned (`consult()`'s own contract: one
+ * `CouncilResponse` per member, from the final round); `members.length` is
+ * the `n` — deliberately the roster that actually ran (post `--single` /
+ * `--siblings` filtering), never the full config roster a filtered run
+ * never attempted. A response carrying `.error` (or a missing response
+ * entry altogether) counts as absent, classified through the same
+ * `AbsentReason` vocabulary a static (pre-call) resolution failure uses, so
+ * one artefact buckets every absence — construction-time and mid-flight —
+ * under one taxonomy.
+ */
+export function _postRunQuorum(
+    members: ExternalAIClient[],
+    responses: CouncilResponse[],
+    ai_cfg: Dict,
+): { quorum: QuorumResult; absent: Dict[] } {
+    const absent: Dict[] = [];
+    let present = 0;
+    for (let i = 0; i < members.length; i++) {
+        const m = members[i] as ExternalAIClient;
+        const r = responses[i];
+        // Round 7 § 5.2 — attendance is a NON-EMPTY answer, not the absence of an
+        // error. `!r.error` alone counted a member that returned zero bytes, and
+        // that is not hypothetical: a 290 s curl timeout returned an empty body
+        // with no error set in two sessions (`9fc9ba3e`, `4ac2f7ac`) and the
+        // banner printed `2/2 present` — a single-voice verdict presented as
+        // convergence, on a paid run. An empty answer contributes nothing to a
+        // quorum by definition, whatever the transport thought of it.
+        if (r !== undefined && !r.error && r.text.trim() !== '') {
+            present += 1;
+            continue;
+        }
+        const raw = r?.error ?? (r !== undefined && r.text.trim() === '' ? 'empty response body' : 'no response');
+        const failure = classifyCliFailure(raw);
+        absent.push({
+            member: m.name,
+            reason: absentReasonFromCliFailure(failure) ?? 'unavailable',
+            detail: raw,
+        });
+    }
+    return { quorum: evaluateQuorum(members.length, present, _quorum_setting_from(ai_cfg)), absent };
+}
+
+/**
+ * One-line k-of-n banner, mirrored from `orchestrator.ts::_render_quorum_line`
+ * but for the CLI's own stdout stream rather than the rendered report —
+ * "attendance is telemetry, never a silent drop" applies to the estimate
+ * preview too, not only to a completed pass.
+ */
+export function _format_quorum_line(q: QuorumResult, phase?: QuorumEventPhase): string {
+    // The phase tag is not decoration. A degraded run prints attendance TWICE —
+    // the pre-run reading before the estimate table, the post-run reading after
+    // the consult — and the two disagree by construction: `2/2 present …
+    // concluded` then `0/2 present … INCONCLUSIVE`. Same prefix, opposite
+    // content, and until 2026-08-12 neither line said which was which, so an
+    // operator skimming (or anything grepping `council:quorum ·`) could take the
+    // stale one. The event log had solved this from the start with an explicit
+    // `phase` field; stdout had not. Optional, because the estimate path prints
+    // exactly one line and a tag there would claim a distinction it does not make.
+    const tag = phase === undefined ? '' : `${phase === 'pre_run' ? 'before the run' : 'after the run'} · `;
+    const verdict = q.status === 'concluded' ? 'concluded' : 'INCONCLUSIVE — release gate holds';
+    // Round 7 § 5.3 — a degraded pass says so. `1/2 present, needed 1 —
+    // concluded` is literally true and reads as agreement; with a threshold of 1
+    // a solo answer concludes, and nothing in the line distinguishes "both
+    // members agreed" from "one member answered". The counts were always there;
+    // what was missing is the word that stops a reader inferring convergence.
+    const degraded =
+        q.present < q.total ? `  ⚠️  DEGRADED — ${String(q.total - q.present)} member(s) did not answer; this is not convergence.` : '';
+    return `council:quorum · ${tag}${q.present}/${q.total} present, needed ${q.threshold} — ${verdict}.${degraded}`;
+}

package/src/scripts/ai_team/team_dispatch.ts

@@ -43,9 +43,11 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import {
+    CLI_CONSUMER_TEAM,
     type CouncilResponse,
     load_cli_call_counts,
     OpenAICliClient,
+    QUOTA_SOURCE_PROVIDER,
 } from '../ai_council/clients.js';
 import {
     checkCodexAvailability,
@@ -361,7 +363,9 @@ export interface TeamReviewFinding {
 }
 
 export interface TeamReviewQuota {
-    /** Today's openai-bucket call count AFTER this run. */
+    /** The shared-bucket key this run books into — read from the client, not assumed. */
+    readonly provider: string;
+    /** Today's call count in that bucket AFTER this run. */
     readonly used: number;
     /** `ai_team.max_calls_per_day` — the team-side ceiling on the shared bucket. */
     readonly ceiling: number;
@@ -549,9 +553,23 @@ export interface RunTeamReviewOptions {
     halted?: boolean;
 }
 
-function _quota_snapshot(config: AiTeamConfig, cli_calls_path: string | null): TeamReviewQuota {
+/**
+ * Read the bucket this run actually books into.
+ *
+ * `provider` comes from the CLIENT (`client.name`), never from a literal. It was
+ * hardcoded to `'openai'`, which happened to be correct because
+ * `TeamReviewCliClient extends OpenAICliClient` — and would have gone silently
+ * wrong the moment the team transport moved, reporting a bucket nobody was
+ * booking while the real one filled up. A report that names its own subject
+ * cannot drift away from it.
+ */
+function _quota_snapshot(
+    config: AiTeamConfig,
+    cli_calls_path: string | null,
+    provider: string,
+): TeamReviewQuota {
     const counts = load_cli_call_counts(cli_calls_path);
-    return { used: counts['openai'] ?? 0, ceiling: config.max_calls_per_day };
+    return { provider, used: counts[provider] ?? 0, ceiling: config.max_calls_per_day };
 }
 
 function _envelope_from_response(
@@ -571,9 +589,19 @@ function _envelope_from_response(
                 'codex CLI auth failed (auth_expired) — run `codex login`, then retry. ' +
                 'No review was produced.';
         } else if (response.error === 'cli_quota_exhausted') {
+            // `cli_quota_exhausted` covers two events with opposite remedies, so
+            // the message must not assert one of them unconditionally. "Resets at
+            // UTC midnight" is true only of OUR counter; when the vendor refused
+            // us, their window governs and we do not know it.
             blocking_reason =
-                `daily cli-call quota exhausted for the shared openai bucket ` +
-                `(${quota.used}/${quota.ceiling}) — resets at UTC midnight. No review was produced.`;
+                response.metadata?.['quota_source'] === QUOTA_SOURCE_PROVIDER
+                    ? `the ${quota.provider} CLI refused the call as over its own quota ` +
+                      `(local bucket ${quota.used}/${quota.ceiling}) — the provider's window ` +
+                      'governs, not ours. No review was produced.'
+                    : `daily cli-call quota exhausted for the shared ${quota.provider} bucket ` +
+                      `(${quota.used}/${quota.ceiling}) — resets at UTC midnight, or clear it with ` +
+                      '`agent-config council:quota --reset <provider> --confirm`. ' +
+                      'No review was produced.';
         } else {
             blocking_reason = `codex CLI transport failed: ${response.error}. No review was produced.`;
         }
@@ -649,10 +677,16 @@ export function run_team_review(opts: RunTeamReviewOptions = {}): TeamReviewRunR
                   model: config.model,
                   max_calls_per_day: config.max_calls_per_day,
                   cli_calls_path,
+                  // The team half of the two enumerated consumers of the shared
+                  // counter. Declared here because the client cannot know its
+                  // caller — the bucket standing at 171 calls with zero recorded
+                  // council exchanges is precisely what an unattributed counter
+                  // cannot explain.
+                  consumer: CLI_CONSUMER_TEAM,
               });
 
     const response = client.ask(TEAM_REVIEW_SYSTEM_PROMPT, render_review_user_prompt(bundle));
-    const quota = _quota_snapshot(config, cli_calls_path);
+    const quota = _quota_snapshot(config, cli_calls_path, client.name);
     const envelope = _envelope_from_response(response, bundle, quota);
     out(JSON.stringify(envelope, null, 2));
     return { mode: 'call', header, bundle, envelope };

package/src/scripts/build_archive_index.ts

@@ -45,6 +45,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
 import { parse_frontmatter } from './validate_frontmatter.js';
 
@@ -217,12 +218,24 @@ export function archiveFiles(dir: string): string[] {
         .sort();
 }
 
-export function buildIndex(dir: string): ArchiveEntry[] {
-    return archiveFiles(dir).map((name) =>
+/**
+ * Build entries from an enumeration the CALLER already performed.
+ *
+ * Split out so the ledger's plan and the results can come from ONE walk. With
+ * two walks, a file created between them reports as a skip that never happened
+ * and a file deleted between them yields an entry that was never planned — the
+ * plan would describe a different directory state than the results.
+ */
+export function buildIndexFrom(dir: string, names: readonly string[]): ArchiveEntry[] {
+    return names.map((name) =>
         buildEntry(name.replace(/\.md$/, ''), fs.readFileSync(path.join(dir, name), 'utf8')),
     );
 }
 
+export function buildIndex(dir: string): ArchiveEntry[] {
+    return buildIndexFrom(dir, archiveFiles(dir));
+}
+
 /** Table-cell text: pipes escaped, newlines flattened, never empty. */
 function _cell(value: string | null): string {
     if (value === null) {
@@ -309,7 +322,44 @@ export function main(argv: readonly string[]): number {
     const quiet = argv.includes('--quiet');
     const dir = path.join(ROOT, ARCHIVE_REL);
 
-    const entries = buildIndex(dir);
+    // ONE walk feeds both the plan and the results.
+    //
+    // Planning the result set and completing it in the next statement would make
+    // `planned === completed, skipped=0` true by construction — an accounting
+    // line that can never report anything. Planning a SECOND walk is only
+    // marginally better: it describes a directory state the results did not come
+    // from. Enumerating once and passing that list into the builder makes the
+    // gap real — the natural future fix for an unreadable archive file is a
+    // `try/catch { continue }` in the builder, and that file then shows up here
+    // as a skip instead of vanishing.
+    //
+    // `not-extractable` is a real reading rather than a skip and therefore
+    // completes — but a frontmatter PARSE failure is swallowed by `_frontmatter`
+    // and zeroes title/verdict/status, which is a genuine per-target degrade the
+    // disposition tally cannot show. Both are visible here as the difference
+    // between the planned and completed sets.
+    const walked = archiveFiles(dir);
+    const entries = buildIndexFrom(dir, walked);
+    const planned = walked.map((f) => path.basename(f, '.md'));
+    const produced = new Set(entries.map((e) => e.slug));
+    const ledger = new GateLedger('build_archive_index');
+    ledger.plan(planned);
+    for (const slug of planned) {
+        // `check_did_not_run`, not `no_applicable_files`: the file IS one the
+        // check applies to — the entry build did not produce a reading for it.
+        if (produced.has(slug)) ledger.complete(slug);
+        else ledger.skip(slug, 'check_did_not_run');
+    }
+    // A produced entry outside the plan means the two sets came apart despite
+    // the single walk; the ledger would under-state the denominator silently.
+    const unplanned = [...produced].filter((s) => !planned.includes(s));
+    if (unplanned.length > 0) {
+        throw new Error(
+            `build_archive_index: ${String(unplanned.length)} entry/entries were produced but never ` +
+                `planned (${unplanned.slice(0, 5).join(', ')}) — the ledger denominator is wrong.`,
+        );
+    }
+
     try {
         reportScanned({
             gate: 'build_archive_index',
@@ -325,6 +375,15 @@ export function main(argv: readonly string[]): number {
         throw err;
     }
 
+    // Reported before the `--check` and write paths branch, so both publish the
+    // same accounting. NOT on all three: the earliest exit — `reportScanned`
+    // throwing `DeadScopeError` on an empty walk — returns above this line and
+    // reports nothing, which is the one exit where the accounting would say the
+    // most. Left as-is rather than papered over: the ledger has no targets to
+    // report there either, and moving it above the scope assertion would publish
+    // a plan for a root the assertion is about to reject.
+    ledger.report();
+
     const mdPath = path.join(dir, INDEX_MD);
     const jsonPath = path.join(dir, INDEX_JSON);
     const md = renderMarkdown(entries);