@bridge_gpt/mcp-server 0.2.67 → 0.2.69

package/build/conductor/epic-branch-ci-inspection.js

@@ -0,0 +1,1375 @@
+/**
+ * Epic-branch CI inspection for the installer (BAPI-1405).
+ *
+ * Two read-mostly questions the install gate flow asks about a GitHub
+ * repository before it records the repository's epic-branch CI decision:
+ *
+ * 1. Do the repository's workflows run for a pull request whose BASE is an
+ *    epic branch (`epic/<EPIC>`)? Answered from the working tree through the
+ *    injected {@link GateDiscoveryFs}, deterministically, with no LLM and no
+ *    YAML library.
+ * 2. Do the branch rules for `epic/<EPIC>` require approvals, and can that
+ *    approval requirement be narrowly exempted? Answered through the user's own
+ *    `gh` session via an injected, shell-free {@link GhRunner}.
+ *
+ * ## Trigger-coverage truth table
+ *
+ * The Python twin `classify_epic_pull_request_trigger` in
+ * `api/library/github/workflow_inspection.py` implements the same table with
+ * `yaml.safe_load`; the two must agree. Each workflow answers `covers`,
+ * `does_not_cover`, or `could_not_tell` with one closed reason token
+ * ({@link EpicCoverageReason}). Applied in this order:
+ *
+ * 1. Empty, unparseable, or non-mapping document, or no trigger key →
+ *    `could_not_tell` / `unparseable`. The trigger key is the root `on`, which
+ *    YAML 1.1 reads as boolean `true` when unquoted: the root keys `on`, `"on"`,
+ *    `'on'`, and the plain booleans `true`/`True`/`TRUE`/`On`/`ON`/`yes`/`Yes`/
+ *    `YES` are all accepted. A quoted `"on"` wins over a boolean key, as
+ *    `parsed.get("on", parsed.get(True))` does.
+ * 2. Anything in the trigger block this scanner cannot read confidently —
+ *    anchors, aliases, tags, merge keys, block scalars, non-empty flow mappings,
+ *    multi-line flow collections, tabs in indentation, multi-document streams —
+ *    or a trigger value that is not a string, list, or mapping →
+ *    `could_not_tell` / `unsupported_structure`.
+ * 3. Trigger forms:
+ *    - a string: `pull_request` / `pull_request_target` covers;
+ *    - a list: covers when it names either PR event (any non-string item
+ *      otherwise makes it `unsupported_structure`);
+ *    - a mapping: each of `pull_request` and `pull_request_target` is judged on
+ *      its own —
+ *      - null or `{}` → covers; any other non-mapping → `unsupported_structure`;
+ *      - `paths` / `paths-ignore` present → `path_filter`;
+ *      - `types` present → passes only when it is a list of strings holding
+ *        both `opened` and `synchronize`, else `types_filter`;
+ *      - both `branches` and `branches-ignore` → `branch_filter_uncertain`;
+ *      - `branches` (a string is a one-element list; an empty or non-string
+ *        list is uncertain) → ordered, last match wins, `!` negates:
+ *        state starts NONE_IN; a positive ALL → ALL_IN, a positive SOME keeps
+ *        ALL_IN else → UNKNOWN; a negative ALL → NONE_IN, a negative SOME keeps
+ *        NONE_IN else → UNKNOWN; NONE patterns change nothing. ALL_IN → covers,
+ *        NONE_IN → `does_not_cover` / `branch_filter_excludes_epic`, UNKNOWN →
+ *        `branch_filter_uncertain`;
+ *      - `branches-ignore` → an empty list covers; any `!` entry or non-string
+ *        is uncertain; any ALL pattern → `does_not_cover`; all NONE → covers;
+ *        otherwise uncertain;
+ *      - no filter → covers.
+ *    Pattern classes against `epic/<EPIC>` (EPIC has no `/`; `*` and `?`
+ *    never match `/`, `**` matches anything): ALL is exactly `**`, `epic/*`, or
+ *    `epic/**`. NONE is a pattern with no `/`, no `**`, and no `[` (bare `*`
+ *    included); a wildcard-free literal not starting with `epic/`; or a
+ *    pattern whose literal text before its first wildcard (`*?[+!`) is neither
+ *    a prefix of `epic/` nor starts with it. Everything else is SOME.
+ * 4. Any PR key that covers → `covers` / `pr_trigger_covers`. Indirect
+ *    triggers and job-level `uses` only ADD runs and never block a cover.
+ * 5. Otherwise the first PR key that could not be told → that key's reason.
+ * 6. Otherwise `merge_group` / `workflow_run` / `workflow_call` among the
+ *    trigger names → `indirect_trigger`; else a job-level `uses` →
+ *    `reusable_workflow_job`; else `does_not_cover` with
+ *    `branch_filter_excludes_epic` when a PR key was present, `no_pr_trigger`
+ *    when none was.
+ *
+ * Scanner scope: the trigger block is parsed fully (block mappings, block
+ * sequences including the compact form, single-line flow sequences of scalars,
+ * `{}`, plain and quoted scalars with YAML 1.1 implicit typing, comments).
+ * The rest of the document is only checked for root-level shape; a document
+ * that is invalid YAML only OUTSIDE the trigger block and `jobs` headers is not
+ * detected here (the Python twin would answer `unparseable`).
+ *
+ * The repository aggregate is `covers` when any workflow covers. It is
+ * `does_not_cover` only after a successful, untruncated listing in which every
+ * workflow was read and does not cover (a confirmed empty or confirmed absent
+ * `.github/workflows` is `no_workflows`); otherwise `could_not_tell`.
+ *
+ * ## Approval exemption
+ *
+ * The only write this module can make is adding `refs/heads/epic/**` to the
+ * `conditions.ref_name.exclude` list of a repository-level ruleset whose only
+ * rule is `pull_request`, and only when the caller passes an eligible
+ * {@link ExemptionScopeAssessment} (the install flow asks for explicit consent
+ * first). Success is reported only after a re-read shows no `pull_request`
+ * rule on the branch and an unchanged set of required status check contexts.
+ *
+ * Every returned reason is a bounded token: no `gh` output, URL, or token text
+ * is ever returned. Nothing here throws.
+ */
+import { MAX_DISCOVERY_FILE_BYTES, MAX_WORKFLOW_FILES, } from "./gate-discovery.js";
+export const EPIC_COVERAGE_REASONS = [
+    "pr_trigger_covers",
+    "no_pr_trigger",
+    "branch_filter_excludes_epic",
+    "path_filter",
+    "branch_filter_uncertain",
+    "types_filter",
+    "indirect_trigger",
+    "reusable_workflow_job",
+    "unparseable",
+    "unsupported_structure",
+    "listing_failed",
+    "file_limit_reached",
+    "read_failed",
+    "no_workflows",
+];
+export const DEFAULT_PER_READ_TIMEOUT_MS = 5_000;
+export const DEFAULT_OVERALL_BUDGET_MS = 30_000;
+const EPIC_PREFIX = "epic/";
+const EPIC_ALL_PATTERNS = new Set(["**", "epic/*", "epic/**"]);
+const GLOB_CHARS = new Set(["*", "?", "[", "+", "!"]);
+const PR_TRIGGER_KEYS = ["pull_request", "pull_request_target"];
+const INDIRECT_TRIGGER_KEYS = new Set(["merge_group", "workflow_run", "workflow_call"]);
+/** Classify one (non-negated) filter pattern; see the module truth table. */
+export function classifyEpicBranchPattern(pattern) {
+    if (EPIC_ALL_PATTERNS.has(pattern))
+        return "all";
+    if (!pattern.includes("/") && !pattern.includes("**") && !pattern.includes("["))
+        return "none";
+    let firstGlob = pattern.length;
+    for (let i = 0; i < pattern.length; i++) {
+        if (GLOB_CHARS.has(pattern[i])) {
+            firstGlob = i;
+            break;
+        }
+    }
+    if (firstGlob === pattern.length)
+        return pattern.startsWith(EPIC_PREFIX) ? "some" : "none";
+    const prefix = pattern.slice(0, firstGlob);
+    if (EPIC_PREFIX.startsWith(prefix) || prefix.startsWith(EPIC_PREFIX))
+        return "some";
+    return "none";
+}
+const COVERS = { coverage: "covers", reason: "pr_trigger_covers" };
+const EXCLUDES = { coverage: "does_not_cover", reason: "branch_filter_excludes_epic" };
+function couldNotTell(reason) {
+    return { coverage: "could_not_tell", reason };
+}
+/** Thrown internally when the scanner meets structure it will not guess at. */
+class UnsupportedYaml extends Error {
+}
+function unsupported() {
+    throw new UnsupportedYaml("unsupported");
+}
+/** Map-key identity: strings by value, booleans by value, anything else opaque. */
+function keyId(node) {
+    if (node.t === "str")
+        return `s:${node.v}`;
+    if (node.t === "bool")
+        return `b:${node.v}`;
+    if (node.t === "null")
+        return "n:";
+    unsupported();
+}
+function filterPatterns(node) {
+    if (node === undefined)
+        return null;
+    if (node.t === "str")
+        return [node.v];
+    if (node.t === "seq" && node.items.every((i) => i.t === "str")) {
+        return node.items.map((i) => i.v);
+    }
+    return null;
+}
+function classifyBranches(node) {
+    const patterns = filterPatterns(node);
+    if (patterns === null || patterns.length === 0)
+        return couldNotTell("branch_filter_uncertain");
+    let state = "none_in";
+    for (const raw of patterns) {
+        const negated = raw.startsWith("!");
+        const match = classifyEpicBranchPattern(negated ? raw.slice(1) : raw);
+        if (match === "none")
+            continue;
+        if (!negated) {
+            if (match === "all")
+                state = "all_in";
+            else if (state !== "all_in")
+                state = "unknown";
+        }
+        else if (match === "all") {
+            state = "none_in";
+        }
+        else if (state !== "none_in") {
+            state = "unknown";
+        }
+    }
+    if (state === "all_in")
+        return COVERS;
+    if (state === "none_in")
+        return EXCLUDES;
+    return couldNotTell("branch_filter_uncertain");
+}
+function classifyBranchesIgnore(node) {
+    if (node !== undefined && node.t === "seq" && node.items.length === 0)
+        return COVERS;
+    const patterns = filterPatterns(node);
+    if (patterns === null || patterns.some((p) => p.startsWith("!"))) {
+        return couldNotTell("branch_filter_uncertain");
+    }
+    const matches = patterns.map(classifyEpicBranchPattern);
+    if (matches.includes("all"))
+        return EXCLUDES;
+    if (matches.every((m) => m === "none"))
+        return COVERS;
+    return couldNotTell("branch_filter_uncertain");
+}
+function classifyPrEvent(node) {
+    if (node.t === "null")
+        return COVERS;
+    if (node.t !== "map")
+        return couldNotTell("unsupported_structure");
+    const e = node.entries;
+    if (e.size === 0)
+        return COVERS;
+    if (e.has("s:paths") || e.has("s:paths-ignore"))
+        return couldNotTell("path_filter");
+    if (e.has("s:types")) {
+        const types = e.get("s:types");
+        const ok = types !== undefined &&
+            types.t === "seq" &&
+            types.items.every((i) => i.t === "str") &&
+            types.items.some((i) => i.t === "str" && i.v === "opened") &&
+            types.items.some((i) => i.t === "str" && i.v === "synchronize");
+        if (!ok)
+            return couldNotTell("types_filter");
+    }
+    const hasBranches = e.has("s:branches");
+    const hasIgnore = e.has("s:branches-ignore");
+    if (hasBranches && hasIgnore)
+        return couldNotTell("branch_filter_uncertain");
+    if (hasBranches)
+        return classifyBranches(e.get("s:branches"));
+    if (hasIgnore)
+        return classifyBranchesIgnore(e.get("s:branches-ignore"));
+    return COVERS;
+}
+// ---------------------------------------------------------------------------
+// Scalar reading (YAML 1.1 / PyYAML implicit resolution)
+// ---------------------------------------------------------------------------
+const BOOL_TRUE = new Set(["yes", "Yes", "YES", "true", "True", "TRUE", "on", "On", "ON"]);
+const BOOL_FALSE = new Set(["no", "No", "NO", "false", "False", "FALSE", "off", "Off", "OFF"]);
+const NULL_WORDS = new Set(["~", "null", "Null", "NULL", ""]);
+const INT_RE = /^(?:[-+]?0b[0-1_]+|[-+]?0[0-7_]+|[-+]?(?:0|[1-9][0-9_]*)|[-+]?0x[0-9a-fA-F_]+|[-+]?[1-9][0-9_]*(?::[0-5]?[0-9])+)$/;
+const FLOAT_RE = /^(?:[-+]?(?:[0-9][0-9_]*)\.[0-9_]*(?:[eE][-+][0-9]+)?|\.[0-9][0-9_]*(?:[eE][-+][0-9]+)?|[-+]?[0-9][0-9_]*(?::[0-5]?[0-9])+\.[0-9_]*|[-+]?\.(?:inf|Inf|INF)|\.(?:nan|NaN|NAN))$/;
+const TIMESTAMP_RE = /^(?:[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]|[0-9][0-9][0-9][0-9]-[0-9][0-9]?-[0-9][0-9]?(?:[Tt]|[ \t]+)[0-9][0-9]?:[0-9][0-9]:[0-9][0-9](?:\.[0-9]*)?(?:[ \t]*(?:Z|[-+][0-9][0-9]?(?::[0-9][0-9])?))?)$/;
+/** Resolve a plain scalar the way PyYAML's SafeLoader does (merge/value tags are refused). */
+function resolvePlain(v) {
+    if (NULL_WORDS.has(v))
+        return { t: "null" };
+    if (BOOL_TRUE.has(v))
+        return { t: "bool", v: true };
+    if (BOOL_FALSE.has(v))
+        return { t: "bool", v: false };
+    if (INT_RE.test(v) || FLOAT_RE.test(v) || TIMESTAMP_RE.test(v))
+        return { t: "other" };
+    if (v === "<<" || v === "=")
+        unsupported();
+    return { t: "str", v };
+}
+/** Characters that may not start a plain scalar (or start a construct we refuse). */
+const REFUSED_STARTS = new Set(["|", ">", "&", "*", "!", "%", "@", "`", "{", "[", "]", "}", ",", "#", '"', "'"]);
+function onlyCommentAfter(rem) {
+    return rem.trim() === "" || /^\s+#/.test(rem);
+}
+/** PyYAML's single-character double-quote escapes (a line-continuation escape is refused). */
+const DQ_ESCAPES = {
+    "0": "\0",
+    a: "\x07",
+    b: "\b",
+    t: "\t",
+    "\t": "\t",
+    n: "\n",
+    v: "\v",
+    f: "\f",
+    r: "\r",
+    e: "\x1b",
+    " ": " ",
+    '"': '"',
+    "/": "/",
+    "\\": "\\",
+    N: "\u0085",
+    _: "\u00a0",
+    L: "\u2028",
+    P: "\u2029",
+};
+/**
+ * Read a quoted scalar starting at `text[start]`. Returns the value and the
+ * index after the closing quote. Double quotes decode PyYAML's escapes
+ * (single-character, `\xHH`, `\uHHHH`, `\UHHHHHHHH`); anything else is refused.
+ */
+function readQuoted(text, start) {
+    const q = text[start];
+    let value = "";
+    for (let i = start + 1; i < text.length; i++) {
+        const ch = text[i];
+        if (q === '"' && ch === "\\") {
+            const next = text[i + 1] ?? "";
+            const simple = DQ_ESCAPES[next];
+            if (simple !== undefined) {
+                value += simple;
+                i++;
+                continue;
+            }
+            const width = next === "x" ? 2 : next === "u" ? 4 : next === "U" ? 8 : 0;
+            const hex = text.slice(i + 2, i + 2 + width);
+            if (width === 0 || !/^[0-9A-Fa-f]+$/.test(hex) || hex.length !== width)
+                unsupported();
+            const cp = parseInt(hex, 16);
+            if (cp > 0x10ffff || (cp >= 0xd800 && cp <= 0xdfff))
+                unsupported();
+            value += String.fromCodePoint(cp);
+            i += 1 + width;
+            continue;
+        }
+        if (ch === q) {
+            if (q === "'" && text[i + 1] === "'") {
+                value += "'";
+                i++;
+                continue;
+            }
+            return { value, end: i + 1 };
+        }
+        value += ch;
+    }
+    unsupported(); // unterminated on this line: a multi-line scalar
+}
+/** A single-line flow sequence of scalars, e.g. `[push, "pull_request"]`. */
+function parseFlowSeq(text) {
+    const items = [];
+    let i = 1;
+    const skipSpaces = () => {
+        while (text[i] === " ")
+            i++;
+    };
+    skipSpaces();
+    if (text[i] === "]") {
+        if (!onlyCommentAfter(text.slice(i + 1)))
+            unsupported();
+        return { t: "seq", items };
+    }
+    for (;;) {
+        skipSpaces();
+        const ch = text[i];
+        if (ch === undefined)
+            unsupported();
+        if (ch === '"' || ch === "'") {
+            const q = readQuoted(text, i);
+            items.push({ t: "str", v: q.value });
+            i = q.end;
+            skipSpaces();
+        }
+        else {
+            let j = i;
+            while (j < text.length && text[j] !== "," && text[j] !== "]")
+                j++;
+            const raw = text.slice(i, j).trim();
+            if (raw === "" ||
+                REFUSED_STARTS.has(raw[0]) ||
+                /^[-?:](\s|$)/.test(raw) ||
+                /[[\]{}#:\t]/.test(raw)) {
+                unsupported();
+            }
+            items.push(resolvePlain(raw));
+            i = j;
+        }
+        if (text[i] === ",") {
+            i++;
+            skipSpaces();
+            if (text[i] === "]") {
+                // A single trailing comma is valid YAML: `[a, b,]`.
+                if (!onlyCommentAfter(text.slice(i + 1)))
+                    unsupported();
+                return { t: "seq", items };
+            }
+            if (text[i] === undefined || text[i] === ",")
+                unsupported();
+            continue;
+        }
+        if (text[i] === "]") {
+            if (!onlyCommentAfter(text.slice(i + 1)))
+                unsupported();
+            return { t: "seq", items };
+        }
+        unsupported();
+    }
+}
+/** Read the inline value after `key:` or `- ` (already trimmed). */
+function parseInline(rest) {
+    if (rest === "" || rest.startsWith("#"))
+        return { t: "null" };
+    const c = rest[0];
+    if (c === "[")
+        return parseFlowSeq(rest);
+    if (c === "{") {
+        if (/^\{\s*\}(\s*|\s+#.*)$/.test(rest))
+            return { t: "map", entries: new Map() };
+        unsupported();
+    }
+    if (c === '"' || c === "'") {
+        const q = readQuoted(rest, 0);
+        if (!onlyCommentAfter(rest.slice(q.end)))
+            unsupported();
+        return { t: "str", v: q.value };
+    }
+    if (REFUSED_STARTS.has(c) || /^[-?:](\s|$)/.test(rest))
+        unsupported();
+    const comment = rest.search(/\s#/);
+    const value = (comment >= 0 ? rest.slice(0, comment) : rest).trim();
+    if (value === "" || /:(\s|$)/.test(value) || value.includes("\t"))
+        unsupported();
+    return resolvePlain(value);
+}
+/**
+ * Split a block-mapping line into key and inline rest, or null when the line
+ * is not a `key:` entry. Keys may be plain or quoted.
+ */
+function splitKey(text) {
+    let key;
+    let after;
+    const c = text[0];
+    if (c === '"' || c === "'") {
+        let q;
+        try {
+            q = readQuoted(text, 0);
+        }
+        catch {
+            return null;
+        }
+        after = text.slice(q.end).replace(/^ +/, "");
+        if (!after.startsWith(":"))
+            return null;
+        after = after.slice(1);
+        if (after !== "" && after[0] !== " ")
+            return null;
+        key = { t: "str", v: q.value };
+    }
+    else {
+        if (c === undefined || REFUSED_STARTS.has(c) || /^[-?:](\s|$)/.test(text))
+            return null;
+        let colon = -1;
+        for (let i = 0; i < text.length; i++) {
+            if (text[i] === "#" && i > 0 && /\s/.test(text[i - 1]))
+                return null;
+            if (text[i] === ":" && (i + 1 === text.length || text[i + 1] === " ")) {
+                colon = i;
+                break;
+            }
+        }
+        if (colon < 0)
+            return null;
+        const raw = text.slice(0, colon).trimEnd();
+        if (raw === "" || raw.length > 1000 || raw.includes("\t"))
+            return null;
+        key = resolvePlain(raw);
+        after = text.slice(colon + 1);
+    }
+    let rest = after.trim();
+    if (rest.startsWith("#"))
+        rest = "";
+    return { key, rest };
+}
+function isSeqItem(l) {
+    return l.text === "-" || l.text.startsWith("- ");
+}
+/** Strict line reader for the trigger block: refuses tabs in indentation. */
+function checkLine(l) {
+    if (l.tabIndent)
+        unsupported();
+    return l;
+}
+function parseBlockAt(ls, i) {
+    const l = checkLine(ls[i]);
+    return isSeqItem(l) ? parseSeqAt(ls, i, l.indent) : parseMapAt(ls, i, l.indent);
+}
+function parseValueAfterKey(ls, i, keyIndent, allowCompactSeq) {
+    if (i < ls.length) {
+        const l = checkLine(ls[i]);
+        if (l.indent > keyIndent)
+            return parseBlockAt(ls, i);
+        if (allowCompactSeq && l.indent === keyIndent && isSeqItem(l))
+            return parseSeqAt(ls, i, keyIndent);
+    }
+    return { node: { t: "null" }, next: i };
+}
+function parseMapAt(ls, start, n) {
+    const entries = new Map();
+    let i = start;
+    while (i < ls.length) {
+        const l = checkLine(ls[i]);
+        if (l.indent < n)
+            break;
+        if (l.indent > n || isSeqItem(l))
+            unsupported();
+        const kv = splitKey(l.text);
+        if (kv === null)
+            unsupported();
+        const id = keyId(kv.key);
+        let node;
+        let next;
+        if (kv.rest === "") {
+            ({ node, next } = parseValueAfterKey(ls, i + 1, n, true));
+        }
+        else {
+            node = parseInline(kv.rest);
+            next = i + 1;
+            if (next < ls.length && ls[next].indent > n)
+                unsupported();
+        }
+        entries.set(id, node); // duplicate keys: last wins, as in PyYAML
+        i = next;
+    }
+    return { node: { t: "map", entries }, next: i };
+}
+function parseSeqAt(ls, start, n) {
+    const items = [];
+    let i = start;
+    while (i < ls.length) {
+        const l = checkLine(ls[i]);
+        if (l.indent < n)
+            break;
+        if (l.indent > n)
+            unsupported();
+        if (!isSeqItem(l))
+            break;
+        const content = l.text.slice(1).trim();
+        if (content === "" || content.startsWith("#")) {
+            const r = parseValueAfterKey(ls, i + 1, n, false);
+            items.push(r.node);
+            i = r.next;
+            continue;
+        }
+        if (content === "-" || content.startsWith("- ") || splitKey(content) !== null)
+            unsupported();
+        items.push(parseInline(content));
+        i++;
+        if (i < ls.length && ls[i].indent > n)
+            unsupported();
+    }
+    return { node: { t: "seq", items }, next: i };
+}
+// ---------------------------------------------------------------------------
+// Document scan
+// ---------------------------------------------------------------------------
+/** True when the text holds a character PyYAML refuses (non-printable) or a line break it treats specially. */
+function hasRefusedChars(text) {
+    for (const ch of text) {
+        const cp = ch.codePointAt(0) ?? 0;
+        if (cp === 0x09 || cp === 0x0a)
+            continue;
+        if (cp === 0x0d)
+            continue; // a lone CR is caught below
+        if (cp >= 0x20 && cp <= 0x7e)
+            continue;
+        if (cp >= 0xa0 && cp <= 0xd7ff && cp !== 0x2028 && cp !== 0x2029)
+            continue;
+        if (cp >= 0xe000 && cp <= 0xfffc && cp !== 0xfeff)
+            continue;
+        if (cp >= 0x10000 && cp <= 0x10ffff)
+            continue;
+        return true;
+    }
+    return /\r(?!\n)/.test(text);
+}
+/** Does an inline root value at least close on its own line? */
+function rootRestLooksSingleLine(rest) {
+    const c = rest[0];
+    if (c === undefined)
+        return true;
+    if (c === "*" || c === "&" || c === "!" || c === "%" || c === "@" || c === "`")
+        return false;
+    if (c === '"' || c === "'") {
+        try {
+            const q = readQuoted(rest, 0);
+            return onlyCommentAfter(rest.slice(q.end));
+        }
+        catch {
+            return false;
+        }
+    }
+    if (c === "[" || c === "{") {
+        let depth = 0;
+        let quote = null;
+        for (let i = 0; i < rest.length; i++) {
+            const ch = rest[i];
+            if (quote) {
+                if (ch === quote)
+                    quote = null;
+                continue;
+            }
+            if (ch === '"' || ch === "'")
+                quote = ch;
+            else if (ch === "[" || ch === "{")
+                depth++;
+            else if (ch === "]" || ch === "}") {
+                depth--;
+                if (depth === 0)
+                    return onlyCommentAfter(rest.slice(i + 1));
+            }
+        }
+        return false;
+    }
+    return true;
+}
+function scanRoot(text) {
+    if (hasRefusedChars(text))
+        return { kind: "unsupported" };
+    const lines = [];
+    for (const raw of text.split(/\r?\n/)) {
+        const trimmed = raw.trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        const indent = raw.length - raw.trimStart().length;
+        lines.push({
+            indent,
+            text: trimmed,
+            tabIndent: raw.slice(0, indent).includes("\t"),
+            leadTab: raw.startsWith("\t"),
+        });
+    }
+    if (lines.length === 0)
+        return { kind: "unparseable" };
+    const entries = [];
+    let sawContent = false;
+    for (const l of lines) {
+        if (l.indent === 0) {
+            if (l.text === "---" || l.text.startsWith("--- ") || l.text.startsWith("---#")) {
+                if (sawContent || l.text !== "---")
+                    return { kind: "unsupported" };
+                continue;
+            }
+            if (l.text.startsWith("...") || l.text.startsWith("%"))
+                return { kind: "unsupported" };
+            sawContent = true;
+            if (isSeqItem(l)) {
+                if (entries.length === 0)
+                    return { kind: "unparseable" }; // a sequence document
+                entries[entries.length - 1].region.push(l);
+                continue;
+            }
+            const kv = splitKey(l.text);
+            if (kv === null)
+                return { kind: "unsupported" };
+            if (kv.key.t !== "str" && kv.key.t !== "bool")
+                return { kind: "unsupported" };
+            if (!rootRestLooksSingleLine(kv.rest))
+                return { kind: "unsupported" };
+            entries.push({ id: keyId(kv.key), rest: kv.rest, region: [] });
+            continue;
+        }
+        // Indented line: belongs to the latest root entry. A tab-led line cannot be indentation.
+        if (l.leadTab)
+            return { kind: "unsupported" };
+        sawContent = true;
+        if (entries.length === 0)
+            return { kind: "unsupported" };
+        entries[entries.length - 1].region.push(l);
+    }
+    return { kind: "ok", entries };
+}
+/** Find the trigger entry: a string `on` wins over a boolean-true key; last duplicate wins. */
+function findTrigger(entries) {
+    let str = null;
+    let bool = null;
+    for (const e of entries) {
+        if (e.id === "s:on")
+            str = e;
+        else if (e.id === "b:true")
+            bool = e;
+    }
+    return str ?? bool;
+}
+function parseEntryValue(e) {
+    if (e.rest !== "") {
+        if (e.region.length > 0)
+            unsupported();
+        return parseInline(e.rest);
+    }
+    if (e.region.length === 0)
+        return { t: "null" };
+    const r = parseBlockAt(e.region, 0);
+    if (r.next !== e.region.length)
+        unsupported();
+    return r.node;
+}
+/** True when any job under the root `jobs` mapping has a job-level `uses` key. */
+function jobsHaveUses(entries) {
+    let jobs = null;
+    for (const e of entries)
+        if (e.id === "s:jobs")
+            jobs = e;
+    if (jobs === null)
+        return false;
+    if (jobs.rest !== "") {
+        if (jobs.region.length === 0 && /^\{\s*\}(\s*|\s+#.*)$/.test(jobs.rest))
+            return false;
+        if (jobs.region.length === 0 && parseInline(jobs.rest).t !== "map")
+            return false;
+        unsupported();
+    }
+    const region = jobs.region;
+    if (region.length === 0)
+        return false;
+    const jobIndent = region[0].indent;
+    if (jobIndent === 0)
+        unsupported();
+    let childIndent = null;
+    let inJob = false;
+    for (const l of region) {
+        if (l.indent < jobIndent)
+            unsupported();
+        if (l.indent === jobIndent) {
+            checkLine(l);
+            const kv = splitKey(l.text);
+            if (kv === null || kv.rest !== "")
+                unsupported();
+            inJob = true;
+            childIndent = null;
+            continue;
+        }
+        if (!inJob)
+            unsupported();
+        childIndent ??= l.indent;
+        if (l.indent < childIndent)
+            unsupported();
+        if (l.indent > childIndent)
+            continue;
+        checkLine(l);
+        if (isSeqItem(l))
+            continue;
+        const kv = splitKey(l.text);
+        if (kv === null)
+            unsupported();
+        if (kv.key.t === "str" && kv.key.v === "uses")
+            return true;
+    }
+    return false;
+}
+function classifyOrThrow(text) {
+    if (typeof text !== "string" || text.trim() === "")
+        return couldNotTell("unparseable");
+    const root = scanRoot(text);
+    if (root.kind === "unparseable")
+        return couldNotTell("unparseable");
+    if (root.kind === "unsupported")
+        return couldNotTell("unsupported_structure");
+    const trigger = findTrigger(root.entries);
+    if (trigger === null)
+        return couldNotTell("unparseable");
+    // Every candidate trigger entry is parsed, not just the winner: a losing
+    // duplicate must still be valid YAML for the document to load at all.
+    for (const e of root.entries) {
+        if (e !== trigger && (e.id === "s:on" || e.id === "b:true"))
+            parseEntryValue(e);
+    }
+    const node = parseEntryValue(trigger);
+    let triggerNames;
+    let prResults = [];
+    if (node.t === "str") {
+        if (PR_TRIGGER_KEYS.includes(node.v))
+            return COVERS;
+        triggerNames = [node.v];
+    }
+    else if (node.t === "seq") {
+        if (node.items.some((i) => i.t === "str" && PR_TRIGGER_KEYS.includes(i.v))) {
+            return COVERS;
+        }
+        if (!node.items.every((i) => i.t === "str"))
+            return couldNotTell("unsupported_structure");
+        triggerNames = node.items.map((i) => i.v);
+    }
+    else if (node.t === "map") {
+        triggerNames = [...node.entries.keys()].filter((k) => k.startsWith("s:")).map((k) => k.slice(2));
+        prResults = PR_TRIGGER_KEYS.filter((k) => node.entries.has(`s:${k}`)).map((k) => classifyPrEvent(node.entries.get(`s:${k}`)));
+        if (prResults.some((r) => r.coverage === "covers"))
+            return COVERS;
+        const uncertain = prResults.find((r) => r.coverage === "could_not_tell");
+        if (uncertain)
+            return uncertain;
+    }
+    else {
+        return couldNotTell("unsupported_structure");
+    }
+    if (triggerNames.some((n) => INDIRECT_TRIGGER_KEYS.has(n)))
+        return couldNotTell("indirect_trigger");
+    if (jobsHaveUses(root.entries))
+        return couldNotTell("reusable_workflow_job");
+    return prResults.length > 0 ? EXCLUDES : { coverage: "does_not_cover", reason: "no_pr_trigger" };
+}
+/**
+ * Does this workflow's PR trigger run for a pull request whose base is
+ * `epic/<EPIC>`? Never throws; see the module truth table.
+ */
+export function classifyEpicPullRequestTrigger(text) {
+    try {
+        return classifyOrThrow(text);
+    }
+    catch (err) {
+        return couldNotTell(err instanceof UnsupportedYaml ? "unsupported_structure" : "unparseable");
+    }
+}
+// ---------------------------------------------------------------------------
+// Repository aggregate
+// ---------------------------------------------------------------------------
+const WORKFLOWS_DIR = ".github/workflows";
+function isPlainEntry(name) {
+    return name !== "" && name !== "." && name !== ".." && !/[/\\\0]/.test(name);
+}
+function byCodeUnit(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+const TIMED_OUT = Symbol("timed_out");
+async function readWithTimeout(fsSeam, relPath, timeoutMs) {
+    let timer;
+    try {
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(TIMED_OUT), Math.max(0, timeoutMs));
+        });
+        const result = await Promise.race([fsSeam.readText(relPath), timeout]);
+        if (result === TIMED_OUT || typeof result !== "string")
+            return null;
+        if (Buffer.byteLength(result, "utf8") > MAX_DISCOVERY_FILE_BYTES)
+            return null;
+        return result;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Inspect every workflow under `.github/workflows` and aggregate. Bounded by
+ * {@link MAX_WORKFLOW_FILES}, {@link MAX_DISCOVERY_FILE_BYTES}, a per-read
+ * timeout, and an overall read budget. Never throws.
+ */
+export async function inspectEpicBranchWorkflowCoverage(fs, budget = {}) {
+    const now = budget.now ?? Date.now;
+    const perRead = budget.perReadTimeoutMs ?? DEFAULT_PER_READ_TIMEOUT_MS;
+    const overall = budget.overallBudgetMs ?? DEFAULT_OVERALL_BUDGET_MS;
+    try {
+        let entries;
+        try {
+            entries = await fs.listDir(WORKFLOWS_DIR);
+        }
+        catch {
+            entries = null;
+        }
+        if (entries === null) {
+            let exists;
+            try {
+                exists = await fs.exists(WORKFLOWS_DIR);
+            }
+            catch {
+                exists = null;
+            }
+            return exists === false
+                ? { coverage: "does_not_cover", reason: "no_workflows", workflows: [] }
+                : { coverage: "could_not_tell", reason: "listing_failed", workflows: [] };
+        }
+        if (!Array.isArray(entries))
+            return { coverage: "could_not_tell", reason: "listing_failed", workflows: [] };
+        const all = entries
+            .filter((n) => typeof n === "string" && isPlainEntry(n) && /\.ya?ml$/.test(n))
+            .sort(byCodeUnit);
+        const truncated = all.length > MAX_WORKFLOW_FILES;
+        const files = all.slice(0, MAX_WORKFLOW_FILES);
+        if (files.length === 0)
+            return { coverage: "does_not_cover", reason: "no_workflows", workflows: [] };
+        const started = now();
+        const workflows = [];
+        for (const file of files) {
+            const path = `${WORKFLOWS_DIR}/${file}`;
+            const remaining = overall - (now() - started);
+            if (remaining <= 0) {
+                workflows.push({ path, coverage: "could_not_tell", reason: "read_failed" });
+                continue;
+            }
+            const text = await readWithTimeout(fs, path, Math.min(perRead, remaining));
+            if (text === null) {
+                workflows.push({ path, coverage: "could_not_tell", reason: "read_failed" });
+                continue;
+            }
+            workflows.push({ path, ...classifyEpicPullRequestTrigger(text) });
+        }
+        if (workflows.some((w) => w.coverage === "covers")) {
+            return { coverage: "covers", reason: "pr_trigger_covers", workflows };
+        }
+        if (truncated)
+            return { coverage: "could_not_tell", reason: "file_limit_reached", workflows };
+        if (workflows.some((w) => w.reason === "read_failed")) {
+            return { coverage: "could_not_tell", reason: "read_failed", workflows };
+        }
+        const unresolved = workflows.find((w) => w.coverage === "could_not_tell");
+        if (unresolved)
+            return { coverage: "could_not_tell", reason: unresolved.reason, workflows };
+        const excluded = workflows.some((w) => w.reason === "branch_filter_excludes_epic");
+        return {
+            coverage: "does_not_cover",
+            reason: excluded ? "branch_filter_excludes_epic" : "no_pr_trigger",
+            workflows,
+        };
+    }
+    catch {
+        return { coverage: "could_not_tell", reason: "listing_failed", workflows: [] };
+    }
+}
+/** Closed reason tokens returned by the `gh` functions. */
+export const EPIC_BRANCH_RULES_REASONS = [
+    "invalid_input",
+    "gh_unavailable",
+    "gh_unauthenticated",
+    "gh_failed",
+    "not_found",
+    "unparseable_response",
+    "malformed_rule",
+    "rules_truncated",
+    "branch_not_proven",
+    "approvals_required",
+    "approvals_not_required",
+    "no_rules_apply",
+];
+/** Closed reason tokens for {@link assessApprovalExemptionScope} / {@link applyApprovalExemption}. */
+export const EXEMPTION_REASONS = [
+    "eligible",
+    "no_approval_rule",
+    "rules_unreadable",
+    "malformed_rule",
+    "not_repository_ruleset",
+    "ruleset_unreadable",
+    "ruleset_detail_incomplete",
+    "ruleset_not_branch_target",
+    "ruleset_has_other_rules",
+    "ruleset_has_other_conditions",
+    "exclusion_present",
+    "scope_not_eligible",
+    "ruleset_changed",
+    "apply_failed",
+    "verification_failed",
+    "approvals_still_required",
+    "status_checks_changed",
+    "confirmed",
+];
+/** The ref exclusion an approved exemption adds. */
+export const EPIC_EXCLUDE_REF = "refs/heads/epic/**";
+const RULES_PER_PAGE = 100;
+const OWNER_REPO_RE = /^[A-Za-z0-9_.-]{1,100}\/[A-Za-z0-9_.-]{1,100}$/;
+const BRANCH_RE = /^[A-Za-z0-9._/-]{1,255}$/;
+function validOwnerRepo(ownerRepo) {
+    return typeof ownerRepo === "string" && OWNER_REPO_RE.test(ownerRepo) && !ownerRepo.split("/").some((p) => p === "." || p === "..");
+}
+function validBranch(branch) {
+    return (typeof branch === "string" &&
+        BRANCH_RE.test(branch) &&
+        !branch.startsWith("-") &&
+        !branch.startsWith("/") &&
+        !branch.endsWith("/") &&
+        !branch.split("/").some((p) => p === "" || p === "." || p === ".."));
+}
+function encodeBranchPath(branch) {
+    return branch.split("/").map(encodeURIComponent).join("/");
+}
+const GH_JSON_HEADERS = ["-H", "Accept: application/vnd.github+json", "-H", "X-GitHub-Api-Version: 2022-11-28"];
+/** Run `gh api ...` and parse JSON. Output text is inspected for status only and never returned. */
+async function ghApiJson(run, args, input) {
+    let result;
+    try {
+        result = await run(["api", ...GH_JSON_HEADERS, ...args], input === undefined ? undefined : { input });
+    }
+    catch {
+        return { ok: false, reason: "gh_unavailable" };
+    }
+    if (!result || typeof result.exitCode !== "number")
+        return { ok: false, reason: "gh_failed" };
+    if (result.exitCode !== 0) {
+        const err = typeof result.stderr === "string" ? result.stderr : "";
+        if (/HTTP 404\b/.test(err))
+            return { ok: false, reason: "not_found" };
+        if (/HTTP 401\b|gh auth login|not logged in|authentication required/i.test(err)) {
+            return { ok: false, reason: "gh_unauthenticated" };
+        }
+        return { ok: false, reason: "gh_failed" };
+    }
+    try {
+        return { ok: true, json: JSON.parse(typeof result.stdout === "string" ? result.stdout : "") };
+    }
+    catch {
+        return { ok: false, reason: "unparseable_response" };
+    }
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isNonNegInt(v) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 0;
+}
+/** GET the effective rules for a branch and validate every entry. */
+async function readBranchRules(run, ownerRepo, branch) {
+    const call = await ghApiJson(run, [
+        `repos/${ownerRepo}/rules/branches/${encodeBranchPath(branch)}?per_page=${RULES_PER_PAGE}`,
+    ]);
+    if (!call.ok)
+        return { ok: false, reason: call.reason };
+    if (!Array.isArray(call.json))
+        return { ok: false, reason: "unparseable_response" };
+    if (call.json.length >= RULES_PER_PAGE)
+        return { ok: false, reason: "rules_truncated" };
+    const pullRequestRules = [];
+    const checks = new Set();
+    for (const rule of call.json) {
+        if (!isRecord(rule) || typeof rule.type !== "string")
+            return { ok: false, reason: "malformed_rule" };
+        const rulesetId = isNonNegInt(rule.ruleset_id) ? rule.ruleset_id : null;
+        const sourceType = typeof rule.ruleset_source_type === "string" ? rule.ruleset_source_type : null;
+        const source = typeof rule.ruleset_source === "string" ? rule.ruleset_source : null;
+        if (rule.type === "pull_request") {
+            const p = rule.parameters;
+            if (!isRecord(p) || !isNonNegInt(p.required_approving_review_count)) {
+                return { ok: false, reason: "malformed_rule" };
+            }
+            pullRequestRules.push({
+                count: p.required_approving_review_count,
+                codeOwnerReview: p.require_code_owner_review === true,
+                rulesetId,
+                sourceType,
+                source,
+            });
+        }
+        else if (rule.type === "required_status_checks") {
+            const p = rule.parameters;
+            if (!isRecord(p) || !Array.isArray(p.required_status_checks))
+                return { ok: false, reason: "malformed_rule" };
+            for (const c of p.required_status_checks) {
+                if (!isRecord(c) || typeof c.context !== "string")
+                    return { ok: false, reason: "malformed_rule" };
+                checks.add(c.context);
+            }
+        }
+    }
+    return { ok: true, rules: { pullRequestRules, statusChecks: [...checks].sort(byCodeUnit) } };
+}
+/** Prove the branch exists: true, false (404), or null (could not tell). */
+async function branchExists(run, ownerRepo, branch) {
+    const call = await ghApiJson(run, [`repos/${ownerRepo}/branches/${encodeBranchPath(branch)}`]);
+    if (call.ok)
+        return isRecord(call.json) ? true : null;
+    return call.reason === "not_found" ? false : null;
+}
+const NO_DEFAULT_CONTEXT = { defaultBranch: null, approvals: "could_not_tell", count: null };
+/**
+ * Read classic branch protection on the repository's DEFAULT branch, as
+ * context only. GET-only and bounded: the repository read (for
+ * `default_branch`), the protection read, and — only on a protection 404 — a
+ * branch read proving the branch is visible (a 404 alone may mean "cannot
+ * see"). Absent review settings → `no`. Any failure → `could_not_tell`.
+ * Never throws; returns no response text.
+ */
+export async function readDefaultBranchClassicContextViaGh(run, ownerRepo) {
+    try {
+        if (!validOwnerRepo(ownerRepo))
+            return NO_DEFAULT_CONTEXT;
+        const repo = await ghApiJson(run, [`repos/${ownerRepo}`]);
+        if (!repo.ok || !isRecord(repo.json))
+            return NO_DEFAULT_CONTEXT;
+        const defaultBranch = repo.json.default_branch;
+        if (typeof defaultBranch !== "string" || !validBranch(defaultBranch))
+            return NO_DEFAULT_CONTEXT;
+        const unknown = { defaultBranch, approvals: "could_not_tell", count: null };
+        const branchPath = encodeBranchPath(defaultBranch);
+        const prot = await ghApiJson(run, [`repos/${ownerRepo}/branches/${branchPath}/protection`]);
+        if (!prot.ok) {
+            if (prot.reason !== "not_found")
+                return unknown;
+            const exists = await branchExists(run, ownerRepo, defaultBranch);
+            return exists === true ? { defaultBranch, approvals: "no", count: null } : unknown;
+        }
+        if (!isRecord(prot.json))
+            return unknown;
+        const reviews = prot.json.required_pull_request_reviews;
+        if (reviews === undefined || reviews === null)
+            return { defaultBranch, approvals: "no", count: null };
+        if (!isRecord(reviews))
+            return unknown;
+        const count = reviews.required_approving_review_count;
+        if (!isNonNegInt(count))
+            return unknown;
+        return { defaultBranch, approvals: count > 0 ? "yes" : "no", count };
+    }
+    catch {
+        return NO_DEFAULT_CONTEXT;
+    }
+}
+function withDefaultContext(f, c) {
+    return {
+        ...f,
+        defaultBranch: c.defaultBranch,
+        defaultBranchClassicApprovals: c.approvals,
+        defaultBranchClassicApprovalCount: c.count,
+    };
+}
+function rulesCouldNotTell(branch, reason) {
+    return {
+        branch,
+        approvalsRequired: "could_not_tell",
+        requiredApprovingReviewCount: null,
+        requiredStatusChecks: [],
+        observationQuality: "could_not_tell",
+        reason,
+    };
+}
+/**
+ * Read the effective branch rules for `branch` (normally `epic/<EPIC>`) through
+ * `gh`. A `pull_request` rule requiring at least one approval (or code-owner
+ * review) → `yes` / `inferred` (bypass eligibility is unknown). No such rule,
+ * every rule well formed, and the branch proven to exist → `no` / `exact`. For
+ * a branch not proven to exist the same answer is `no` / `inferred`: GitHub
+ * documents that "the branch does not need to exist; rules that would apply to
+ * a branch with that name will be returned"
+ * (https://docs.github.com/en/rest/repos/rules#get-rules-for-a-branch). That is
+ * documented but not yet live-verified (Bridge-GPT/bridge-api is a private
+ * repository whose plan lacks rulesets), hence `inferred`. A non-200 reply,
+ * including the 403 a plan without rulesets returns, stays `could_not_tell`. It also
+ * attaches the default branch's classic protection as separately labelled
+ * CONTEXT ({@link readDefaultBranchClassicContextViaGh}); that context never
+ * changes `approvalsRequired`. Never throws.
+ */
+export async function readEpicBranchRulesViaGh(run, ownerRepo, branch) {
+    try {
+        if (!validOwnerRepo(ownerRepo) || !validBranch(branch))
+            return rulesCouldNotTell(String(branch), "invalid_input");
+        const finding = await readEpicBranchRulesOnly(run, ownerRepo, branch);
+        // When gh itself is missing or signed out, the context read would fail the
+        // same way; skip it rather than spend two more doomed calls.
+        const ghDown = finding.reason === "gh_unavailable" || finding.reason === "gh_unauthenticated";
+        const context = ghDown ? NO_DEFAULT_CONTEXT : await readDefaultBranchClassicContextViaGh(run, ownerRepo);
+        return withDefaultContext(finding, context);
+    }
+    catch {
+        return rulesCouldNotTell(typeof branch === "string" ? branch : "", "gh_failed");
+    }
+}
+async function readEpicBranchRulesOnly(run, ownerRepo, branch) {
+    const read = await readBranchRules(run, ownerRepo, branch);
+    if (!read.ok)
+        return rulesCouldNotTell(branch, read.reason);
+    const { pullRequestRules, statusChecks } = read.rules;
+    if (pullRequestRules.length > 0) {
+        const count = Math.max(...pullRequestRules.map((r) => r.count));
+        const required = count > 0 || pullRequestRules.some((r) => r.codeOwnerReview);
+        return {
+            branch,
+            approvalsRequired: required ? "yes" : "no",
+            requiredApprovingReviewCount: count,
+            requiredStatusChecks: statusChecks,
+            observationQuality: "inferred",
+            reason: required ? "approvals_required" : "approvals_not_required",
+        };
+    }
+    // The rules read is trusted even for a branch that does not exist yet (see
+    // above); only the quality depends on whether the branch was proven to exist.
+    const exists = await branchExists(run, ownerRepo, branch);
+    return {
+        branch,
+        approvalsRequired: "no",
+        requiredApprovingReviewCount: null,
+        requiredStatusChecks: statusChecks,
+        observationQuality: exists === true ? "exact" : "inferred",
+        reason: "no_rules_apply",
+    };
+}
+/**
+ * Validate one ruleset's full detail and build its update body: the ruleset as
+ * read (name, target, enforcement, conditions, rules, bypass_actors), with
+ * {@link EPIC_EXCLUDE_REF} appended to `conditions.ref_name.exclude`.
+ */
+async function checkRuleset(run, ownerRepo, id) {
+    const call = await ghApiJson(run, [`repos/${ownerRepo}/rulesets/${id}`]);
+    if (!call.ok || !isRecord(call.json))
+        return { ok: false, reason: "ruleset_unreadable" };
+    const d = call.json;
+    if (d.id !== id || typeof d.name !== "string" || typeof d.enforcement !== "string") {
+        return { ok: false, reason: "ruleset_detail_incomplete" };
+    }
+    if (d.source_type !== "Repository")
+        return { ok: false, reason: "not_repository_ruleset" };
+    if (typeof d.source === "string" && d.source.toLowerCase() !== ownerRepo.toLowerCase()) {
+        return { ok: false, reason: "not_repository_ruleset" };
+    }
+    if (d.target !== "branch")
+        return { ok: false, reason: "ruleset_not_branch_target" };
+    if (!Array.isArray(d.rules) || !Array.isArray(d.bypass_actors) || !isRecord(d.conditions)) {
+        return { ok: false, reason: "ruleset_detail_incomplete" };
+    }
+    if (d.rules.length !== 1 || !isRecord(d.rules[0]) || d.rules[0].type !== "pull_request") {
+        return { ok: false, reason: "ruleset_has_other_rules" };
+    }
+    const conditionKeys = Object.keys(d.conditions);
+    if (conditionKeys.length !== 1 || conditionKeys[0] !== "ref_name") {
+        return { ok: false, reason: "ruleset_has_other_conditions" };
+    }
+    const refName = d.conditions.ref_name;
+    if (!isRecord(refName) ||
+        !Array.isArray(refName.include) ||
+        !Array.isArray(refName.exclude) ||
+        !refName.include.every((s) => typeof s === "string") ||
+        !refName.exclude.every((s) => typeof s === "string")) {
+        return { ok: false, reason: "ruleset_detail_incomplete" };
+    }
+    if (refName.exclude.includes(EPIC_EXCLUDE_REF))
+        return { ok: false, reason: "exclusion_present" };
+    const body = {
+        name: d.name,
+        target: d.target,
+        enforcement: d.enforcement,
+        conditions: { ...d.conditions, ref_name: { ...refName, exclude: [...refName.exclude, EPIC_EXCLUDE_REF] } },
+        rules: d.rules,
+        bypass_actors: d.bypass_actors,
+    };
+    return { ok: true, body };
+}
+function ineligible(reason, rulesetIds = []) {
+    return { eligible: false, reason, rulesetIds };
+}
+/**
+ * Decide whether the approval requirement on `branch` can be exempted by only
+ * excluding `epic/**` from repository-level rulesets. Eligible only when every
+ * applicable `pull_request` rule comes from a readable, repository-level,
+ * branch-targeted ruleset whose sole rule is that `pull_request` rule and whose
+ * only condition is `ref_name`. Read-only. Never throws.
+ */
+export async function assessApprovalExemptionScope(run, ownerRepo, branch) {
+    try {
+        if (!validOwnerRepo(ownerRepo) || !validBranch(branch))
+            return ineligible("rules_unreadable");
+        const read = await readBranchRules(run, ownerRepo, branch);
+        if (!read.ok)
+            return ineligible(read.reason === "malformed_rule" ? "malformed_rule" : "rules_unreadable");
+        const prRules = read.rules.pullRequestRules;
+        if (prRules.length === 0)
+            return ineligible("no_approval_rule");
+        const ids = new Set();
+        for (const r of prRules) {
+            if (r.rulesetId === null || r.sourceType === null)
+                return ineligible("malformed_rule");
+            if (r.sourceType !== "Repository")
+                return ineligible("not_repository_ruleset");
+            ids.add(r.rulesetId);
+        }
+        const rulesetIds = [...ids].sort((a, b) => a - b);
+        for (const id of rulesetIds) {
+            const check = await checkRuleset(run, ownerRepo, id);
+            if (!check.ok)
+                return ineligible(check.reason, rulesetIds);
+        }
+        return { eligible: true, reason: "eligible", rulesetIds };
+    }
+    catch {
+        return ineligible("rules_unreadable");
+    }
+}
+function sameList(a, b) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+/**
+ * Apply the exemption: add {@link EPIC_EXCLUDE_REF} to each assessed ruleset's
+ * ref exclusions (`gh api --method PUT repos/{o}/{r}/rulesets/{id} --input -`),
+ * then re-read the branch rules. Confirmed only when no `pull_request` rule
+ * remains and the required status check contexts are unchanged. Refuses unless
+ * `assessment.eligible`; re-validates each ruleset immediately before writing.
+ * Never attempts a repair. The caller must have the user's explicit consent.
+ */
+export async function applyApprovalExemption(run, ownerRepo, branch, assessment) {
+    try {
+        if (!assessment ||
+            assessment.eligible !== true ||
+            !Array.isArray(assessment.rulesetIds) ||
+            assessment.rulesetIds.length === 0 ||
+            !assessment.rulesetIds.every(isNonNegInt) ||
+            !validOwnerRepo(ownerRepo) ||
+            !validBranch(branch)) {
+            return { confirmed: false, reason: "scope_not_eligible" };
+        }
+        const before = await readBranchRules(run, ownerRepo, branch);
+        if (!before.ok)
+            return { confirmed: false, reason: "ruleset_changed" };
+        const bodies = [];
+        for (const id of assessment.rulesetIds) {
+            const check = await checkRuleset(run, ownerRepo, id);
+            if (!check.ok)
+                return { confirmed: false, reason: "ruleset_changed" };
+            bodies.push({ id, body: check.body });
+        }
+        for (const { id, body } of bodies) {
+            const put = await ghApiJson(run, ["--method", "PUT", `repos/${ownerRepo}/rulesets/${id}`, "--input", "-"], JSON.stringify(body));
+            if (!put.ok)
+                return { confirmed: false, reason: "apply_failed" };
+        }
+        const after = await readBranchRules(run, ownerRepo, branch);
+        if (!after.ok)
+            return { confirmed: false, reason: "verification_failed" };
+        if (after.rules.pullRequestRules.length > 0)
+            return { confirmed: false, reason: "approvals_still_required" };
+        if (!sameList(before.rules.statusChecks, after.rules.statusChecks)) {
+            return { confirmed: false, reason: "status_checks_changed" };
+        }
+        return { confirmed: true, reason: "confirmed" };
+    }
+    catch {
+        return { confirmed: false, reason: "verification_failed" };
+    }
+}
+/**
+ * Copyable, repository-specific manual steps for exempting epic branches from
+ * approval rules. Makes no change itself. `epicBranch` defaults to the
+ * placeholder `epic/<EPIC>`.
+ */
+export function exemptionManualSteps(ownerRepo, epicBranch = "epic/<EPIC>") {
+    const repo = validOwnerRepo(ownerRepo) ? ownerRepo : "<OWNER>/<REPO>";
+    const branch = epicBranch === "epic/<EPIC>" || validBranch(epicBranch) ? epicBranch : "epic/<EPIC>";
+    return [
+        "1. List the repository's rulesets and the rules that apply to an epic branch:",
+        `   gh api repos/${repo}/rulesets`,
+        `   gh api repos/${repo}/rules/branches/${branch}`,
+        "2. For each pull_request rule above, note its ruleset_id and view that ruleset:",
+        `   gh api repos/${repo}/rulesets/<RULESET_ID>`,
+        `3. Add "${EPIC_EXCLUDE_REF}" to conditions.ref_name.exclude and send the whole ruleset back:`,
+        `   gh api repos/${repo}/rulesets/<RULESET_ID> | jq '{name, target, enforcement, conditions, rules, bypass_actors} | .conditions.ref_name.exclude += ["${EPIC_EXCLUDE_REF}"]' > ruleset.json`,
+        `   gh api --method PUT repos/${repo}/rulesets/<RULESET_ID> --input ruleset.json`,
+        "   Or in the GitHub UI: Settings → Rules → Rulesets → <ruleset> → Target branches → Exclude by pattern → epic/**",
+        "4. Keep required status checks enforced on epic branches. If the same ruleset also requires status checks,",
+        "   move the pull_request rule into its own ruleset first instead of excluding epic/** from the shared one.",
+        "5. Confirm no pull_request rule remains and the required checks are unchanged:",
+        `   gh api repos/${repo}/rules/branches/${branch}`,
+    ];
+}
+/** Map the installer's richer exemption outcome onto the stored evidence vocabulary. */
+export function mapExemptionOutcomeToEvidence(o) {
+    switch (o) {
+        case "applied":
+            return "exempt";
+        case "declined":
+        case "printed_steps":
+        case "not_needed":
+            return "not_exempt";
+        default:
+            return "unknown";
+    }
+}
+/** Build the closed, secret-free evidence recorded beside the decision. */
+export function buildEpicBranchCiEvidence(coverage, rules, exemption) {
+    const approvals = rules?.approvalsRequired ?? "could_not_tell";
+    let quality;
+    if (coverage === "could_not_tell" || approvals === "could_not_tell" || rules?.observationQuality === "could_not_tell") {
+        quality = "could_not_tell";
+    }
+    else if (rules?.observationQuality === "inferred") {
+        quality = "inferred";
+    }
+    else {
+        quality = "exact";
+    }
+    return {
+        workflow_triggers_cover_epic: coverage === "covers" ? true : coverage === "does_not_cover" ? false : null,
+        required_approvals_apply_to_epic: approvals === "yes" ? true : approvals === "no" ? false : null,
+        observation_quality: quality,
+        exemption_outcome: mapExemptionOutcomeToEvidence(exemption),
+    };
+}