@event4u/agent-config 16.1.0 → 16.2.0

package/src/scripts/_lib/body_portable.ts

@@ -0,0 +1,102 @@
+/**
+ * `body-portable` — does a skill's declared frontmatter survive the MCP-lite
+ * carrier whole?
+ *
+ * road-to-semantic-parity-before-off-menu, Phase 2.1.
+ *
+ * WHAT THIS DECIDES, AND WHAT IT DOES NOT
+ *
+ * It decides ELIGIBILITY only. It marks nothing, excludes nothing, and is not a
+ * verdict about which skills matter. A committed list of skills this returns
+ * false for is one step from a menu-exclusion discharged by citing it, which is
+ * precisely the laundering the parked menu-economy roadmap's Risk 1 names — a
+ * measurement of carrier coverage reused as a judgement about worth. Nothing in
+ * the tree consumes this as an exclusion trigger, and building the half that
+ * could is a separate decision that has not been taken.
+ *
+ * THE RULE
+ *
+ * A skill is body-portable when every key it declares is one the carrier
+ * transports whole. Three ways to fail, and they are deliberately not
+ * distinguished in the boolean:
+ *
+ *   - a DROPPED key — the carrier never reads it, so the semantic stays on disk.
+ *   - a PARTIAL key — the carrier reads it and transports part of the value.
+ *     `triggers` is the only one: `keyword` and `phrase` travel, while
+ *     `file_pattern`, `path_prefix`, `command` and `reason` do not. Counting it
+ *     as portable would make a path-triggered skill look complete when the very
+ *     routing that selects it never leaves the disk.
+ *   - an UNKNOWN key — one the schema does not declare at all. It fails CLOSED.
+ *     The alternative is to ignore what you cannot classify, and an unknown key
+ *     is exactly the case where the carrier's behaviour is unestablished, so
+ *     returning true there would assert portability from ignorance.
+ *
+ * SCOPE: one carrier, `ContentEntry` in `src/cli/mcp/content.ts`. A second
+ * delivery path drops a different set and needs its own predicate rather than a
+ * widened reading of this one.
+ */
+
+import { INDEXED_TRIGGER_KEYS } from '../../shared/skillRanking.js';
+
+/**
+ * Frontmatter keys `buildEntry` reads and transports whole
+ * (`src/cli/mcp/content.ts` — `fm.name`, `fm.description`, `fm.source`,
+ * `fm.personas`).
+ *
+ * Derived from the carrier source, never from the schema: a schema property the
+ * carrier does not read is dropped no matter what the schema says about it.
+ */
+export const CARRIED_KEYS: readonly string[] = ['name', 'description', 'source', 'personas'];
+
+/**
+ * Keys the carrier reads but truncates, with the sub-keys that actually travel.
+ *
+ * The sub-key list is IMPORTED from `INDEXED_TRIGGER_KEYS` rather than restated.
+ * Restating it was the first version of this file and it is a silent-lie shape:
+ * add a third indexed key and a hand-copied literal keeps reporting the old two
+ * while the carrier transports three, so the census `travels` column would be
+ * wrong with every test still green.
+ */
+export const PARTIAL_KEYS: Readonly<Record<string, readonly string[]>> = {
+    triggers: INDEXED_TRIGGER_KEYS,
+};
+
+/** Why a skill is not body-portable. Empty when it is. */
+export interface PortabilityReasons {
+    /** Declared keys the carrier transports only in part. */
+    readonly partial: readonly string[];
+    /** Declared keys the carrier does not read, including keys the schema does not declare. */
+    readonly dropped: readonly string[];
+}
+
+export interface PortabilityVerdict extends PortabilityReasons {
+    readonly portable: boolean;
+}
+
+/**
+ * Classify one skill's declared frontmatter keys.
+ *
+ * Pure: it reads nothing and depends only on its argument and the two constants
+ * above.
+ */
+export function classifyPortability(frontmatter: Readonly<Record<string, unknown>>): PortabilityVerdict {
+    const partial: string[] = [];
+    const dropped: string[] = [];
+
+    for (const key of Object.keys(frontmatter).sort()) {
+        if (CARRIED_KEYS.includes(key)) continue;
+        if (Object.hasOwn(PARTIAL_KEYS, key)) {
+            partial.push(key);
+            continue;
+        }
+        // Dropped, and an unknown key lands here too — failing closed.
+        dropped.push(key);
+    }
+
+    return { portable: partial.length === 0 && dropped.length === 0, partial, dropped };
+}
+
+/** The predicate itself. `true` only when nothing the skill declares is lost. */
+export function isBodyPortable(frontmatter: Readonly<Record<string, unknown>>): boolean {
+    return classifyPortability(frontmatter).portable;
+}

package/src/scripts/_lib/cc_transcript.ts

@@ -82,6 +82,16 @@ export interface TranscriptRecord {
     /** Raw `timestamp` field from the record, or null when absent. */
     timestamp: string | null;
     usage: TokenCounts;
+    /**
+     * UTF-8 byte length of this record's own `message.content`, or `null` when
+     * the scan did not ask for it ({@link ScanOptions.measureBytes}) or the
+     * record carries no serialisable content.
+     *
+     * `null` is NOT zero. A record whose content was never measured and a
+     * record whose content is empty are different facts, and a ratio built
+     * over the first would divide by a denominator it never observed.
+     */
+    content_bytes: number | null;
 }
 
 export interface ScanOptions {
@@ -98,6 +108,17 @@ export interface ScanOptions {
     maxAgeDays?: number;
     /** Clock used to evaluate `maxAgeDays` — injectable for tests. */
     now?: Date;
+    /**
+     * Also measure each record's `message.content` byte length
+     * ({@link TranscriptRecord.content_bytes}).
+     *
+     * OPT-IN, because it costs a second serialisation of content the scan
+     * otherwise never touches, and the existing callers — `cost_summary`,
+     * `preamble_byte_census`, the bench harness — want token sums only. A
+     * caller that does not ask gets `content_bytes: null` on every record and
+     * pays nothing.
+     */
+    measureBytes?: boolean;
 }
 
 export interface ScanResult {
@@ -161,7 +182,7 @@ interface RawUsage {
 
 interface RawAssistantRecord {
     type?: unknown;
-    message?: { id?: unknown; model?: unknown; usage?: RawUsage };
+    message?: { id?: unknown; model?: unknown; usage?: RawUsage; content?: unknown };
     requestId?: unknown;
     agentId?: unknown;
     isSidechain?: unknown;
@@ -180,6 +201,29 @@ function toTokenCounts(raw: RawUsage | undefined): TokenCounts {
     };
 }
 
+/**
+ * UTF-8 byte length of one record's `message.content`, or `null` when there is
+ * nothing serialisable to measure.
+ *
+ * Bytes, never characters: a multibyte block costs what it costs, and
+ * `String.length` would under-report it. Content is what this reader can
+ * actually SEE — the request's system prompt, tool definitions and prior turns
+ * are not in the transcript at all (`preamble_byte_census` records the same
+ * limitation), so a ratio built from this is a ratio over assistant output and
+ * is labelled as such wherever it surfaces.
+ */
+export function measureContentBytes(raw: RawAssistantRecord): number | null {
+    const content = raw.message?.content;
+    if (content === undefined || content === null) return null;
+    if (typeof content === 'string') return Buffer.byteLength(content, 'utf8');
+    try {
+        return Buffer.byteLength(JSON.stringify(content), 'utf8');
+    } catch {
+        // Circular or otherwise unserialisable — unmeasurable, not zero.
+        return null;
+    }
+}
+
 /** Subagent iff a non-empty top-level `agentId` OR `isSidechain === true` — see module doc comment. */
 function classifyBucket(raw: RawAssistantRecord): TranscriptBucket {
     const hasAgentId = typeof raw.agentId === 'string' && raw.agentId.length > 0;
@@ -285,6 +329,7 @@ export function scanTranscripts(opts: ScanOptions = {}): ScanResult {
                 model: typeof raw.message.model === 'string' ? raw.message.model : 'unknown',
                 timestamp: typeof raw.timestamp === 'string' ? raw.timestamp : null,
                 usage: toTokenCounts(raw.message.usage),
+                content_bytes: opts.measureBytes === true ? measureContentBytes(raw) : null,
             });
         }
     }
@@ -298,6 +343,92 @@ export function scanTranscripts(opts: ScanOptions = {}): ScanResult {
     };
 }
 
+/* -------------------------------------------------------------------------- */
+/* Bytes — measured on the corpus, never assumed                               */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * A bytes-per-token ratio, together with the two sums it was divided from and
+ * the population it was measured over.
+ *
+ * The sums travel WITH the ratio on purpose. A bare ratio is the shape that
+ * becomes a constant: somebody copies the number, it outlives the corpus that
+ * produced it, and the next reader cannot tell what it measured. Carrying
+ * `content_bytes` and `output_tokens` means the division is re-derivable from
+ * the record itself.
+ */
+export interface BytesPerToken {
+    /** Always `'measured'` — this value is a division of two counted sums. */
+    basis: 'measured';
+    /** Summed `content_bytes` over the records that carried one. */
+    content_bytes: number;
+    /** Summed `output_tokens` over those same records. */
+    output_tokens: number;
+    /** `content_bytes / output_tokens`. */
+    bytes_per_token: number;
+    /** Records that contributed — `content_bytes !== null` and `output_tokens > 0`. */
+    records: number;
+}
+
+/**
+ * Measure a bytes-per-token ratio ON THE GIVEN RECORDS. Returns `null` when
+ * nothing in the corpus can supply one.
+ *
+ * `null` is the honest outcome and callers must render it as such rather than
+ * substituting a default: a ratio invented where none was measured is exactly
+ * the constant this function exists to make unnecessary. There is deliberately
+ * no fallback value anywhere in this module — the factor is a property of the
+ * corpus, and a corpus that cannot supply one has not supplied one.
+ */
+export function measureBytesPerToken(records: readonly TranscriptRecord[]): BytesPerToken | null {
+    let bytes = 0;
+    let tokens = 0;
+    let n = 0;
+    for (const rec of records) {
+        if (rec.content_bytes === null || rec.usage.output_tokens <= 0) continue;
+        bytes += rec.content_bytes;
+        tokens += rec.usage.output_tokens;
+        n += 1;
+    }
+    if (n === 0 || tokens <= 0) return null;
+    return {
+        basis: 'measured',
+        content_bytes: bytes,
+        output_tokens: tokens,
+        bytes_per_token: bytes / tokens,
+        records: n,
+    };
+}
+
+/** A byte figure obtained by multiplying a token count by a measured ratio. */
+export interface DerivedBytes {
+    /** Always `'derived'`. Never `'measured'` — nothing counted these bytes. */
+    basis: 'derived';
+    /** The token count that was multiplied. */
+    tokens: number;
+    /** The ratio used, carried so the arithmetic sits beside its result. */
+    factor: BytesPerToken;
+    /** `tokens * factor.bytes_per_token`, rounded to a whole byte. */
+    bytes: number;
+}
+
+/**
+ * Multiply a token count by a ratio measured on the same corpus.
+ *
+ * The result carries `basis: 'derived'` and the factor that produced it, so a
+ * derived figure and a counted one can never be read as the same number — the
+ * failure this whole path is shaped to prevent. `null` factor in, `null` out.
+ */
+export function derivedBytes(tokens: number, factor: BytesPerToken | null): DerivedBytes | null {
+    if (factor === null) return null;
+    return {
+        basis: 'derived',
+        tokens,
+        factor,
+        bytes: Math.round(tokens * factor.bytes_per_token),
+    };
+}
+
 function emptyAggregate(bucket: TranscriptBucket): BucketAggregate {
     return {
         bucket,

package/src/scripts/_lib/concern_sla_window.ts

@@ -0,0 +1,200 @@
+/**
+ * Per-concern SLA measurement and the warn-only window's reporting.
+ *
+ * Extracted from `bench_hook_latency.ts` on 2026-10-01, not for tidiness: the
+ * additions that made `one-question-per-ask` measurable and gave the warn-only
+ * window a reader pushed that file from 1,361 lines to 1,583, i.e. 83 lines
+ * past the 1,500-line source ceiling, and `check_source_size_budget`'s ratchet
+ * asked for exactly this by name. Raising the baseline was the other option
+ * and is the one the ratchet exists to make visible rather than easy — a MOVE
+ * gives the budget back instead of spending it, which is the doctrine every
+ * entry in `gate-violation-baselines.json` records.
+ *
+ * It is also the better boundary on its own terms. Everything here answers one
+ * question — which blocking concern is bounded, by how much, and did this run
+ * cross it — and none of it is about measuring a hook SLOT, which is what the
+ * bench itself does.
+ *
+ * NOTHING HERE GATES. The bound these functions read is not armed anywhere:
+ * step 3.3 of `road-to-a-kernel-that-guards-its-plumbing` is its only consumer
+ * and is blocked on the window these functions report. A measurement that can
+ * red a build before its bar is validated is Risk 1 of that roadmap.
+ */
+import * as fs from 'node:fs';
+
+/**
+ * The subset of a per-concern row the window needs: a measurement and a bound.
+ *
+ * Declared here rather than imported so the dependency runs one way only —
+ * `bench_hook_latency.ts` imports this module and this module imports nothing
+ * back. `ConcernLatencyRow` satisfies it structurally, so the caller passes its
+ * own rows unchanged and no adapter exists to drift.
+ */
+export interface BoundedConcern {
+    readonly concern: string;
+    /** p95 of the concern's own durations in microseconds, or null when untimed. */
+    readonly p95_us: number | null;
+    /** The registered SLA in milliseconds, or null when none is registered. */
+    readonly sla_ms: number | null;
+    /** The budget carried a value for this concern that is not a number. */
+    readonly sla_malformed: boolean;
+}
+
+/**
+ * An alternate tool shape for the synthetic payload.
+ *
+ * The default payload names `Read`, which is the right default for every gated
+ * number: it is the common non-matching case consumers pay on every tool call.
+ * But a concern filtered by the manifest's per-concern `tools:` key is SKIPPED
+ * in-process on a payload naming a tool it does not claim, so it never produces
+ * a sample and the per-concern report prints `not_measured` for it — correctly,
+ * and uselessly for a step that needs a bound.
+ *
+ * `one-question-per-ask` is the live instance: `severity: blocking`, filtered to
+ * `AskUserQuestion` and five aliases. It is the only blocking concern the
+ * default payload cannot reach, and the owning roadmap's Phase-3 blocker names
+ * the choice explicitly — "either a payload shaped to trigger it or an explicit
+ * decision that an unmeasured blocking concern keeps the current 30 s timeout".
+ * This is the first branch: measure it, so the decision is not forced by the
+ * harness.
+ *
+ * Measurement-only, like `--bundle` and `--payload-bytes`. It is reachable only
+ * from `concernSlaPass`, which gates nothing and writes no budget row — a probe
+ * payload must never produce a gated slot number, because the slot caps were
+ * derived against the `Read` shape and a different shape runs a different
+ * concern chain.
+ */
+export interface ToolShape {
+    readonly tool_name: string;
+    readonly tool_input: Record<string, unknown>;
+}
+
+/**
+ * The probe that reaches `one-question-per-ask`.
+ *
+ * ONE question, not two: a single question is the ALLOW path, and the allow
+ * path is what an ordinary call costs. Two questions would measure the deny
+ * path — the rarer branch, and the one that builds a message — so a bound taken
+ * from it would describe the exception rather than the rule. Both run
+ * `countStructuredAskQuestions`, which is the concern's actual work.
+ */
+export const ASK_PROBE: ToolShape = {
+    tool_name: 'AskUserQuestion',
+    tool_input: { questions: [{ question: 'bench probe' }] },
+};
+
+/**
+ * The one concern the ask probe exists to measure.
+ *
+ * Named rather than inferred from the `tools:` filter: a future concern added
+ * with an overlapping filter would be measured under a payload chosen for THIS
+ * one, and silently adopting it is the contamination above wearing a different
+ * shape.
+ */
+export const PROBE_TARGET = 'one-question-per-ask';
+
+/**
+ * Append only `target`'s samples from the probe sink onto the main sink.
+ *
+ * The probe sink is read and then left in place; it is a temp-dir file the
+ * caller owns. A read failure is not fatal — the probe is an observation, and
+ * a bench that dies because one auxiliary sink was unreadable converts a
+ * measurement into an outage, which is the posture `readConcernTimings`
+ * already takes one level down.
+ */
+export function mergeProbeSamples(probeSink: string, sinkPath: string, target: string): void {
+    let text: string;
+    try {
+        text = fs.readFileSync(probeSink, 'utf-8');
+    } catch {
+        return;
+    }
+    const keep: string[] = [];
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '') continue;
+        let row: { concern?: unknown };
+        try {
+            row = JSON.parse(trimmed) as typeof row;
+        } catch {
+            continue;
+        }
+        if (row.concern === target) keep.push(trimmed);
+    }
+    if (keep.length === 0) return;
+    try {
+        fs.appendFileSync(sinkPath, `${keep.join('\n')}\n`, 'utf-8');
+    } catch {
+        /* the sink is an observation aid; losing it must not fail the bench */
+    }
+}
+
+/**
+ * The warn-only window, made legible — observe-only, gating nothing.
+ *
+ * Step 3.3 derives a per-concern timeout of `sla_ms x 3` and its own text says
+ * "warn-only for the first measured window, then deny". A window nothing
+ * observes is not a window: with `sla_ms` registered and no reader, the flip
+ * would be taken on the absence of a complaint rather than on a reading.
+ *
+ * So this is the instrument. Every bench run — local or CI, gated or not —
+ * prints each blocking concern's measured p95 beside its registered bound and
+ * names any concern that crossed it. The window is then a span of runs a human
+ * can read, and the flip has an evidence base that exists before it is taken.
+ *
+ * It lives in the measurement harness and NOT in the dispatcher deliberately.
+ * A runtime warn would be a dispatcher change shipped as part of a step that is
+ * blocked on the very readings it would produce, and Risk 1 of the owning
+ * roadmap is precisely about acting on a bound before it is validated.
+ *
+ * A concern with no registered SLA, or no measurement, is NOT an overrun — it
+ * is an unknown, and the two must not collapse. Returning it as "fine" would
+ * let an unregistered concern read as a clean window.
+ */
+export interface SlaOverrun {
+    concern: string;
+    p95_us: number;
+    /** `sla_ms x 3`, in microseconds — the bound step 3.3 would apply. */
+    bound_us: number;
+}
+
+/**
+ * What a run can actually say about the window — three counts, never one.
+ *
+ * `registered` is how many concerns carry a bound. `usable` is how many of
+ * those this run could compare against it. The gap is what an earlier version
+ * of the summary line silently dropped: it printed "none over" off `registered`,
+ * so a run that measured none of its bounded concerns read exactly like a run
+ * that measured all of them and found nothing. That is the same
+ * unknown-collapsed-into-fine failure `slaOverruns` refuses per row, one level
+ * up at the summary.
+ */
+export interface WindowState {
+    registered: number;
+    usable: number;
+    /** Registered but not comparable this run — unmeasured or malformed. */
+    unusable: number;
+}
+
+export function windowState(rows: readonly BoundedConcern[]): WindowState {
+    let registered = 0;
+    let usable = 0;
+    for (const row of rows) {
+        if (row.sla_ms === null && !row.sla_malformed) continue;
+        registered += 1;
+        if (!row.sla_malformed && row.sla_ms !== null && row.p95_us !== null) usable += 1;
+    }
+    return { registered, usable, unusable: registered - usable };
+}
+
+export function slaOverruns(rows: readonly BoundedConcern[]): SlaOverrun[] {
+    const out: SlaOverrun[] = [];
+    for (const row of rows) {
+        if (row.sla_ms === null || row.sla_malformed || row.p95_us === null) continue;
+        const bound_us = row.sla_ms * 3 * 1000;
+        if (row.p95_us > bound_us) {
+            out.push({ concern: row.concern, p95_us: row.p95_us, bound_us });
+        }
+    }
+    return out;
+}

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)',