@loopover/engine 1.0.0

package/dist/review/review-thread-findings.d.ts

@@ -0,0 +1 @@
+export declare const REVIEW_THREAD_BLOCKER_CODE = "review_thread_unresolved";

package/dist/review/review-thread-findings.js

@@ -0,0 +1 @@
+export const REVIEW_THREAD_BLOCKER_CODE = "review_thread_unresolved";

package/dist/review/safe-url.d.ts

@@ -0,0 +1,5 @@
+/** https + public (non-loopback, non-private) host. */
+export declare function isSafeHttpUrl(raw: string): boolean;
+/** Like isSafeHttpUrl but also permits secure WebSocket endpoints (`wss:`, `ws:`) — base-layer chain
+ *  endpoints (subtensor RPC/WSS/archive) are probed via JSON-RPC, not HTTP. Same SSRF host/IP guard. */
+export declare function isSafeEndpointUrl(raw: string): boolean;

package/dist/review/safe-url.js

@@ -0,0 +1,137 @@
+// SSRF-safe URL guard (content-lane primitive).
+//
+// SELF-CONTAINED NATIVE PORT (reviewbot→gittensory convergence). Ported from reviewbot's
+// core/source-url.ts isSafeHttpUrl + isSafeEndpointUrl (the host/IP guard, including the encoded-IP
+// decoding that a dotted-quad regex misses), hardened so a trailing-dot or `*.localhost` host can't
+// dodge the loopback check. PURE — no imports, no I/O.
+//
+// Rejects non-HTTPS (isSafeHttpUrl), localhost / `*.localhost` / .local / .internal, and private/
+// loopback/link-local IPs in any literal notation (decimal `2130706433`, hex `0x7f000001`, octal,
+// short `127.1`, and the IPv6 forms). isSafeEndpointUrl additionally permits wss:/ws: for base-layer
+// chain endpoints.
+function parseIpv4Component(part) {
+    if (/^0x[0-9a-f]+$/i.test(part))
+        return parseInt(part, 16);
+    if (/^0[0-7]+$/.test(part))
+        return parseInt(part, 8); // leading-zero → octal
+    if (/^(?:0|[1-9]\d*)$/.test(part))
+        return parseInt(part, 10);
+    return null;
+}
+function ipv4ToInt(host) {
+    const parts = host.split(".");
+    if (parts.length < 1 || parts.length > 4)
+        return null;
+    const vals = [];
+    for (const part of parts) {
+        const v = parseIpv4Component(part);
+        if (v === null || !Number.isFinite(v) || v < 0)
+            return null;
+        vals.push(v);
+    }
+    const n = vals.length;
+    // Byte-faithful overflow guards from reviewbot's core/source-url.ts. Unreachable via the public
+    // isSafe*Url entry points: a host reaches here only after `new URL()`, and the WHATWG parser
+    // rejects any all-numeric dotted host whose components overflow (so the >0xff / >lastMax / >2^32
+    // cases never arrive), while a host that survives parsing as a domain has a non-numeric label that
+    // makes parseIpv4Component bail (line 26) before these run. Retained for source parity + defense.
+    /* v8 ignore start -- @preserve unreachable through new URL() host normalization (see note above) */
+    for (let i = 0; i < n - 1; i += 1)
+        if (vals[i] > 0xff)
+            return null;
+    const lastMax = [0xffffffff, 0xffffff, 0xffff, 0xff][n - 1];
+    if (vals[n - 1] > lastMax)
+        return null;
+    let result = vals[n - 1];
+    for (let i = 0; i < n - 1; i += 1)
+        result += vals[i] * 256 ** (3 - i);
+    return result > 0xffffffff ? null : result >>> 0;
+    /* v8 ignore stop */
+}
+function ipv4IsPrivateOrLocal(host) {
+    const n = ipv4ToInt(host);
+    if (n === null)
+        return false;
+    const a = (n >>> 24) & 0xff;
+    const b = (n >>> 16) & 0xff;
+    if (a === 0 || a === 10 || a === 127)
+        return true; // 0.0.0.0/8, 10/8, loopback
+    if (a === 169 && b === 254)
+        return true; // link-local (incl. cloud metadata 169.254.169.254)
+    if (a === 192 && b === 168)
+        return true;
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    return false;
+}
+function ipv6IsPrivateOrLocal(host) {
+    const addr = host.replace(/^\[|\]$/g, "");
+    // Caller (hostIsPrivateOrLocal) only invokes this when the host contains ":", and bracket
+    // stripping never removes an interior colon — so the no-colon guard's true side is unreachable.
+    /* v8 ignore next -- @preserve true side unreachable: caller guards host.includes(":") */
+    if (!addr.includes(":"))
+        return false;
+    if (addr === "::1" || addr === "::")
+        return true;
+    // `new URL()` collapses the dotted IPv4-mapped form (::ffff:127.0.0.1) to the hex form
+    // (::ffff:7f00:1), so this dotted-quad regex never matches via the public entry points; the hex
+    // branch below carries the IPv4-mapped case. Retained for source parity.
+    const dotted = addr.match(/::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+    /* v8 ignore next -- @preserve dotted ::ffff:N.N.N.N is normalized to hex by new URL() */
+    if (dotted)
+        return ipv4IsPrivateOrLocal(dotted[1]);
+    const hex = addr.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (hex) {
+        const hi = parseInt(hex[1], 16);
+        const lo = parseInt(hex[2], 16);
+        return ipv4IsPrivateOrLocal(`${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`);
+    }
+    const first = addr.split(":")[0];
+    if (first.startsWith("fc") || first.startsWith("fd"))
+        return true; // ULA fc00::/7
+    if (/^fe[89ab]/.test(first))
+        return true; // link-local fe80::/10
+    return false;
+}
+function hostIsPrivateOrLocal(host) {
+    // Normalize once: lower-case, then strip the FQDN root dot(s) the parser keeps on named hosts
+    // (`localhost.`) but not on IP literals — else `localhost.` / `foo.internal.` would read as public.
+    const h = host.toLowerCase().replace(/\.+$/, "");
+    // localhost + its RFC 6761 `*.localhost` namespace, plus the reserved `.local` (mDNS) / `.internal`.
+    if (h === "localhost" || h.endsWith(".localhost"))
+        return true;
+    if (h.endsWith(".local") || h.endsWith(".internal"))
+        return true;
+    if (h === "0.0.0.0" || h === "::1" || h === "[::1]")
+        return true;
+    if (h.includes(":"))
+        return ipv6IsPrivateOrLocal(h);
+    return ipv4IsPrivateOrLocal(h);
+}
+/** https + public (non-loopback, non-private) host. */
+export function isSafeHttpUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== "https:")
+        return false;
+    return !hostIsPrivateOrLocal(url.hostname);
+}
+/** Like isSafeHttpUrl but also permits secure WebSocket endpoints (`wss:`, `ws:`) — base-layer chain
+ *  endpoints (subtensor RPC/WSS/archive) are probed via JSON-RPC, not HTTP. Same SSRF host/IP guard. */
+export function isSafeEndpointUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (!["https:", "wss:", "ws:"].includes(url.protocol))
+        return false;
+    return !hostIsPrivateOrLocal(url.hostname);
+}

package/dist/review/screenshot-table-gate.d.ts

@@ -0,0 +1,87 @@
+import type { ScreenshotTableGateAction, ScreenshotTableGateConfig } from "../types/manifest-deps-types.js";
+export type { ScreenshotTableGateAction, ScreenshotTableGateConfig } from "../types/manifest-deps-types.js";
+export declare const DEFAULT_SCREENSHOT_TABLE_GATE: ScreenshotTableGateConfig;
+export declare function isScreenshotTableGateAction(value: unknown): value is ScreenshotTableGateAction;
+/** Normalize a raw `requireScreenshotTable` value (DB JSON or `.gittensory.yml`) into a validated config. Never
+ *  throws: malformed fields fall back to the default (disabled/empty), matching every other settings normalizer
+ *  in this codebase. */
+export declare function normalizeScreenshotTableGateConfig(input: unknown, warnings: string[]): ScreenshotTableGateConfig;
+/** True when `body` contains at least one markdown TABLE region (`| ... |` header + separator row) whose cells
+ *  embed image markup — either `![alt](url)` or an `<img ...>` tag — inside the table. A screenshot pasted as a
+ *  bare inline image OUTSIDE any table does not count (the contract requires captioned thumbnails INSIDE a
+ *  table, not a wall of raw images). Deliberately simple/regex-based (no markdown AST dependency) — false
+ *  negatives fail toward "no table found" (in-scope PRs still need a real table), false positives fail toward
+ *  "table found" (never blocks a PR that plausibly complied); both directions are acceptable for a
+ *  first-pass deterministic heuristic that a maintainer can always override by hand. */
+export declare function hasImageBearingMarkdownTable(body: string | null | undefined): boolean;
+/** True when `body` has a large inline image OUTSIDE of any markdown table — a common way contributors dodge
+ *  the table requirement (paste screenshots directly into the body instead of inside a captioned table row). */
+export declare function hasImageOutsideTable(body: string | null | undefined): boolean;
+/** True when any changed file path is an image under a scoped path (a screenshot committed to the repo instead
+ *  of uploaded to the PR body via GitHub's CDN, per the contract). `scopedPaths` should be the SAME glob list
+ *  used for scope matching (`whenPaths`) so this only flags an image landing where visual work is expected —
+ *  not an unrelated asset (e.g. a favicon) added anywhere else in the repo. Empty `scopedPaths` (no path scoping
+ *  configured) checks every changed path. */
+export declare function hasCommittedImageFile(changedFiles: string[], scopedPaths: string[]): boolean;
+/** One data row of a detected markdown table: the cell texts in source order (leading/trailing pipes and
+ *  whitespace stripped). Deliberately a SEPARATE table-detection pass from {@link hasImageBearingMarkdownTable}
+ *  rather than a shared refactor of it -- that function's exact behavior is pinned by existing tests, and this
+ *  one needs actual cell contents (not just "does some cell have an image"), so duplicating its short
+ *  header+separator detection loop keeps both independently simple instead of risking a regression in either
+ *  from a shared-code change. */
+export declare function extractTableRows(body: string | null | undefined): string[][];
+/** The image URLs found in each detected table row (source order), for rows with at least two — a real
+ *  before/after pair worth comparing, not a single decorative image or caption-only row. Reuses
+ *  {@link extractTableRows}'s own header+separator detection rather than re-scanning the body. A row with
+ *  MORE than two images (e.g. a desktop+mobile matrix row) keeps every image; callers that only want a pair
+ *  slice it themselves. */
+export declare function extractTableRowImageUrls(body: string | null | undefined): string[][];
+/** One (viewport, theme) combination the matrix must cover. `theme: null` means the theme dimension isn't
+ *  required at all (a repo can require viewport coverage without color-mode coverage). */
+export type ScreenshotMatrixPair = {
+    viewport: string;
+    theme: string | null;
+};
+/** The full set of (viewport, theme) pairs `config` requires, or `[]` when matrix mode is off. Matrix mode
+ *  turns on via `requireViewports` alone -- `requireThemes` with an empty `requireViewports` has no effect,
+ *  since there is no viewport to cross it against. */
+export declare function requiredScreenshotMatrixPairs(config: ScreenshotTableGateConfig): ScreenshotMatrixPair[];
+/** The subset of `pairs` with NO satisfying row anywhere in `body`'s tables. Empty ⇒ full coverage. */
+export declare function missingScreenshotMatrixPairs(body: string | null | undefined, pairs: ScreenshotMatrixPair[]): ScreenshotMatrixPair[];
+/** Build the rejection reason for a matrix violation, naming exactly which viewport/theme combinations are
+ *  still missing a real before+after pair -- so the contributor knows precisely what to add, not just that
+ *  "something" is missing. */
+export declare function buildScreenshotMatrixMessage(missing: ScreenshotMatrixPair[]): string;
+/** True when the PR is IN SCOPE for the gate: it carries one of `config.whenLabels` OR touches a path matching
+ *  one of `config.whenPaths`. Both empty ⇒ every PR is in scope (an operator who enables the gate with no
+ *  scoping at all wants it enforced everywhere). Only one non-empty list configured ⇒ that list alone decides
+ *  scope (the other, empty list can never exclude a PR the configured one matched). */
+export declare function isScreenshotTableGateInScope(config: ScreenshotTableGateConfig, prLabels: string[], changedFiles: string[]): boolean;
+export declare const DEFAULT_SCREENSHOT_CONTRACT_MESSAGE: string;
+export type ScreenshotTableGateResult = {
+    violated: boolean;
+    reason: string | null;
+};
+/** PURE evaluator. Off (`enabled: false`) or out-of-scope (no configured label/path match) ⇒ no violation.
+ *  `botCaptureSatisfied` ⇒ no violation regardless of mode (an automated capture is equivalent to a
+ *  hand-authored table, and the bot doesn't (yet) shoot a full viewport/theme matrix -- see #4535's scope note).
+ *
+ *  Two modes, chosen by whether `config.requireViewports` is non-empty (#4535):
+ *  - MATRIX mode: every required (viewport, theme) pair (`requiredScreenshotMatrixPairs`) must have a labeled
+ *    before/after row. Violated ⇒ the reason names exactly which pairs are still missing.
+ *  - PRESENCE mode (the original #2006 behavior, unchanged): in scope AND (no image-bearing table in the body
+ *    OR an image pasted outside a table OR a committed image file under a scoped path) ⇒ violated, with the
+ *    configured (or default) templated message as the reason. */
+export declare function evaluateScreenshotTableGate(input: {
+    config: ScreenshotTableGateConfig;
+    prBody: string | null | undefined;
+    prLabels: string[];
+    changedFiles: string[];
+    /** #4110: true when the bot's own before/after capture pipeline (review.visual.enabled) already produced a
+     *  REAL before+after render pair for this PR's current head — evidence equivalent to a hand-authored table.
+     *  A successful automated capture satisfies the gate on its own, ahead of (and regardless of) the body-table
+     *  anti-gaming checks below — those exist to stop a contributor from FAKING compliance without the bot's
+     *  help, which doesn't apply once the bot has already proven the change visually. Absent/false ⇒
+     *  byte-identical to pre-#4110 behavior (body-table evidence only). */
+    botCaptureSatisfied?: boolean | undefined;
+}): ScreenshotTableGateResult;

package/dist/review/screenshot-table-gate.js

@@ -0,0 +1,340 @@
+import { matchesAny } from "../signals/change-guardrail.js";
+// Config-driven before/after screenshot-table gate (#2006). Contributor visual/frontend PRs are unreviewable
+// at a glance without before/after evidence — this is a DETERMINISTIC (no AI, zero hallucination risk) check
+// that a PR's body contains a markdown table with image markup, scoped to the repo's configured labels/paths.
+// Mirrors the shape of contributor-blacklist.ts / linked-issue-hard-rules-config.ts: a normalizer (DB JSON or
+// `.gittensory.yml` → validated config) plus a pure evaluator the trigger calls with live PR facts. Off by
+// default (`enabled: false`) — a self-hoster opts in per repo, never hard-coded for any one project.
+const MAX_LABELS = 50;
+const MAX_PATHS = 50;
+const MAX_LABEL_CHARS = 100;
+const MAX_PATH_CHARS = 300;
+const MAX_MATRIX_DIMENSION = 12;
+const MAX_MATRIX_TOKEN_CHARS = 40;
+const MAX_SKILL_FILE_URL_CHARS = 300;
+// Extensions treated as "an image file" for the committed-image-file check below. Deliberately excludes SVG:
+// an SVG can embed script/foreign-object content, so it is never accepted as review evidence anywhere in this
+// repo (see the PR template's own UI Evidence rule) — a committed .svg is caught by neither this check nor the
+// body-table one, exactly like the template's existing screenshots-must-be-raster rule.
+const IMAGE_EXTENSIONS = [".png", ".jpg", ".jpeg", ".gif", ".webp"];
+export const DEFAULT_SCREENSHOT_TABLE_GATE = {
+    enabled: false,
+    whenLabels: [],
+    whenPaths: [],
+    action: "close",
+    requireViewports: [],
+    requireThemes: [],
+};
+const VALID_ACTIONS = ["close", "advisory"];
+export function isScreenshotTableGateAction(value) {
+    return typeof value === "string" && VALID_ACTIONS.includes(value);
+}
+function normalizeStringList(value, field, max, maxChars, warnings) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        warnings.push(`settings.requireScreenshotTable.${field} must be an array; ignoring it.`);
+        return [];
+    }
+    const out = [];
+    for (const [index, item] of value.entries()) {
+        if (out.length >= max) {
+            warnings.push(`settings.requireScreenshotTable.${field} is capped at ${max} entries; dropping the rest.`);
+            break;
+        }
+        if (typeof item !== "string" || item.trim().length === 0) {
+            warnings.push(`settings.requireScreenshotTable.${field}[${index}] must be a non-empty string; ignoring it.`);
+            continue;
+        }
+        out.push(item.trim().slice(0, maxChars));
+    }
+    return out;
+}
+/** Normalize a raw `requireScreenshotTable` value (DB JSON or `.gittensory.yml`) into a validated config. Never
+ *  throws: malformed fields fall back to the default (disabled/empty), matching every other settings normalizer
+ *  in this codebase. */
+export function normalizeScreenshotTableGateConfig(input, warnings) {
+    if (input === undefined || input === null)
+        return { ...DEFAULT_SCREENSHOT_TABLE_GATE, whenLabels: [], whenPaths: [], requireViewports: [], requireThemes: [] };
+    if (typeof input !== "object" || Array.isArray(input)) {
+        warnings.push("settings.requireScreenshotTable must be an object; using the default (disabled).");
+        return { ...DEFAULT_SCREENSHOT_TABLE_GATE, whenLabels: [], whenPaths: [], requireViewports: [], requireThemes: [] };
+    }
+    const record = input;
+    const enabled = typeof record.enabled === "boolean" ? record.enabled : DEFAULT_SCREENSHOT_TABLE_GATE.enabled;
+    if (record.enabled !== undefined && typeof record.enabled !== "boolean") {
+        warnings.push(`settings.requireScreenshotTable.enabled must be a boolean; using the default "${DEFAULT_SCREENSHOT_TABLE_GATE.enabled}".`);
+    }
+    const action = isScreenshotTableGateAction(record.action)
+        ? record.action
+        : (() => {
+            if (record.action !== undefined)
+                warnings.push(`settings.requireScreenshotTable.action must be "close" or "advisory" (#4110 removed request_changes/comment as dead config surface); using the default "close".`);
+            return DEFAULT_SCREENSHOT_TABLE_GATE.action;
+        })();
+    const message = typeof record.message === "string" && record.message.trim().length > 0 ? record.message.trim() : undefined;
+    if (record.message !== undefined && message === undefined) {
+        warnings.push("settings.requireScreenshotTable.message must be a non-empty string; using the default message.");
+    }
+    const skillFileUrl = normalizeSkillFileUrl(record.skillFileUrl, warnings);
+    return {
+        enabled,
+        whenLabels: normalizeStringList(record.whenLabels, "whenLabels", MAX_LABELS, MAX_LABEL_CHARS, warnings),
+        whenPaths: normalizeStringList(record.whenPaths, "whenPaths", MAX_PATHS, MAX_PATH_CHARS, warnings),
+        action,
+        requireViewports: normalizeStringList(record.requireViewports, "requireViewports", MAX_MATRIX_DIMENSION, MAX_MATRIX_TOKEN_CHARS, warnings),
+        requireThemes: normalizeStringList(record.requireThemes, "requireThemes", MAX_MATRIX_DIMENSION, MAX_MATRIX_TOKEN_CHARS, warnings),
+        ...(message !== undefined ? { message } : {}),
+        ...(skillFileUrl !== undefined ? { skillFileUrl } : {}),
+    };
+}
+/** Validate a `skillFileUrl` override: same trust/validation level as `message` above (a trusted
+ *  maintainer-authored config value, never fetched server-side -- it is only ever embedded as TEXT in a
+ *  GitHub comment/close reason, so there is no SSRF surface here to guard against, unlike a URL the
+ *  server would dereference). Malformed values are dropped with a warning, never silently coerced. */
+function normalizeSkillFileUrl(value, warnings) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value.trim().length === 0 || value.trim().length > MAX_SKILL_FILE_URL_CHARS) {
+        warnings.push(`settings.requireScreenshotTable.skillFileUrl must be a non-empty string no longer than ${MAX_SKILL_FILE_URL_CHARS} characters; ignoring it.`);
+        return undefined;
+    }
+    return value.trim();
+}
+/** Linear-time markdown table separator check. The previous single-regex form nested unbounded `\\s*` inside a
+ *  repeated group and could catastrophically backtrack on attacker-controlled PR bodies; this splits on `|` and
+ *  validates each cell independently instead. */
+const TABLE_SEPARATOR_CELL = /^\s*:?-{3,}:?\s*$/;
+function isMarkdownTableSeparatorRow(line) {
+    const trimmed = line.trim();
+    if (!trimmed || !/-{3,}/.test(trimmed))
+        return false;
+    const withoutEdgePipes = trimmed.replace(/^\|/, "").replace(/\|$/, "").trim();
+    const cells = withoutEdgePipes.split("|");
+    return cells.every((cell) => TABLE_SEPARATOR_CELL.test(cell));
+}
+/** True when `body` contains at least one markdown TABLE region (`| ... |` header + separator row) whose cells
+ *  embed image markup — either `![alt](url)` or an `<img ...>` tag — inside the table. A screenshot pasted as a
+ *  bare inline image OUTSIDE any table does not count (the contract requires captioned thumbnails INSIDE a
+ *  table, not a wall of raw images). Deliberately simple/regex-based (no markdown AST dependency) — false
+ *  negatives fail toward "no table found" (in-scope PRs still need a real table), false positives fail toward
+ *  "table found" (never blocks a PR that plausibly complied); both directions are acceptable for a
+ *  first-pass deterministic heuristic that a maintainer can always override by hand. */
+export function hasImageBearingMarkdownTable(body) {
+    if (!body)
+        return false;
+    const lines = body.split(/\r?\n/);
+    const tableRowPattern = /^\s*\|.*\|\s*$/;
+    const imagePattern = /!\[[^\]]*\]\([^)]+\)|<img\b[^>]*>/i;
+    for (let i = 0; i < lines.length - 1; i += 1) {
+        // `i < lines.length - 1` guarantees both indices are in bounds; the `?? ""` fallbacks only exist to
+        // satisfy noUncheckedIndexedAccess and are never actually reached.
+        /* v8 ignore next -- defensive: the loop bound above guarantees lines[i] always exists here. */
+        const header = lines[i] ?? "";
+        /* v8 ignore next -- defensive: the loop bound above guarantees lines[i + 1] always exists here. */
+        const separator = lines[i + 1] ?? "";
+        if (!tableRowPattern.test(header) || !isMarkdownTableSeparatorRow(separator))
+            continue;
+        // Found a table (header + separator). Scan its body rows (until a blank line or a non-table line) for
+        // image markup in any cell.
+        let j = i + 2;
+        /* v8 ignore next -- defensive: the `j < lines.length` guard above guarantees lines[j] always exists here. */
+        while (j < lines.length && tableRowPattern.test(lines[j] ?? "")) {
+            if (imagePattern.test(lines[j] ?? ""))
+                return true;
+            j += 1;
+        }
+    }
+    return false;
+}
+/** True when `body` has a large inline image OUTSIDE of any markdown table — a common way contributors dodge
+ *  the table requirement (paste screenshots directly into the body instead of inside a captioned table row). */
+export function hasImageOutsideTable(body) {
+    if (!body)
+        return false;
+    const lines = body.split(/\r?\n/);
+    const tableRowPattern = /^\s*\|.*\|\s*$/;
+    const imagePattern = /!\[[^\]]*\]\([^)]+\)|<img\b[^>]*>/i;
+    return lines.some((line) => imagePattern.test(line) && !tableRowPattern.test(line));
+}
+/** True when any changed file path is an image under a scoped path (a screenshot committed to the repo instead
+ *  of uploaded to the PR body via GitHub's CDN, per the contract). `scopedPaths` should be the SAME glob list
+ *  used for scope matching (`whenPaths`) so this only flags an image landing where visual work is expected —
+ *  not an unrelated asset (e.g. a favicon) added anywhere else in the repo. Empty `scopedPaths` (no path scoping
+ *  configured) checks every changed path. */
+export function hasCommittedImageFile(changedFiles, scopedPaths) {
+    return changedFiles.some((file) => {
+        const lower = file.toLowerCase();
+        if (!IMAGE_EXTENSIONS.some((ext) => lower.endsWith(ext)))
+            return false;
+        return scopedPaths.length === 0 || matchesAny(file, scopedPaths);
+    });
+}
+const IMAGE_CELL_PATTERN = /!\[[^\]]*\]\([^)]+\)|<img\b[^>]*>/i;
+/** One data row of a detected markdown table: the cell texts in source order (leading/trailing pipes and
+ *  whitespace stripped). Deliberately a SEPARATE table-detection pass from {@link hasImageBearingMarkdownTable}
+ *  rather than a shared refactor of it -- that function's exact behavior is pinned by existing tests, and this
+ *  one needs actual cell contents (not just "does some cell have an image"), so duplicating its short
+ *  header+separator detection loop keeps both independently simple instead of risking a regression in either
+ *  from a shared-code change. */
+export function extractTableRows(body) {
+    if (!body)
+        return [];
+    const lines = body.split(/\r?\n/);
+    const tableRowPattern = /^\s*\|.*\|\s*$/;
+    const rows = [];
+    for (let i = 0; i < lines.length - 1; i += 1) {
+        /* v8 ignore next -- defensive: the loop bound above guarantees lines[i] always exists here. */
+        const header = lines[i] ?? "";
+        /* v8 ignore next -- defensive: the loop bound above guarantees lines[i + 1] always exists here. */
+        const separator = lines[i + 1] ?? "";
+        if (!tableRowPattern.test(header) || !isMarkdownTableSeparatorRow(separator))
+            continue;
+        let j = i + 2;
+        /* v8 ignore next -- defensive: the `j < lines.length` guard above guarantees lines[j] always exists here. */
+        while (j < lines.length && tableRowPattern.test(lines[j] ?? "")) {
+            /* v8 ignore next -- defensive: same loop-bound guarantee as above. */
+            const line = lines[j] ?? "";
+            const cells = line
+                .trim()
+                .replace(/^\|/, "")
+                .replace(/\|$/, "")
+                .split("|")
+                .map((cell) => cell.trim());
+            rows.push(cells);
+            j += 1;
+        }
+        i = j - 1;
+    }
+    return rows;
+}
+// Matches EITHER markdown image syntax (`![alt](url)`, optionally with a trailing `"title"`) OR an `<img
+// src="...">` tag, capturing the URL from whichever alternative matched -- covers a bare `![]()` cell and the
+// PR template's own clickable-thumbnail convention (`[![before](url)](url)`, where the OUTER `[...](...)` is
+// the click-through link and this pattern correctly targets the INNER `!`-prefixed image markup instead).
+const CELL_IMAGE_URL_PATTERN = /!\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)|<img\b[^>]*\bsrc=["']([^"']+)["'][^>]*>/i;
+function extractCellImageUrl(cell) {
+    const match = cell.match(CELL_IMAGE_URL_PATTERN);
+    if (!match)
+        return null;
+    /* v8 ignore next -- defensive: whichever alternative of CELL_IMAGE_URL_PATTERN matched always captures a
+     * non-empty group (both require at least one non-`)`/non-`"` character), so this fallback is unreachable. */
+    return match[1] ?? match[2] ?? null;
+}
+/** The image URLs found in each detected table row (source order), for rows with at least two — a real
+ *  before/after pair worth comparing, not a single decorative image or caption-only row. Reuses
+ *  {@link extractTableRows}'s own header+separator detection rather than re-scanning the body. A row with
+ *  MORE than two images (e.g. a desktop+mobile matrix row) keeps every image; callers that only want a pair
+ *  slice it themselves. */
+export function extractTableRowImageUrls(body) {
+    return extractTableRows(body)
+        .map((row) => row.map(extractCellImageUrl).filter((url) => url !== null))
+        .filter((urls) => urls.length >= 2);
+}
+/** The full set of (viewport, theme) pairs `config` requires, or `[]` when matrix mode is off. Matrix mode
+ *  turns on via `requireViewports` alone -- `requireThemes` with an empty `requireViewports` has no effect,
+ *  since there is no viewport to cross it against. */
+export function requiredScreenshotMatrixPairs(config) {
+    if (config.requireViewports.length === 0)
+        return [];
+    if (config.requireThemes.length === 0)
+        return config.requireViewports.map((viewport) => ({ viewport, theme: null }));
+    const pairs = [];
+    for (const viewport of config.requireViewports) {
+        for (const theme of config.requireThemes)
+            pairs.push({ viewport, theme });
+    }
+    return pairs;
+}
+/** True when some row's first cell (the row LABEL, e.g. "Desktop · Light") mentions both `pair.viewport` and
+ *  `pair.theme` (case-insensitive substring match -- tolerant of whatever separator character the contributor
+ *  used between them) AND that row has at least two image-bearing cells among the rest (before + after). */
+function rowSatisfiesMatrixPair(row, pair) {
+    // `?? ""` only exists to satisfy noUncheckedIndexedAccess -- `extractTableRows`'s `.split("|")` always
+    // produces at least one cell, even for an empty-string row, so `row[0]` is never actually undefined here.
+    /* v8 ignore next -- defensive: see the comment above. */
+    const label = (row[0] ?? "").toLowerCase();
+    if (!label.includes(pair.viewport.toLowerCase()))
+        return false;
+    if (pair.theme !== null && !label.includes(pair.theme.toLowerCase()))
+        return false;
+    const imageCells = row.slice(1).filter((cell) => IMAGE_CELL_PATTERN.test(cell)).length;
+    return imageCells >= 2;
+}
+/** The subset of `pairs` with NO satisfying row anywhere in `body`'s tables. Empty ⇒ full coverage. */
+export function missingScreenshotMatrixPairs(body, pairs) {
+    if (pairs.length === 0)
+        return [];
+    const rows = extractTableRows(body);
+    return pairs.filter((pair) => !rows.some((row) => rowSatisfiesMatrixPair(row, pair)));
+}
+function formatMatrixPair(pair) {
+    return pair.theme === null ? pair.viewport : `${pair.viewport} · ${pair.theme}`;
+}
+/** Build the rejection reason for a matrix violation, naming exactly which viewport/theme combinations are
+ *  still missing a real before+after pair -- so the contributor knows precisely what to add, not just that
+ *  "something" is missing. */
+export function buildScreenshotMatrixMessage(missing) {
+    const list = missing.map(formatMatrixPair).join(", ");
+    const dimensionLabel = missing.some((pair) => pair.theme !== null) ? "viewport × theme" : "viewport";
+    return ("This pull request changes UI/visual code but its screenshot evidence is incomplete. Every required " +
+        `${dimensionLabel} combination needs its own before/after image pair in a labeled table row (e.g. ` +
+        '"Desktop · Light | before | after"). Still missing: ' +
+        `${list}.\n\nPlease resubmit with the remaining rows filled in.`);
+}
+/** Append a contributor skill-file link to an auto-generated rejection message (#4540 follow-up). A no-op
+ *  when `skillFileUrl` is unset -- callers only reach this on the AUTO-GENERATED path (a `message`
+ *  override already owns its entire text and is never passed through here). */
+function appendSkillLink(text, skillFileUrl) {
+    return skillFileUrl ? `${text}\n\nSee ${skillFileUrl} for the exact format and examples.` : text;
+}
+/** True when the PR is IN SCOPE for the gate: it carries one of `config.whenLabels` OR touches a path matching
+ *  one of `config.whenPaths`. Both empty ⇒ every PR is in scope (an operator who enables the gate with no
+ *  scoping at all wants it enforced everywhere). Only one non-empty list configured ⇒ that list alone decides
+ *  scope (the other, empty list can never exclude a PR the configured one matched). */
+export function isScreenshotTableGateInScope(config, prLabels, changedFiles) {
+    if (config.whenLabels.length === 0 && config.whenPaths.length === 0)
+        return true;
+    const wantedLabels = new Set(config.whenLabels.map((label) => label.toLowerCase()));
+    const labelMatch = config.whenLabels.length > 0 && prLabels.some((label) => wantedLabels.has(label.toLowerCase()));
+    const pathMatch = config.whenPaths.length > 0 && changedFiles.some((file) => matchesAny(file, config.whenPaths));
+    return labelMatch || pathMatch;
+}
+export const DEFAULT_SCREENSHOT_CONTRACT_MESSAGE = "This pull request changes UI/visual code but its description is missing a before/after screenshot table. " +
+    "Every changed page/feature needs a **markdown table** with a before column and an after column, each cell a " +
+    "clickable thumbnail (uploaded to the PR, not committed to the repo) with a caption below — for example:\n\n" +
+    "| Before | After |\n| --- | --- |\n| [![before](url)](url) — caption | [![after](url)](url) — caption |\n\n" +
+    "Please resubmit with the table filled in.";
+const NO_VIOLATION = { violated: false, reason: null };
+/** PURE evaluator. Off (`enabled: false`) or out-of-scope (no configured label/path match) ⇒ no violation.
+ *  `botCaptureSatisfied` ⇒ no violation regardless of mode (an automated capture is equivalent to a
+ *  hand-authored table, and the bot doesn't (yet) shoot a full viewport/theme matrix -- see #4535's scope note).
+ *
+ *  Two modes, chosen by whether `config.requireViewports` is non-empty (#4535):
+ *  - MATRIX mode: every required (viewport, theme) pair (`requiredScreenshotMatrixPairs`) must have a labeled
+ *    before/after row. Violated ⇒ the reason names exactly which pairs are still missing.
+ *  - PRESENCE mode (the original #2006 behavior, unchanged): in scope AND (no image-bearing table in the body
+ *    OR an image pasted outside a table OR a committed image file under a scoped path) ⇒ violated, with the
+ *    configured (or default) templated message as the reason. */
+export function evaluateScreenshotTableGate(input) {
+    const { config } = input;
+    if (!config.enabled)
+        return NO_VIOLATION;
+    if (!isScreenshotTableGateInScope(config, input.prLabels, input.changedFiles))
+        return NO_VIOLATION;
+    if (input.botCaptureSatisfied === true)
+        return NO_VIOLATION;
+    const matrixPairs = requiredScreenshotMatrixPairs(config);
+    if (matrixPairs.length > 0) {
+        const missing = missingScreenshotMatrixPairs(input.prBody, matrixPairs);
+        if (missing.length === 0)
+            return NO_VIOLATION;
+        return { violated: true, reason: config.message ?? appendSkillLink(buildScreenshotMatrixMessage(missing), config.skillFileUrl) };
+    }
+    const hasTable = hasImageBearingMarkdownTable(input.prBody);
+    const outsideTable = hasImageOutsideTable(input.prBody);
+    const committedImage = hasCommittedImageFile(input.changedFiles, config.whenPaths);
+    if (hasTable && !outsideTable && !committedImage)
+        return NO_VIOLATION;
+    return { violated: true, reason: config.message ?? appendSkillLink(DEFAULT_SCREENSHOT_CONTRACT_MESSAGE, config.skillFileUrl) };
+}

package/dist/review/unlinked-issue-guardrail-config.d.ts

@@ -0,0 +1,9 @@
+import type { UnlinkedIssueGuardrailConfig, UnlinkedIssueGuardrailMode } from "../types/manifest-deps-types.js";
+export declare const DEFAULT_UNLINKED_ISSUE_GUARDRAIL: UnlinkedIssueGuardrailConfig;
+export declare function isUnlinkedIssueGuardrailMode(value: unknown): value is UnlinkedIssueGuardrailMode;
+/**
+ * Normalize a raw `.gittensory.yml settings.unlinkedIssueGuardrail` value into a typed config,
+ * fail-safe: any malformed field falls back to its own default and pushes a warning rather than
+ * rejecting the whole block. Mirrors `normalizeLinkedIssueHardRulesConfig`'s per-field discipline.
+ */
+export declare function normalizeUnlinkedIssueGuardrailConfig(input: unknown, warnings: string[]): UnlinkedIssueGuardrailConfig;

package/dist/review/unlinked-issue-guardrail-config.js

@@ -0,0 +1,44 @@
+const VALID_UNLINKED_ISSUE_GUARDRAIL_MODES = ["hold", "off"];
+const DEFAULT_MIN_CONFIDENCE = 0.85;
+export const DEFAULT_UNLINKED_ISSUE_GUARDRAIL = {
+    mode: "off",
+    minConfidence: DEFAULT_MIN_CONFIDENCE,
+};
+export function isUnlinkedIssueGuardrailMode(value) {
+    return typeof value === "string" && VALID_UNLINKED_ISSUE_GUARDRAIL_MODES.includes(value);
+}
+function normalizeMode(value, warnings) {
+    if (value === undefined)
+        return DEFAULT_UNLINKED_ISSUE_GUARDRAIL.mode;
+    if (isUnlinkedIssueGuardrailMode(value))
+        return value;
+    warnings.push(`settings.unlinkedIssueGuardrail.mode must be one of hold, off; using the default "${DEFAULT_UNLINKED_ISSUE_GUARDRAIL.mode}".`);
+    return DEFAULT_UNLINKED_ISSUE_GUARDRAIL.mode;
+}
+function normalizeMinConfidence(value, warnings) {
+    if (value === undefined)
+        return DEFAULT_UNLINKED_ISSUE_GUARDRAIL.minConfidence;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+        warnings.push(`settings.unlinkedIssueGuardrail.minConfidence must be a number between 0 and 1; using the default "${DEFAULT_MIN_CONFIDENCE}".`);
+        return DEFAULT_MIN_CONFIDENCE;
+    }
+    return value;
+}
+/**
+ * Normalize a raw `.gittensory.yml settings.unlinkedIssueGuardrail` value into a typed config,
+ * fail-safe: any malformed field falls back to its own default and pushes a warning rather than
+ * rejecting the whole block. Mirrors `normalizeLinkedIssueHardRulesConfig`'s per-field discipline.
+ */
+export function normalizeUnlinkedIssueGuardrailConfig(input, warnings) {
+    if (input === undefined)
+        return { ...DEFAULT_UNLINKED_ISSUE_GUARDRAIL };
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        warnings.push("settings.unlinkedIssueGuardrail must be an object; using the default off policy.");
+        return { ...DEFAULT_UNLINKED_ISSUE_GUARDRAIL };
+    }
+    const record = input;
+    return {
+        mode: normalizeMode(record.mode, warnings),
+        minConfidence: normalizeMinConfidence(record.minConfidence, warnings),
+    };
+}