@event4u/agent-config 14.23.0 → 16.0.0

package/src/scripts/_lib/ratification_artifact.ts

@@ -0,0 +1,278 @@
+/**
+ * The ratification artifact — ADR-268 § 4's control, in one reader.
+ *
+ * ADR-268 § 4 permits an agent to edit kernel rules, governance hooks and
+ * authority schemas inside an authorised mission, and forbids it to ratify its
+ * own increase in power:
+ *
+ * ```
+ * AN AGENT MAY MODIFY ITS CONSTITUTION. IT MAY NOT RATIFY ITS OWN INCREASE IN POWER.
+ * THE PARTY GAINING THE AUTHORITY IS NEVER THE PARTY RECORDING THE RATIFICATION.
+ * PROVIDER DIVERSITY IS REQUIRED WHERE TWO PROVIDERS ARE CONFIGURED.
+ * ```
+ *
+ * That sentence is the whole reason this module exists as a pure reader with
+ * no filesystem and no network: the gate that reds a PR
+ * (`check_kernel_edit_ratified`) and the tests that prove it reds must decide
+ * from the same code, or the fixture proves a second implementation rather
+ * than the shipped one.
+ *
+ * Why `reviewed_by` is checked against BOTH producer fields.
+ * `road-to-typed-grants-that-persist` Phase 5.1 names one fixture — an
+ * artifact whose `proposed_by` equals its `reviewed_by` is rejected. The Iron
+ * Law above is broader than that fixture: the party gaining the authority is
+ * the party that proposed the expansion AND the party that implemented it, and
+ * an artifact reviewed by its own implementer is the same defect wearing the
+ * other field's name. Both are rejected, and this paragraph is why the code is
+ * wider than the step that asked for it.
+ *
+ * What this module does NOT decide: whether a diff is authority-EXPANDING.
+ * That is a judgement over rule prose, not a property of the artifact, and
+ * ADR-268 § 4 makes the artifact required for the expanding case only.
+ * `check_kernel_edit_ratified` requires the artifact for every kernel-rule
+ * diff instead — a strictly stronger and decidable rule — and says so in its
+ * own header rather than pretending to classify.
+ */
+
+import { readAdrFrontmatter, type AdrFrontmatter } from './adr_frontmatter.js';
+
+/** Where a ratification artifact lives. One directory, so the gate can find it. */
+export const RATIFICATION_DIR = 'agents/evidence/ratifications';
+
+/**
+ * The verdict vocabulary — closed, because an open one is a free-text field
+ * that always reads as approval to a grep.
+ */
+export const RATIFICATION_VERDICTS = [
+    'ratified',
+    'confirmed-non-expanding',
+    'refused',
+    'non-convergent',
+] as const;
+export type RatificationVerdict = (typeof RATIFICATION_VERDICTS)[number];
+
+/**
+ * The two verdicts that let a diff land.
+ *
+ * `confirmed-non-expanding` exists because the gate demands an artifact for
+ * EVERY kernel and governance-hook diff, including a typo fix. Calling that a
+ * ratification of an authority expansion would be false, and a vocabulary that
+ * forces a false label is a vocabulary people route around. Adopted from the
+ * round-1 review, which named the pressure this relieves.
+ */
+export const PASSING_VERDICTS: ReadonlySet<string> = new Set([
+    'ratified',
+    'confirmed-non-expanding',
+]);
+
+/** The six fields Phase 5.1 names, all required. */
+export const RATIFICATION_FIELDS = [
+    'proposed_by',
+    'implemented_by',
+    'reviewed_by',
+    'providers',
+    'verdict',
+    'effective_after',
+] as const;
+
+export interface RatificationArtifact {
+    proposed_by: string;
+    implemented_by: string;
+    reviewed_by: string;
+    /** Provider ids consulted, in source order. Diversity is counted over this. */
+    providers: string[];
+    verdict: RatificationVerdict;
+    /** `merge`, or an ISO-8601 instant. Never a bare "later". */
+    effective_after: string;
+}
+
+export interface RatificationProblem {
+    /** Stable code, so a test asserts the reason rather than the wording. */
+    code:
+        | 'no-frontmatter'
+        | 'missing-field'
+        | 'unknown-verdict'
+        | 'self-ratified'
+        | 'no-providers'
+        | 'diversity-required'
+        | 'diversity-unverifiable'
+        | 'bad-effective-after';
+    message: string;
+}
+
+export interface RatificationReading {
+    artifact: RatificationArtifact | null;
+    problems: RatificationProblem[];
+}
+
+/** `merge`, or an ISO-8601 instant with a timezone. */
+const EFFECTIVE_AFTER_RE =
+    /^(merge|\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2}))$/;
+
+function scalarOf(fm: AdrFrontmatter, key: string): string | null {
+    const raw = fm.scalars[key];
+    if (typeof raw !== 'string') {
+        return null;
+    }
+    const trimmed = raw.trim();
+    return trimmed === '' ? null : trimmed;
+}
+
+/**
+ * Read `providers` in either shape the frontmatter parser can produce — a YAML
+ * list (nested) or an inline `[a, b]` scalar. Accepting both is not laxity:
+ * the ADR frontmatter corpus already carries both shapes for `basis`, and a
+ * reader that took only one would reject a correctly-authored artifact.
+ */
+export function readProviders(fm: AdrFrontmatter): string[] {
+    const nested = fm.nested['providers'];
+    if (Array.isArray(nested)) {
+        return nested.map((p) => String(p).trim()).filter((p) => p !== '');
+    }
+    const scalar = scalarOf(fm, 'providers');
+    if (scalar === null) {
+        return [];
+    }
+    return scalar
+        .replace(/^\[|\]$/g, '')
+        .split(',')
+        .map((p) => p.trim().replace(/^["']|["']$/g, ''))
+        .filter((p) => p !== '');
+}
+
+/**
+ * Validate one artifact's text.
+ *
+ * `configuredProviders` is the count `agent-config council:status` reports.
+ * Pass `null` when it could not be established — the diversity rule then does
+ * not fire, and the caller says so, because an unmeasured count is not
+ * evidence that diversity was unavailable.
+ */
+export function readRatification(
+    text: string,
+    configuredProviders: number | null,
+): RatificationReading {
+    const problems: RatificationProblem[] = [];
+    const fm = readAdrFrontmatter(text);
+    if (fm === null) {
+        return {
+            artifact: null,
+            problems: [{ code: 'no-frontmatter', message: 'no YAML frontmatter block' }],
+        };
+    }
+
+    const providers = readProviders(fm);
+    const values: Record<string, string | null> = {};
+    for (const field of RATIFICATION_FIELDS) {
+        if (field === 'providers') {
+            continue;
+        }
+        values[field] = scalarOf(fm, field);
+        if (values[field] === null) {
+            problems.push({ code: 'missing-field', message: `missing or empty \`${field}:\`` });
+        }
+    }
+    if (providers.length === 0) {
+        problems.push({ code: 'no-providers', message: 'missing or empty `providers:`' });
+    }
+
+    const verdict = values['verdict'] ?? null;
+    if (verdict !== null && !(RATIFICATION_VERDICTS as readonly string[]).includes(verdict)) {
+        problems.push({
+            code: 'unknown-verdict',
+            message: `verdict \`${verdict}\` is not one of ${RATIFICATION_VERDICTS.join(', ')}`,
+        });
+    }
+
+    const effective = values['effective_after'] ?? null;
+    if (effective !== null && !EFFECTIVE_AFTER_RE.test(effective)) {
+        problems.push({
+            code: 'bad-effective-after',
+            message: `effective_after \`${effective}\` is neither \`merge\` nor an ISO-8601 instant`,
+        });
+    }
+
+    // The Iron Law. Checked against both producer fields — see the header.
+    const reviewer = values['reviewed_by'];
+    if (reviewer !== null) {
+        for (const producerField of ['proposed_by', 'implemented_by'] as const) {
+            const producer = values[producerField];
+            if (producer !== null && producer === reviewer) {
+                problems.push({
+                    code: 'self-ratified',
+                    message:
+                        `\`${producerField}\` equals \`reviewed_by\` (${reviewer}) — ` +
+                        'the party gaining the authority may not record the ratification (ADR-268 section 4)',
+                });
+            }
+        }
+    }
+
+    // Diversity, against the REQUIRED count.
+    //
+    // Round 1 refused the previous shape: the count came from the user-global
+    // council config, which is absent on a CI runner, so the rule silently did
+    // not fire there. `null` now means the required count could not be
+    // established, and that is a REFUSAL rather than a skip — a control that
+    // passes when it cannot measure is advisory.
+    if (configuredProviders === null) {
+        problems.push({
+            code: 'diversity-unverifiable',
+            message:
+                'the required provider count could not be read, so diversity is unverifiable — ' +
+                'a control that cannot measure fails closed (src/config/ratification-policy.json)',
+        });
+    } else if (configuredProviders >= 2) {
+        const distinct = new Set(providers);
+        if (distinct.size < configuredProviders) {
+            problems.push({
+                code: 'diversity-required',
+                message:
+                    `${configuredProviders} distinct providers are required; ` +
+                    `the artifact names ${distinct.size} (${providers.join(', ') || 'none'})`,
+            });
+        }
+    }
+
+    if (problems.length > 0) {
+        return { artifact: null, problems };
+    }
+
+    return {
+        artifact: {
+            proposed_by: values['proposed_by'] as string,
+            implemented_by: values['implemented_by'] as string,
+            reviewed_by: reviewer as string,
+            providers,
+            verdict: verdict as RatificationVerdict,
+            effective_after: effective as string,
+        },
+        problems: [],
+    };
+}
+
+/** True when the artifact parses and carries a verdict that lets the diff land. */
+export function isRatified(reading: RatificationReading): boolean {
+    return reading.artifact !== null && PASSING_VERDICTS.has(reading.artifact.verdict);
+}
+
+/**
+ * The required distinct-provider count, from the repository's own policy file.
+ *
+ * Returns `null` when the file is missing or unparseable, and the caller turns
+ * that into a refusal — never a skip. Reading the policy from the repository
+ * rather than from the user-global council config is the round-1 fix: a runner
+ * has the repository and does not have the operator's home directory.
+ */
+export function readRequiredProviders(policyText: string | null): number | null {
+    if (policyText === null) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(policyText) as { required_providers?: unknown };
+        const n = parsed.required_providers;
+        return typeof n === 'number' && Number.isInteger(n) && n >= 1 ? n : null;
+    } catch {
+        return null;
+    }
+}

package/src/scripts/_lib/release_findings_ingest.ts

@@ -0,0 +1,324 @@
+/**
+ * The release's side of the findings-ledger contract: verification, not
+ * production.
+ *
+ * WHY THE CONTRACT EXISTS. The findings ledger is the durable record a release
+ * makes about what its own review found, and `check_finding_dispositions`
+ * treats an absent one for a SHIPPED version as a failure — repo-wide, because
+ * the same check runs on every pull request. Producing it was documented and
+ * unowned: the self-review workflow uploaded an artifact and its own comment
+ * said a human should run `--ingest`. Nobody did, so the ledger went missing
+ * once per release, six times between 14.19.0 and 15.0.0, and each absence was
+ * cleared by whoever happened to be pushing an unrelated change.
+ *
+ * WHY THE INGEST IS NOT HERE. Two review rounds established that no placement
+ * inside `release.ts` works. `finding-dispositions` runs on the release PR and
+ * reds while the ledger lacks a finding the review reported, so a step that
+ * produced the ledger after the check wait could never run — the wait had
+ * already died on that red check — and a step that produced it before the wait
+ * pushed a commit the wait then had to redo, on a head whose checks had not
+ * started. The owner's decision on 2026-09-11 was to move the ingest into the
+ * workflow that already holds the artifact, which is the one place where the
+ * ledger can exist before any gate looks for it.
+ *
+ * WHY THE PUSH NEEDS A PAT. A third review round found that the move alone did
+ * not fix the ordering, it relocated it: the ingest job is a check run of the
+ * same `pull_request` event, so its push lands inside the release's own check
+ * wait — and a push authenticated with GITHUB_TOKEN creates no run, leaving a
+ * head with zero checks against a protection that requires one. The job pushes
+ * with `RELEASE_PR_TOKEN` instead, the pattern `release.yml` already uses, so
+ * the push produces the checks the wait is waiting for. Without that secret the
+ * job declines to push at all rather than produce the deadlock, and the absence
+ * arrives here as a missing ledger with the cause named.
+ *
+ * WHAT IS LEFT HERE. Two questions and a stop for each: is the ledger on the
+ * REMOTE branch, and does the disposition gate pass. Neither is repaired by
+ * the release — filling a disposition states what the release ships, with a
+ * rationale and a named verifier, and no automation writes one.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { isBlocking, parse_ledger } from '../check_finding_dispositions.js';
+
+
+/** Where a release's ledger lives, relative to the repository root. */
+export function ledgerRelPath(version: string): string {
+    return `agents/evidence/release-findings/${version}.json`;
+}
+
+/**
+ * The workflow that produces and commits the ledger, named so a message can
+ * point the operator at the right run log.
+ *
+ * A rename there without one here is caught by
+ * `release_findings_ingest.test.ts`, which reads the workflow file rather than
+ * trusting this string.
+ */
+export const FINDINGS_WORKFLOW = 'self-review-gate.yml';
+
+/**
+ * Argv proving the ledger is on the REMOTE branch — the only ref that answers
+ * the question the release is asking.
+ *
+ * Three refs give three different answers and only one is right. The working
+ * tree says "a file exists here", which a by-hand ingest also satisfies. The
+ * LOCAL branch ref says "a commit here carries it", which a commit that failed
+ * to push has already made true — so probing it answers identically to the
+ * filesystem in exactly the case the probe exists for, which is the defect a
+ * second review round caught in the first attempt at this fix. The
+ * remote-tracking ref is the one that goes false when a push fails, and the
+ * merge reads the remote.
+ *
+ * `remote` is a parameter rather than a constant so a fork or a mirror is not
+ * silently assumed to be `origin`.
+ */
+export function ledgerOnBranchArgv(remote: string, branch: string, rel: string): string[] {
+    return ['cat-file', '-e', `${remote}/${branch}:${rel}`];
+}
+
+/**
+ * Why the release refuses to continue without a ledger on the branch.
+ *
+ * Continuing would merge and tag with no ledger, and an absent ledger becomes a
+ * repo-wide failure the moment the tag exists — that is the six-release failure
+ * this mechanism ends, so it is a stop rather than a warning.
+ *
+ * The causes are named because the operator has to pick one and most of them
+ * are ordinary. With the ingest in CI, "it has not happened yet" is the common
+ * case and waiting is the answer; a repository without the review secret never
+ * gets one at all and needs the ledger by hand, once per release, which is a
+ * real cost and is stated here rather than discovered.
+ */
+export function ledgerAbsentMessage(version: string, branch: string, remote: string): string {
+    return (
+        `${ledgerRelPath(version)} is not on ${remote}/${branch}.\n` +
+        '  The release stops: continuing would merge and tag with no findings ledger, and an ' +
+        'absent ledger for a shipped version reds every pull request in the repository.\n' +
+        `  The ${FINDINGS_WORKFLOW} workflow commits it to the release branch once it has ` +
+        'reviewed the head. Ordinary causes, in the order to check them: the review has not ' +
+        'finished yet (wait, then resume); the review found nothing and its commit is still in ' +
+        'flight (same); no ANTHROPIC_API_KEY, so no review ran and no ledger will appear — write ' +
+        `one with a no_findings_reason and push it to ${branch}; no RELEASE_PR_TOKEN, in which ` +
+        'case the job refuses to push rather than deadlock this wait and says so as a warning in ' +
+        'its run log — configure the PAT, or write the ledger by hand; or the workflow could not ' +
+        'push, which its run log will say.\n' +
+        '  Then: `git pull` on the release branch, and resume.'
+    );
+}
+
+/**
+ * Why the release refuses to continue when the PR is already merged and the
+ * ledger is not on the trunk either.
+ *
+ * This is the state the whole mechanism exists to prevent, reached the one way
+ * that survives every guard before it: the ingest produced nothing, step 7
+ * stopped, and the PR was merged by hand anyway. A resumed run then finds
+ * `state === 'MERGED'` and — until this check existed — printed "the ledger
+ * rode in with it" without reading anything, tagged, and published. The absent
+ * ledger for a shipped version is what reds every pull request in the
+ * repository, so the assertion had to become a question.
+ *
+ * The release branch is gone by now, so there is no workflow run left to wait
+ * for: the remaining path is a ledger written onto the trunk by hand.
+ */
+export function ledgerAbsentAfterMergeMessage(
+    version: string,
+    trunk: string,
+    remote: string,
+): string {
+    return (
+        `${ledgerRelPath(version)} is on neither the release branch nor ${remote}/${trunk}, and ` +
+        'the release pull request is already merged.\n' +
+        '  The release stops: tagging now ships a version whose findings ledger does not exist, ' +
+        'and an absent ledger for a shipped version reds every pull request in the repository.\n' +
+        `  The release branch is gone, so the ${FINDINGS_WORKFLOW} run that would have committed ` +
+        'the ledger cannot be waited for. Write the ledger on the trunk instead — the review for ' +
+        'this version is in its own workflow run, or record a no_findings_reason if none ran — ' +
+        'push it, and resume.'
+    );
+}
+
+/**
+ * The message a release stops with when the disposition gate refuses.
+ *
+ * `blocking` is what the release could count itself: findings that are blocking
+ * and carry no `status`. It is deliberately NOT presented as the reason — the
+ * gate refuses for more shapes than that (an unknown status, an empty rationale
+ * or verifier, a `fixed` with no commit, a malformed ledger, an undeterminable
+ * release status), and an earlier version of this message asserted "N blocking
+ * … carry no disposition" for every one of them. At N = 0 that produced an
+ * instruction nobody could follow.
+ *
+ * So the gate's own output is the reason, passed in and printed, and this text
+ * only says where the file is, why the release stopped, and how to resume.
+ */
+export function dispositionStopMessage(
+    version: string,
+    gateOutput: string,
+    blocking: number,
+    resumeCmd: string,
+): string {
+    const count =
+        blocking > 0 ? `  ${blocking} of them are blocking findings with no status yet.\n` : '';
+    return (
+        `the disposition gate refuses ${version}. Its own report:\n` +
+        `${gateOutput.trim() || '  (the gate printed nothing — run it directly to see why)'}\n` +
+        count +
+        `  The ledger is at ${ledgerRelPath(version)} and the release stops here by design: a ` +
+        'disposition is an adjudication of what this release ships, with a rationale and a ' +
+        'named verifier, and no automation may write one.\n' +
+        `  Resolve what the report names, push the release branch, then: ${resumeCmd}`
+    );
+}
+
+/** The release's own subprocess result shape, mirrored so this module stays free of it. */
+interface StepRunResult {
+    returncode: number;
+    stdout: string;
+    stderr: string;
+}
+
+/**
+ * What the step needs from the release script, injected rather than imported.
+ *
+ * `release.ts` sits past the source-size cap where every line is charged, and
+ * this step is the release's side of the contract this module already owns — so
+ * it lives here. Injection rather than an import of `release_publication.ts`
+ * keeps `_lib` free of a dependency on its own caller.
+ */
+export interface LedgerStepDeps {
+    run: (argv: string[], opts: { check: boolean; capture: boolean }) => StepRunResult;
+    die: (msg: string) => never;
+    /** Prints the step banner, so the caller keeps the step number. */
+    step: (msg: string) => void;
+    /** Where the step reports the ref it read. */
+    write: (s: string) => void;
+    /** Absolute repository root, for resolving the ledger on disk. */
+    repoRoot: string;
+    /** Remote name, never assumed to be `origin`. */
+    remote: string;
+    /** The trunk the release merges into — the ref to ask once the branch is gone. */
+    trunk: string;
+    /**
+     * The PR number for `--pr`, resolved late.
+     *
+     * Late because the release probes its PR once at the top and only on a
+     * resumed run, so on a first run the number was null here and `--pr` was
+     * silently dropped — and the release then passed a strictly weaker check
+     * than `finding-dispositions`, learning about an un-ingested finding from
+     * CI instead. By the time this step runs the PR exists either way.
+     */
+    resolvePr: () => number | null;
+}
+
+/**
+ * Verify the release carries its own findings ledger, or stop.
+ *
+ * VERIFIES, NEVER PRODUCES — the why is the module docstring above. Placed
+ * between the check wait and the merge: the ledger lives on the release branch
+ * and the merge deletes it, so this is the last moment the question means
+ * anything, and after the wait so a red `finding-dispositions` has already
+ * stopped the release with the check's own name rather than a duplicate of it.
+ *
+ * Two questions, each answered with a stop:
+ *
+ *   1. Is the ledger on the ref the merge will read? On an open PR that is the
+ *      remote release branch; once the PR is merged the branch is deleted and
+ *      the ledger, if it was ever produced, rode into the trunk. The merged
+ *      path used to ask nothing and assert the good case.
+ *   2. Does the disposition gate pass, in `--pr` mode — the same mode CI uses,
+ *      so the release cannot pass a weaker check than the one it is trying to
+ *      pre-satisfy.
+ *
+ * Neither answer is repaired here. Filling a disposition states what the release
+ * ships, with a rationale and a named verifier; no automation writes one.
+ */
+export function settleFindingsLedger(
+    deps: LedgerStepDeps,
+    version: string,
+    branch: string,
+    merged: boolean,
+): void {
+    deps.step(
+        merged
+            ? 'Verify the findings ledger rode in with the merge'
+            : 'Verify the self-review findings ledger',
+    );
+    const rel = ledgerRelPath(version);
+    const ref = merged ? deps.trunk : branch;
+
+    // REFRESH BEFORE READING, AND FAST-FORWARD BEFORE ASKING THE GATE. Both
+    // halves are a defect a fourth review measured, and they are the same
+    // defect seen from two sides. `cat-file -e <remote>/<ref>:<path>` reads
+    // `.git`, not GitHub — and nothing in a first run refreshes that
+    // remote-tracking ref after CI commits the ledger: preflight fetches before
+    // the branch exists, and step 4's push sets the ref to the pushed commit,
+    // which is strictly older than the ledger commit. So the probe answered
+    // "absent" on every first release. The disposition gate then reads the
+    // WORKING TREE, which the same push left equally stale, so a fetch alone
+    // would fix the probe and hand the gate an empty ledger instead.
+    //
+    // `--ff-only` on purpose: the release pushed this ref itself, so the only
+    // commit ahead of it should be CI's. Anything else means the branch moved
+    // under the run, and stopping is better than merging a tree nobody read.
+    // Both are `check: false` — a fetch that fails leaves the probe to report
+    // the absence with a message that says what to do.
+    deps.run(['git', 'fetch', deps.remote, ref], { check: false, capture: true });
+    deps.run(['git', 'pull', '--ff-only', deps.remote, ref], { check: false, capture: true });
+
+    const onBranch =
+        deps.run(['git', ...ledgerOnBranchArgv(deps.remote, ref, rel)], {
+            check: false,
+            capture: true,
+        }).returncode === 0;
+    if (!onBranch) {
+        deps.die(
+            merged
+                ? ledgerAbsentAfterMergeMessage(version, deps.trunk, deps.remote)
+                : ledgerAbsentMessage(version, branch, deps.remote),
+        );
+    }
+    deps.write(`    ledger on ${deps.remote}/${ref}: ${rel}\n`);
+
+    const argv = ['./scripts-run', 'src/scripts/check_finding_dispositions', '--release', version];
+    const pr = deps.resolvePr();
+    if (pr !== null) {
+        argv.push('--pr', String(pr));
+    }
+    const verdict = deps.run(argv, { check: false, capture: true });
+    if (verdict.returncode !== 0) {
+        deps.die(
+            dispositionStopMessage(
+                version,
+                // BOTH streams. The gate writes its scan line to stdout and its
+                // per-finding diagnosis to stderr, so preferring stdout showed
+                // the operator `scanned: N` and discarded the entire reason the
+                // release stopped.
+                [verdict.stdout, verdict.stderr].map((s) => s.trim()).filter(Boolean).join('\n'),
+                blockingWithoutDisposition(path.join(deps.repoRoot, rel)),
+                'task release -- --resume --yes',
+            ),
+        );
+    }
+}
+
+/**
+ * How many blocking findings carry no status — a figure for the stop message,
+ * never the reason for it.
+ *
+ * The gate refuses for more shapes than this counts (an unknown status, an
+ * empty rationale or verifier, a `fixed` with no commit, a malformed ledger),
+ * which is why the gate's own output is what the operator is shown.
+ */
+function blockingWithoutDisposition(ledgerAbs: string): number {
+    if (!fs.existsSync(ledgerAbs)) {
+        return 0;
+    }
+    try {
+        const ledger = parse_ledger(fs.readFileSync(ledgerAbs, 'utf-8'), ledgerAbs);
+        return ledger.findings.filter((f) => isBlocking(f) && !f.status).length;
+    } catch {
+        return 0;
+    }
+}

package/src/scripts/_lib/release_tag_dispatch.ts

@@ -0,0 +1,63 @@
+/**
+ * The `--ci` fallback dispatch of the three tag-triggered workflows.
+ *
+ * Extracted from `release.ts` as a lowering commit under
+ * `check_source_size_budget`, whose own contract names splitting an
+ * over-ceiling file as the improvement it exists to force. The block is
+ * self-contained — three workflow names, one loop, one warning — and nothing
+ * else in step 10 reads it.
+ *
+ * WHY IT EXISTS. A tag pushed with the default `GITHUB_TOKEN` fires no
+ * tag-triggered workflow: GitHub's recursion guard suppresses the event. All
+ * three workflows accept a `tag` input for exactly this recovery, so under
+ * `--ci` the release dispatches them rather than waiting for an event that will
+ * never arrive. When the tag was pushed with a PAT they already fired and this
+ * is redundant.
+ *
+ * WHY IT NEVER FAILS THE RELEASE. By the time it runs the release is complete —
+ * the tag is pushed, the GitHub Release is created, npm publishes
+ * asynchronously. Dispatching through the API additionally needs the token's
+ * `actions:write` scope, and a 403 for a missing scope must not mark an
+ * already-shipped release as failed. So it warns and continues.
+ */
+
+/** The tag-triggered workflows, in the order the release dispatches them. */
+export const TAG_TRIGGERED_WORKFLOWS = [
+    'release-guard.yml',
+    'publish-npm.yml',
+    'cloud-release.yml',
+] as const;
+
+interface DispatchRunResult {
+    returncode: number;
+}
+
+export interface TagDispatchDeps {
+    run: (argv: string[], opts: { check: boolean }) => DispatchRunResult;
+    /** Where a non-fatal dispatch failure is reported. */
+    warn: (s: string) => void;
+    /** The ref the dispatch runs against — the trunk. */
+    trunk: string;
+}
+
+/** Why one failed dispatch is a warning and not a stop, said to the operator. */
+export function dispatchWarning(workflow: string, code: number, version: string): string {
+    return (
+        `⚠️  Could not dispatch ${workflow} (exit ${code}) — the release ${version} is ` +
+        `already complete (tag + GitHub Release created; npm publishes async). If the tag was ` +
+        `pushed with a PAT, ${workflow} already fired on the tag push. If you rely on the explicit ` +
+        `dispatch, grant RELEASE_PR_TOKEN the "Actions: read and write" scope (fine-grained PAT) ` +
+        `or the "workflow" scope (classic PAT).\n`
+    );
+}
+
+export function dispatchTagWorkflows(deps: TagDispatchDeps, version: string): void {
+    for (const wf of TAG_TRIGGERED_WORKFLOWS) {
+        const r = deps.run(['gh', 'workflow', 'run', wf, '--ref', deps.trunk, '-f', `tag=${version}`], {
+            check: false,
+        });
+        if (r.returncode !== 0) {
+            deps.warn(dispatchWarning(wf, r.returncode, version));
+        }
+    }
+}