@loopover/engine 1.0.0

package/dist/focus-manifest.js

@@ -0,0 +1,2730 @@
+/**
+ * Focus-manifest parse/compile core (#2280). Extracted to `@loopover/engine` so the maintainer
+ * review stack and the miner's goal-spec parser share identical, versioned manifest logic instead of drifting
+ * apart. This is the MINER-side parse-pattern template for {@link MinerGoalSpec} (`.gittensory-miner.yml`) —
+ * same tolerant-parser shape: typed config + safe defaults + warnings, never throws.
+ *
+ * App-local resolver/guidance functions (`resolveEffectiveSettings`, `buildFocusManifestGuidance`, etc.) remain
+ * in `src/signals/focus-manifest.ts` as a shim over this module.
+ */
+import { parse as parseYaml } from "yaml";
+import { normalizeAutonomyPolicy, normalizeAutoMaintainPolicy } from "./settings/autonomy.js";
+import { normalizeCommandAuthorizationPolicy } from "./settings/command-authorization.js";
+import { normalizeContributorBlacklist } from "./settings/contributor-blacklist.js";
+import { normalizeAutoCloseExemptLogins } from "./settings/auto-close-exempt.js";
+import { MAX_TYPE_LABEL_NAME_LENGTH, normalizeTypeLabelSet } from "./settings/pr-type-label.js";
+import { normalizeLinkedIssueLabelPropagationConfig, VALID_LINKED_ISSUE_LABEL_PROPAGATION_MODES, } from "./review/linked-issue-label-propagation.js";
+import { isLinkedIssueHardRuleMode, normalizeLinkedIssueHardRulesConfig, } from "./review/linked-issue-hard-rules-config.js";
+import { isUnlinkedIssueGuardrailMode, normalizeUnlinkedIssueGuardrailConfig, } from "./review/unlinked-issue-guardrail-config.js";
+import { normalizeAdvisoryAiRoutingConfig } from "./review/advisory-ai-routing-config.js";
+import { isScreenshotTableGateAction, normalizeScreenshotTableGateConfig, } from "./review/screenshot-table-gate.js";
+import { normalizeModerationLabel, normalizeModerationRules } from "./settings/moderation-rules.js";
+import { REES_ANALYZER_NAME_SET } from "./review/enrichment-analyzer-names.js";
+import { hasUnsafeWildcardCount } from "./signals/change-guardrail.js";
+import { isSafeHttpUrl } from "./review/safe-url.js";
+/** Canonical local-filesystem-root vocabulary for public-safety filtering (from `src/signals/redaction.ts`). */
+const PUBLIC_LOCAL_PATH_INLINE = String.raw `/Users/|/home/|/root/|/var/|/opt/|/tmp/|/private/|[A-Za-z]:[\\/]Users[\\/]|[A-Za-z]:[\\/]Program Files[\\/]`;
+// The converged per-PR review features a self-host operator toggles PER-REPO under `features:` in the private
+// `.gittensory.yml`. Each feature ALSO has a GLOBAL env flag (GITTENSORY_REVIEW_*) that stays a master
+// kill-switch (the feature never runs when its env flag is off, regardless of this block). See
+// review/feature-activation.ts for the resolver (env kill-switch → per-repo override → env-allowlist default).
+// NOTE: only the per-PR REVIEW features whose every activation site is migrated are listed here. grounding
+// (#4100) is now migrated too — its original "coupled to the merge/close DISPOSITION path" blocker was the
+// removed AI CI-refutation path (grounding-wire.ts's aiCiRefutationActive is now a vestigial historical-
+// compatibility helper with zero real callers); grounding today only shapes reviewer PROMPT content, same
+// shape as rag/reputation. contentLane got its own richer `contentLane:` block below (#2435) instead of a
+// boolean here, since it resolves to a whole RegistryLaneSpec, not an on/off toggle — see
+// resolveRegistryLaneSpec in review/content-lane/spec-resolver.ts (its own precedence already matches this
+// block's env-kill-switch → override → allowlist-default shape one-for-one; it just isn't literally routed
+// through resolveConvergedFeature yet — a disclosed, low-priority fast-follow, #4616). `selftune` (#4104)
+// ALSO deliberately lives outside this block, as its own top-level `review.selftune` field below — it has no
+// `GITTENSORY_REVIEW_REPOS` allowlist to fall back to (its own repo scoping is `isAgentConfigured`, a
+// different consent boundary), so it doesn't fit this resolver's env-kill-switch → override → allowlist-
+// default shape; see `selfTuneRepos` in `review/selftune-wire.ts`. `e2eTests` (#4190, part of the #4189
+// E2E-test-generation epic) fits this shape exactly as a plain symmetric override — unlike `safety`/
+// `grounding` it has no force-on-only or force-off-only floor/ceiling, since AI-generated test content
+// carries no security-hardening or full-file-fetch rationale to protect from a repo-controlled override.
+// `screenshots` (#4616) joined this block for the SAME reason `e2eTests` fits it plainly: capturing a
+// before/after render of the PR's own web-visible files carries no security-hardening or full-file-fetch
+// rationale either, so it gets the standard override, not an asymmetric one. Before #4616 it had NO
+// `features:` override at all (env flag AND allowlist only) despite being documented right next to its six
+// siblings in `.gittensory.yml.example` — a self-hoster who guessed `features.screenshots: true` (a natural
+// guess given the sibling keys) found it silently did nothing. `features.screenshots` is layered UNDER the
+// separate, richer `review.visual.*` block (route/preview-URL config, #3609/#3610, and `review.visual.enabled:
+// false` as an always-available additional force-off, #4083) — that block still narrows/disables capture
+// AFTER this key decides whether capture is even attempted for the repo at all; the two are independent and
+// `review.visual.enabled` keeps its own existing force-off-only semantics untouched by this change.
+// `improvementSignal` (#4738, foundation phase of the #4737 PR-improvement-signal epic) is likewise a plain
+// symmetric override: it is a READ-ONLY advisory quality-delta signal, not a security control, so a repo-
+// level `false` behaves like any other plain override with no floor/ceiling. This is activation wiring only
+// -- no tier reads the resolved value yet (sibling sub-issues #4739-#4746 build the deterministic/LLM/panel
+// behavior that will gate on it).
+export const CONVERGED_FEATURE_KEYS = ["rag", "reputation", "unifiedComment", "safety", "grounding", "e2eTests", "screenshots", "improvementSignal"];
+/** Optional ecosystem/network integrations under the `experimental:` block — plugins that couple gittensory to
+ *  an external system rather than core review behavior. Starts with `gittensor` (the subnet mining-registry/
+ *  scoring integration gittensory originally shipped with); future plugins land in this same array as the
+ *  product broadens beyond gittensor. Deliberately a SEPARATE block from `features:` (converged review
+ *  capabilities) — an operator (especially self-host) should be able to see at a glance which toggles are "how
+ *  gittensory reviews PRs" vs "which external network/ecosystem this instance opts into." */
+export const EXPERIMENTAL_PLUGIN_KEYS = ["gittensor"];
+/** Field keys for the public review-panel rows a maintainer can show/hide via `review.fields`. `improvementSignal`
+ *  (#4744) is the newest: the optional row combining the deterministic structural-improvement tier (#4742) and,
+ *  where also active, the LLM tier's composed value judgment (#4743) -- default-shown, like every sibling here,
+ *  when the `improvementSignal` converged feature itself is active for the repo. */
+export const REVIEW_FIELD_KEYS = ["linkedIssue", "relatedWork", "reviewLoad", "validationEvidence", "openPrQueue", "contributorContext", "gateResult", "improvementSignal"];
+// `review.profile` (#review-profile): how nitpicky the AI maintainer review is. `chill` = surface only blocking
+// defects (bugs/security/breakage), suppress style nits; `assertive` = also raise minor improvements & nits;
+// `balanced` (default / absent) leaves the reviewer prompt byte-identical. A presentation knob only — it NEVER
+// changes the gate verdict, only how much advisory detail the review write-up carries.
+export const REVIEW_PROFILES = ["chill", "balanced", "assertive"];
+export const REVIEW_FINDING_SEVERITY_LADDER = ["critical", "major", "minor", "nitpick"];
+/** `review.linkedIssueSatisfaction` modes (#2173). `off` = not evaluated (same as unset). */
+export const LINKED_ISSUE_SATISFACTION_MODES = ["off", "advisory", "block"];
+/** `review.comment_verbosity` levels (#2047). `normal` = today's behavior (same as unset). */
+export const COMMENT_VERBOSITY_LEVELS = ["quiet", "normal", "detailed"];
+/** `review.e2e_test_delivery` modes (#4197). `comment` = today's behavior (same as unset). */
+export const E2E_TEST_DELIVERY_MODES = ["comment", "commit"];
+/** `review.auto_review.cadence` (#one-shot-review-cadence). `one_shot` = the AI-generated content (main review,
+ *  slop advisory, linked-issue satisfaction) is produced once per PR and never automatically regenerated
+ *  afterward — not on a new push, not on CI-check completion, not on a scheduled sweep tick; only an explicit
+ *  maintainer retrigger (the PR-panel checkbox or `@gittensory review` as a maintainer) spends a fresh call.
+ *  `continuous` = the traditional behavior — every trigger re-runs AI content generation, subject to each
+ *  feature's own head-SHA cache. Orthogonal to `aiReviewMode`'s enforcement-strictness axis (off/advisory/
+ *  block) — the deterministic gate (CI status, mergeability, static-rule blockers) is NEVER affected by this
+ *  and always re-evaluates on every pass regardless of cadence. */
+export const AI_REVIEW_CADENCES = ["one_shot", "continuous"];
+export const EMPTY_MAX_FINDINGS_CONFIG = { blockers: null, nits: null };
+export const EMPTY_AUTO_REVIEW_CONFIG = {
+    skipDrafts: null,
+    cadence: null,
+    ignoreAuthors: [],
+    ignoreTitleKeywords: [],
+    skipLabels: [],
+    skipDocsOnly: null,
+    maxAddedLines: 0,
+    maxFiles: 0,
+    baseBranches: [],
+    autoPauseAfterReviewedCommits: null,
+};
+export const EMPTY_SELF_HOST_AI_MODEL_CONFIG = {
+    claudeModel: null,
+    claudeEffort: null,
+    codexModel: null,
+    codexEffort: null,
+    ollamaModel: null,
+    openaiModel: null,
+    openaiCompatibleModel: null,
+    anthropicModel: null,
+};
+export const EMPTY_VISUAL_CONFIG = {
+    productionUrl: null,
+    preview: { urlTemplate: null },
+    routes: { paths: [], maxRoutes: null },
+    themes: [],
+    gif: false,
+    enabled: null,
+    themeStorageKey: null,
+    actionsFallback: false,
+};
+// A hard cap so a hostile/huge manifest can't bloat the reviewer prompt (mirrors REVIEW_FIELD_KEYS discipline).
+const MAX_PATH_INSTRUCTIONS = 50;
+const MAX_LIST_ITEMS = 200;
+const MAX_ITEM_LENGTH = 300;
+const MAX_GLOBSTAR_SLASH_ALTERNATIVES = 128;
+// 128 KiB, not 64 KiB: gittensory.full.yml (our own reference doc, parsed by config-templates.test.ts as a
+// round-trip check) organically grows every time a new review.* knob ships and had already reached 65522/65536
+// bytes on main before this comment was written -- one doc line from any PR would trip the old ceiling. A real
+// per-repo .gittensory.yml never needs anywhere near this size, so the DoS-guard intent is unaffected (#2006).
+export const MAX_FOCUS_MANIFEST_BYTES = 128 * 1024;
+const EMPTY_GATE_CONFIG = {
+    present: false,
+    enabled: null,
+    checkMode: null,
+    pack: null,
+    linkedIssue: null,
+    duplicates: null,
+    readinessMode: null,
+    readinessMinScore: null,
+    slopMode: null,
+    slopMinScore: null,
+    slopAiAdvisory: null,
+    sizeMode: null,
+    lockfileIntegrityMode: null,
+    aiReviewMode: null,
+    aiReviewByok: null,
+    aiReviewProvider: null,
+    aiReviewModel: null,
+    aiReviewAllAuthors: null,
+    aiReviewCloseConfidence: null,
+    aiReviewLowConfidenceDisposition: null,
+    aiReviewCombine: null,
+    aiReviewOnMerge: null,
+    aiReviewReviewers: null,
+    mergeReadiness: null,
+    manifestPolicy: null,
+    selfAuthoredLinkedIssue: null,
+    linkedIssueSatisfaction: null,
+    dryRun: null,
+    firstTimeContributorGrace: null,
+    premergeContentRecheck: null,
+    requireFreshRebaseWindowMinutes: null,
+    claMode: null,
+    claConsentPhrase: null,
+    claCheckRunName: null,
+    claCheckRunAppSlug: null,
+    expectedCiContexts: null,
+    aiJudgmentBlockersMode: null,
+    copycatMode: null,
+    copycatMinScore: null,
+};
+const EMPTY_FEATURES_CONFIG = {
+    present: false,
+    rag: null,
+    reputation: null,
+    unifiedComment: null,
+    safety: null,
+    grounding: null,
+    e2eTests: null,
+    screenshots: null,
+    improvementSignal: null,
+};
+const EMPTY_EXPERIMENTAL_CONFIG = {
+    present: false,
+    gittensor: null,
+};
+const EMPTY_CONTENT_LANE_CONFIG = {
+    present: false,
+    entryFileGlob: null,
+    providerFileGlob: null,
+    artifactGlob: null,
+    collectionField: null,
+    maxAppendedEntries: null,
+    duplicateKeyFields: [],
+    validatorId: null,
+};
+const DEFAULT_REPO_DOC_REFRESH_INTERVAL_DAYS = 7;
+const EMPTY_REPO_DOC_GENERATION_CONFIG = {
+    present: false,
+    enabled: false,
+    scope: ["agents"],
+    allowOverwriteExisting: false,
+    refreshIntervalDays: DEFAULT_REPO_DOC_REFRESH_INTERVAL_DAYS,
+};
+const DEFAULT_REVIEW_RECAP_CADENCE_DAYS = 7;
+const EMPTY_REVIEW_RECAP_CONFIG = {
+    present: false,
+    enabled: false,
+    cadenceDays: DEFAULT_REVIEW_RECAP_CADENCE_DAYS,
+};
+const DEFAULT_MAINTAINER_RECAP_CADENCE = "weekly";
+const DEFAULT_MAINTAINER_RECAP_CHANNEL = "discord";
+const EMPTY_MAINTAINER_RECAP_CONFIG = {
+    present: false,
+    enabled: false,
+    cadence: DEFAULT_MAINTAINER_RECAP_CADENCE,
+    channel: DEFAULT_MAINTAINER_RECAP_CHANNEL,
+};
+const EMPTY_MANIFEST = {
+    present: false,
+    source: "none",
+    wantedPaths: [],
+    preferredLabels: [],
+    linkedIssuePolicy: "optional",
+    testExpectations: [],
+    issueDiscoveryPolicy: "neutral",
+    maintainerNotes: [],
+    publicNotes: [],
+    gate: { ...EMPTY_GATE_CONFIG },
+    settings: {},
+    review: { present: false, footerText: null, note: null, fields: {}, enrichmentAnalyzers: {}, profile: null, tone: null, securityFocus: null, inlineComments: null, fixHandoff: null, autoMergeSummary: null, suggestions: null, changedFilesSummary: null, effortScore: null, impactMap: null, cultureProfile: null, selftune: null, reviewMemory: null, findingCategories: null, inlineCommentsPerCategory: null, minFindingSeverity: null, maxFindings: { ...EMPTY_MAX_FINDINGS_CONFIG }, commentVerbosity: null, e2eTestDelivery: null, e2eTestAutoTrigger: null, pathInstructions: [], instructions: null, excludePaths: [], pathFilters: [], preMergeChecks: [], autoReview: { ...EMPTY_AUTO_REVIEW_CONFIG }, aiModel: { ...EMPTY_SELF_HOST_AI_MODEL_CONFIG }, visual: { ...EMPTY_VISUAL_CONFIG }, linkedIssueSatisfaction: null, sharedConfigSource: null },
+    features: { ...EMPTY_FEATURES_CONFIG },
+    experimental: { ...EMPTY_EXPERIMENTAL_CONFIG },
+    contentLane: { ...EMPTY_CONTENT_LANE_CONFIG },
+    repoDocGeneration: { ...EMPTY_REPO_DOC_GENERATION_CONFIG },
+    reviewRecap: { ...EMPTY_REVIEW_RECAP_CONFIG },
+    maintainerRecap: { ...EMPTY_MAINTAINER_RECAP_CONFIG },
+    warnings: [],
+};
+// This surface's economic/identity term vocabulary is intentionally richer than the canonical
+// PUBLIC_UNSAFE_TERMS (extra phrases like "public score estimate"), so it stays a local literal. The local
+// filesystem paths, however, compose from the canonical PUBLIC_LOCAL_PATH_INLINE in redaction.ts (which also
+// covers `/var/`, previously missed here, plus `/root/` and the forward-slash Windows form `C:/Users/`) so this
+// guard cannot drift from the canonical boundary on a leaking root.
+const FOCUS_MANIFEST_TERMS = /\b(reward\w*|score\w*|wallets?|hotkeys?|coldkeys?|seed[-\s]?phrases?|mnemonics?|private[-\s]?keys?|farming|payouts?|rankings?|raw[-\s]?trust(?:[-\s]?scores?)?|trust[-\s]?scores?|private[-\s]?reviewability|reviewability(?:[-\s]?internals?)?|private[-\s]?scoreability|scoreability|public[-\s]?score[-\s]?(?:estimate|prediction|claim)s?|estimated[-\s]?scores?|score[-\s]?(?:estimate|prediction|preview)s?)\b/i;
+const FOCUS_MANIFEST_LOCAL_PATH_PATTERN = new RegExp(PUBLIC_LOCAL_PATH_INLINE, "i");
+/**
+ * Public-safe redaction guard shared with the local-branch packet renderer. Public manifest
+ * text must not leak reward, wallet/key, ranking, or local filesystem path material.
+ */
+export function isFocusManifestPublicSafe(text) {
+    return !FOCUS_MANIFEST_TERMS.test(text) && !FOCUS_MANIFEST_LOCAL_PATH_PATTERN.test(text);
+}
+function emptyManifest(source, warnings = []) {
+    return {
+        ...EMPTY_MANIFEST,
+        source,
+        warnings,
+        gate: { ...EMPTY_GATE_CONFIG },
+        settings: {},
+        review: { present: false, footerText: null, note: null, fields: {}, enrichmentAnalyzers: {}, profile: null, tone: null, securityFocus: null, inlineComments: null, fixHandoff: null, autoMergeSummary: null, suggestions: null, changedFilesSummary: null, effortScore: null, impactMap: null, cultureProfile: null, selftune: null, reviewMemory: null, findingCategories: null, inlineCommentsPerCategory: null, minFindingSeverity: null, maxFindings: { ...EMPTY_MAX_FINDINGS_CONFIG }, commentVerbosity: null, e2eTestDelivery: null, e2eTestAutoTrigger: null, pathInstructions: [], instructions: null, excludePaths: [], pathFilters: [], preMergeChecks: [], autoReview: { ...EMPTY_AUTO_REVIEW_CONFIG }, aiModel: { ...EMPTY_SELF_HOST_AI_MODEL_CONFIG }, visual: { ...EMPTY_VISUAL_CONFIG }, linkedIssueSatisfaction: null, sharedConfigSource: null },
+        features: { ...EMPTY_FEATURES_CONFIG },
+        experimental: { ...EMPTY_EXPERIMENTAL_CONFIG },
+        contentLane: { ...EMPTY_CONTENT_LANE_CONFIG },
+        repoDocGeneration: { ...EMPTY_REPO_DOC_GENERATION_CONFIG },
+        reviewRecap: { ...EMPTY_REVIEW_RECAP_CONFIG },
+        maintainerRecap: { ...EMPTY_MAINTAINER_RECAP_CONFIG },
+    };
+}
+function normalizeStringList(value, field, warnings) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        warnings.push(`Manifest field "${field}" must be a list; ignoring a ${typeof value} value.`);
+        return [];
+    }
+    const result = [];
+    for (const entry of value) {
+        if (typeof entry !== "string") {
+            warnings.push(`Manifest field "${field}" skipped a non-string entry.`);
+            continue;
+        }
+        const trimmed = entry.trim();
+        if (!trimmed)
+            continue;
+        // Truncate in place, then flow through the same de-dup and cap logic. Falling through (rather than
+        // `continue`-ing) keeps over-long entries subject to both limits, so untrusted manifests cannot
+        // bypass de-duplication or the MAX_LIST_ITEMS safety cap via pathological long entries.
+        let normalized = trimmed;
+        if (normalized.length > MAX_ITEM_LENGTH) {
+            warnings.push(`Manifest field "${field}" truncated an over-long entry.`);
+            normalized = normalized.slice(0, MAX_ITEM_LENGTH);
+        }
+        if (!result.includes(normalized))
+            result.push(normalized);
+        if (result.length >= MAX_LIST_ITEMS) {
+            warnings.push(`Manifest field "${field}" exceeded ${MAX_LIST_ITEMS} entries; extra entries ignored.`);
+            break;
+        }
+    }
+    return result;
+}
+/** Like {@link normalizeStringList}, but returns `null` (not `[]`) when unset or when nothing survives
+ *  validation — the convention every OTHER `FocusManifestGateConfig` field uses for "not configured", so
+ *  the resolver's `!== null` overlay checks work uniformly. */
+function normalizeOptionalStringList(value, field, warnings) {
+    if (value === undefined || value === null)
+        return null;
+    const list = normalizeStringList(value, field, warnings);
+    return list.length > 0 ? list : null;
+}
+function normalizeEnum(value, field, allowed, fallback, warnings) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "string" || !allowed.includes(value)) {
+        warnings.push(`Manifest field "${field}" must be one of ${allowed.join(", ")}; falling back to "${fallback}".`);
+        return fallback;
+    }
+    return value;
+}
+function normalizeSource(raw, value, warnings) {
+    if (raw)
+        return raw;
+    return normalizeEnum(value, "source", ["repo_file", "api_record", "none"], "api_record", warnings);
+}
+function normalizeOptionalGateMode(value, field, warnings) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (normalized === "off" || normalized === "advisory" || normalized === "block")
+            return normalized;
+    }
+    warnings.push(`Manifest gate field "${field}" must be one of off, advisory, block; ignoring "${String(value)}".`);
+    return null;
+}
+/** `gate.readiness.mode` (and its `settings.qualityGateMode` alias below) is documented and parsed as the shared
+ *  off/advisory/block tri-state, but buildQualityGateWarning (src/rules/advisory.ts) always produces a
+ *  warning-severity finding — never a blocker — and isConfiguredGateBlocker has no branch for it: readiness/
+ *  quality is intentionally informational-only and can never hard-block a PR. Without this, a maintainer who
+ *  sets `mode: block` believes a real quality floor is enforced when the effective behavior is silently
+ *  advisory-only (#2267). Downgrade "block" to "advisory" here, with a clear deprecation warning, so the parsed
+ *  config always matches what the gate actually does. Exported so the settings-write API routes (the
+ *  dashboard/API path for the SAME `qualityGateMode` field) can apply the identical downgrade before persisting. */
+export function normalizeReadinessGateMode(value, field, warnings) {
+    const mode = normalizeOptionalGateMode(value, field, warnings);
+    if (mode !== "block")
+        return mode;
+    warnings.push(`Manifest gate field "${field}" no longer accepts "block" — readiness/quality is informational-only and can never hard-block a PR; downgrading to "advisory". Use gate.manifestPolicy or another enforceable gate for a real quality floor.`);
+    return "advisory";
+}
+function normalizeOptionalBoolean(value, field, warnings) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value === "boolean")
+        return value;
+    warnings.push(`Manifest gate field "${field}" must be a boolean; ignoring a ${typeof value} value.`);
+    return null;
+}
+function normalizeOptionalScore(value, field, warnings) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        warnings.push(`Manifest gate field "${field}" must be a number between 0 and 100; ignoring it.`);
+        return null;
+    }
+    return Math.max(0, Math.min(100, Math.round(value)));
+}
+function normalizeOptionalNonNegativeInt(value, field, warnings) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+        warnings.push(`Manifest field "${field}" must be a non-negative integer; ignoring it.`);
+        return null;
+    }
+    return value;
+}
+/** Parse auto-review size caps where 0 means disabled (byte-identical default). (#2065) */
+function normalizeAutoReviewSizeCap(value, field, warnings) {
+    if (value === undefined || value === null)
+        return 0;
+    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+        warnings.push(`Manifest field "${field}" must be a non-negative integer; ignoring it.`);
+        return 0;
+    }
+    return value;
+}
+/** Normalize an optional confidence threshold in [0,1] (#7) — a fractional value (NOT a 0-100 score), so it is
+ *  clamped into range WITHOUT rounding. Absent/null ⇒ null (the resolver leaves the gate's 0.93 default in place);
+ *  a non-finite/non-number value is ignored with a warning. */
+function normalizeOptionalConfidence(value, field, warnings) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        warnings.push(`Manifest gate field "${field}" must be a number between 0 and 1; ignoring it.`);
+        return null;
+    }
+    return Math.max(0, Math.min(1, value));
+}
+// A hard cap on `gate.aiReview.reviewers` entries — the combiner only ever addresses reviewer[0]/[1] (single runs
+// one, consensus/synthesis run two), so anything beyond 2 is inert; capping at 4 leaves headroom without letting a
+// hostile/huge manifest bloat the parsed config for no functional gain.
+const MAX_AI_REVIEW_REVIEWERS = 4;
+/** Normalize `gate.aiReview.reviewers` (#2567) — a list of `{ model, fallback? }` entries naming self-host
+ *  providers (e.g. `claude-code`, `codex`) to run in place of the operator's `AI_REVIEW_PLAN.reviewers`. Each
+ *  entry needs a non-empty string `model`; `fallback` is optional and, when present, must also be a non-empty
+ *  string. Invalid entries are dropped with a warning rather than failing the whole list, mirroring the other
+ *  manifest list parsers. Absent/empty/all-invalid ⇒ null (so the resolver's `??` fallback to the operator's
+ *  plan is untouched). */
+function normalizeOptionalReviewers(value, field, warnings) {
+    if (value === undefined || value === null)
+        return null;
+    if (!Array.isArray(value)) {
+        warnings.push(`Manifest gate field "${field}" must be a list of { model, fallback? }; ignoring it.`);
+        return null;
+    }
+    const out = [];
+    for (const [index, entry] of value.entries()) {
+        if (out.length >= MAX_AI_REVIEW_REVIEWERS) {
+            warnings.push(`Manifest gate field "${field}" is capped at ${MAX_AI_REVIEW_REVIEWERS} entries; dropping the rest.`);
+            break;
+        }
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+            warnings.push(`Manifest gate field "${field}[${index}]" must be a mapping with a "model" string; ignoring it.`);
+            continue;
+        }
+        const e = entry;
+        const model = typeof e.model === "string" ? e.model.trim() : "";
+        if (!model) {
+            warnings.push(`Manifest gate field "${field}[${index}].model" must be a non-empty string; ignoring the entry.`);
+            continue;
+        }
+        const fallback = typeof e.fallback === "string" && e.fallback.trim() ? e.fallback.trim() : undefined;
+        out.push(fallback ? { model, fallback } : { model });
+    }
+    return out.length > 0 ? out : null;
+}
+/**
+ * Parse the optional `gate:` mapping. Every field stays `null` when unset so the resolver can layer
+ * this OVER DB settings without clobbering. A nested `readiness: { mode, minScore }` block is accepted.
+ */
+function parseGateConfig(value, warnings) {
+    if (value === undefined || value === null)
+        return { ...EMPTY_GATE_CONFIG };
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push(`Manifest field "gate" must be a mapping; ignoring it.`);
+        return { ...EMPTY_GATE_CONFIG };
+    }
+    const record = value;
+    const readiness = record.readiness;
+    const readinessRecord = readiness !== null && typeof readiness === "object" && !Array.isArray(readiness) ? readiness : undefined;
+    if (readiness !== undefined && readiness !== null && readinessRecord === undefined) {
+        warnings.push(`Manifest gate field "gate.readiness" must be a mapping; ignoring it.`);
+    }
+    const aiReview = record.aiReview;
+    const aiReviewRecord = aiReview !== null && typeof aiReview === "object" && !Array.isArray(aiReview) ? aiReview : undefined;
+    if (aiReview !== undefined && aiReview !== null && aiReviewRecord === undefined) {
+        warnings.push(`Manifest gate field "gate.aiReview" must be a mapping; ignoring it.`);
+    }
+    const slop = record.slop;
+    const slopRecord = slop !== null && typeof slop === "object" && !Array.isArray(slop) ? slop : undefined;
+    if (slop !== undefined && slop !== null && slopRecord === undefined) {
+        warnings.push(`Manifest gate field "gate.slop" must be a mapping; ignoring it.`);
+    }
+    const copycat = record.copycat;
+    const copycatRecord = copycat !== null && typeof copycat === "object" && !Array.isArray(copycat) ? copycat : undefined;
+    if (copycat !== undefined && copycat !== null && copycatRecord === undefined) {
+        warnings.push(`Manifest gate field "gate.copycat" must be a mapping; ignoring it.`);
+    }
+    const size = record.size;
+    const sizeRecord = size !== null && typeof size === "object" && !Array.isArray(size) ? size : undefined;
+    if (size !== undefined && size !== null && sizeRecord === undefined) {
+        warnings.push(`Manifest gate field "gate.size" must be a mapping; ignoring it.`);
+    }
+    const cla = record.cla;
+    const claRecord = cla !== null && typeof cla === "object" && !Array.isArray(cla) ? cla : undefined;
+    if (cla !== undefined && cla !== null && claRecord === undefined) {
+        warnings.push(`Manifest gate field "gate.cla" must be a mapping; ignoring it.`);
+    }
+    const gate = {
+        present: false,
+        enabled: normalizeOptionalBoolean(record.enabled, "gate.enabled", warnings),
+        checkMode: normalizeOptionalEnum(record.checkMode, "gate.checkMode", ["required", "visible", "disabled"], warnings),
+        pack: normalizeOptionalEnum(record.pack, "gate.pack", ["gittensor", "oss-anti-slop"], warnings),
+        linkedIssue: normalizeOptionalGateMode(record.linkedIssue, "gate.linkedIssue", warnings),
+        duplicates: normalizeOptionalGateMode(record.duplicates, "gate.duplicates", warnings),
+        readinessMode: normalizeReadinessGateMode(readinessRecord?.mode, "gate.readiness.mode", warnings),
+        readinessMinScore: normalizeOptionalScore(readinessRecord?.minScore, "gate.readiness.minScore", warnings),
+        slopMode: normalizeOptionalGateMode(slopRecord?.mode, "gate.slop.mode", warnings),
+        slopMinScore: normalizeOptionalScore(slopRecord?.minScore, "gate.slop.minScore", warnings),
+        slopAiAdvisory: normalizeOptionalBoolean(slopRecord?.aiAdvisory, "gate.slop.aiAdvisory", warnings),
+        sizeMode: normalizeOptionalGateMode(sizeRecord?.mode, "gate.size.mode", warnings),
+        lockfileIntegrityMode: normalizeOptionalGateMode(record.lockfileIntegrity, "gate.lockfileIntegrity", warnings),
+        aiReviewMode: normalizeOptionalGateMode(aiReviewRecord?.mode, "gate.aiReview.mode", warnings),
+        aiReviewByok: normalizeOptionalBoolean(aiReviewRecord?.byok, "gate.aiReview.byok", warnings),
+        aiReviewProvider: normalizeOptionalEnum(aiReviewRecord?.provider, "gate.aiReview.provider", ["anthropic", "openai"], warnings),
+        aiReviewModel: normalizeOptionalString(aiReviewRecord?.model, "gate.aiReview.model", warnings),
+        aiReviewAllAuthors: normalizeOptionalBoolean(aiReviewRecord?.allAuthors, "gate.aiReview.allAuthors", warnings),
+        aiReviewCloseConfidence: normalizeOptionalConfidence(aiReviewRecord?.closeConfidence, "gate.aiReview.closeConfidence", warnings),
+        aiReviewLowConfidenceDisposition: normalizeOptionalEnum(aiReviewRecord?.lowConfidenceDisposition, "gate.aiReview.lowConfidenceDisposition", ["one_shot", "hold_for_review", "advisory_only"], warnings),
+        aiReviewCombine: normalizeOptionalEnum(aiReviewRecord?.combine, "gate.aiReview.combine", ["single", "consensus", "synthesis"], warnings),
+        aiReviewOnMerge: normalizeOptionalEnum(aiReviewRecord?.onMerge, "gate.aiReview.onMerge", ["either", "both"], warnings),
+        aiReviewReviewers: normalizeOptionalReviewers(aiReviewRecord?.reviewers, "gate.aiReview.reviewers", warnings),
+        mergeReadiness: normalizeOptionalGateMode(record.mergeReadiness, "gate.mergeReadiness", warnings),
+        manifestPolicy: normalizeOptionalGateMode(record.manifestPolicy, "gate.manifestPolicy", warnings),
+        selfAuthoredLinkedIssue: normalizeOptionalGateMode(record.selfAuthoredLinkedIssue, "gate.selfAuthoredLinkedIssue", warnings),
+        linkedIssueSatisfaction: normalizeOptionalGateMode(record.linkedIssueSatisfaction, "gate.linkedIssueSatisfaction", warnings),
+        dryRun: normalizeOptionalBoolean(record.dryRun, "gate.dryRun", warnings),
+        firstTimeContributorGrace: normalizeOptionalBoolean(record.firstTimeContributorGrace, "gate.firstTimeContributorGrace", warnings),
+        premergeContentRecheck: normalizeOptionalBoolean(record.premergeContentRecheck, "gate.premergeContentRecheck", warnings),
+        requireFreshRebaseWindowMinutes: normalizeOptionalPositiveInteger(record.requireFreshRebaseWindow, "gate.requireFreshRebaseWindow", warnings),
+        claMode: normalizeOptionalGateMode(record.claMode, "gate.claMode", warnings),
+        claConsentPhrase: parsePublicSafeText(claRecord?.consentPhrase, "gate.cla.consentPhrase", warnings),
+        claCheckRunName: parsePublicSafeText(claRecord?.checkRunName, "gate.cla.checkRunName", warnings),
+        claCheckRunAppSlug: parsePublicSafeText(claRecord?.checkRunAppSlug, "gate.cla.checkRunAppSlug", warnings),
+        expectedCiContexts: normalizeOptionalStringList(record.expectedCiContexts, "gate.expectedCiContexts", warnings),
+        aiJudgmentBlockersMode: normalizeOptionalEnum(record.aiJudgmentBlockers, "gate.aiJudgmentBlockers", ["gate", "advisory"], warnings),
+        copycatMode: normalizeOptionalEnum(copycatRecord?.mode, "gate.copycat.mode", ["off", "warn", "label", "block"], warnings),
+        copycatMinScore: normalizeOptionalScore(copycatRecord?.minScore, "gate.copycat.minScore", warnings),
+    };
+    // #2266: the flag is parsed, clamped, and threaded end-to-end, but the gate evaluator never reads it — a
+    // maintainer who sets it to true believing it softens a blocker for newcomers gets no such effect. Surface
+    // that inertness at parse time rather than leaving it silently no-op; `false`/unset matches the (also inert)
+    // default, so only an explicit `true` is worth flagging.
+    if (gate.firstTimeContributorGrace === true) {
+        warnings.push(`Manifest field "gate.firstTimeContributorGrace" is currently reserved/inert — it does not soften a blocker outcome for first-time contributors.`);
+    }
+    // gate.enabled only controls whether the "LoopOver Orb Review Agent" check-run publishes (the legacy
+    // enabled -> reviewCheckMode alias in applyGateConfigOverrides) -- it does NOT gate spend, merge, comment,
+    // label, or close behavior, and it cannot express checkMode's "visible" state. checkMode always wins when
+    // both are set, so once an operator sets checkMode, a lingering enabled becomes pure inert noise they have
+    // no reason to notice or remove -- only warn while checkMode is still absent (a paired enabled+checkMode
+    // config, the documented convention, is not worth flagging). Caused two real incidents under this exact
+    // ambiguity (an operator flipping enabled to restore unrelated spend/gate behavior got a surprise check-run
+    // side effect instead, twice).
+    if (gate.enabled !== null && gate.checkMode === null) {
+        warnings.push(`Manifest field "gate.enabled" only controls whether the LoopOver Orb Review Agent check-run publishes — it does not gate spend, merge, comment, label, or close behavior, and it cannot express reviewCheckMode's "visible" state. Set "gate.checkMode" (required/visible/disabled) explicitly instead of "gate.enabled".`);
+    }
+    gate.present =
+        gate.enabled !== null ||
+            gate.checkMode !== null ||
+            gate.pack !== null ||
+            gate.linkedIssue !== null ||
+            gate.duplicates !== null ||
+            gate.readinessMode !== null ||
+            gate.readinessMinScore !== null ||
+            gate.slopMode !== null ||
+            gate.slopMinScore !== null ||
+            gate.slopAiAdvisory !== null ||
+            gate.sizeMode !== null ||
+            gate.lockfileIntegrityMode !== null ||
+            gate.aiReviewMode !== null ||
+            gate.aiReviewByok !== null ||
+            gate.aiReviewProvider !== null ||
+            gate.aiReviewModel !== null ||
+            gate.aiReviewAllAuthors !== null ||
+            gate.aiReviewCloseConfidence !== null ||
+            gate.aiReviewLowConfidenceDisposition !== null ||
+            gate.aiReviewCombine !== null ||
+            gate.aiReviewOnMerge !== null ||
+            gate.aiReviewReviewers !== null ||
+            gate.mergeReadiness !== null ||
+            gate.manifestPolicy !== null ||
+            gate.selfAuthoredLinkedIssue !== null ||
+            gate.linkedIssueSatisfaction !== null ||
+            gate.dryRun !== null ||
+            gate.firstTimeContributorGrace !== null ||
+            gate.premergeContentRecheck !== null ||
+            gate.requireFreshRebaseWindowMinutes !== null ||
+            gate.claMode !== null ||
+            gate.claConsentPhrase !== null ||
+            gate.claCheckRunName !== null ||
+            gate.claCheckRunAppSlug !== null ||
+            gate.expectedCiContexts !== null ||
+            gate.aiJudgmentBlockersMode !== null ||
+            gate.copycatMode !== null ||
+            gate.copycatMinScore !== null;
+    return gate;
+}
+/**
+ * Serialize a gate config back into the parse-compatible `gate:` shape so a cached manifest snapshot
+ * round-trips through {@link parseGateConfig} unchanged. Returns null when nothing is configured.
+ */
+export function gateConfigToJson(gate) {
+    if (!gate.present)
+        return null;
+    const out = {};
+    if (gate.enabled !== null)
+        out.enabled = gate.enabled;
+    if (gate.checkMode !== null)
+        out.checkMode = gate.checkMode;
+    if (gate.pack !== null)
+        out.pack = gate.pack;
+    if (gate.linkedIssue !== null)
+        out.linkedIssue = gate.linkedIssue;
+    if (gate.duplicates !== null)
+        out.duplicates = gate.duplicates;
+    if (gate.readinessMode !== null || gate.readinessMinScore !== null) {
+        const readiness = {};
+        if (gate.readinessMode !== null)
+            readiness.mode = gate.readinessMode;
+        if (gate.readinessMinScore !== null)
+            readiness.minScore = gate.readinessMinScore;
+        out.readiness = readiness;
+    }
+    if (gate.sizeMode !== null)
+        out.size = { mode: gate.sizeMode };
+    if (gate.lockfileIntegrityMode !== null)
+        out.lockfileIntegrity = gate.lockfileIntegrityMode;
+    if (gate.slopMode !== null || gate.slopMinScore !== null || gate.slopAiAdvisory !== null) {
+        const slop = {};
+        if (gate.slopMode !== null)
+            slop.mode = gate.slopMode;
+        if (gate.slopMinScore !== null)
+            slop.minScore = gate.slopMinScore;
+        if (gate.slopAiAdvisory !== null)
+            slop.aiAdvisory = gate.slopAiAdvisory;
+        out.slop = slop;
+    }
+    if (gate.aiReviewMode !== null ||
+        gate.aiReviewByok !== null ||
+        gate.aiReviewProvider !== null ||
+        gate.aiReviewModel !== null ||
+        gate.aiReviewAllAuthors !== null ||
+        gate.aiReviewCloseConfidence !== null ||
+        gate.aiReviewLowConfidenceDisposition !== null ||
+        gate.aiReviewCombine !== null ||
+        gate.aiReviewOnMerge !== null ||
+        gate.aiReviewReviewers !== null) {
+        const aiReview = {};
+        if (gate.aiReviewMode !== null)
+            aiReview.mode = gate.aiReviewMode;
+        if (gate.aiReviewByok !== null)
+            aiReview.byok = gate.aiReviewByok;
+        if (gate.aiReviewProvider !== null)
+            aiReview.provider = gate.aiReviewProvider;
+        if (gate.aiReviewModel !== null)
+            aiReview.model = gate.aiReviewModel;
+        if (gate.aiReviewAllAuthors !== null)
+            aiReview.allAuthors = gate.aiReviewAllAuthors;
+        if (gate.aiReviewCloseConfidence !== null)
+            aiReview.closeConfidence = gate.aiReviewCloseConfidence;
+        if (gate.aiReviewLowConfidenceDisposition !== null)
+            aiReview.lowConfidenceDisposition = gate.aiReviewLowConfidenceDisposition;
+        if (gate.aiReviewCombine !== null)
+            aiReview.combine = gate.aiReviewCombine;
+        if (gate.aiReviewOnMerge !== null)
+            aiReview.onMerge = gate.aiReviewOnMerge;
+        if (gate.aiReviewReviewers !== null) {
+            aiReview.reviewers = gate.aiReviewReviewers.map((r) => r.fallback ? { model: r.model, fallback: r.fallback } : { model: r.model });
+        }
+        out.aiReview = aiReview;
+    }
+    if (gate.mergeReadiness !== null)
+        out.mergeReadiness = gate.mergeReadiness;
+    if (gate.manifestPolicy !== null)
+        out.manifestPolicy = gate.manifestPolicy;
+    if (gate.selfAuthoredLinkedIssue !== null)
+        out.selfAuthoredLinkedIssue = gate.selfAuthoredLinkedIssue;
+    if (gate.linkedIssueSatisfaction !== null)
+        out.linkedIssueSatisfaction = gate.linkedIssueSatisfaction;
+    if (gate.dryRun !== null)
+        out.dryRun = gate.dryRun;
+    if (gate.firstTimeContributorGrace !== null)
+        out.firstTimeContributorGrace = gate.firstTimeContributorGrace;
+    if (gate.premergeContentRecheck !== null)
+        out.premergeContentRecheck = gate.premergeContentRecheck;
+    if (gate.requireFreshRebaseWindowMinutes !== null)
+        out.requireFreshRebaseWindow = gate.requireFreshRebaseWindowMinutes;
+    if (gate.claMode !== null)
+        out.claMode = gate.claMode;
+    if (gate.claConsentPhrase !== null || gate.claCheckRunName !== null || gate.claCheckRunAppSlug !== null) {
+        const cla = {};
+        if (gate.claConsentPhrase !== null)
+            cla.consentPhrase = gate.claConsentPhrase;
+        if (gate.claCheckRunName !== null)
+            cla.checkRunName = gate.claCheckRunName;
+        if (gate.claCheckRunAppSlug !== null)
+            cla.checkRunAppSlug = gate.claCheckRunAppSlug;
+        out.cla = cla;
+    }
+    if (gate.expectedCiContexts !== null)
+        out.expectedCiContexts = gate.expectedCiContexts;
+    if (gate.aiJudgmentBlockersMode !== null)
+        out.aiJudgmentBlockers = gate.aiJudgmentBlockersMode;
+    if (gate.copycatMode !== null || gate.copycatMinScore !== null) {
+        const copycat = {};
+        if (gate.copycatMode !== null)
+            copycat.mode = gate.copycatMode;
+        if (gate.copycatMinScore !== null)
+            copycat.minScore = gate.copycatMinScore;
+        out.copycat = copycat;
+    }
+    return out;
+}
+/**
+ * Parse the optional `features:` mapping — per-repo activation overrides for the converged review features.
+ * Each recognized key becomes a tri-state (`true`/`false`/`null`); unknown keys and non-boolean values are
+ * dropped with a warning. `present` is true when at least one key was explicitly set, so an operator can make
+ * the manifest "present" with only a `features:` block.
+ */
+function parseFeaturesConfig(value, warnings) {
+    const features = { ...EMPTY_FEATURES_CONFIG };
+    if (value === undefined || value === null)
+        return features;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push('Manifest "features" must be a mapping; ignoring it.');
+        return features;
+    }
+    const record = value;
+    for (const key of CONVERGED_FEATURE_KEYS) {
+        features[key] = normalizeOptionalBoolean(record[key], `features.${key}`, warnings);
+    }
+    features.present = CONVERGED_FEATURE_KEYS.some((key) => features[key] !== null);
+    return features;
+}
+/** Serialize a features config back into the parse-compatible `features:` shape so a cached snapshot round-trips
+ *  through {@link parseFeaturesConfig} unchanged. Returns null when nothing is configured. */
+export function featuresConfigToJson(features) {
+    if (!features.present)
+        return null;
+    const out = {};
+    for (const key of CONVERGED_FEATURE_KEYS) {
+        if (features[key] !== null)
+            out[key] = features[key];
+    }
+    return out;
+}
+/**
+ * Parse the optional `experimental:` mapping — per-repo activation for optional ecosystem/network plugins
+ * (starting with `gittensor`, the subnet mining/scoring integration). Mirrors parseFeaturesConfig's shape and
+ * validation; kept as a SEPARATE top-level block from `features:` so plugin integrations that couple gittensory
+ * to an external network stay visibly distinct from the converged REVIEW capabilities `features:` toggles, and
+ * so future plugins land in the same place without touching `features:`'s semantics.
+ */
+function parseExperimentalConfig(value, warnings) {
+    const experimental = { ...EMPTY_EXPERIMENTAL_CONFIG };
+    if (value === undefined || value === null)
+        return experimental;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push('Manifest "experimental" must be a mapping; ignoring it.');
+        return experimental;
+    }
+    const record = value;
+    for (const key of EXPERIMENTAL_PLUGIN_KEYS) {
+        experimental[key] = normalizeOptionalBoolean(record[key], `experimental.${key}`, warnings);
+    }
+    experimental.present = EXPERIMENTAL_PLUGIN_KEYS.some((key) => experimental[key] !== null);
+    return experimental;
+}
+/** Serialize an experimental config back into the parse-compatible `experimental:` shape so a cached snapshot
+ *  round-trips through {@link parseExperimentalConfig} unchanged. Returns null when nothing is configured. */
+export function experimentalConfigToJson(experimental) {
+    if (!experimental.present)
+        return null;
+    const out = {};
+    for (const key of EXPERIMENTAL_PLUGIN_KEYS) {
+        if (experimental[key] !== null)
+            out[key] = experimental[key];
+    }
+    return out;
+}
+/** A positive INTEGER count (not a score/confidence) — e.g. `contentLane.maxAppendedEntries` counts discrete
+ *  surfaces[] entries, so a fractional value (a likely typo) would render a nonsensical contributor-facing close
+ *  message ("append between 1 and 2.5 entries"). Rejects fractional and non-positive values alike. */
+function normalizeOptionalPositiveInteger(value, field, warnings) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value === "number" && Number.isInteger(value) && value > 0)
+        return value;
+    warnings.push(`Manifest field "${field}" must be a positive whole number; ignoring it.`);
+    return null;
+}
+const MAX_CONTRIBUTOR_OPEN_ITEM_CAP = 100;
+function normalizeOptionalContributorOpenItemCap(value, field, warnings) {
+    const parsed = normalizeOptionalPositiveInteger(value, field, warnings);
+    if (parsed === null)
+        return null;
+    return Math.min(parsed, MAX_CONTRIBUTOR_OPEN_ITEM_CAP);
+}
+const REVIEW_VISUAL_MAX_ROUTES_LIMIT = 5;
+function normalizeOptionalVisualMaxRoutes(value, warnings) {
+    const maxRoutes = normalizeOptionalPositiveInteger(value, "review.visual.routes.max_routes", warnings);
+    if (maxRoutes === null)
+        return null;
+    if (maxRoutes <= REVIEW_VISUAL_MAX_ROUTES_LIMIT)
+        return maxRoutes;
+    warnings.push(`Manifest field "review.visual.routes.max_routes" must be at most ${REVIEW_VISUAL_MAX_ROUTES_LIMIT}; clamping it.`);
+    return REVIEW_VISUAL_MAX_ROUTES_LIMIT;
+}
+/** Normalize + bound a maintainer-supplied glob string: trims/length-caps like any other string field, AND
+ *  rejects one globToRegExp (review/content-lane/spec-resolver.ts's reuse of the guardrail-path compiler) would
+ *  itself refuse to compile safely. Reuses `hasUnsafeWildcardCount` — globToRegExp's OWN safety predicate —
+ *  rather than a locally-counted threshold: a caller that counts wildcards differently (e.g. raw `*` characters,
+ *  which double-counts a `**` pair as 2 groups instead of 1) can accept a glob globToRegExp then silently
+ *  compiles to NEVER_MATCHES, configuring a lane that is "present" but can never activate on any changed file
+ *  (#confirmed-bug). A glob over the cap is REJECTED (warns, returns null) rather than truncated — silently
+ *  cutting wildcards out of a maintainer's pattern would silently change its meaning, which is worse than making
+ *  them fix an over-complex glob. */
+function normalizeOptionalGlob(value, field, warnings) {
+    const normalized = normalizeOptionalString(value, field, warnings);
+    if (normalized === null)
+        return null;
+    if (normalized.length > MAX_ITEM_LENGTH) {
+        // REJECT, not truncate: cutting characters out of a glob changes which files it matches (e.g. a
+        // mid-directory-name cut can turn a narrow, intended pattern into one that matches an unrelated path
+        // prefix, or one that never matches anything) — silently compiling a DIFFERENT pattern than the
+        // maintainer configured is worse than making them shorten an over-complex glob.
+        warnings.push(`Manifest field "${field}" is an over-long glob (${normalized.length} > ${MAX_ITEM_LENGTH} chars); ignoring it.`);
+        return null;
+    }
+    if (hasUnsafeWildcardCount(normalized)) {
+        warnings.push(`Manifest field "${field}" has too many wildcards to compile safely; ignoring it.`);
+        return null;
+    }
+    return normalized;
+}
+/**
+ * Parse the optional `contentLane:` mapping — per-repo registry-review lane configuration (#2435). `entryFileGlob`
+ * and `collectionField` are REQUIRED to build a usable spec; a config missing either — including a glob rejected
+ * by `normalizeOptionalGlob`'s wildcard cap — degrades to "not configured" (a warning, falling through to the
+ * allowlist default) rather than a broken half-spec. Glob fields stay plain strings here — compiling them to
+ * RegExp is the resolver's job (`review/content-lane/spec-resolver.ts`), not the parser's, so this file stays
+ * free of a RegExp-from-config compile step; it's still this file's job to keep an over-complex glob from ever
+ * reaching that compile step at all.
+ */
+function parseContentLaneConfig(value, warnings) {
+    if (value === undefined || value === null)
+        return { ...EMPTY_CONTENT_LANE_CONFIG };
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push('Manifest field "contentLane" must be a mapping; ignoring it.');
+        return { ...EMPTY_CONTENT_LANE_CONFIG };
+    }
+    const record = value;
+    const entryFileGlob = normalizeOptionalGlob(record.entryFileGlob, "contentLane.entryFileGlob", warnings);
+    const providerFileGlob = normalizeOptionalGlob(record.providerFileGlob, "contentLane.providerFileGlob", warnings);
+    const artifactGlob = normalizeOptionalGlob(record.artifactGlob, "contentLane.artifactGlob", warnings);
+    const collectionField = normalizeOptionalString(record.collectionField, "contentLane.collectionField", warnings);
+    const maxAppendedEntries = normalizeOptionalPositiveInteger(record.maxAppendedEntries, "contentLane.maxAppendedEntries", warnings);
+    const duplicateKeyFields = normalizeStringList(record.duplicateKeyFields, "contentLane.duplicateKeyFields", warnings);
+    const validatorId = normalizeOptionalString(record.validatorId, "contentLane.validatorId", warnings);
+    if (!entryFileGlob || !collectionField) {
+        warnings.push('Manifest field "contentLane" requires both entryFileGlob and collectionField; ignoring it.');
+        return { ...EMPTY_CONTENT_LANE_CONFIG };
+    }
+    return { present: true, entryFileGlob, providerFileGlob, artifactGlob, collectionField, maxAppendedEntries, duplicateKeyFields, validatorId };
+}
+/** Serialize a contentLane config back into the parse-compatible `contentLane:` shape so a cached snapshot
+ *  round-trips through {@link parseContentLaneConfig} unchanged. Returns null when nothing is configured. */
+export function contentLaneConfigToJson(contentLane) {
+    if (!contentLane.present || !contentLane.entryFileGlob || !contentLane.collectionField)
+        return null;
+    const out = { entryFileGlob: contentLane.entryFileGlob, collectionField: contentLane.collectionField };
+    if (contentLane.providerFileGlob !== null)
+        out.providerFileGlob = contentLane.providerFileGlob;
+    if (contentLane.artifactGlob !== null)
+        out.artifactGlob = contentLane.artifactGlob;
+    if (contentLane.maxAppendedEntries !== null)
+        out.maxAppendedEntries = contentLane.maxAppendedEntries;
+    if (contentLane.duplicateKeyFields.length > 0)
+        out.duplicateKeyFields = contentLane.duplicateKeyFields;
+    if (contentLane.validatorId !== null)
+        out.validatorId = contentLane.validatorId;
+    return out;
+}
+const REPO_DOC_GENERATION_SCOPES = ["agents", "skills"];
+/** `undefined`/`null` (key omitted) falls back to the default scope; a non-list value is a genuine type error
+ *  and ALSO falls back to the default (rather than emptying it out, which would silently disable an otherwise
+ *  `enabled: true` config); an actual list -- even an explicitly empty one, or one where every entry is
+ *  invalid -- is respected as "nothing in scope", since that is a deliberate, well-typed value. */
+function parseRepoDocGenerationScope(value, warnings) {
+    if (value === undefined || value === null)
+        return [...EMPTY_REPO_DOC_GENERATION_CONFIG.scope];
+    if (!Array.isArray(value)) {
+        warnings.push('Manifest field "repoDocGeneration.scope" must be a list; falling back to the default scope.');
+        return [...EMPTY_REPO_DOC_GENERATION_CONFIG.scope];
+    }
+    const raw = normalizeStringList(value, "repoDocGeneration.scope", warnings);
+    return raw.filter((entry) => {
+        if (REPO_DOC_GENERATION_SCOPES.includes(entry))
+            return true;
+        warnings.push(`Manifest field "repoDocGeneration.scope" has an unrecognized entry "${entry}"; ignoring it.`);
+        return false;
+    });
+}
+/**
+ * Parse the optional `repoDocGeneration:` mapping (#3002). Unlike `gate:`/`settings:`, every field here has a
+ * concrete default rather than a null "unconfigured" sentinel -- there is no DB layer to overlay onto, so the
+ * parsed value (or the default, when a key is omitted) IS the effective value. An explicitly empty `scope: []`
+ * is honored as "nothing in scope" (not coerced back to the default); only an OMITTED `scope` key falls back to
+ * `["agents"]`, mirroring how `undefined`/`null` mean "unset" everywhere else in this file.
+ */
+function parseRepoDocGenerationConfig(value, warnings) {
+    if (value === undefined || value === null)
+        return { ...EMPTY_REPO_DOC_GENERATION_CONFIG };
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push('Manifest field "repoDocGeneration" must be a mapping; ignoring it.');
+        return { ...EMPTY_REPO_DOC_GENERATION_CONFIG };
+    }
+    const record = value;
+    const enabled = normalizeOptionalBoolean(record.enabled, "repoDocGeneration.enabled", warnings) ?? false;
+    const allowOverwriteExisting = normalizeOptionalBoolean(record.allowOverwriteExisting, "repoDocGeneration.allowOverwriteExisting", warnings) ?? false;
+    const scope = parseRepoDocGenerationScope(record.scope, warnings);
+    const refreshIntervalDays = normalizeOptionalPositiveInteger(record.refreshIntervalDays, "repoDocGeneration.refreshIntervalDays", warnings) ?? DEFAULT_REPO_DOC_REFRESH_INTERVAL_DAYS;
+    return { present: true, enabled, scope, allowOverwriteExisting, refreshIntervalDays };
+}
+/** Serialize a repoDocGeneration config back into the parse-compatible shape so a cached snapshot round-trips
+ *  through {@link parseRepoDocGenerationConfig} unchanged. Returns null when nothing is configured. */
+export function repoDocGenerationConfigToJson(config) {
+    if (!config.present)
+        return null;
+    return { enabled: config.enabled, scope: config.scope, allowOverwriteExisting: config.allowOverwriteExisting, refreshIntervalDays: config.refreshIntervalDays };
+}
+/**
+ * Parse the optional `reviewRecap:` mapping (#1963). Mirrors {@link parseRepoDocGenerationConfig}: every
+ * field has a concrete default (no DB layer to overlay onto), so the parsed value IS the effective value.
+ */
+function parseReviewRecapConfig(value, warnings) {
+    if (value === undefined || value === null)
+        return { ...EMPTY_REVIEW_RECAP_CONFIG };
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push('Manifest field "reviewRecap" must be a mapping; ignoring it.');
+        return { ...EMPTY_REVIEW_RECAP_CONFIG };
+    }
+    const record = value;
+    const enabled = normalizeOptionalBoolean(record.enabled, "reviewRecap.enabled", warnings) ?? false;
+    const cadenceDays = normalizeOptionalPositiveInteger(record.cadenceDays, "reviewRecap.cadenceDays", warnings) ?? DEFAULT_REVIEW_RECAP_CADENCE_DAYS;
+    return { present: true, enabled, cadenceDays };
+}
+/** Serialize a reviewRecap config back into the parse-compatible shape so a cached snapshot round-trips
+ *  through {@link parseReviewRecapConfig} unchanged. Returns null when nothing is configured. */
+export function reviewRecapConfigToJson(config) {
+    if (!config.present)
+        return null;
+    return { enabled: config.enabled, cadenceDays: config.cadenceDays };
+}
+/**
+ * Parse the optional `maintainerRecap:` mapping (#1963, #2250). Mirrors {@link parseReviewRecapConfig}: every
+ * field has a concrete default (no DB layer to overlay onto), so the parsed value IS the effective value. An
+ * invalid `cadence`/`channel` falls back to its default via {@link normalizeEnum} (with a warning) rather than
+ * silently firing more often or targeting an unsupported channel.
+ */
+function parseMaintainerRecapConfig(value, warnings) {
+    if (value === undefined || value === null)
+        return { ...EMPTY_MAINTAINER_RECAP_CONFIG };
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push('Manifest field "maintainerRecap" must be a mapping; ignoring it.');
+        return { ...EMPTY_MAINTAINER_RECAP_CONFIG };
+    }
+    const record = value;
+    const enabled = normalizeOptionalBoolean(record.enabled, "maintainerRecap.enabled", warnings) ?? false;
+    const cadence = normalizeEnum(record.cadence, "maintainerRecap.cadence", ["daily", "weekly"], DEFAULT_MAINTAINER_RECAP_CADENCE, warnings);
+    const channel = normalizeEnum(record.channel, "maintainerRecap.channel", ["discord"], DEFAULT_MAINTAINER_RECAP_CHANNEL, warnings);
+    return { present: true, enabled, cadence, channel };
+}
+/** Serialize a maintainerRecap config back into the parse-compatible shape so a cached snapshot round-trips
+ *  through {@link parseMaintainerRecapConfig} unchanged. Returns null when nothing is configured. */
+export function maintainerRecapConfigToJson(config) {
+    if (!config.present)
+        return null;
+    return { enabled: config.enabled, cadence: config.cadence, channel: config.channel };
+}
+function normalizeOptionalEnum(value, field, allowed, warnings) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value === "string" && allowed.includes(value))
+        return value;
+    warnings.push(`Manifest settings field "${field}" must be one of ${allowed.join(", ")}; ignoring "${String(value)}".`);
+    return null;
+}
+function normalizeOptionalString(value, field, warnings) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value === "string" && value.trim().length > 0)
+        return value.trim();
+    warnings.push(`Manifest settings field "${field}" must be a non-empty string; ignoring it.`);
+    return null;
+}
+// Keep the review-nag lookback operationally bounded so repo-controlled config cannot overflow Date
+// arithmetic. Duplicated from settings/agent-actions.ts's own MAX_REVIEW_NAG_COOLDOWN_DAYS (same value,
+// same rationale) rather than imported: this module is part of the UI package's typechecked closure, and
+// agent-actions.ts transitively imports github/commands.ts -> utils/crypto.ts, pulling a heavier
+// GitHub-App-specific dependency chain into the UI build for one small constant.
+const MAX_REVIEW_NAG_COOLDOWN_DAYS = 365;
+/**
+ * Parse the optional `settings:` mapping — a partial repository-settings override. Only recognized
+ * fields are kept; unknown/invalid values are dropped with a warning and never throw.
+ */
+function parseSettingsOverride(value, warnings, source) {
+    if (value === undefined || value === null)
+        return {};
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push(`Manifest field "settings" must be a mapping; ignoring it.`);
+        return {};
+    }
+    const r = value;
+    const out = {};
+    const commentMode = normalizeOptionalEnum(r.commentMode, "settings.commentMode", ["off", "detected_contributors_only", "all_prs"], warnings);
+    if (commentMode !== null)
+        out.commentMode = commentMode;
+    const publicAudienceMode = normalizeOptionalEnum(r.publicAudienceMode, "settings.publicAudienceMode", ["oss_maintainer", "gittensor_only"], warnings);
+    if (publicAudienceMode !== null)
+        out.publicAudienceMode = publicAudienceMode;
+    const publicSignalLevel = normalizeOptionalEnum(r.publicSignalLevel, "settings.publicSignalLevel", ["minimal", "standard"], warnings);
+    if (publicSignalLevel !== null)
+        out.publicSignalLevel = publicSignalLevel;
+    const checkRunMode = normalizeOptionalEnum(r.checkRunMode, "settings.checkRunMode", ["off", "enabled"], warnings);
+    if (checkRunMode !== null)
+        out.checkRunMode = checkRunMode;
+    const checkRunDetailLevel = normalizeOptionalEnum(r.checkRunDetailLevel, "settings.checkRunDetailLevel", ["minimal", "standard"], warnings);
+    if (checkRunDetailLevel !== null)
+        out.checkRunDetailLevel = checkRunDetailLevel;
+    const regateSweepOrderMode = normalizeOptionalEnum(r.regateSweepOrderMode, "settings.regateSweepOrderMode", ["staleness", "oldest-first"], warnings);
+    if (regateSweepOrderMode !== null)
+        out.regateSweepOrderMode = regateSweepOrderMode;
+    // Same tri-state field as gate.checkMode above (the friendly gate alias overlays onto it in
+    // resolveEffectiveSettings, and wins when both are set).
+    const reviewCheckMode = normalizeOptionalEnum(r.reviewCheckMode, "settings.reviewCheckMode", ["required", "visible", "disabled"], warnings);
+    if (reviewCheckMode !== null)
+        out.reviewCheckMode = reviewCheckMode;
+    const autoProjectMilestoneMatch = normalizeOptionalEnum(r.autoProjectMilestoneMatch, "settings.autoProjectMilestoneMatch", ["off", "suggest", "auto"], warnings);
+    if (autoProjectMilestoneMatch !== null)
+        out.autoProjectMilestoneMatch = autoProjectMilestoneMatch;
+    const autoProjectMilestoneMatchBackend = normalizeOptionalEnum(r.autoProjectMilestoneMatchBackend, "settings.autoProjectMilestoneMatchBackend", ["github", "linear"], warnings);
+    if (autoProjectMilestoneMatchBackend !== null)
+        out.autoProjectMilestoneMatchBackend = autoProjectMilestoneMatchBackend;
+    const linkedIssueGateMode = normalizeOptionalGateMode(r.linkedIssueGateMode, "settings.linkedIssueGateMode", warnings);
+    if (linkedIssueGateMode !== null)
+        out.linkedIssueGateMode = linkedIssueGateMode;
+    const duplicatePrGateMode = normalizeOptionalGateMode(r.duplicatePrGateMode, "settings.duplicatePrGateMode", warnings);
+    if (duplicatePrGateMode !== null)
+        out.duplicatePrGateMode = duplicatePrGateMode;
+    const selfAuthoredLinkedIssueGateMode = normalizeOptionalGateMode(r.selfAuthoredLinkedIssueGateMode, "settings.selfAuthoredLinkedIssueGateMode", warnings);
+    if (selfAuthoredLinkedIssueGateMode !== null)
+        out.selfAuthoredLinkedIssueGateMode = selfAuthoredLinkedIssueGateMode;
+    // Same tri-state field as gate.readiness.mode above (the friendly gate alias overlays onto it in
+    // resolveEffectiveSettings) — apply the identical "block" → "advisory" downgrade here too, so a maintainer
+    // setting `settings.qualityGateMode: block` directly hits the same deprecation warning (#2267).
+    const qualityGateMode = normalizeReadinessGateMode(r.qualityGateMode, "settings.qualityGateMode", warnings);
+    if (qualityGateMode !== null)
+        out.qualityGateMode = qualityGateMode;
+    const qualityGateMinScore = normalizeOptionalScore(r.qualityGateMinScore, "settings.qualityGateMinScore", warnings);
+    if (qualityGateMinScore !== null)
+        out.qualityGateMinScore = qualityGateMinScore;
+    const aiReviewMode = normalizeOptionalGateMode(r.aiReviewMode, "settings.aiReviewMode", warnings);
+    if (aiReviewMode !== null)
+        out.aiReviewMode = aiReviewMode;
+    const aiReviewProvider = normalizeOptionalEnum(r.aiReviewProvider, "settings.aiReviewProvider", ["anthropic", "openai"], warnings);
+    if (aiReviewProvider !== null)
+        out.aiReviewProvider = aiReviewProvider;
+    const aiReviewModel = normalizeOptionalString(r.aiReviewModel, "settings.aiReviewModel", warnings);
+    if (aiReviewModel !== null)
+        out.aiReviewModel = aiReviewModel;
+    const gittensorLabel = normalizeOptionalString(r.gittensorLabel, "settings.gittensorLabel", warnings);
+    if (gittensorLabel !== null)
+        out.gittensorLabel = gittensorLabel;
+    // #label-scoping: an explicit yml `null` is load-bearing (closes WITHOUT any label), matching
+    // contributorOpenPrCap's own null-vs-omitted distinction — must be checked BEFORE normalizeOptionalString,
+    // which otherwise collapses null and undefined to the same "unset" result.
+    if (r.blacklistLabel === null) {
+        out.blacklistLabel = null;
+    }
+    else {
+        const blacklistLabel = normalizeOptionalString(r.blacklistLabel, "settings.blacklistLabel", warnings);
+        if (blacklistLabel !== null)
+            out.blacklistLabel = blacklistLabel;
+    }
+    const publicSurface = normalizeOptionalEnum(r.publicSurface, "settings.publicSurface", ["off", "comment_and_label", "comment_only", "label_only"], warnings);
+    if (publicSurface !== null)
+        out.publicSurface = publicSurface;
+    for (const key of ["aiReviewByok", "aiReviewAllAuthors", "closeOwnerAuthors", "autoLabelEnabled", "typeLabelsEnabled", "badgeEnabled", "publicQualityMetrics", "createMissingLabel", "includeMaintainerAuthors", "requireLinkedIssue", "backfillEnabled", "agentPaused", "agentDryRun"]) {
+        const flag = normalizeOptionalBoolean(r[key], `settings.${key}`, warnings);
+        if (flag !== null)
+            out[key] = flag;
+    }
+    // agentGlobalFreezeOverride is deliberately NOT in the generic boolean loop above (#4372/#4391/operator-only-
+    // freeze-fix): it is an OPERATOR-ONLY emergency lever ("re-activate this one repo while the fleet-wide kill-
+    // switch stays on elsewhere"), and every OTHER settings field in that loop is readable from BOTH the public,
+    // maintainer-owned `.gittensory.yml` committed in the repo's own git history (source: "repo_file") AND the
+    // operator's private, container-local self-host config (source: "api_record") -- see loadRepoFocusManifestWithCachePolicy
+    // in focus-manifest-loader.ts for how each source is produced. A repo MAINTAINER must never be able to grant
+    // their own repo an exemption from the operator's fleet-wide freeze via their own committed yml (that is
+    // exactly the "scope leak" #4391 closed by stripping this field from the shared loop entirely). But the
+    // OPERATOR's own private config source is a fundamentally different trust boundary -- it is edited only by
+    // whoever has filesystem access to the container's private config directory, not by any repo's maintainers --
+    // and #4391 over-corrected by also removing the operator's own legitimate, config-as-code path for this lever,
+    // forcing raw undocumented DB writes as the only remaining mechanism (violating this project's config-as-code
+    // convention: every operator-facing control belongs in the global-default + per-repo-override config files,
+    // env vars are for bootstrap only). Restore it, gated STRICTLY to the private source.
+    if (source === "api_record") {
+        const agentGlobalFreezeOverride = normalizeOptionalBoolean(r.agentGlobalFreezeOverride, "settings.agentGlobalFreezeOverride", warnings);
+        if (agentGlobalFreezeOverride !== null)
+            out.agentGlobalFreezeOverride = agentGlobalFreezeOverride;
+    }
+    else if (r.agentGlobalFreezeOverride !== undefined) {
+        // A public/maintainer-owned manifest attempting to set this is silently dropped, not surfaced as a normal
+        // "invalid value" warning -- warnings are public-safe text that can reach a contributor-facing preview, and
+        // this should not teach a non-operator that the field exists or that they almost bypassed the fleet freeze.
+        warnings.push("Ignored settings.agentGlobalFreezeOverride: operator-only, not settable from a repo-owned manifest.");
+    }
+    // Agent-layer autonomy dial (#773): `settings.autonomy` maps each action class to a level. Only set it
+    // when at least one valid class→level pair survives normalization, so a malformed block never blanks the
+    // DB-configured policy via the resolver's `{...dbSettings, ...manifest.settings}` overlay.
+    if (r.autonomy !== undefined) {
+        const autonomy = normalizeAutonomyPolicy(r.autonomy);
+        if (Object.keys(autonomy).length > 0)
+            out.autonomy = autonomy;
+    }
+    // Auto-maintain policy (#774): `settings.autoMaintain` declares the full policy (defaults fill any unset
+    // field) and overlays the DB value via the resolver. Only a mapping is honoured; anything else is ignored.
+    if (typeof r.autoMaintain === "object" && r.autoMaintain !== null && !Array.isArray(r.autoMaintain)) {
+        out.autoMaintain = normalizeAutoMaintainPolicy(r.autoMaintain);
+    }
+    // Command authorization policy (#2268 config-as-code parity): `settings.commandAuthorization` declares the
+    // full role policy the same way `autoMaintain` does — the normalizer fills any unset/invalid FIELD from
+    // DEFAULT_COMMAND_AUTHORIZATION_POLICY, so a partially-valid mapping yields a complete, safe policy that
+    // overlays the DB value via the resolver's `{...dbSettings, ...manifest.settings}` spread. But an invalid
+    // TOP-LEVEL shape (not a mapping at all) is a different case: normalizeCommandAuthorizationPolicy's own
+    // fallback there is meant for callers with no DB value to fall back to, not for this overlay — applying it
+    // here would let a typo'd config silently overwrite a stricter DB-persisted policy with the built-in
+    // default. So only apply the normalized policy when the raw value was actually a mapping; otherwise warn
+    // and leave `out.commandAuthorization` unset so the resolver preserves whatever the DB already has.
+    if (typeof r.commandAuthorization === "object" && r.commandAuthorization !== null && !Array.isArray(r.commandAuthorization)) {
+        const { policy, warnings: commandAuthorizationWarnings } = normalizeCommandAuthorizationPolicy(r.commandAuthorization);
+        warnings.push(...commandAuthorizationWarnings);
+        out.commandAuthorization = policy;
+    }
+    else if (r.commandAuthorization !== undefined) {
+        warnings.push(`Manifest "settings.commandAuthorization" must be an object; ignoring it and keeping any existing policy.`);
+    }
+    // TYPE label category overrides (#priority-linked-issue-gate, #label-modularity): unlike
+    // commandAuthorization/autoMaintain above, this is deliberately kept SPARSE -- only the keys actually
+    // present AND validly-shaped in the raw YAML are copied onto `out.typeLabels` (via
+    // `normalizeTypeLabelSet`, which still fills in the built-in bug/feature/priority keys to run its own
+    // shape checks, but those defaults-filled values are discarded here). A manifest naming only
+    // `typeLabels.priority` must inherit `bug`/`feature` from the DB-persisted value in
+    // `resolveEffectiveSettings`, not have them silently reset to the built-in gittensor:* names -- assigning
+    // the normalizer's complete object here would do exactly that via the resolver's wholesale
+    // `{...dbSettings, ...manifest.settings}` spread. The per-field shape check below (not just "is the key
+    // present") matters too: a malformed value (e.g. `typeLabels.priority: 123`) is present but invalid, so
+    // `normalizeTypeLabelSet` warns and reports its OWN built-in-default fallback for that key -- copying
+    // that fallback into the sparse override would silently overwrite a DB-customized value with the
+    // built-in default on a config typo, instead of leaving the DB value alone. The loop is generic over
+    // whatever keys the raw object actually has (not hardcoded to bug/feature/priority), so an arbitrary
+    // custom category (e.g. `security`) sparse-overrides exactly like a built-in one. The normalizer
+    // enforces the category-count and label-name caps before a sparse key can survive into the override.
+    if (typeof r.typeLabels === "object" && r.typeLabels !== null && !Array.isArray(r.typeLabels)) {
+        const rawTypeLabels = r.typeLabels;
+        if (Object.keys(rawTypeLabels).length === 0) {
+            // A literal `typeLabels: {}` is a DELIBERATE, complete declaration -- "zero configured categories
+            // for this repo" -- distinct from a sparse override whose named keys all failed validation (the
+            // `else` branch below, which must NOT wipe the DB value). Represented as `null` so
+            // `resolveEffectiveSettings` can tell the two apart even though both would otherwise collapse to
+            // the same empty-object shape (#label-modularity).
+            out.typeLabels = null;
+        }
+        else {
+            const validated = normalizeTypeLabelSet(rawTypeLabels, warnings);
+            const isValidLabelName = (value) => typeof value === "string" && value.trim().length > 0 && value.trim().length <= MAX_TYPE_LABEL_NAME_LENGTH;
+            const sparseTypeLabels = {};
+            for (const key of Object.keys(rawTypeLabels)) {
+                if (isValidLabelName(rawTypeLabels[key]) && validated[key] !== undefined)
+                    sparseTypeLabels[key] = validated[key];
+            }
+            out.typeLabels = sparseTypeLabels;
+        }
+    }
+    else if (r.typeLabels !== undefined) {
+        warnings.push(`Manifest "settings.typeLabels" must be an object; ignoring it and keeping any existing label names.`);
+    }
+    // Linked-issue label propagation (#priority-linked-issue-gate): same sparse-partial shape as typeLabels
+    // above, for the same reason -- this is the ONLY mechanism that can ever select a maintainer-reward
+    // label like gittensor:priority (never inferred from title/files/AI/PR-labels), so a manifest overriding
+    // just one field (e.g. `enabled`) must not silently reset `mappings` back to the built-in empty default
+    // and discard a DB-configured mapping list. Each field is gated on its OWN raw shape being valid (not
+    // just "is the key present"), for the same reason as typeLabels above -- e.g. a typo'd
+    // `mappings: "oops"` must never silently replace a DB-configured mapping list with the normalizer's
+    // empty-array fallback. A validly-shaped `mappings` array is still a complete replacement when present
+    // (arrays have no per-item precedence semantics here, and any individually-invalid entries inside it
+    // are dropped by the normalizer, not the array itself), matching the array-replace-wholesale overlay
+    // behavior documented for the private-config layer.
+    if (typeof r.linkedIssueLabelPropagation === "object" && r.linkedIssueLabelPropagation !== null && !Array.isArray(r.linkedIssueLabelPropagation)) {
+        const rawPropagation = r.linkedIssueLabelPropagation;
+        const validated = normalizeLinkedIssueLabelPropagationConfig(rawPropagation, warnings);
+        const sparsePropagation = {};
+        if (typeof rawPropagation.enabled === "boolean")
+            sparsePropagation.enabled = validated.enabled;
+        if (typeof rawPropagation.mode === "string" && VALID_LINKED_ISSUE_LABEL_PROPAGATION_MODES.includes(rawPropagation.mode)) {
+            sparsePropagation.mode = validated.mode;
+        }
+        if (Array.isArray(rawPropagation.mappings))
+            sparsePropagation.mappings = validated.mappings;
+        out.linkedIssueLabelPropagation = sparsePropagation;
+    }
+    else if (r.linkedIssueLabelPropagation !== undefined) {
+        warnings.push(`Manifest "settings.linkedIssueLabelPropagation" must be an object; ignoring it and keeping any existing policy.`);
+    }
+    // Linked-issue hard rules: same sparse-partial overlay contract as linkedIssueLabelPropagation. A global config
+    // can enable the policy and set label lists; a repo override can toggle one mode without resetting those lists.
+    if (typeof r.linkedIssueHardRules === "object" && r.linkedIssueHardRules !== null && !Array.isArray(r.linkedIssueHardRules)) {
+        const rawRules = r.linkedIssueHardRules;
+        const validated = normalizeLinkedIssueHardRulesConfig(rawRules, warnings);
+        const sparseRules = {};
+        if (isLinkedIssueHardRuleMode(rawRules.ownerAssignedClose))
+            sparseRules.ownerAssignedClose = validated.ownerAssignedClose;
+        if (isLinkedIssueHardRuleMode(rawRules.assignedIssueClose))
+            sparseRules.assignedIssueClose = validated.assignedIssueClose;
+        if (isLinkedIssueHardRuleMode(rawRules.missingPointLabelClose))
+            sparseRules.missingPointLabelClose = validated.missingPointLabelClose;
+        if (isLinkedIssueHardRuleMode(rawRules.maintainerOnlyLabelClose))
+            sparseRules.maintainerOnlyLabelClose = validated.maintainerOnlyLabelClose;
+        if (Array.isArray(rawRules.pointBearingLabels))
+            sparseRules.pointBearingLabels = validated.pointBearingLabels;
+        if (Array.isArray(rawRules.maintainerOnlyLabels))
+            sparseRules.maintainerOnlyLabels = validated.maintainerOnlyLabels;
+        if (typeof rawRules.defaultLabelRepo === "boolean")
+            sparseRules.defaultLabelRepo = validated.defaultLabelRepo;
+        if (typeof rawRules.verifyBeforeClose === "boolean")
+            sparseRules.verifyBeforeClose = validated.verifyBeforeClose;
+        if (typeof rawRules.closeDelaySeconds === "number" && Number.isFinite(rawRules.closeDelaySeconds) && rawRules.closeDelaySeconds >= 0) {
+            sparseRules.closeDelaySeconds = validated.closeDelaySeconds;
+        }
+        out.linkedIssueHardRules = sparseRules;
+    }
+    else if (r.linkedIssueHardRules !== undefined) {
+        warnings.push(`Manifest "settings.linkedIssueHardRules" must be an object; ignoring it and keeping any existing policy.`);
+    }
+    // Unlinked-issue guardrail (#unlinked-issue-guardrail): same sparse-partial overlay contract as
+    // linkedIssueHardRules above -- a repo naming only `mode` must not silently reset `minConfidence` back to
+    // the built-in default.
+    if (typeof r.unlinkedIssueGuardrail === "object" && r.unlinkedIssueGuardrail !== null && !Array.isArray(r.unlinkedIssueGuardrail)) {
+        const rawGuardrail = r.unlinkedIssueGuardrail;
+        const validated = normalizeUnlinkedIssueGuardrailConfig(rawGuardrail, warnings);
+        const sparseGuardrail = {};
+        if (isUnlinkedIssueGuardrailMode(rawGuardrail.mode))
+            sparseGuardrail.mode = validated.mode;
+        if (typeof rawGuardrail.minConfidence === "number" && Number.isFinite(rawGuardrail.minConfidence) && rawGuardrail.minConfidence >= 0 && rawGuardrail.minConfidence <= 1) {
+            sparseGuardrail.minConfidence = validated.minConfidence;
+        }
+        out.unlinkedIssueGuardrail = sparseGuardrail;
+    }
+    else if (r.unlinkedIssueGuardrail !== undefined) {
+        warnings.push(`Manifest "settings.unlinkedIssueGuardrail" must be an object; ignoring it and keeping any existing policy.`);
+    }
+    // Screenshot-table gate (#2006): same sparse-partial overlay contract as unlinkedIssueGuardrail above -- a
+    // repo naming only `enabled` must not silently reset `whenLabels`/`whenPaths`/`action`/`message`.
+    if (typeof r.screenshotTableGate === "object" && r.screenshotTableGate !== null && !Array.isArray(r.screenshotTableGate)) {
+        const rawGate = r.screenshotTableGate;
+        const validated = normalizeScreenshotTableGateConfig(rawGate, warnings);
+        const sparseGate = {};
+        if (typeof rawGate.enabled === "boolean")
+            sparseGate.enabled = validated.enabled;
+        if (Array.isArray(rawGate.whenLabels))
+            sparseGate.whenLabels = validated.whenLabels;
+        if (Array.isArray(rawGate.whenPaths))
+            sparseGate.whenPaths = validated.whenPaths;
+        if (isScreenshotTableGateAction(rawGate.action))
+            sparseGate.action = validated.action;
+        if (typeof rawGate.message === "string" && rawGate.message.trim().length > 0)
+            sparseGate.message = validated.message;
+        if (Array.isArray(rawGate.requireViewports))
+            sparseGate.requireViewports = validated.requireViewports;
+        if (Array.isArray(rawGate.requireThemes))
+            sparseGate.requireThemes = validated.requireThemes;
+        if (typeof rawGate.skillFileUrl === "string" && rawGate.skillFileUrl.trim().length > 0)
+            sparseGate.skillFileUrl = validated.skillFileUrl;
+        out.screenshotTableGate = sparseGate;
+    }
+    else if (r.screenshotTableGate !== undefined) {
+        warnings.push(`Manifest "settings.screenshotTableGate" must be an object; ignoring it and keeping any existing policy.`);
+    }
+    // Advisory-AI routing (#4364): same sparse-partial overlay contract as screenshotTableGate above -- a repo
+    // naming only `slop` must not silently reset `e2eTestGen`/`planner`/`summaries` back to their defaults.
+    if (typeof r.advisoryAiRouting === "object" && r.advisoryAiRouting !== null && !Array.isArray(r.advisoryAiRouting)) {
+        const rawRouting = r.advisoryAiRouting;
+        const validated = normalizeAdvisoryAiRoutingConfig(rawRouting, warnings);
+        const sparseRouting = {};
+        if (typeof rawRouting.slop === "boolean")
+            sparseRouting.slop = validated.slop;
+        if (typeof rawRouting.e2eTestGen === "boolean")
+            sparseRouting.e2eTestGen = validated.e2eTestGen;
+        if (typeof rawRouting.planner === "boolean")
+            sparseRouting.planner = validated.planner;
+        if (typeof rawRouting.summaries === "boolean")
+            sparseRouting.summaries = validated.summaries;
+        if (typeof rawRouting.chatQa === "boolean")
+            sparseRouting.chatQa = validated.chatQa;
+        if (typeof rawRouting.chatQaFrontierFallback === "boolean")
+            sparseRouting.chatQaFrontierFallback = validated.chatQaFrontierFallback;
+        if (typeof rawRouting.intentRouting === "boolean")
+            sparseRouting.intentRouting = validated.intentRouting;
+        out.advisoryAiRouting = sparseRouting;
+    }
+    else if (r.advisoryAiRouting !== undefined) {
+        warnings.push(`Manifest "settings.advisoryAiRouting" must be an object; ignoring it and keeping any existing policy.`);
+    }
+    // Contributor blacklist (#1425): `settings.contributorBlacklist` is a list of banned-login entries. Only set it
+    // when at least one VALID entry survives normalization, so a malformed block never blanks the DB-configured
+    // list via the resolver's `{...dbSettings, ...manifest.settings}` overlay. Normalization warnings are folded in.
+    if (r.contributorBlacklist !== undefined) {
+        const { entries, warnings: blacklistWarnings } = normalizeContributorBlacklist(r.contributorBlacklist);
+        warnings.push(...blacklistWarnings);
+        if (entries.length > 0)
+            out.contributorBlacklist = entries;
+    }
+    // Per-contributor open PR/issue caps (#2270): discrete counts, not scores — reuse the same positive-integer
+    // shape as contentLane.maxAppendedEntries so a fractional/non-positive typo is dropped with a warning
+    // instead of configuring a nonsensical cap. Valid counts clamp to the fixed live-verification budget. UNLIKE
+    // contributorBlacklist above, an explicit yml `null` here is
+    // load-bearing (not the same as omitting the key): the documented `yml > DB > null` precedence means a
+    // maintainer must be able to force a DB-configured cap back to "no cap" via `.gittensory.yml` without deleting
+    // the DB row. `normalizeOptionalPositiveInteger` collapses "absent" and "null" to the same silent `null`
+    // return, so that distinction has to be made HERE, before calling it: a literal `null` sets the key to `null`
+    // (clears); omitted (`undefined`) leaves the key unset (preserves the DB value via the resolver's spread); an
+    // invalid non-null value (fractional/non-positive/wrong type) warns and also leaves the key unset.
+    if (r.contributorOpenPrCap === null) {
+        out.contributorOpenPrCap = null;
+    }
+    else {
+        const contributorOpenPrCap = normalizeOptionalContributorOpenItemCap(r.contributorOpenPrCap, "settings.contributorOpenPrCap", warnings);
+        if (contributorOpenPrCap !== null)
+            out.contributorOpenPrCap = contributorOpenPrCap;
+    }
+    if (r.contributorOpenIssueCap === null) {
+        out.contributorOpenIssueCap = null;
+    }
+    else {
+        const contributorOpenIssueCap = normalizeOptionalContributorOpenItemCap(r.contributorOpenIssueCap, "settings.contributorOpenIssueCap", warnings);
+        if (contributorOpenIssueCap !== null)
+            out.contributorOpenIssueCap = contributorOpenIssueCap;
+    }
+    // #label-scoping: same load-bearing-null idiom as blacklistLabel above.
+    if (r.contributorCapLabel === null) {
+        out.contributorCapLabel = null;
+    }
+    else {
+        const contributorCapLabel = normalizeOptionalString(r.contributorCapLabel, "settings.contributorCapLabel", warnings);
+        if (contributorCapLabel !== null)
+            out.contributorCapLabel = contributorCapLabel;
+    }
+    // CI-run cancellation on a contributor_cap close (#2462): an explicit yml `null` is load-bearing (clears a
+    // DB-configured value back to "unset", falling through to the CONTRIBUTOR_CAP_CANCEL_CI_DEFAULT env var),
+    // matching contributorOpenPrCap's own null-vs-omitted distinction above.
+    if (r.contributorCapCancelCi === null) {
+        out.contributorCapCancelCi = null;
+    }
+    else {
+        const contributorCapCancelCi = normalizeOptionalBoolean(r.contributorCapCancelCi, "settings.contributorCapCancelCi", warnings);
+        if (contributorCapCancelCi !== null)
+            out.contributorCapCancelCi = contributorCapCancelCi;
+    }
+    // Review-request nagging cooldown (#2463): throttle a contributor repeatedly pinging @gittensory for review.
+    const reviewNagPolicy = normalizeOptionalEnum(r.reviewNagPolicy, "settings.reviewNagPolicy", ["off", "hold", "close"], warnings);
+    if (reviewNagPolicy !== null)
+        out.reviewNagPolicy = reviewNagPolicy;
+    const reviewNagMaxPings = normalizeOptionalPositiveInteger(r.reviewNagMaxPings, "settings.reviewNagMaxPings", warnings);
+    if (reviewNagMaxPings !== null)
+        out.reviewNagMaxPings = reviewNagMaxPings;
+    const reviewNagCooldownDays = normalizeOptionalPositiveInteger(r.reviewNagCooldownDays, "settings.reviewNagCooldownDays", warnings);
+    if (reviewNagCooldownDays !== null && reviewNagCooldownDays <= MAX_REVIEW_NAG_COOLDOWN_DAYS)
+        out.reviewNagCooldownDays = reviewNagCooldownDays;
+    if (reviewNagCooldownDays !== null && reviewNagCooldownDays > MAX_REVIEW_NAG_COOLDOWN_DAYS) {
+        warnings.push(`Manifest field "settings.reviewNagCooldownDays" must be at most ${MAX_REVIEW_NAG_COOLDOWN_DAYS}; ignoring it.`);
+    }
+    // #label-scoping: same load-bearing-null idiom as blacklistLabel above.
+    if (r.reviewNagLabel === null) {
+        out.reviewNagLabel = null;
+    }
+    else {
+        const reviewNagLabel = normalizeOptionalString(r.reviewNagLabel, "settings.reviewNagLabel", warnings);
+        if (reviewNagLabel !== null)
+            out.reviewNagLabel = reviewNagLabel;
+    }
+    // Maintainer-mention nag moderation (#label-scoping): GitHub logins ALSO throttled under the review-nag
+    // cooldown above, on top of the bot's own @gittensory handle. Only set it when at least one VALID login
+    // survives normalization, so a malformed block never blanks the DB-configured list via the resolver's
+    // `{...dbSettings, ...manifest.settings}` overlay (same reasoning as autoCloseExemptLogins below).
+    if (r.reviewNagMonitoredMentions !== undefined) {
+        const { logins: monitoredMentions, warnings: monitoredMentionWarnings } = normalizeAutoCloseExemptLogins(r.reviewNagMonitoredMentions);
+        warnings.push(...monitoredMentionWarnings);
+        if (monitoredMentions.length > 0)
+            out.reviewNagMonitoredMentions = monitoredMentions;
+    }
+    // Shared repo-scoped exemption list (#2463): only set it when at least one VALID login survives
+    // normalization, so a malformed block never blanks the DB-configured list via the resolver's overlay.
+    if (r.autoCloseExemptLogins !== undefined) {
+        const { logins, warnings: exemptWarnings } = normalizeAutoCloseExemptLogins(r.autoCloseExemptLogins);
+        warnings.push(...exemptWarnings);
+        if (logins.length > 0)
+            out.autoCloseExemptLogins = logins;
+    }
+    // Hard manual-review guardrails are config-as-code only. Arrays replace lower layers wholesale, so only an
+    // explicit [] or a non-empty valid list replaces a private global setting. Null/malformed values are ignored
+    // instead of clearing.
+    if (Array.isArray(r.hardGuardrailGlobs)) {
+        const hardGuardrailGlobs = normalizeStringList(r.hardGuardrailGlobs, "settings.hardGuardrailGlobs", warnings);
+        if (r.hardGuardrailGlobs.length === 0 || hardGuardrailGlobs.length > 0) {
+            out.hardGuardrailGlobs = hardGuardrailGlobs;
+        }
+        else {
+            warnings.push(`Manifest "settings.hardGuardrailGlobs" did not contain any valid path globs; ignoring it and keeping any existing guardrails.`);
+        }
+    }
+    else if (r.hardGuardrailGlobs !== undefined) {
+        warnings.push(`Manifest "settings.hardGuardrailGlobs" must be an array of path globs; ignoring it and keeping any existing guardrails.`);
+    }
+    // Manual-review label is deliberately separate from review_state_label so operators can use one hold label
+    // without enabling the old ready/changes disposition labels. Null disables only the label, not the hold.
+    if (r.manualReviewLabel === null) {
+        out.manualReviewLabel = null;
+    }
+    else {
+        const manualReviewLabel = normalizeOptionalString(r.manualReviewLabel, "settings.manualReviewLabel", warnings);
+        if (manualReviewLabel !== null)
+            out.manualReviewLabel = manualReviewLabel;
+    }
+    if (r.readyToMergeLabel === null) {
+        out.readyToMergeLabel = null;
+    }
+    else {
+        const readyToMergeLabel = normalizeOptionalString(r.readyToMergeLabel, "settings.readyToMergeLabel", warnings);
+        if (readyToMergeLabel !== null)
+            out.readyToMergeLabel = readyToMergeLabel;
+    }
+    if (r.changesRequestedLabel === null) {
+        out.changesRequestedLabel = null;
+    }
+    else {
+        const changesRequestedLabel = normalizeOptionalString(r.changesRequestedLabel, "settings.changesRequestedLabel", warnings);
+        if (changesRequestedLabel !== null)
+            out.changesRequestedLabel = changesRequestedLabel;
+    }
+    if (r.migrationCollisionLabel === null) {
+        out.migrationCollisionLabel = null;
+    }
+    else {
+        const migrationCollisionLabel = normalizeOptionalString(r.migrationCollisionLabel, "settings.migrationCollisionLabel", warnings);
+        if (migrationCollisionLabel !== null)
+            out.migrationCollisionLabel = migrationCollisionLabel;
+    }
+    if (r.pendingClosureLabel === null) {
+        out.pendingClosureLabel = null;
+    }
+    else {
+        const pendingClosureLabel = normalizeOptionalString(r.pendingClosureLabel, "settings.pendingClosureLabel", warnings);
+        if (pendingClosureLabel !== null)
+            out.pendingClosureLabel = pendingClosureLabel;
+    }
+    // Account-age throttle (#2561): an explicit yml `null` is load-bearing (clears a DB-configured threshold
+    // back to "off"), matching contributorOpenPrCap's own null-vs-omitted distinction above.
+    if (r.accountAgeThresholdDays === null) {
+        out.accountAgeThresholdDays = null;
+    }
+    else {
+        const accountAgeThresholdDays = normalizeOptionalPositiveInteger(r.accountAgeThresholdDays, "settings.accountAgeThresholdDays", warnings);
+        if (accountAgeThresholdDays !== null)
+            out.accountAgeThresholdDays = accountAgeThresholdDays;
+    }
+    const newAccountLabel = normalizeOptionalString(r.newAccountLabel, "settings.newAccountLabel", warnings);
+    if (newAccountLabel !== null)
+        out.newAccountLabel = newAccountLabel;
+    // Per-command @gittensory rate limit (#2560): generalizes review-nag's cooldown pattern to every command.
+    const commandRateLimitPolicy = normalizeOptionalEnum(r.commandRateLimitPolicy, "settings.commandRateLimitPolicy", ["off", "hold"], warnings);
+    if (commandRateLimitPolicy !== null)
+        out.commandRateLimitPolicy = commandRateLimitPolicy;
+    const commandRateLimitMaxPerWindow = normalizeOptionalPositiveInteger(r.commandRateLimitMaxPerWindow, "settings.commandRateLimitMaxPerWindow", warnings);
+    if (commandRateLimitMaxPerWindow !== null)
+        out.commandRateLimitMaxPerWindow = commandRateLimitMaxPerWindow;
+    const commandRateLimitAiMaxPerWindow = normalizeOptionalPositiveInteger(r.commandRateLimitAiMaxPerWindow, "settings.commandRateLimitAiMaxPerWindow", warnings);
+    if (commandRateLimitAiMaxPerWindow !== null)
+        out.commandRateLimitAiMaxPerWindow = commandRateLimitAiMaxPerWindow;
+    const commandRateLimitWindowHours = normalizeOptionalPositiveInteger(r.commandRateLimitWindowHours, "settings.commandRateLimitWindowHours", warnings);
+    if (commandRateLimitWindowHours !== null)
+        out.commandRateLimitWindowHours = commandRateLimitWindowHours;
+    // Moderation-rules engine (#selfhost-mod-engine): per-repo override of the global moderation config.
+    const moderationGateMode = normalizeOptionalEnum(r.moderationGateMode, "settings.moderationGateMode", ["inherit", "off", "enabled"], warnings);
+    if (moderationGateMode !== null)
+        out.moderationGateMode = moderationGateMode;
+    // #gate-flagged: normalizeModerationRules returns an EMPTY rules array for two semantically different
+    // inputs -- a genuinely empty yml list (`moderationRules: []`, an intentional "opt every rule out for this
+    // repo") and a MALFORMED one (a non-array, or an array where every entry fails validation) that degrades to
+    // empty as its safe fallback. Applying the malformed case as an override would silently disable every rule
+    // for this repo instead of leaving the DB-configured value intact, so the two must be told apart by the RAW
+    // input's own shape -- not just the normalized result -- before assigning. A PARTIAL list (some valid, some
+    // invalid entries) still applies the surviving valid subset, mirroring autoCloseExemptLogins' behavior.
+    if (r.moderationRules !== undefined) {
+        const { rules, warnings: moderationRuleWarnings } = normalizeModerationRules(r.moderationRules);
+        warnings.push(...moderationRuleWarnings);
+        const intentionalEmptyList = Array.isArray(r.moderationRules) && r.moderationRules.length === 0;
+        if (rules.length > 0 || intentionalEmptyList)
+            out.moderationRules = rules;
+    }
+    const moderationWarningLabel = normalizeModerationLabel(r.moderationWarningLabel);
+    if (moderationWarningLabel !== undefined)
+        out.moderationWarningLabel = moderationWarningLabel;
+    const moderationBannedLabel = normalizeModerationLabel(r.moderationBannedLabel);
+    if (moderationBannedLabel !== undefined)
+        out.moderationBannedLabel = moderationBannedLabel;
+    // Review-evasion protection (#review-evasion-protection): a contributor closing/converting-to-draft their
+    // own PR while gittensory has an active review pass running is dodging the one-shot review.
+    const reviewEvasionProtection = normalizeOptionalEnum(r.reviewEvasionProtection, "settings.reviewEvasionProtection", ["off", "close"], warnings);
+    if (reviewEvasionProtection !== null)
+        out.reviewEvasionProtection = reviewEvasionProtection;
+    // #label-scoping: same load-bearing-null idiom as blacklistLabel above.
+    if (r.reviewEvasionLabel === null) {
+        out.reviewEvasionLabel = null;
+    }
+    else {
+        const reviewEvasionLabel = normalizeOptionalString(r.reviewEvasionLabel, "settings.reviewEvasionLabel", warnings);
+        if (reviewEvasionLabel !== null)
+            out.reviewEvasionLabel = reviewEvasionLabel;
+    }
+    const reviewEvasionComment = normalizeOptionalBoolean(r.reviewEvasionComment, "settings.reviewEvasionComment", warnings);
+    if (reviewEvasionComment !== null)
+        out.reviewEvasionComment = reviewEvasionComment;
+    const mergeTrainMode = normalizeOptionalEnum(r.mergeTrainMode, "settings.mergeTrainMode", ["off", "audit", "enforce"], warnings);
+    if (mergeTrainMode !== null)
+        out.mergeTrainMode = mergeTrainMode;
+    return out;
+}
+/** Serialize the settings override for the cache round-trip; returns null when nothing is set. */
+export function settingsOverrideToJson(settings) {
+    if (Object.keys(settings).length === 0)
+        return null;
+    return { ...settings };
+}
+/** A bounded, PUBLIC-SAFE maintainer string (footer/note). Trimmed, length-capped, and rejected with a
+ *  warning if it contains any forbidden public term — it is then dropped, never published. */
+function parsePublicSafeText(value, field, warnings) {
+    const text = normalizeOptionalString(value, field, warnings);
+    if (text === null)
+        return null;
+    const bounded = text.length > MAX_ITEM_LENGTH ? text.slice(0, MAX_ITEM_LENGTH) : text;
+    if (!isFocusManifestPublicSafe(bounded)) {
+        warnings.push(`Manifest "${field}" contains content that is not public-safe; ignoring it.`);
+        return null;
+    }
+    return bounded;
+}
+/**
+ * Parse the optional `review:` block — maintainer overrides for the public review-panel content. Never
+ * throws; invalid/unsafe values are dropped with warnings.
+ */
+function parseReviewConfig(value, warnings) {
+    const empty = { present: false, footerText: null, note: null, fields: {}, enrichmentAnalyzers: {}, profile: null, tone: null, securityFocus: null, inlineComments: null, fixHandoff: null, autoMergeSummary: null, suggestions: null, changedFilesSummary: null, effortScore: null, impactMap: null, cultureProfile: null, selftune: null, reviewMemory: null, findingCategories: null, inlineCommentsPerCategory: null, minFindingSeverity: null, maxFindings: { ...EMPTY_MAX_FINDINGS_CONFIG }, commentVerbosity: null, e2eTestDelivery: null, e2eTestAutoTrigger: null, pathInstructions: [], instructions: null, excludePaths: [], pathFilters: [], preMergeChecks: [], autoReview: { ...EMPTY_AUTO_REVIEW_CONFIG }, aiModel: { ...EMPTY_SELF_HOST_AI_MODEL_CONFIG }, visual: { ...EMPTY_VISUAL_CONFIG }, linkedIssueSatisfaction: null, sharedConfigSource: null };
+    if (value === undefined || value === null)
+        return empty;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push(`Manifest field "review" must be a mapping; ignoring it.`);
+        return empty;
+    }
+    const r = value;
+    const footerRecord = r.footer !== null && typeof r.footer === "object" && !Array.isArray(r.footer) ? r.footer : undefined;
+    if (r.footer !== undefined && r.footer !== null && footerRecord === undefined)
+        warnings.push(`Manifest "review.footer" must be a mapping; ignoring it.`);
+    const fieldsRecord = r.fields !== null && typeof r.fields === "object" && !Array.isArray(r.fields) ? r.fields : undefined;
+    if (r.fields !== undefined && r.fields !== null && fieldsRecord === undefined)
+        warnings.push(`Manifest "review.fields" must be a mapping; ignoring it.`);
+    const fields = {};
+    if (fieldsRecord) {
+        for (const key of REVIEW_FIELD_KEYS) {
+            const flag = normalizeOptionalBoolean(fieldsRecord[key], `review.fields.${key}`, warnings);
+            if (flag !== null)
+                fields[key] = flag;
+        }
+    }
+    const enrichmentRecord = r.enrichment !== null && typeof r.enrichment === "object" && !Array.isArray(r.enrichment) ? r.enrichment : undefined;
+    if (r.enrichment !== undefined && r.enrichment !== null && enrichmentRecord === undefined)
+        warnings.push(`Manifest "review.enrichment" must be a mapping; ignoring it.`);
+    const enrichmentAnalyzers = {};
+    if (enrichmentRecord) {
+        for (const key of Object.keys(enrichmentRecord)) {
+            if (!REES_ANALYZER_NAME_SET.has(key)) {
+                warnings.push(`Manifest "review.enrichment" has unknown analyzer "${key}"; ignoring it.`);
+                continue;
+            }
+            const flag = normalizeOptionalBoolean(enrichmentRecord[key], `review.enrichment.${key}`, warnings);
+            if (flag !== null)
+                enrichmentAnalyzers[key] = flag;
+        }
+    }
+    const footerText = footerRecord ? parsePublicSafeText(footerRecord.text, "review.footer.text", warnings) : null;
+    const note = parsePublicSafeText(r.note, "review.note", warnings);
+    const profile = parseReviewProfile(r.profile, warnings);
+    const tone = parsePublicSafeText(r.tone, "review.tone", warnings);
+    const securityFocus = normalizeOptionalBoolean(r.security_focus, "review.security_focus", warnings);
+    const inlineComments = normalizeOptionalBoolean(r.inline_comments, "review.inline_comments", warnings);
+    const fixHandoff = normalizeOptionalBoolean(r.fixHandoff, "review.fixHandoff", warnings);
+    const autoMergeSummary = normalizeOptionalBoolean(r.auto_merge_summary, "review.auto_merge_summary", warnings);
+    const suggestions = normalizeOptionalBoolean(r.suggestions, "review.suggestions", warnings);
+    const changedFilesSummary = normalizeOptionalBoolean(r.changed_files_summary, "review.changed_files_summary", warnings);
+    const effortScore = normalizeOptionalBoolean(r.effort_score, "review.effort_score", warnings);
+    const impactMap = normalizeOptionalBoolean(r.impact_map, "review.impact_map", warnings);
+    const cultureProfile = normalizeOptionalBoolean(r.culture_profile, "review.culture_profile", warnings);
+    const selftune = normalizeOptionalBoolean(r.selftune, "review.selftune", warnings);
+    const reviewMemory = normalizeOptionalBoolean(r.memory, "review.memory", warnings);
+    const findingCategories = normalizeOptionalBoolean(r.finding_categories, "review.finding_categories", warnings);
+    const inlineCommentsPerCategory = normalizeOptionalNonNegativeInt(r.inline_comments_per_category, "review.inline_comments_per_category", warnings);
+    const minFindingSeverity = normalizeOptionalEnum(r.min_finding_severity, "review.min_finding_severity", REVIEW_FINDING_SEVERITY_LADDER, warnings);
+    const maxFindings = parseMaxFindingsConfig(r.max_findings, warnings);
+    const commentVerbosity = normalizeOptionalEnum(r.comment_verbosity, "review.comment_verbosity", COMMENT_VERBOSITY_LEVELS, warnings);
+    const e2eTestDelivery = normalizeOptionalEnum(r.e2e_test_delivery, "review.e2e_test_delivery", E2E_TEST_DELIVERY_MODES, warnings);
+    const e2eTestAutoTrigger = normalizeOptionalBoolean(r.e2e_test_auto_trigger, "review.e2e_test_auto_trigger", warnings);
+    const pathInstructions = parseReviewPathInstructions(r.path_instructions, warnings);
+    const instructions = parsePublicSafeText(r.instructions, "review.instructions", warnings);
+    const excludePaths = parseReviewExcludePaths(r.exclude_paths, warnings);
+    const pathFilters = parseReviewPathFilters(r.path_filters, warnings);
+    const preMergeChecks = parseReviewPreMergeChecks(r.pre_merge_checks, warnings);
+    const autoReview = parseAutoReviewConfig(r.auto_review, warnings);
+    const aiModel = parseSelfHostAiModelConfig(r.ai_model, warnings);
+    const visual = parseVisualConfig(r.visual, warnings);
+    const linkedIssueSatisfaction = normalizeOptionalEnum(r.linkedIssueSatisfaction, "review.linkedIssueSatisfaction", LINKED_ISSUE_SATISFACTION_MODES, warnings);
+    return {
+        present: footerText !== null ||
+            note !== null ||
+            profile !== null ||
+            tone !== null ||
+            securityFocus !== null ||
+            inlineComments !== null ||
+            fixHandoff !== null ||
+            autoMergeSummary !== null ||
+            suggestions !== null ||
+            changedFilesSummary !== null ||
+            effortScore !== null ||
+            impactMap !== null ||
+            cultureProfile !== null ||
+            selftune !== null ||
+            reviewMemory !== null ||
+            findingCategories !== null ||
+            inlineCommentsPerCategory !== null ||
+            minFindingSeverity !== null ||
+            maxFindingsPresent(maxFindings) ||
+            commentVerbosity !== null ||
+            e2eTestDelivery !== null ||
+            e2eTestAutoTrigger !== null ||
+            pathInstructions.length > 0 ||
+            instructions !== null ||
+            excludePaths.length > 0 ||
+            pathFilters.length > 0 ||
+            preMergeChecks.length > 0 ||
+            autoReviewPresent(autoReview) ||
+            selfHostAiModelPresent(aiModel) ||
+            visualConfigPresent(visual) ||
+            linkedIssueSatisfaction !== null ||
+            Object.keys(fields).length > 0 ||
+            Object.keys(enrichmentAnalyzers).length > 0,
+        footerText,
+        note,
+        fields,
+        autoReview,
+        aiModel,
+        visual,
+        linkedIssueSatisfaction,
+        enrichmentAnalyzers,
+        profile,
+        tone,
+        securityFocus,
+        inlineComments,
+        fixHandoff,
+        autoMergeSummary,
+        suggestions,
+        changedFilesSummary,
+        effortScore,
+        impactMap,
+        cultureProfile,
+        selftune,
+        reviewMemory,
+        findingCategories,
+        inlineCommentsPerCategory,
+        minFindingSeverity,
+        maxFindings,
+        commentVerbosity,
+        e2eTestDelivery,
+        e2eTestAutoTrigger,
+        pathInstructions,
+        instructions,
+        excludePaths,
+        pathFilters,
+        preMergeChecks,
+        sharedConfigSource: null,
+    };
+}
+function pickOverlayNullable(override, base) {
+    return override !== null ? override : base;
+}
+function pickOverlayStringList(override, base) {
+    return override.length > 0 ? [...override] : [...base];
+}
+function pickOverlayPartialRecord(override, base) {
+    return { ...base, ...override };
+}
+function overlayMaxFindingsConfig(base, override) {
+    return {
+        blockers: pickOverlayNullable(override.blockers, base.blockers),
+        nits: pickOverlayNullable(override.nits, base.nits),
+    };
+}
+function overlayAutoReviewConfig(base, override) {
+    return {
+        skipDrafts: pickOverlayNullable(override.skipDrafts, base.skipDrafts),
+        cadence: pickOverlayNullable(override.cadence, base.cadence),
+        ignoreAuthors: pickOverlayStringList(override.ignoreAuthors, base.ignoreAuthors),
+        ignoreTitleKeywords: pickOverlayStringList(override.ignoreTitleKeywords, base.ignoreTitleKeywords),
+        skipLabels: pickOverlayStringList(override.skipLabels, base.skipLabels),
+        skipDocsOnly: pickOverlayNullable(override.skipDocsOnly, base.skipDocsOnly),
+        maxAddedLines: override.maxAddedLines > 0 ? override.maxAddedLines : base.maxAddedLines,
+        maxFiles: override.maxFiles > 0 ? override.maxFiles : base.maxFiles,
+        baseBranches: pickOverlayStringList(override.baseBranches, base.baseBranches),
+        autoPauseAfterReviewedCommits: pickOverlayNullable(override.autoPauseAfterReviewedCommits, base.autoPauseAfterReviewedCommits),
+    };
+}
+function overlaySelfHostAiModelConfig(base, override) {
+    return {
+        claudeModel: pickOverlayNullable(override.claudeModel, base.claudeModel),
+        claudeEffort: pickOverlayNullable(override.claudeEffort, base.claudeEffort),
+        codexModel: pickOverlayNullable(override.codexModel, base.codexModel),
+        codexEffort: pickOverlayNullable(override.codexEffort, base.codexEffort),
+        ollamaModel: pickOverlayNullable(override.ollamaModel, base.ollamaModel),
+        openaiModel: pickOverlayNullable(override.openaiModel, base.openaiModel),
+        openaiCompatibleModel: pickOverlayNullable(override.openaiCompatibleModel, base.openaiCompatibleModel),
+        anthropicModel: pickOverlayNullable(override.anthropicModel, base.anthropicModel),
+    };
+}
+function overlayVisualConfig(base, override) {
+    return {
+        productionUrl: pickOverlayNullable(override.productionUrl, base.productionUrl),
+        preview: { urlTemplate: pickOverlayNullable(override.preview.urlTemplate, base.preview.urlTemplate) },
+        routes: {
+            paths: pickOverlayStringList(override.routes.paths, base.routes.paths),
+            maxRoutes: pickOverlayNullable(override.routes.maxRoutes, base.routes.maxRoutes),
+        },
+        themes: override.themes.length > 0 ? [...override.themes] : [...base.themes],
+        gif: override.gif ? override.gif : base.gif,
+        enabled: pickOverlayNullable(override.enabled, base.enabled),
+        themeStorageKey: pickOverlayNullable(override.themeStorageKey, base.themeStorageKey),
+        actionsFallback: override.actionsFallback ? override.actionsFallback : base.actionsFallback,
+    };
+}
+function computeReviewConfigPresent(review) {
+    return (review.footerText !== null ||
+        review.note !== null ||
+        review.profile !== null ||
+        review.tone !== null ||
+        review.securityFocus !== null ||
+        review.inlineComments !== null ||
+        review.fixHandoff !== null ||
+        review.autoMergeSummary !== null ||
+        review.suggestions !== null ||
+        review.changedFilesSummary !== null ||
+        review.effortScore !== null ||
+        review.impactMap !== null ||
+        review.cultureProfile !== null ||
+        review.selftune !== null ||
+        review.reviewMemory !== null ||
+        review.findingCategories !== null ||
+        review.inlineCommentsPerCategory !== null ||
+        review.minFindingSeverity !== null ||
+        maxFindingsPresent(review.maxFindings) ||
+        review.commentVerbosity !== null ||
+        review.e2eTestDelivery !== null ||
+        review.e2eTestAutoTrigger !== null ||
+        review.pathInstructions.length > 0 ||
+        review.instructions !== null ||
+        review.excludePaths.length > 0 ||
+        review.pathFilters.length > 0 ||
+        review.preMergeChecks.length > 0 ||
+        autoReviewPresent(review.autoReview) ||
+        selfHostAiModelPresent(review.aiModel) ||
+        visualConfigPresent(review.visual) ||
+        review.linkedIssueSatisfaction !== null ||
+        Object.keys(review.fields).length > 0 ||
+        Object.keys(review.enrichmentAnalyzers).length > 0);
+}
+/** Overlay a higher-priority `review:` config onto a shared/base layer (#2046). Per-field: override wins when set;
+ *  base fills gaps; defaults stay byte-identical. `sharedConfigSource` on the override is preserved when present. */
+export function overlayReviewConfig(base, override) {
+    const merged = {
+        footerText: pickOverlayNullable(override.footerText, base.footerText),
+        note: pickOverlayNullable(override.note, base.note),
+        fields: pickOverlayPartialRecord(override.fields, base.fields),
+        enrichmentAnalyzers: pickOverlayPartialRecord(override.enrichmentAnalyzers, base.enrichmentAnalyzers),
+        profile: pickOverlayNullable(override.profile, base.profile),
+        tone: pickOverlayNullable(override.tone, base.tone),
+        securityFocus: pickOverlayNullable(override.securityFocus, base.securityFocus),
+        inlineComments: pickOverlayNullable(override.inlineComments, base.inlineComments),
+        fixHandoff: pickOverlayNullable(override.fixHandoff, base.fixHandoff),
+        autoMergeSummary: pickOverlayNullable(override.autoMergeSummary, base.autoMergeSummary),
+        suggestions: pickOverlayNullable(override.suggestions, base.suggestions),
+        changedFilesSummary: pickOverlayNullable(override.changedFilesSummary, base.changedFilesSummary),
+        effortScore: pickOverlayNullable(override.effortScore, base.effortScore),
+        impactMap: pickOverlayNullable(override.impactMap, base.impactMap),
+        cultureProfile: pickOverlayNullable(override.cultureProfile, base.cultureProfile),
+        selftune: pickOverlayNullable(override.selftune, base.selftune),
+        reviewMemory: pickOverlayNullable(override.reviewMemory, base.reviewMemory),
+        findingCategories: pickOverlayNullable(override.findingCategories, base.findingCategories),
+        inlineCommentsPerCategory: pickOverlayNullable(override.inlineCommentsPerCategory, base.inlineCommentsPerCategory),
+        minFindingSeverity: pickOverlayNullable(override.minFindingSeverity, base.minFindingSeverity),
+        maxFindings: overlayMaxFindingsConfig(base.maxFindings, override.maxFindings),
+        commentVerbosity: pickOverlayNullable(override.commentVerbosity, base.commentVerbosity),
+        e2eTestDelivery: pickOverlayNullable(override.e2eTestDelivery, base.e2eTestDelivery),
+        e2eTestAutoTrigger: pickOverlayNullable(override.e2eTestAutoTrigger, base.e2eTestAutoTrigger),
+        pathInstructions: override.pathInstructions.length > 0 ? [...override.pathInstructions] : [...base.pathInstructions],
+        instructions: pickOverlayNullable(override.instructions, base.instructions),
+        excludePaths: pickOverlayStringList(override.excludePaths, base.excludePaths),
+        pathFilters: pickOverlayStringList(override.pathFilters, base.pathFilters),
+        preMergeChecks: override.preMergeChecks.length > 0 ? [...override.preMergeChecks] : [...base.preMergeChecks],
+        autoReview: overlayAutoReviewConfig(base.autoReview, override.autoReview),
+        aiModel: overlaySelfHostAiModelConfig(base.aiModel, override.aiModel),
+        visual: overlayVisualConfig(base.visual, override.visual),
+        linkedIssueSatisfaction: pickOverlayNullable(override.linkedIssueSatisfaction, base.linkedIssueSatisfaction),
+        sharedConfigSource: override.sharedConfigSource ?? base.sharedConfigSource,
+        present: false,
+    };
+    merged.present = computeReviewConfigPresent(merged);
+    return merged;
+}
+/** Parse a raw `review:` mapping value. Exported for the private-config shared overlay (#2046). */
+export function parseReviewConfigMapping(value, warnings) {
+    return parseReviewConfig(value, warnings);
+}
+function maxFindingsPresent(config) {
+    return config.blockers !== null || config.nits !== null;
+}
+/** Parse `review.max_findings` — optional non-negative caps for blockers/nits display in the unified comment. */
+function parseMaxFindingsConfig(value, warnings) {
+    if (value === undefined || value === null)
+        return { ...EMPTY_MAX_FINDINGS_CONFIG };
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push(`Manifest "review.max_findings" must be a mapping; ignoring it.`);
+        return { ...EMPTY_MAX_FINDINGS_CONFIG };
+    }
+    const record = value;
+    return {
+        blockers: normalizeOptionalNonNegativeInt(record.blockers, "review.max_findings.blockers", warnings),
+        nits: normalizeOptionalNonNegativeInt(record.nits, "review.max_findings.nits", warnings),
+    };
+}
+function autoReviewPresent(config) {
+    return (config.skipDrafts !== null ||
+        config.cadence !== null ||
+        config.ignoreAuthors.length > 0 ||
+        config.ignoreTitleKeywords.length > 0 ||
+        config.skipLabels.length > 0 ||
+        config.skipDocsOnly !== null ||
+        config.maxAddedLines > 0 ||
+        config.maxFiles > 0 ||
+        config.baseBranches.length > 0 ||
+        config.autoPauseAfterReviewedCommits !== null);
+}
+/** Parse `review.auto_review` — deterministic AI review eligibility filters. (#1954 / #2038–#2041) */
+function parseAutoReviewConfig(value, warnings) {
+    if (value === undefined || value === null)
+        return { ...EMPTY_AUTO_REVIEW_CONFIG };
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push(`Manifest field "review.auto_review" must be a mapping; ignoring it.`);
+        return { ...EMPTY_AUTO_REVIEW_CONFIG };
+    }
+    const record = value;
+    return {
+        skipDrafts: normalizeOptionalBoolean(record.skip_drafts, "review.auto_review.skip_drafts", warnings),
+        cadence: normalizeOptionalEnum(record.cadence, "review.auto_review.cadence", AI_REVIEW_CADENCES, warnings),
+        ignoreAuthors: parseManifestGlobList(record.ignore_authors, "review.auto_review.ignore_authors", warnings),
+        ignoreTitleKeywords: parseAutoReviewTitleKeywords(record.ignore_title_keywords, warnings),
+        skipLabels: parseAutoReviewSkipLabels(record.skip_labels, warnings),
+        skipDocsOnly: normalizeOptionalBoolean(record.skip_docs_only, "review.auto_review.skip_docs_only", warnings),
+        maxAddedLines: normalizeAutoReviewSizeCap(record.max_added_lines, "review.auto_review.max_added_lines", warnings),
+        maxFiles: normalizeAutoReviewSizeCap(record.max_files, "review.auto_review.max_files", warnings),
+        baseBranches: parseManifestGlobList(record.base_branches, "review.auto_review.base_branches", warnings),
+        autoPauseAfterReviewedCommits: normalizeOptionalNonNegativeInt(record.auto_pause_after_reviewed_commits, "review.auto_review.auto_pause_after_reviewed_commits", warnings),
+    };
+}
+function selfHostAiModelPresent(config) {
+    return (config.claudeModel !== null ||
+        config.claudeEffort !== null ||
+        config.codexModel !== null ||
+        config.codexEffort !== null ||
+        config.ollamaModel !== null ||
+        config.openaiModel !== null ||
+        config.openaiCompatibleModel !== null ||
+        config.anthropicModel !== null);
+}
+/** Parse `review.ai_model` — per-repo self-host reviewer model/effort overrides. Values are opaque, bounded,
+ *  public-safe strings (like `review.tone`) — never validated against a fixed model/effort enum here, so this
+ *  parser never drifts from the provider's own effort allowlist (`src/selfhost/ai.ts`); an invalid effort value
+ *  degrades the SAME way an invalid env-sourced one already does (falls back to "medium" at resolve time).
+ *  (#selfhost-ai-model-override) */
+function parseSelfHostAiModelConfig(value, warnings) {
+    if (value === undefined || value === null)
+        return { ...EMPTY_SELF_HOST_AI_MODEL_CONFIG };
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push(`Manifest field "review.ai_model" must be a mapping; ignoring it.`);
+        return { ...EMPTY_SELF_HOST_AI_MODEL_CONFIG };
+    }
+    const record = value;
+    return {
+        claudeModel: parsePublicSafeText(record.claude_model, "review.ai_model.claude_model", warnings),
+        claudeEffort: parsePublicSafeText(record.claude_effort, "review.ai_model.claude_effort", warnings),
+        codexModel: parsePublicSafeText(record.codex_model, "review.ai_model.codex_model", warnings),
+        codexEffort: parsePublicSafeText(record.codex_effort, "review.ai_model.codex_effort", warnings),
+        ollamaModel: parsePublicSafeText(record.ollama_model, "review.ai_model.ollama_model", warnings),
+        openaiModel: parsePublicSafeText(record.openai_model, "review.ai_model.openai_model", warnings),
+        openaiCompatibleModel: parsePublicSafeText(record.openai_compatible_model, "review.ai_model.openai_compatible_model", warnings),
+        anthropicModel: parsePublicSafeText(record.anthropic_model, "review.ai_model.anthropic_model", warnings),
+    };
+}
+function visualConfigPresent(config) {
+    return (config.productionUrl !== null ||
+        config.preview.urlTemplate !== null ||
+        config.routes.paths.length > 0 ||
+        config.routes.maxRoutes !== null ||
+        config.themes.length > 0 ||
+        config.gif ||
+        config.enabled !== null ||
+        config.themeStorageKey !== null ||
+        config.actionsFallback);
+}
+const VISUAL_THEME_VALUES = ["light", "dark"];
+/** Parse `review.visual.themes` — which `prefers-color-scheme` variants to capture (#3678). Empty/default ⇒
+ *  the capture pipeline falls back to a single light-theme render, byte-identical to today. Unlike
+ *  `routes.paths` (an open-ended glob list), this is a closed 2-value enum, so entries are validated against
+ *  it directly rather than reusing the generic glob-list parser. */
+function parseVisualThemes(value, warnings) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        warnings.push(`Manifest "review.visual.themes" must be a list of "light"/"dark"; ignoring it.`);
+        return [];
+    }
+    const out = [];
+    for (const [index, entry] of value.entries()) {
+        const theme = typeof entry === "string" ? entry.trim().toLowerCase() : undefined;
+        if (!theme || !VISUAL_THEME_VALUES.includes(theme)) {
+            warnings.push(`Manifest "review.visual.themes[${index}]" must be "light" or "dark"; ignoring it.`);
+            continue;
+        }
+        if (!out.includes(theme))
+            out.push(theme);
+    }
+    return out;
+}
+// `{number}`/`{head_sha}`/`{head_sha_short}` are GitHub-controlled facts about the PR (never attacker-supplied
+// free text), so substitution itself carries no injection risk. The dummy values here exist only to make the
+// TEMPLATE STRING (which a maintainer authored, and could still typo) validate as a well-formed HTTPS URL
+// before it's ever used — see parseVisualUrlTemplate below.
+const VISUAL_URL_TEMPLATE_DUMMY_VARS = {
+    "{number}": "1",
+    "{head_sha_short}": "0000000",
+    "{head_sha}": "0000000000000000000000000000000000000000",
+};
+/** Parse `review.visual.production_url` — validated at CONFIG-READ time against the exact same SSRF guard
+ *  (`isSafeHttpUrl`) the renderer itself unconditionally applies to every URL it navigates to. Unlike
+ *  `preview.url_template`, this is a plain static origin with no `{number}`/`{head_sha}` placeholders to
+ *  substitute — the "before" shot is always the SAME production page, just at a different path per route. */
+function parseVisualProductionUrl(value, warnings) {
+    const url = parsePublicSafeText(value, "review.visual.production_url", warnings);
+    if (url === null)
+        return null;
+    if (!isSafeHttpUrl(url)) {
+        warnings.push(`Manifest "review.visual.production_url" must be a valid HTTPS URL targeting a public host; ignoring it.`);
+        return null;
+    }
+    return url;
+}
+/** Parse `review.visual.preview.url_template` — validated at CONFIG-READ time against the exact same SSRF
+ *  guard (`isSafeHttpUrl`) the renderer itself unconditionally applies to every URL it navigates to,
+ *  regardless of source (`src/review/visual/shot.ts`). This is deliberately redundant with that runtime
+ *  check, not a replacement for it — it exists so a maintainer sees a warning immediately for a malformed
+ *  template (e.g. a typo'd scheme, or an accidental internal host) instead of only discovering it later as
+ *  a silently-blank "after" cell. Placeholders are substituted with dummy values before validation since the
+ *  raw template (e.g. `https://pr-{number}.example.com`) is not itself a parseable URL. */
+function parseVisualUrlTemplate(value, warnings) {
+    const template = parsePublicSafeText(value, "review.visual.preview.url_template", warnings);
+    if (template === null)
+        return null;
+    let probe = template;
+    for (const [placeholder, dummy] of Object.entries(VISUAL_URL_TEMPLATE_DUMMY_VARS))
+        probe = probe.split(placeholder).join(dummy);
+    if (!isSafeHttpUrl(probe)) {
+        warnings.push(`Manifest "review.visual.preview.url_template" must be a valid HTTPS URL (with {number}/{head_sha}/{head_sha_short} placeholders substituted) targeting a public host; ignoring it.`);
+        return null;
+    }
+    return template;
+}
+/** Parse `review.visual` — per-repo before/after screenshot-capture config (#3609 preview / #3610 routes /
+ *  #3678 themes). */
+function parseVisualConfig(value, warnings) {
+    if (value === undefined || value === null)
+        return { ...EMPTY_VISUAL_CONFIG };
+    if (typeof value !== "object" || Array.isArray(value)) {
+        warnings.push(`Manifest field "review.visual" must be a mapping; ignoring it.`);
+        return { ...EMPTY_VISUAL_CONFIG };
+    }
+    const record = value;
+    const productionUrl = parseVisualProductionUrl(record.production_url, warnings);
+    const previewRecord = record.preview !== null && typeof record.preview === "object" && !Array.isArray(record.preview) ? record.preview : undefined;
+    if (record.preview !== undefined && record.preview !== null && previewRecord === undefined) {
+        warnings.push(`Manifest "review.visual.preview" must be a mapping; ignoring it.`);
+    }
+    const urlTemplate = previewRecord ? parseVisualUrlTemplate(previewRecord.url_template, warnings) : null;
+    const routesRecord = record.routes !== null && typeof record.routes === "object" && !Array.isArray(record.routes) ? record.routes : undefined;
+    if (record.routes !== undefined && record.routes !== null && routesRecord === undefined) {
+        warnings.push(`Manifest "review.visual.routes" must be a mapping; ignoring it.`);
+    }
+    const paths = routesRecord ? parseManifestGlobList(routesRecord.paths, "review.visual.routes.paths", warnings) : [];
+    const maxRoutes = routesRecord ? normalizeOptionalVisualMaxRoutes(routesRecord.max_routes, warnings) : null;
+    const themes = parseVisualThemes(record.themes, warnings);
+    const gif = normalizeOptionalBoolean(record.gif, "review.visual.gif", warnings) === true;
+    const enabled = normalizeOptionalBoolean(record.enabled, "review.visual.enabled", warnings);
+    const themeStorageKey = parsePublicSafeText(record.theme_storage_key, "review.visual.theme_storage_key", warnings);
+    const actionsFallback = normalizeOptionalBoolean(record.actions_fallback, "review.visual.actions_fallback", warnings) === true;
+    return { productionUrl, preview: { urlTemplate }, routes: { paths, maxRoutes }, themes, gif, enabled, themeStorageKey, actionsFallback };
+}
+function parseAutoReviewTitleKeywords(value, warnings) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        warnings.push(`Manifest "review.auto_review.ignore_title_keywords" must be a list of strings; ignoring it.`);
+        return [];
+    }
+    const out = [];
+    for (const [index, entry] of value.entries()) {
+        if (out.length >= MAX_PATH_INSTRUCTIONS) {
+            warnings.push(`Manifest "review.auto_review.ignore_title_keywords" is capped at ${MAX_PATH_INSTRUCTIONS} entries; dropping the rest.`);
+            break;
+        }
+        const raw = typeof entry === "string" ? entry.trim() : "";
+        if (!raw) {
+            warnings.push(`Manifest "review.auto_review.ignore_title_keywords[${index}]" must be a non-empty string; ignoring it.`);
+            continue;
+        }
+        const safe = parsePublicSafeText(raw, `review.auto_review.ignore_title_keywords[${index}]`, warnings);
+        if (safe !== null)
+            out.push(safe);
+    }
+    return out;
+}
+function parseAutoReviewSkipLabels(value, warnings) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        warnings.push(`Manifest "review.auto_review.skip_labels" must be a list of strings; ignoring it.`);
+        return [];
+    }
+    const seen = new Set();
+    const out = [];
+    for (const [index, entry] of value.entries()) {
+        if (out.length >= MAX_PATH_INSTRUCTIONS) {
+            warnings.push(`Manifest "review.auto_review.skip_labels" is capped at ${MAX_PATH_INSTRUCTIONS} entries; dropping the rest.`);
+            break;
+        }
+        const raw = typeof entry === "string" ? entry.trim() : "";
+        if (!raw) {
+            warnings.push(`Manifest "review.auto_review.skip_labels[${index}]" must be a non-empty string; ignoring it.`);
+            continue;
+        }
+        const safe = parsePublicSafeText(raw, `review.auto_review.skip_labels[${index}]`, warnings);
+        if (safe === null)
+            continue;
+        const key = safe.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(key);
+    }
+    return out;
+}
+/** Parse `review.pre_merge_checks` — an array of DETERMINISTIC pre-merge assertions. Each entry needs a non-empty
+ *  public-safe `name` and at least ONE assertion (`title_contains` / `description_contains` / `require_label`,
+ *  each public-safe); `when_paths` (optional) gates the check to PRs touching a matching glob; `enforce` (default
+ *  false) makes a failure a hard blocker. Invalid entries are dropped with a warning; capped at
+ *  MAX_PATH_INSTRUCTIONS so a hostile manifest can't bloat the gate. (#review-pre-merge-checks) */
+function parseReviewPreMergeChecks(value, warnings) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        warnings.push(`Manifest "review.pre_merge_checks" must be a list of checks; ignoring it.`);
+        return [];
+    }
+    const out = [];
+    for (const [index, entry] of value.entries()) {
+        if (out.length >= MAX_PATH_INSTRUCTIONS) {
+            warnings.push(`Manifest "review.pre_merge_checks" is capped at ${MAX_PATH_INSTRUCTIONS} entries; dropping the rest.`);
+            break;
+        }
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+            warnings.push(`Manifest "review.pre_merge_checks[${index}]" must be a mapping; ignoring it.`);
+            continue;
+        }
+        const e = entry;
+        if (e.name === undefined || e.name === null) {
+            warnings.push(`Manifest "review.pre_merge_checks[${index}].name" is required; ignoring the entry.`);
+            continue;
+        }
+        const name = parsePublicSafeText(e.name, `review.pre_merge_checks[${index}].name`, warnings);
+        if (name === null)
+            continue; // non-string / empty / not-public-safe → already warned
+        const titleContains = e.title_contains === undefined || e.title_contains === null ? null : parsePublicSafeText(e.title_contains, `review.pre_merge_checks[${index}].title_contains`, warnings);
+        const descriptionContains = e.description_contains === undefined || e.description_contains === null ? null : parsePublicSafeText(e.description_contains, `review.pre_merge_checks[${index}].description_contains`, warnings);
+        const requireLabel = e.require_label === undefined || e.require_label === null ? null : parsePublicSafeText(e.require_label, `review.pre_merge_checks[${index}].require_label`, warnings);
+        if (titleContains === null && descriptionContains === null && requireLabel === null) {
+            warnings.push(`Manifest "review.pre_merge_checks[${index}]" needs at least one of title_contains / description_contains / require_label; ignoring it.`);
+            continue;
+        }
+        const whenPaths = parseManifestGlobList(e.when_paths, `review.pre_merge_checks[${index}].when_paths`, warnings);
+        const enforce = normalizeOptionalBoolean(e.enforce, `review.pre_merge_checks[${index}].enforce`, warnings) === true;
+        out.push({ name, whenPaths, titleContains, descriptionContains, requireLabel, enforce });
+    }
+    return out;
+}
+/** Parse a manifest glob list (e.g. `review.exclude_paths`, a check's `when_paths`) — an array of non-empty
+ *  string globs; blanks/non-strings are dropped with a warning. Capped at MAX_PATH_INSTRUCTIONS so a hostile
+ *  manifest can't bloat the matcher. `fieldLabel` makes the warnings name the right field. */
+function parseManifestGlobList(value, fieldLabel, warnings) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        warnings.push(`Manifest "${fieldLabel}" must be a list of path globs; ignoring it.`);
+        return [];
+    }
+    const out = [];
+    const seen = new Set();
+    for (const [index, entry] of value.entries()) {
+        const glob = typeof entry === "string" ? entry.trim() : "";
+        if (!glob) {
+            warnings.push(`Manifest "${fieldLabel}[${index}]" must be a non-empty string; ignoring it.`);
+            continue;
+        }
+        if (glob.length > MAX_ITEM_LENGTH) {
+            warnings.push(`Manifest "${fieldLabel}[${index}]" exceeds ${MAX_ITEM_LENGTH} chars; ignoring it.`);
+            continue;
+        }
+        const key = glob.toLowerCase();
+        if (seen.has(key))
+            continue;
+        if (out.length >= MAX_PATH_INSTRUCTIONS) {
+            warnings.push(`Manifest "${fieldLabel}" is capped at ${MAX_PATH_INSTRUCTIONS} entries; dropping the rest.`);
+            break;
+        }
+        seen.add(key);
+        out.push(glob);
+    }
+    return out;
+}
+/** Parse `review.exclude_paths` — globs whose matching files are excluded from the AI review. (#review-exclude-paths) */
+function parseReviewExcludePaths(value, warnings) {
+    return parseManifestGlobList(value, "review.exclude_paths", warnings);
+}
+/** Parse `review.path_filters` — include globs plus optional leading-`!` negation entries. (#2043) */
+function parseReviewPathFilters(value, warnings) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        warnings.push(`Manifest "review.path_filters" must be a list of path globs; ignoring it.`);
+        return [];
+    }
+    const out = [];
+    for (const [index, entry] of value.entries()) {
+        if (out.length >= MAX_PATH_INSTRUCTIONS) {
+            warnings.push(`Manifest "review.path_filters" is capped at ${MAX_PATH_INSTRUCTIONS} entries; dropping the rest.`);
+            break;
+        }
+        const raw = typeof entry === "string" ? entry.trim() : "";
+        if (!raw) {
+            warnings.push(`Manifest "review.path_filters[${index}]" must be a non-empty string; ignoring it.`);
+            continue;
+        }
+        const negated = raw.startsWith("!");
+        const glob = negated ? raw.slice(1).trim() : raw;
+        if (!glob) {
+            warnings.push(`Manifest "review.path_filters[${index}]" must include a glob after a leading '!'; ignoring it.`);
+            continue;
+        }
+        if (glob.length > MAX_ITEM_LENGTH) {
+            warnings.push(`Manifest "review.path_filters[${index}]" exceeds ${MAX_ITEM_LENGTH} chars; ignoring it.`);
+            continue;
+        }
+        out.push(negated ? `!${glob}` : glob);
+    }
+    return out;
+}
+/** Parse `review.path_instructions` — an array of `{ path, instructions }` entries. Each must have a non-empty
+ *  string `path` (a manifest glob) and PUBLIC-SAFE string `instructions`; invalid/unsafe entries are dropped with
+ *  a warning. Capped at MAX_PATH_INSTRUCTIONS so a huge manifest can't bloat the reviewer prompt. */
+function parseReviewPathInstructions(value, warnings) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        warnings.push(`Manifest "review.path_instructions" must be a list of { path, instructions }; ignoring it.`);
+        return [];
+    }
+    const out = [];
+    for (const [index, entry] of value.entries()) {
+        if (out.length >= MAX_PATH_INSTRUCTIONS) {
+            warnings.push(`Manifest "review.path_instructions" is capped at ${MAX_PATH_INSTRUCTIONS} entries; dropping the rest.`);
+            break;
+        }
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+            warnings.push(`Manifest "review.path_instructions[${index}]" must be a mapping with path + instructions; ignoring it.`);
+            continue;
+        }
+        const e = entry;
+        const path = typeof e.path === "string" ? e.path.trim() : "";
+        if (!path) {
+            warnings.push(`Manifest "review.path_instructions[${index}].path" must be a non-empty string; ignoring the entry.`);
+            continue;
+        }
+        if (path.length > MAX_ITEM_LENGTH) {
+            warnings.push(`Manifest "review.path_instructions[${index}].path" exceeds ${MAX_ITEM_LENGTH} chars; ignoring the entry.`);
+            continue;
+        }
+        if (e.instructions === undefined || e.instructions === null) {
+            warnings.push(`Manifest "review.path_instructions[${index}].instructions" is required; ignoring the entry.`);
+            continue;
+        }
+        const instructions = parsePublicSafeText(e.instructions, `review.path_instructions[${index}].instructions`, warnings);
+        if (instructions === null)
+            continue; // non-string / empty / not-public-safe → already warned
+        out.push({ path, instructions });
+    }
+    return out;
+}
+/** Parse `review.profile` — one of chill / balanced / assertive (case-insensitive). `balanced` normalizes to
+ *  null (the default, so the reviewer prompt stays byte-identical). Any other value is ignored with a warning. */
+function parseReviewProfile(value, warnings) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "string") {
+        warnings.push(`Manifest "review.profile" must be a string (chill | balanced | assertive); ignoring it.`);
+        return null;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "balanced")
+        return null; // default → no prompt change
+    if (normalized === "chill" || normalized === "assertive")
+        return normalized;
+    warnings.push(`Manifest "review.profile" must be one of chill / balanced / assertive; ignoring "${value.slice(0, 32)}".`);
+    return null;
+}
+/** Serialize the review config for the cache round-trip; returns null when nothing is set. */
+export function reviewConfigToJson(review) {
+    if (!review.present)
+        return null;
+    const out = {};
+    if (review.footerText !== null)
+        out.footer = { text: review.footerText };
+    if (review.note !== null)
+        out.note = review.note;
+    if (review.profile !== null)
+        out.profile = review.profile;
+    if (review.tone !== null)
+        out.tone = review.tone;
+    if (review.securityFocus !== null)
+        out.security_focus = review.securityFocus;
+    if (review.inlineComments !== null)
+        out.inline_comments = review.inlineComments;
+    if (review.fixHandoff !== null)
+        out.fixHandoff = review.fixHandoff;
+    if (review.autoMergeSummary !== null)
+        out.auto_merge_summary = review.autoMergeSummary;
+    if (review.suggestions !== null)
+        out.suggestions = review.suggestions;
+    if (review.changedFilesSummary !== null)
+        out.changed_files_summary = review.changedFilesSummary;
+    if (review.effortScore !== null)
+        out.effort_score = review.effortScore;
+    if (review.impactMap !== null)
+        out.impact_map = review.impactMap;
+    if (review.cultureProfile !== null)
+        out.culture_profile = review.cultureProfile;
+    if (review.selftune !== null)
+        out.selftune = review.selftune;
+    if (review.reviewMemory !== null)
+        out.memory = review.reviewMemory;
+    if (review.findingCategories !== null)
+        out.finding_categories = review.findingCategories;
+    if (review.inlineCommentsPerCategory !== null)
+        out.inline_comments_per_category = review.inlineCommentsPerCategory;
+    if (review.minFindingSeverity !== null)
+        out.min_finding_severity = review.minFindingSeverity;
+    if (maxFindingsPresent(review.maxFindings)) {
+        const maxFindings = {};
+        if (review.maxFindings.blockers !== null)
+            maxFindings.blockers = review.maxFindings.blockers;
+        if (review.maxFindings.nits !== null)
+            maxFindings.nits = review.maxFindings.nits;
+        out.max_findings = maxFindings;
+    }
+    if (review.commentVerbosity !== null)
+        out.comment_verbosity = review.commentVerbosity;
+    if (review.e2eTestDelivery !== null)
+        out.e2e_test_delivery = review.e2eTestDelivery;
+    if (review.e2eTestAutoTrigger !== null)
+        out.e2e_test_auto_trigger = review.e2eTestAutoTrigger;
+    if (review.instructions !== null)
+        out.instructions = review.instructions;
+    if (review.pathInstructions.length > 0)
+        out.path_instructions = review.pathInstructions.map((entry) => ({ path: entry.path, instructions: entry.instructions }));
+    if (review.excludePaths.length > 0)
+        out.exclude_paths = [...review.excludePaths];
+    if (review.pathFilters.length > 0)
+        out.path_filters = [...review.pathFilters];
+    if (autoReviewPresent(review.autoReview)) {
+        const autoReview = {};
+        if (review.autoReview.skipDrafts !== null)
+            autoReview.skip_drafts = review.autoReview.skipDrafts;
+        if (review.autoReview.cadence !== null)
+            autoReview.cadence = review.autoReview.cadence;
+        if (review.autoReview.ignoreAuthors.length > 0)
+            autoReview.ignore_authors = [...review.autoReview.ignoreAuthors];
+        if (review.autoReview.ignoreTitleKeywords.length > 0)
+            autoReview.ignore_title_keywords = [...review.autoReview.ignoreTitleKeywords];
+        if (review.autoReview.skipLabels.length > 0)
+            autoReview.skip_labels = [...review.autoReview.skipLabels];
+        if (review.autoReview.skipDocsOnly !== null)
+            autoReview.skip_docs_only = review.autoReview.skipDocsOnly;
+        if (review.autoReview.maxAddedLines > 0)
+            autoReview.max_added_lines = review.autoReview.maxAddedLines;
+        if (review.autoReview.maxFiles > 0)
+            autoReview.max_files = review.autoReview.maxFiles;
+        if (review.autoReview.baseBranches.length > 0)
+            autoReview.base_branches = [...review.autoReview.baseBranches];
+        if (review.autoReview.autoPauseAfterReviewedCommits !== null) {
+            autoReview.auto_pause_after_reviewed_commits = review.autoReview.autoPauseAfterReviewedCommits;
+        }
+        out.auto_review = autoReview;
+    }
+    if (review.preMergeChecks.length > 0) {
+        out.pre_merge_checks = review.preMergeChecks.map((check) => {
+            const entry = { name: check.name };
+            if (check.whenPaths.length > 0)
+                entry.when_paths = [...check.whenPaths];
+            if (check.titleContains !== null)
+                entry.title_contains = check.titleContains;
+            if (check.descriptionContains !== null)
+                entry.description_contains = check.descriptionContains;
+            if (check.requireLabel !== null)
+                entry.require_label = check.requireLabel;
+            if (check.enforce)
+                entry.enforce = true;
+            return entry;
+        });
+    }
+    if (Object.keys(review.fields).length > 0)
+        out.fields = { ...review.fields };
+    if (Object.keys(review.enrichmentAnalyzers).length > 0)
+        out.enrichment = { ...review.enrichmentAnalyzers };
+    if (selfHostAiModelPresent(review.aiModel)) {
+        const aiModel = {};
+        if (review.aiModel.claudeModel !== null)
+            aiModel.claude_model = review.aiModel.claudeModel;
+        if (review.aiModel.claudeEffort !== null)
+            aiModel.claude_effort = review.aiModel.claudeEffort;
+        if (review.aiModel.codexModel !== null)
+            aiModel.codex_model = review.aiModel.codexModel;
+        if (review.aiModel.codexEffort !== null)
+            aiModel.codex_effort = review.aiModel.codexEffort;
+        if (review.aiModel.ollamaModel !== null)
+            aiModel.ollama_model = review.aiModel.ollamaModel;
+        if (review.aiModel.openaiModel !== null)
+            aiModel.openai_model = review.aiModel.openaiModel;
+        if (review.aiModel.openaiCompatibleModel !== null)
+            aiModel.openai_compatible_model = review.aiModel.openaiCompatibleModel;
+        if (review.aiModel.anthropicModel !== null)
+            aiModel.anthropic_model = review.aiModel.anthropicModel;
+        out.ai_model = aiModel;
+    }
+    if (visualConfigPresent(review.visual)) {
+        const visual = {};
+        if (review.visual.productionUrl !== null)
+            visual.production_url = review.visual.productionUrl;
+        if (review.visual.preview.urlTemplate !== null)
+            visual.preview = { url_template: review.visual.preview.urlTemplate };
+        if (review.visual.routes.paths.length > 0 || review.visual.routes.maxRoutes !== null) {
+            const routes = {};
+            if (review.visual.routes.paths.length > 0)
+                routes.paths = [...review.visual.routes.paths];
+            if (review.visual.routes.maxRoutes !== null)
+                routes.max_routes = review.visual.routes.maxRoutes;
+            visual.routes = routes;
+        }
+        if (review.visual.themes.length > 0)
+            visual.themes = [...review.visual.themes];
+        if (review.visual.gif)
+            visual.gif = true;
+        if (review.visual.enabled !== null)
+            visual.enabled = review.visual.enabled;
+        if (review.visual.themeStorageKey !== null)
+            visual.theme_storage_key = review.visual.themeStorageKey;
+        if (review.visual.actionsFallback)
+            visual.actions_fallback = true;
+        out.visual = visual;
+    }
+    if (review.linkedIssueSatisfaction !== null)
+        out.linkedIssueSatisfaction = review.linkedIssueSatisfaction;
+    return out;
+}
+/**
+ * Resolve the `review.path_instructions` that APPLY to a PR — those whose glob matches at least one changed path
+ * — into a single prompt section for the AI reviewer, or "" when none match (so the prompt stays byte-identical).
+ * Pure; uses the same manifest path-glob semantics (`matchesManifestPath`) as the rest of the manifest. Capped to
+ * keep the prompt bounded. (#review-path-instructions)
+ */
+export function parseFocusManifest(raw, source) {
+    if (raw === undefined || raw === null)
+        return emptyManifest(source ?? "none");
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        return emptyManifest(source ?? "api_record", ["Manifest must be a mapping of fields; ignoring malformed manifest and falling back to deterministic signals."]);
+    }
+    const record = raw;
+    const warnings = [];
+    const resolvedSource = normalizeSource(source, record.source, warnings);
+    const manifest = {
+        present: true,
+        source: resolvedSource,
+        wantedPaths: normalizeStringList(record.wantedPaths, "wantedPaths", warnings),
+        preferredLabels: normalizeStringList(record.preferredLabels, "preferredLabels", warnings),
+        linkedIssuePolicy: normalizeEnum(record.linkedIssuePolicy, "linkedIssuePolicy", ["required", "preferred", "optional"], "optional", warnings),
+        testExpectations: normalizeStringList(record.testExpectations, "testExpectations", warnings),
+        issueDiscoveryPolicy: normalizeEnum(record.issueDiscoveryPolicy, "issueDiscoveryPolicy", ["encouraged", "neutral", "discouraged"], "neutral", warnings),
+        maintainerNotes: normalizeStringList(record.maintainerNotes, "maintainerNotes", warnings),
+        publicNotes: normalizeStringList(record.publicNotes, "publicNotes", warnings).filter(isFocusManifestPublicSafe),
+        gate: parseGateConfig(record.gate, warnings),
+        settings: parseSettingsOverride(record.settings, warnings, resolvedSource),
+        review: parseReviewConfig(record.review, warnings),
+        features: parseFeaturesConfig(record.features, warnings),
+        experimental: parseExperimentalConfig(record.experimental, warnings),
+        contentLane: parseContentLaneConfig(record.contentLane, warnings),
+        repoDocGeneration: parseRepoDocGenerationConfig(record.repoDocGeneration, warnings),
+        reviewRecap: parseReviewRecapConfig(record.reviewRecap, warnings),
+        maintainerRecap: parseMaintainerRecapConfig(record.maintainerRecap, warnings),
+        warnings,
+    };
+    if (manifest.wantedPaths.length === 0 &&
+        manifest.preferredLabels.length === 0 &&
+        manifest.testExpectations.length === 0 &&
+        manifest.maintainerNotes.length === 0 &&
+        manifest.publicNotes.length === 0 &&
+        manifest.linkedIssuePolicy === "optional" &&
+        manifest.issueDiscoveryPolicy === "neutral" &&
+        !manifest.gate.present &&
+        Object.keys(manifest.settings).length === 0 &&
+        !manifest.review.present &&
+        !manifest.features.present &&
+        !manifest.experimental.present &&
+        !manifest.contentLane.present &&
+        !manifest.repoDocGeneration.present &&
+        !manifest.reviewRecap.present &&
+        !manifest.maintainerRecap.present) {
+        warnings.push("Manifest contained no recognized focus fields; falling back to deterministic signals.");
+        manifest.present = false;
+    }
+    return manifest;
+}
+/**
+ * Parse raw manifest file/record content (JSON or YAML). Malformed content degrades to an empty
+ * manifest with a warning rather than throwing, so a broken `.gittensory` config never breaks analysis.
+ */
+export function parseFocusManifestContent(content, source = "repo_file") {
+    if (content === undefined || content === null || content.trim() === "")
+        return emptyManifest(source);
+    if (content.length > MAX_FOCUS_MANIFEST_BYTES || new TextEncoder().encode(content).byteLength > MAX_FOCUS_MANIFEST_BYTES) {
+        return emptyManifest(source, [`Manifest content exceeded ${MAX_FOCUS_MANIFEST_BYTES} bytes; ignoring it and falling back to deterministic signals.`]);
+    }
+    const trimmed = content.trim();
+    const looksLikeJson = trimmed.startsWith("{") || trimmed.startsWith("[");
+    let parsed;
+    try {
+        parsed = looksLikeJson ? JSON.parse(trimmed) : parseYaml(trimmed);
+    }
+    catch {
+        return emptyManifest(source, [
+            looksLikeJson
+                ? "Manifest content was not valid JSON; ignoring it and falling back to deterministic signals."
+                : "Manifest content was not valid YAML; ignoring it and falling back to deterministic signals.",
+        ]);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return emptyManifest(source, ["Manifest must be a mapping of fields; ignoring malformed manifest and falling back to deterministic signals."]);
+    }
+    return parseFocusManifest(parsed, source);
+}
+/**
+ * Format a manifest's parse `warnings[]` into one grouped, deduped, order-preserving notice for the review
+ * surface — an acceptance criterion of #1670: an invalid/malformed `.gittensory.yml` value should fail
+ * clearly instead of silently falling back to a default. Empty/no warnings ⇒ `null` (byte-identical, no
+ * notice). Pure; reuses the warnings every parser already accumulates rather than a parallel schema. (#2056)
+ */
+export function formatManifestValidationNotice(warnings) {
+    const seen = new Set();
+    const deduped = [];
+    for (const warning of warnings) {
+        const trimmed = warning.trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        deduped.push(trimmed);
+    }
+    if (deduped.length === 0)
+        return null;
+    return deduped.map((warning) => `- ${warning}`).join("\n");
+}
+function normalizePathForMatch(path) {
+    return String(path).replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "").toLowerCase();
+}
+/**
+ * LINEAR-TIME wildcard matcher for a `*`-glob pattern over an already-normalized path. `*` (and a collapsed
+ * run of `*`) matches any run of characters INCLUDING `/` (gittensory globs cross slashes). Implemented as a
+ * prefix + suffix + ordered-substring (indexOf) scan rather than a `.*`-per-star regex: the old regex
+ * (`^.*a.*a...$`) backtracks catastrophically on a near-miss path and could hang the gate for an entire repo
+ * (a manifest glob with many non-adjacent `*`). This algorithm is O(path × parts) with NO backtracking.
+ */
+function linearGlobMatcher(pattern) {
+    // The caller only compiles this for a pattern that contains a wildcard, so split always yields >= 2 parts.
+    const parts = pattern.split(/\*+/); // literal segments between (collapsed) wildcard runs
+    const first = parts[0];
+    const last = parts[parts.length - 1];
+    const middles = parts.slice(1, -1).filter((part) => part.length > 0);
+    return (path) => {
+        if (!path.startsWith(first) || !path.endsWith(last))
+            return false;
+        let idx = first.length;
+        for (const part of middles) {
+            const found = path.indexOf(part, idx);
+            if (found === -1)
+                return false;
+            idx = found + part.length;
+        }
+        return path.length - last.length >= idx; // the suffix must not overlap the consumed prefix/middles
+    };
+}
+/**
+ * Compile a manifest path pattern into a predicate over an ALREADY-normalized path. Supports exact paths,
+ * directory prefixes (`src/` or `src`), and `*` wildcards (`*` and a double-star both match any run of chars
+ * across `/`). A double-star-then-separator prefix means "zero or more path segments", so the mandatory slash
+ * is absorbed and a double-star glob also matches a ROOT-level (zero-depth) file, not only nested ones.
+ * Compiling once lets a caller test many paths against one pattern without recompiling per path.
+ * An empty/blank pattern never matches.
+ */
+function expandGlobstarSlash(pattern) {
+    const alternatives = [""];
+    for (let idx = 0; idx < pattern.length;) {
+        if (pattern.startsWith("**/", idx)) {
+            const count = alternatives.length;
+            const canKeepRootAlternatives = count * 2 <= MAX_GLOBSTAR_SLASH_ALTERNATIVES;
+            for (let altIdx = count - 1; altIdx >= 0; altIdx -= 1) {
+                const prefix = alternatives[altIdx];
+                alternatives[altIdx] = `${prefix}*/`;
+                if (canKeepRootAlternatives)
+                    alternatives.push(prefix);
+            }
+            idx += 3;
+            continue;
+        }
+        for (let altIdx = 0; altIdx < alternatives.length; altIdx += 1)
+            alternatives[altIdx] += pattern[idx];
+        idx += 1;
+    }
+    return alternatives;
+}
+function compileManifestPathMatcher(pattern) {
+    const normalizedPattern = normalizePathForMatch(pattern);
+    if (!normalizedPattern)
+        return () => false;
+    if (normalizedPattern.includes("*")) {
+        // `**/` means zero or more whole path segments. Keep the slash in the non-root alternative so
+        // basename globs (e.g. `**/safe.ts`) do not degrade into suffix globs that match `unsafe.ts`.
+        const matchers = expandGlobstarSlash(normalizedPattern).map((globbed) => globbed.includes("*") ? linearGlobMatcher(globbed) : (normalizedPath) => normalizedPath === globbed);
+        return (normalizedPath) => matchers.some((matcher) => matcher(normalizedPath));
+    }
+    const dirPattern = normalizedPattern.endsWith("/") ? normalizedPattern : `${normalizedPattern}/`;
+    return (normalizedPath) => normalizedPath === normalizedPattern || normalizedPath.startsWith(dirPattern);
+}
+/**
+ * Match a changed path against a manifest path pattern. Supports exact paths, directory
+ * prefixes (`src/` or `src`), and `*` wildcards (`**` collapses to `*`).
+ */
+export function matchesManifestPath(path, pattern) {
+    const normalizedPath = normalizePathForMatch(path);
+    if (!normalizedPath)
+        return false;
+    return compileManifestPathMatcher(pattern)(normalizedPath);
+}
+export function compileFocusManifestPolicy(repoFullNameOrManifest, manifestOrOptions, options = {}) {
+    let repoFullName;
+    let manifest;
+    if (typeof repoFullNameOrManifest === "string") {
+        repoFullName = repoFullNameOrManifest;
+        manifest = manifestOrOptions;
+    }
+    else {
+        repoFullName = "";
+        manifest = repoFullNameOrManifest;
+        options = manifestOrOptions ?? {};
+    }
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const safePublicNotes = manifest.publicNotes.filter(isFocusManifestPublicSafe);
+    const contributionLanes = buildPolicyContributionLanes(manifest);
+    const readinessWarnings = buildPolicyReadinessWarnings(manifest);
+    const entryGuidance = buildPolicyEntryGuidance(manifest);
+    const summary = buildPolicySummary(manifest);
+    return {
+        repoFullName,
+        generatedAt,
+        source: manifest.source,
+        present: manifest.present,
+        publicSafe: {
+            contributionLanes,
+            labelPolicy: {
+                preferredLabels: manifest.preferredLabels.filter(isFocusManifestPublicSafe),
+                required: manifest.linkedIssuePolicy !== "optional",
+            },
+            validation: {
+                expectations: manifest.testExpectations.filter(isFocusManifestPublicSafe),
+                linkedIssuePolicy: manifest.linkedIssuePolicy,
+            },
+            issueDiscoveryPolicy: manifest.issueDiscoveryPolicy,
+            publicNotes: safePublicNotes,
+            readinessWarnings,
+            entryGuidance,
+            summary,
+        },
+        authenticated: {
+            manifestSource: manifest.source,
+            privateNoteCount: manifest.maintainerNotes.length,
+            manifestWarningCount: manifest.warnings.length,
+            parseWarnings: manifest.warnings,
+            readinessWarnings,
+            maintainerContext: manifest.maintainerNotes,
+        },
+    };
+}
+function buildPolicyEntryGuidance(manifest) {
+    const guidance = [];
+    // Build the sentence from the public-safe subset (as preferredLabels and publicNotes below already do, and
+    // as the sibling buildPolicyContributionLanes does for preferredPaths). Joining the raw wantedPaths means a
+    // single reserved-word path (e.g. `src/ranking/`) fails the all-or-nothing public-safety filter at the end
+    // and silently drops the entire focus-areas guidance line instead of surfacing the safe paths.
+    const safeWantedPaths = manifest.wantedPaths.filter(isFocusManifestPublicSafe);
+    if (safeWantedPaths.length > 0) {
+        guidance.push(`Focus changes on maintainer-wanted areas: ${safeWantedPaths.slice(0, 5).join(", ")}.`);
+    }
+    if (manifest.linkedIssuePolicy === "required")
+        guidance.push("Link a tracked issue before opening a pull request.");
+    else if (manifest.linkedIssuePolicy === "preferred")
+        guidance.push("Linking a tracked issue is preferred before opening a pull request.");
+    if (manifest.preferredLabels.length > 0) {
+        const safeLabels = manifest.preferredLabels.filter(isFocusManifestPublicSafe);
+        if (safeLabels.length > 0)
+            guidance.push(`Apply a maintainer-preferred label: ${safeLabels.slice(0, 3).join(", ")}.`);
+    }
+    guidance.push(...manifest.publicNotes.filter(isFocusManifestPublicSafe));
+    return [...new Set(guidance)].filter(isFocusManifestPublicSafe);
+}
+function buildPolicySummary(manifest) {
+    if (!manifest.present)
+        return "No maintainer focus manifest; contribution guidance is not constrained.";
+    if (manifest.issueDiscoveryPolicy === "encouraged")
+        return "Issue-discovery is the preferred contribution mode for this repo.";
+    if (manifest.issueDiscoveryPolicy === "discouraged")
+        return "Direct PRs are preferred; issue-discovery submissions are discouraged.";
+    if (manifest.wantedPaths.length > 0)
+        return "Direct PRs on the maintainer-wanted areas are preferred.";
+    return "Contribution guidance is derived from the maintainer focus manifest.";
+}
+function buildPolicyContributionLanes(manifest) {
+    if (!manifest.present)
+        return [];
+    const lanes = [];
+    const safeWantedPaths = manifest.wantedPaths.filter(isFocusManifestPublicSafe);
+    const safeTestExpectations = manifest.testExpectations.filter(isFocusManifestPublicSafe);
+    // Derive the public preference only from public-safe signals: use the SAME filtered list that surfaces in
+    // validationExpectations below, not the raw testExpectations. Otherwise a manifest whose only test expectation is
+    // public-unsafe (e.g. a wallet/seed phrase) is redacted from the lane yet still flips the public preference to
+    // "preferred" ("…with required validation evidence"), a self-contradictory verdict with no visible basis.
+    const directPrPreference = manifest.issueDiscoveryPolicy === "encouraged" ? "discouraged"
+        : safeWantedPaths.length > 0 || safeTestExpectations.length > 0 ? "preferred"
+            : "neutral";
+    lanes.push({
+        id: "direct-pr",
+        preference: directPrPreference,
+        title: "Direct pull request lane",
+        summary: directPrPreference === "discouraged"
+            ? "Direct pull requests are discouraged; issue discovery is the preferred entry mode."
+            : directPrPreference === "preferred"
+                ? "Contribute changes in maintainer-wanted areas with required validation evidence."
+                : "Direct pull requests are accepted when they stay inside maintainer-wanted scope.",
+        preferredPaths: safeWantedPaths,
+        discouragedPaths: [],
+        validationExpectations: safeTestExpectations,
+        publicNotes: manifest.publicNotes.filter(isFocusManifestPublicSafe),
+    });
+    const issueDiscoveryPreference = manifest.issueDiscoveryPolicy === "encouraged" ? "preferred"
+        : manifest.issueDiscoveryPolicy === "discouraged" ? "discouraged"
+            : "neutral";
+    lanes.push({
+        id: "issue-discovery",
+        preference: issueDiscoveryPreference,
+        title: "Issue discovery lane",
+        summary: issueDiscoveryPreference === "preferred"
+            ? "File well-scoped issue reports that the maintainer has indicated are welcome."
+            : issueDiscoveryPreference === "discouraged"
+                ? "The maintainer has indicated this repo prefers direct fixes over new issue reports."
+                : "Issue discovery is optional; confirm maintainer scope before filing new issues.",
+        preferredPaths: [],
+        discouragedPaths: [],
+        validationExpectations: [],
+        publicNotes: [],
+    });
+    return lanes;
+}
+function buildPolicyReadinessWarnings(manifest) {
+    if (!manifest.present)
+        return [];
+    const warnings = [];
+    if (manifest.wantedPaths.length === 0 && manifest.preferredLabels.length === 0) {
+        warnings.push("Focus manifest does not define wanted paths or preferred labels; contribution scope may be unclear to contributors.");
+    }
+    if (manifest.testExpectations.length === 0) {
+        warnings.push("Focus manifest does not define validation expectations; contributors may not know what tests to run.");
+    }
+    return warnings.filter(isFocusManifestPublicSafe);
+}