@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/_lib/estate_offsets.ts

@@ -0,0 +1,241 @@
+/**
+ * How a CHANGE touches the roadmap estate — the diff half, read once.
+ *
+ * `check_estate_count` answers two different questions with two different
+ * inputs. The count half reads the TREE and ratchets it against the base ref's
+ * tree. This module is the other half: it reads the DIFF and says what the
+ * change did — which roadmaps entered the active top level, which left it, which
+ * of the arrivals declared an exemption, and what that exemption says.
+ *
+ * WHY IT LIVES HERE AND NOT IN THE GATE. `check_source_size_budget` scores
+ * `Σ max(0, lines(f) − 1500)` over `src/**` and the gate crossed the ceiling
+ * when the exemption-shape work landed. That gate does not object to new code;
+ * it objects to new code in the file that is already too big to read, and the
+ * ratchet was right about which file that was. The seam it forced is the one a
+ * reader would draw anyway — tree-reading on one side of it, diff-reading on the
+ * other — so the extraction is a correction rather than a concession.
+ *
+ * `exemptionReason` sits here rather than beside the vocabulary it feeds
+ * (`exemption_shape.ts`) because this is the module that READS a change; that
+ * one is the module that JUDGES a reason. The split is read-then-judge, and
+ * keeping it means the vocabulary module imports no filesystem and no git.
+ */
+import * as path from 'node:path';
+
+import {
+    is_roadmap_candidate as isRoadmapCandidate,
+    parse_frontmatter as parseFrontmatter,
+} from '../../agent-src/scripts/update_roadmap_progress.js';
+
+/** How a change touched the active roadmap tree, as git reports it. */
+export interface OffsetLedger {
+    /** Files that entered the active top level: new files, and un-parked ones. */
+    added: string[];
+    /** Files that left it: deleted, archived, parked or merged away. */
+    offsets: string[];
+    /** Added files carrying an `estate_offset_exempt:` reason, with the reason. */
+    exempt: Array<{ file: string; reason: string }>;
+    /**
+     * The subset of `offsets` that went to `later/`.
+     *
+     * Tracked separately because parking is the one offset that RAISES another
+     * gated count: active falls by one and later rises by one, which under an
+     * exact floor is growth in `later_roadmaps` unless this allowance exists.
+     * Kept out of a general "any offset raises any allowance" rule on purpose —
+     * an archived roadmap must not buy a new `later/` file.
+     */
+    parked: string[];
+}
+
+/** An `estate_growth_exempt:` reason ADDED to a roadmap in this change. */
+export interface GrowthClaim {
+    /** The roadmap the claim was added to, as git reports the path. */
+    file: string;
+    reason: string;
+}
+
+/** `agents/roadmaps/<name>.md` — the active top level. code-comment-allow provenance-comment -- operand, not provenance */
+function isActiveTopLevel(rel: string): boolean {
+    const norm = rel.split(path.sep).join('/');
+    if (!norm.startsWith('agents/roadmaps/') || !norm.endsWith('.md')) {
+        return false;
+    }
+    const tail = norm.slice('agents/roadmaps/'.length);
+    return !tail.includes('/') && isRoadmapCandidate(norm);
+}
+
+/**
+ * A disposition directory — where an offset sends a roadmap.
+ *
+ * `stubs/` is in the set, and it was missing from the first version. Un-stubbing
+ * is the documented promotion path, so a stub moved to the top level is an
+ * ADDITION that T3 must charge, and a roadmap demoted to a stub is an offset.
+ * With `stubs/` unrecognised, a promotion was classified as neither and the lint
+ * could never charge it — the one hole that let an active roadmap arrive for free.
+ */
+function isDisposed(rel: string): boolean {
+    const norm = rel.split(path.sep).join('/');
+    return /^agents\/roadmaps\/(archive|later|skipped|stubs)\//.test(norm);
+}
+
+/** A roadmap parked for later — the one disposition that grows another count. */
+function isParked(rel: string): boolean {
+    return rel.split(path.sep).join('/').startsWith('agents/roadmaps/later/');
+}
+
+/**
+ * Read the exemption reason a newly added roadmap declares, if any.
+ *
+ * The key lives in the file's own frontmatter rather than in a config or a
+ * commit trailer, for the reason `RATCHET_RESET_KEY` gives for living inside the
+ * baseline JSON: the claim then shows up in the diff of the change that makes
+ * it, and a reviewer sees it without being told to look.
+ *
+ * THE BLOCK SCALAR IS READ HERE AND NOT BY `parseFrontmatter`, which is a flat
+ * line parser with no YAML block support: it returns the value as everything
+ * after the first colon. Measured 2026-10-01 across the three roadmap trees,
+ * **38 of 221 exemptions are written `estate_offset_exempt: >-` with the reason
+ * indented beneath**, and for every one of them this function used to return
+ * the literal two-character string `>-`. That is non-empty, so the gate
+ * accepted it — a key whose whole purpose is that a reviewer sees the claim was
+ * being checked against a YAML punctuation mark on one file in six. The fix
+ * belongs here rather than in the shared parser because every other caller of
+ * that parser reads single-token values (`status`, `complexity`) where block
+ * support buys nothing and a rewrite risks the dashboard.
+ */
+export function exemptionReason(text: string): string | null {
+    const block = blockScalar(text, 'estate_offset_exempt');
+    if (block !== null) return block === '' ? null : block;
+    const fm = parseFrontmatter(text);
+    const raw = (fm as Record<string, unknown>)['estate_offset_exempt'];
+    if (typeof raw !== 'string') {
+        return null;
+    }
+    const reason = raw.trim().replace(/^["']|["']$/g, '').trim();
+    return reason === '' ? null : reason;
+}
+
+/**
+ * The folded body of `<key>: >-` / `<key>: |`, or `null` when not that form.
+ *
+ * Returns `''` — not `null` — for a block header with no body, so the caller can
+ * tell "declared and empty" from "not a block scalar". An empty block is the
+ * blank-reason case the key already refuses, and collapsing it into `null` here
+ * would send it back to the flat parser, which would hand back `>-` and accept it.
+ */
+function blockScalar(text: string, key: string): string | null {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    if (m === null) return null;
+    const lines = (m[1] as string).split(/\r?\n/);
+    const head = new RegExp(`^${key}:[ \\t]*(.*)$`);
+    for (let i = 0; i < lines.length; i += 1) {
+        const hm = head.exec(lines[i] as string);
+        if (hm === null) continue;
+        // Only the block indicators. A quoted or bare value is the flat form and
+        // stays with the flat parser, which already handles it.
+        //
+        // THE TRAILING COMMENT IS PART OF THE HEADER, and omitting it was a
+        // BYPASS rather than a parse gap. `estate_offset_exempt: >- # offset`
+        // failed this test, fell through to the flat parser, and came back as
+        // the string `">- # offset"` — which the shape rule then searched for a
+        // disposition word and found one, IN THE COMMENT, over a body it never
+        // read. The indicator may also be written `>2-` as well as `>-2`, so
+        // both orders are accepted; an indentation indicator is never `0`.
+        if (!/^[>|](?:[1-9][-+]?|[-+]?[1-9]?)(?:[ \t]+#.*)?$/.test((hm[1] as string).trim())) return null;
+        const body: string[] = [];
+        for (let j = i + 1; j < lines.length; j += 1) {
+            const line = lines[j] as string;
+            if (line.trim() === '') continue;
+            // The first unindented line ends the block — the next key.
+            if (!/^[ \t]/.test(line)) break;
+            body.push(line.trim());
+        }
+        return body.join(' ').replace(/\s+/g, ' ').trim();
+    }
+    return null;
+}
+
+/**
+ * Classify the change's effect on the active roadmap tree.
+ *
+ * Renames carry information a name-only diff loses: `road-to-x.md` →
+ * `archive/road-to-x.md` is the wanted direction and counts as an offset, while
+ * `later/road-to-x.md` → `road-to-x.md` is an un-parking and counts as an
+ * addition. A top-level-to-top-level rename is neither.
+ */
+export function classifyDiff(
+    nameStatus: string,
+    readFile: (rel: string) => string | null,
+): OffsetLedger {
+    const added: string[] = [];
+    const offsets: string[] = [];
+    const exempt: Array<{ file: string; reason: string }> = [];
+    const parked: string[] = [];
+    for (const line of nameStatus.split('\n')) {
+        if (line.trim() === '') continue;
+        const cols = line.split('\t');
+        const status = (cols[0] ?? '').trim();
+        if (status.startsWith('R') || status.startsWith('C')) {
+            const from = cols[1] ?? '';
+            const to = cols[2] ?? '';
+            if (isActiveTopLevel(from) && isDisposed(to)) {
+                offsets.push(from);
+                if (isParked(to)) parked.push(to);
+            } else if (isDisposed(from) && isActiveTopLevel(to)) {
+                added.push(to);
+            }
+            continue;
+        }
+        const file = cols[1] ?? '';
+        if (!isActiveTopLevel(file)) continue;
+        if (status === 'A') {
+            added.push(file);
+        } else if (status === 'D') {
+            offsets.push(file);
+        }
+    }
+    for (const file of added) {
+        const text = readFile(file);
+        if (text === null) continue;
+        const reason = exemptionReason(text);
+        if (reason !== null) {
+            exempt.push({ file, reason });
+        }
+    }
+    return { added, offsets, exempt, parked };
+}
+
+/**
+ * The `estate_growth_exempt:` reasons this change ADDS, read from the patch.
+ *
+ * Read from the diff rather than from the file, and that is the point: a claim
+ * sitting in a roadmap authorises nothing on a later change, so an exemption
+ * cannot be banked the way surplus in a stored baseline could. It also means a
+ * newly added roadmap and an edited one need no separate handling — in a
+ * `base...HEAD` patch both arrive as `+` lines.
+ *
+ * `--unified=0` keeps context lines out, so a claim that merely sits NEAR an
+ * edited line is not read as added. Deliberately tolerant of leading whitespace
+ * and of quoted values, matching `exemptionReason`; deliberately NOT tolerant of
+ * an empty reason, because an exemption whose reason is blank is the silent
+ * exception the key exists to replace.
+ */
+export function growthClaims(patch: string): GrowthClaim[] {
+    const out: GrowthClaim[] = [];
+    let file = '';
+    for (const line of patch.split('\n')) {
+        // `+++ b/<path>` names the file the following `+` lines belong to. The
+        // `/dev/null` form is a deletion, which cannot carry a claim.
+        const head = /^\+\+\+ b\/(.+)$/.exec(line);
+        if (head !== null) {
+            file = (head[1] ?? '').trim();
+            continue;
+        }
+        if (!line.startsWith('+') || line.startsWith('+++')) continue;
+        const m = /^\+\s*estate_growth_exempt:\s*(.+?)\s*$/.exec(line);
+        if (m === null) continue;
+        const reason = (m[1] ?? '').trim().replace(/^["']|["']$/g, '').trim();
+        if (reason !== '') out.push({ file, reason });
+    }
+    return out;
+}

package/src/scripts/_lib/exemption_shape.ts

@@ -0,0 +1,143 @@
+/**
+ * What an `estate_offset_exempt` reason has to SAY — one vocabulary, two readers.
+ *
+ * THE DEFECT THIS EXISTS TO NAME. The one-in-one-out rule charges every added
+ * active roadmap against a disposed one, and `estate_offset_exempt: <reason>`
+ * is the escape hatch that costs "one reviewable line instead of a silent
+ * exception". `exemptionReason` accepted any non-empty string, so the line was
+ * reviewable in the sense that it existed. Measured 2026-10-01 over the active,
+ * `later/` and `archive/` trees: 221 files carry the key, and 43 of them name
+ * no alternative disposition at all under the three-lemma set the roadmap named
+ * from memory, and 6 under the measured one below — including three that say only
+ * `lane N of <parent>`. The escape hatch was free.
+ *
+ * WHAT A SHAPED REASON SAYS. It names at least one disposition the author
+ * considered instead of adding a file: archiving something, parking it in
+ * `later/`, merging into an existing roadmap, or any of the words this tree
+ * actually uses for those three. The requirement is deliberately NOT "explain
+ * yourself well" — that is unjudgeable — but "name what you rejected", which is
+ * a word that is either present or absent.
+ *
+ * WHY THE VOCABULARY IS MEASURED AND NOT CHOSEN. The commissioning roadmap
+ * named three lemmas, archive / park / merge, from memory. Over the real
+ * population those three cover 178 of 221; the measured ten below cover 215.
+ * The 37-file gap is not boilerplate — "Offsetting it individually is not
+ * possible without splitting the set" and "no completed roadmap to retire
+ * against this addition" both name a rejected alternative in words the
+ * three-lemma set does not carry. A refusal vocabulary that reds one added
+ * roadmap in five on the house style gets weakened until it finds nothing, so
+ * the set here is the one the tree writes. Every number above carries its
+ * producing command: `./scripts-run src/scripts/estate_exemption_shape`.
+ *
+ * `close` is excluded on purpose, and it is the most common verb in these
+ * reasons: it almost always refers to closing WORK, not to disposing of a file,
+ * so accepting it would make the check pass on a sentence that named nothing.
+ *
+ * WHAT THIS DOES NOT DO, stated because a reviewer called it HIGH and the
+ * disagreement is worth recording rather than resolving silently. The cheapest
+ * string that passes is the single word `park`, and `park 1` / `park 2` are two
+ * distinct reasons to the duplicate rule. So this verifies that a disposition
+ * word APPEARS; it does not verify that the author thought about one, and no
+ * check can. The claim the gate's message makes is therefore "name what you
+ * rejected", which is what a word either does or does not do — not "explain
+ * yourself well", which is unjudgeable. A reason gamed down to one word is
+ * visible to a human reviewer in the diff, which is where the key's own stated
+ * purpose puts the real control; what this removes is the case where there was
+ * nothing to look at because the reason was free text nobody had read.
+ *
+ * WHY ONE MODULE. Two readers consume this — the estate gate, which refuses,
+ * and the measurement script, which reports. A second copy of the lemma list is
+ * how a gate and its own evidence drift apart, and a drifted vocabulary fails
+ * silently: the report says the tree conforms while the gate refuses it.
+ */
+
+/**
+ * The dispositions a reason may name, as source strings.
+ *
+ * Exported individually rather than as one baked regex so the measurement
+ * script can report per-lemma counts against the same list the gate refuses on.
+ */
+export const DISPOSITION_LEMMAS: readonly { readonly name: string; readonly source: string }[] = [
+    { name: 'archive', source: String.raw`archiv\w*` },
+    // `park` is the one stem with a common false friend, and a reviewer named
+    // it: `park\w*` matches `parkour` at a word boundary, so a reason saying
+    // nothing about dispositions passes on a word that is not one. Enumerated
+    // instead of stemmed — the inflections this tree writes, and no more. Every
+    // other lemma keeps its stem; none of them has a false friend in English
+    // that could plausibly appear in a sentence about roadmap dispositions.
+    { name: 'park', source: String.raw`unpark(?:ed|ing|s)?\b|park(?:ed|ing|s)?\b` },
+    { name: 'merge', source: String.raw`merg\w*` },
+    { name: 'later', source: String.raw`later\/` },
+    { name: 'offset', source: String.raw`offset\w*` },
+    { name: 'defer', source: String.raw`defer\w*` },
+    { name: 'fold', source: String.raw`fold\w*` },
+    { name: 'consolidate', source: String.raw`consolidat\w*` },
+    { name: 'absorb', source: String.raw`absorb\w*` },
+    { name: 'retire', source: String.raw`retir\w*` },
+];
+
+/** The whole vocabulary as one alternation — the gate's own test. */
+export const DISPOSITION_SOURCE = `\\b(?:${DISPOSITION_LEMMAS.map((l) => l.source).join('|')})`;
+
+const DISPOSITION_RE = new RegExp(DISPOSITION_SOURCE, 'i');
+
+/** Does this reason name at least one rejected alternative? */
+export function namesDisposition(reason: string): boolean {
+    return DISPOSITION_RE.test(reason);
+}
+
+/** Which lemmas a reason names, for the reader's per-file column. */
+export function lemmasNamed(reason: string): string[] {
+    return DISPOSITION_LEMMAS.filter((l) => new RegExp(`\\b(?:${l.source})`, 'i').test(reason)).map((l) => l.name);
+}
+
+/**
+ * The comparison key for "two added files say the same thing".
+ *
+ * Case and whitespace are folded because a reason pasted into a second file and
+ * re-wrapped by an editor is the same reason. Nothing else is folded: a reason
+ * that differs by one clause is a different reason, and a normaliser clever
+ * enough to call those equal would start refusing reasons that genuinely differ.
+ */
+export function reasonKey(reason: string): string {
+    return reason.toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+/** One added file whose exemption reason does not hold up. */
+export interface ExemptionFinding {
+    readonly file: string;
+    readonly kind: 'shapeless' | 'duplicate';
+    /** For `duplicate`, the other added file carrying the same reason. */
+    readonly twin: string | null;
+    readonly reason: string;
+}
+
+/**
+ * Judge the exemptions a single change ADDS — never the ones already in the tree.
+ *
+ * Grandfathering is load-bearing rather than polite. 43 of the 221 existing
+ * reasons name no disposition; re-reading them would land this check red on a
+ * fifth of the corpus, which is a backlog wearing a control's clothes. The
+ * input is `classifyDiff`'s exempt ledger, which by construction lists only the
+ * files this change added.
+ */
+export function exemptionFindings(
+    exempt: readonly { readonly file: string; readonly reason: string }[],
+): ExemptionFinding[] {
+    const out: ExemptionFinding[] = [];
+    const seen = new Map<string, string>();
+    for (const e of exempt) {
+        if (!namesDisposition(e.reason)) {
+            out.push({ file: e.file, kind: 'shapeless', twin: null, reason: e.reason });
+            continue;
+        }
+        const key = reasonKey(e.reason);
+        const twin = seen.get(key);
+        if (twin === undefined) {
+            seen.set(key, e.file);
+            continue;
+        }
+        out.push({ file: e.file, kind: 'duplicate', twin, reason: e.reason });
+    }
+    return out;
+}

package/src/scripts/_lib/fnv.ts

@@ -0,0 +1,23 @@
+/**
+ * FNV-1a, 32-bit — the one definition in this tree.
+ *
+ * Extracted from `rule_trigger_eval.ts`, which still re-exports it under its
+ * own name so its suite keeps importing the symbol it always did. The reason
+ * for the extraction is the reason this file carries a doc block at all: a
+ * second consumer arrived (`measure_skill_ranker_baseline`'s held-out
+ * partition), and two copies of a hash that decides which rows a measurement
+ * reads is the shape in which a partition quietly stops being the same
+ * partition. One definition, two callers.
+ *
+ * Pure — no imports, no I/O, no clock.
+ */
+
+/** FNV-1a over UTF-16 code units, returned as an unsigned 32-bit integer. */
+export function fnv1a(s: string): number {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i += 1) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h >>> 0;
+}

package/src/scripts/_lib/foreign_scan.ts

@@ -0,0 +1,106 @@
+/**
+ * The unclaimed-file scan under this package's own deploy roots.
+ *
+ * Moved verbatim out of `src/scripts/_cli/cmd_doctor.ts`
+ * (road-to-a-tree-that-keeps-its-neighbours Phase 2.6). The behaviour is
+ * unchanged — this is a module boundary, not a rewrite.
+ *
+ * Two reasons it earns its own file. `cmd_doctor.ts` is 2,100 lines above the
+ * `check_source_size_budget` ceiling, so the census line that now links this
+ * listing is paid for by a MOVE rather than by raising the tree-wide excess.
+ * And the neighbour census answers a strictly larger question than this scan
+ * does — this one lists FILES under paths this package deploys to, the census
+ * lists ARTEFACTS wherever a host keeps them — so the two belong beside each
+ * other rather than nested inside a doctor renderer.
+ *
+ * What this scan does NOT do, stated because the two listings look alike: it
+ * never leaves a deploy root, so a neighbour's skill in `~/.claude/skills` or
+ * hook entry in `.cursor/hooks.json` is invisible to it. That gap is the
+ * census's subject, and the census links back here rather than repeating the
+ * paths this one already prints.
+ */
+
+import * as fs from 'node:fs';
+
+/**
+ * `Path.rglob("*")` — every descendant path (dirs + files), recursively.
+ *
+ * Order is not relied upon by callers (they sort the matched set), but the
+ * walk is deterministic (sorted per directory) to keep behaviour stable.
+ */
+export function rglob(root: string, isDir: (p: string) => boolean, join: (a: string, b: string) => string): string[] {
+    const out: string[] = [];
+    const walk = (dir: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const ent of entries) {
+            const full = join(dir, ent.name);
+            out.push(full);
+            let dirLike = ent.isDirectory();
+            if (ent.isSymbolicLink()) {
+                // pathlib rglob follows into symlinked dirs.
+                dirLike = isDir(full);
+            }
+            if (dirLike) {
+                walk(full);
+            }
+        }
+    };
+    walk(root);
+    return out;
+}
+
+export interface ForeignScanDeps {
+    pathExists: (p: string) => boolean;
+    isDir: (p: string) => boolean;
+    isFile: (p: string) => boolean;
+    resolvePath: (p: string) => string;
+    join: (a: string, b: string) => string;
+    /** Resolve one declared deploy root against the consumer root. */
+    resolveRoot: (projectRoot: string, rel: string) => string;
+    defaultRoots: readonly string[];
+}
+
+/**
+ * Walk every declared deploy root and surface unclaimed files. Only regular
+ * files under `deploy_roots` count; bookkeeping is on the resolved final path.
+ */
+export function scanForeign(
+    projectRoot: string,
+    manifest: Record<string, unknown>,
+    known: Set<string>,
+    deps: ForeignScanDeps,
+): string[] {
+    const roots = (manifest['deploy_roots'] as unknown[] | undefined) || Array.from(deps.defaultRoots);
+    const foreign: string[] = [];
+    const seen = new Set<string>();
+    for (const root_rel of roots) {
+        const root = deps.resolveRoot(projectRoot, String(root_rel));
+        if (!deps.pathExists(root) || !deps.isDir(root)) {
+            continue;
+        }
+        for (const child of rglob(root, deps.isDir, deps.join)) {
+            if (!deps.isFile(child)) {
+                continue;
+            }
+            let resolved: string;
+            try {
+                resolved = deps.resolvePath(child);
+            } catch {
+                resolved = child;
+            }
+            if (known.has(resolved) || seen.has(resolved)) {
+                continue;
+            }
+            seen.add(resolved);
+            foreign.push(child);
+        }
+    }
+    foreign.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return foreign;
+}

package/src/scripts/_lib/forge_protection.ts

@@ -73,6 +73,120 @@ export interface ForgeReading {
     readonly deployRestricted: boolean | null;
 }
 
+/**
+ * The all-null reading: nothing was queried.
+ *
+ * Lives here, beside {@link ForgeReading}, rather than in the `doctor` caller
+ * that first needed it — `_lib/forge_reader.ts` returns it on every failure
+ * path, and a second hand-written all-null literal is exactly the drift that
+ * makes "offline output is unchanged" an assertion instead of a fact.
+ *
+ * It MOVED from `_cli/doctor_execution.ts`, which no longer exports it in any
+ * form. Nothing broke, because nothing outside that file imported it — but an
+ * earlier draft of this comment claimed a re-export kept every caller in place,
+ * and no such shim was ever written. Corrected rather than quietly deleted: a
+ * comment describing a compatibility layer that does not exist is the next
+ * reader's false premise.
+ */
+export const UNREAD_FORGE: ForgeReading = {
+    rulesets: null,
+    defaultBranch: null,
+    allowAutoMerge: null,
+    deployRestricted: null,
+};
+
+/**
+ * The two fields of an environment this row reads, as
+ * `GET repos/{owner}/{repo}/environments` returns them.
+ *
+ * A NARROW PROJECTION, not the full payload: the real response also carries
+ * `id`, `protection_rules`, `can_admins_bypass`, timestamps and more. Declared
+ * this way on purpose — a caller passes the real object and structural typing
+ * accepts the superset, while the interface states exactly which fields this
+ * decision depends on. Calling it "the shape" would overstate it.
+ *
+ * `null` is GitHub's encoding for *no restriction at all* — every branch may
+ * deploy. It is therefore the one shape that refutes the row.
+ */
+export interface EnvironmentPolicy {
+    readonly name: string;
+    readonly deployment_branch_policy: {
+        readonly protected_branches?: boolean;
+        readonly custom_branch_policies?: boolean;
+    } | null;
+}
+
+/**
+ * Derive `deployRestricted` from the environments payload.
+ *
+ * **Both restriction mechanisms count, and reading only one is the defect this
+ * function exists to close.** GitHub restricts deployment branches two ways:
+ * `protected_branches` (whatever the forge currently treats as protected) and
+ * `custom_branch_policies` (an explicit named list). A checker that reads only
+ * the first reports "accepts a deployment from any branch" for an environment
+ * pinned to exactly one named branch — which is the opposite of what the
+ * payload says, and is precisely the misreading recorded against this
+ * repository on 2026-09-13: `github-pages` carried
+ * `custom_branch_policies: true` with a single policy, `main`, and was written
+ * up as unrestricted because only `protected_branches` was consulted.
+ *
+ * The named-list mechanism is also the STRICTER of the two here, which is why
+ * the row is satisfied without changing the forge: `protected_branches` widens
+ * with the protected set, while a custom list names one branch and stays there.
+ * On a ruleset-protected repository it is additionally the safer mechanism —
+ * `protected_branches` resolves against a notion of protection whose classic
+ * endpoint 404s here (see the module header), so switching to it would trade a
+ * precise restriction for one whose evaluation is exactly the ambiguity the
+ * `forge-protection-settings` re-scope forbids relying on.
+ *
+ * **An empty environment set returns `null`, not `true`.** The first draft
+ * returned `true` on the reasoning that with no environment there is no
+ * deployment surface to leave open. That is sound about a *confirmed* empty
+ * set and wrong about the value actually reaching this function: an empty
+ * array is what a failed fetch, a truncated page, or a caller that never
+ * queried also produces, and collapsing those into `satisfied` is exactly the
+ * quiet false-positive the three-state row exists to prevent. `null` maps to
+ * `unread`, which is the state this module already reserves for a value nobody
+ * established. A caller that has genuinely confirmed zero environments can say
+ * so by passing `true` itself; it cannot be inferred from the array alone.
+ *
+ * **Wildcard patterns.** A custom policy's NAMES live behind a second call
+ * (`GET .../environments/{name}/deployment-branch-policies`) and accept globs,
+ * so `custom_branch_policies: true` alone cannot distinguish a policy pinned to
+ * `main` from one whose pattern is `*`. Pass `patternsByEnv` when those names
+ * have been read: an environment whose patterns admit everything is reported
+ * unrestricted. Omit it and the flag is trusted — the narrower guarantee was
+ * not checked, which is stated here rather than left for a reader to discover.
+ *
+ * **A confirmed-EMPTY pattern list also yields `false`, and it is NOT the same
+ * case as a wildcard.** With `custom_branch_policies: true` and zero named
+ * patterns nothing matches, so nothing can deploy — strictly the most
+ * restrictive posture there is, and the exact opposite of `*`. Both land on
+ * `false` deliberately, because this row feeds an ACTION line rather than a
+ * permission: an environment configured to accept no deployment at all is a
+ * misconfiguration worth a human look, and `false` surfaces it where `true`
+ * would silently bless it. The direction is the safe one — it can under-report
+ * satisfaction, never over-report it. Written down because the two states are
+ * genuinely opposite, and a reader deriving the behaviour from the expression
+ * alone would reasonably take it for a bug.
+ */
+export function deployRestrictedFrom(
+    environments: readonly EnvironmentPolicy[],
+    patternsByEnv?: Readonly<Record<string, readonly string[]>>,
+): boolean | null {
+    if (environments.length === 0) return null;
+    return environments.every((env) => {
+        const policy = env.deployment_branch_policy;
+        if (policy === null || policy === undefined) return false;
+        if (policy.protected_branches === true) return true;
+        if (policy.custom_branch_policies !== true) return false;
+        const patterns = patternsByEnv?.[env.name];
+        if (patterns === undefined) return true;
+        // A policy admitting every ref restricts nothing, whatever the flag says.
+        return patterns.length > 0 && !patterns.some((p) => p === '*' || p === '**');
+    });
+}
+
 const SOURCE = {
     rulesets: 'GET repos/{owner}/{repo}/rulesets + GET .../rulesets/{id}',
     repo: 'GET repos/{owner}/{repo} (allow_auto_merge)',