@loopover/engine 1.0.0

package/dist/focus-manifest.d.ts

@@ -0,0 +1,826 @@
+import type { AdvisoryAiRoutingConfig, AiReviewLowConfidenceDisposition, CombineStrategy, GatePolicyPack, GateRuleMode, JsonValue, LinkedIssueHardRulesConfig, LinkedIssueLabelPropagationConfig, OnMerge, PrTypeLabelSet, RepositorySettings, ReviewCheckMode, ScreenshotTableGateConfig, UnlinkedIssueGuardrailConfig } from "./types/manifest-deps-types.js";
+import { type ReesAnalyzerName } from "./review/enrichment-analyzer-names.js";
+export type FocusManifestSource = "repo_file" | "api_record" | "none";
+export type FocusManifestLinkedIssuePolicy = "required" | "preferred" | "optional";
+export type FocusManifestIssueDiscoveryPolicy = "encouraged" | "neutral" | "discouraged";
+/**
+ * Maintainer-authored gate configuration declared as code in `.gittensory.yml` under `gate:`. Each
+ * field is `null` when the maintainer did not set it, so the resolver can layer the manifest OVER the
+ * DB-backed RepositorySettings (manifest > DB > safe defaults) without clobbering unset values. All
+ * of these flow through the SAME confirmed-contributor-gated `evaluateGateCheck` path — the manifest
+ * only chooses which deterministic blockers are active, never who can be blocked. There is no single
+ * gate master switch: each per-dimension mode (`linkedIssue`, `duplicates`, `readinessMode`, etc.)
+ * independently controls whether that dimension evaluates. `checkMode`/`enabled` (#2852) is a separate
+ * axis entirely: whether/how the "LoopOver Orb Review Agent" check-RUN publishes, independent of gate
+ * evaluation itself (which always runs regardless of `checkMode`/`enabled`) — see {@link ReviewCheckMode}.
+ */
+export type FocusManifestGateConfig = {
+    present: boolean;
+    /** `gate.enabled` (legacy): a boolean shorthand for `checkMode` below -- `true` maps to `"required"`,
+     *  `false` maps to `"disabled"` (see resolveEffectiveSettings/applyGateConfigOverrides). Despite the name,
+     *  this controls ONLY whether the "LoopOver Orb Review Agent" check-run publishes -- it has NO effect on
+     *  gate evaluation, disposition, comments, labels, audit, spend, or autonomous merge/close, all of which run
+     *  identically regardless of this field. It also cannot express `checkMode`'s third state (`"visible"`), and
+     *  is silently ignored once `checkMode` is set (see the parse-time warning a few lines below this type).
+     *  Caused two real incidents under this exact ambiguity (2026-07: an operator flipping `enabled` to restore
+     *  unrelated spend/gate behavior twice got a surprise check-run side effect instead) -- prefer `checkMode`
+     *  explicitly for any new config. */
+    enabled: boolean | null;
+    /** `gate.checkMode` (#2852): explicit required|visible|disabled review-check publish mode. Takes
+     *  precedence over the legacy `enabled` boolean above when both are set (see resolveEffectiveSettings).
+     *  null (unset) ⇒ fall back to `enabled`, then to `settings.reviewCheckMode` (DB/dashboard), then default. */
+    checkMode: ReviewCheckMode | null;
+    pack: GatePolicyPack | null;
+    linkedIssue: GateRuleMode | null;
+    duplicates: GateRuleMode | null;
+    /** `gate.readiness.mode`/`gate.readiness.minScore` -- this engine-layer pair folds into
+     *  `RepositorySettings.qualityGateMode`/`qualityGateMinScore` (src/signals/focus-manifest.ts), a third
+     *  spelling of the same concept alongside the yml key name; the `readiness` gate is distinct from the
+     *  separate `mergeReadiness` composite gate above. */
+    readinessMode: GateRuleMode | null;
+    readinessMinScore: number | null;
+    slopMode: GateRuleMode | null;
+    slopMinScore: number | null;
+    slopAiAdvisory: boolean | null;
+    sizeMode: GateRuleMode | null;
+    /** `gate.lockfileIntegrity` (#2563): off|advisory|block, off by default. When not off, a changed
+     *  `package-lock.json` diff is scanned for a `resolved`/`integrity` change unaccompanied by a matching
+     *  `package.json` version bump, or a `resolved` URL outside `registry.npmjs.org` — a `lockfile_tamper_risk`
+     *  finding (`block` additionally hard-blocks). Config-as-code only — no DB column or dashboard toggle. */
+    lockfileIntegrityMode: GateRuleMode | null;
+    aiReviewMode: GateRuleMode | null;
+    aiReviewByok: boolean | null;
+    aiReviewProvider: "anthropic" | "openai" | null;
+    aiReviewModel: string | null;
+    aiReviewAllAuthors: boolean | null;
+    /** `gate.aiReview.closeConfidence` (#7): minimum calibrated AI-reviewer confidence (0-1) for an AI defect to BLOCK
+     *  under `aiReview.mode: block`. null (unset) ⇒ the gate's 0.93 default. Clamped to [0,1] at parse time. */
+    aiReviewCloseConfidence: number | null;
+    /** `gate.aiReview.lowConfidenceDisposition` (#4603): disposition for a sub-`closeConfidence`-floor
+     *  `ai_consensus_defect`/`ai_review_split` finding. null (unset) ⇒ `hold_for_review` (the shipped default).
+     *  DB-backed (dashboard-settable too, via the `/ai-review` route); this overrides the stored value -- mirrors
+     *  `aiReviewMode` above, not the config-as-code-only `closeConfidence` sibling field just above. */
+    aiReviewLowConfidenceDisposition: AiReviewLowConfidenceDisposition | null;
+    /** `gate.aiReview.combine` (#2567): per-repo override of the self-host operator's `AI_REVIEW_PLAN.combine`
+     *  boot default (single/consensus/synthesis). null (unset) ⇒ the operator's plan (or `consensus`). A
+     *  REFINEMENT only — see {@link aiReviewOnMerge} for the operator-floor clamp `runGittensoryAiReview` applies
+     *  to the paired `onMerge` field; `combine` itself is not floor-clamped (the three strategies are not ordered
+     *  by strictness, so there is no single "loosening" direction to clamp). */
+    aiReviewCombine: CombineStrategy | null;
+    /** `gate.aiReview.onMerge` (#2567): per-repo override of the `synthesis` merge rule. `either` is the STRICTER
+     *  rule (any one reviewer's blocker blocks/holds); `both` is more PERMISSIVE (requires every reviewer to
+     *  agree). null (unset) ⇒ the operator's `AI_REVIEW_PLAN.onMerge`. A repo may only TIGHTEN the operator's
+     *  floor (never loosen `either` down to `both`) — `runGittensoryAiReview` enforces the clamp at resolve time,
+     *  since only it can see both the per-repo value and the operator's plan. */
+    aiReviewOnMerge: OnMerge | null;
+    /** `gate.aiReview.reviewers` (#2567): per-repo override of the named reviewer pair(s) to run, in place of the
+     *  operator's `AI_REVIEW_PLAN.reviewers` (or the free Workers-AI pair when the operator configured none). null
+     *  (unset) ⇒ the operator's plan. No operator floor applies to WHICH reviewers run (only `onMerge` gates
+     *  strictness), so this always wins unclamped when set. */
+    aiReviewReviewers: ReadonlyArray<{
+        model: string;
+        fallback?: string | null | undefined;
+    }> | null;
+    mergeReadiness: GateRuleMode | null;
+    manifestPolicy: GateRuleMode | null;
+    selfAuthoredLinkedIssue: GateRuleMode | null;
+    /** `gate.linkedIssueSatisfaction` (#1961/#3906): off|advisory|block, off by default. When not off, an AI
+     *  assessment of whether the PR's diff satisfies its primary linked issue's intent runs and renders as a
+     *  collapsible section in the review comment; `block` additionally lets a confidence-floor-passing
+     *  "unaddressed" verdict become a hard blocker. DB-backed (dashboard-settable too); this overrides the
+     *  stored value -- mirrors `aiReviewMode` above, not the config-as-code-only `unlinkedIssueGuardrail`
+     *  pattern. Distinct from the pre-existing, config-as-code-only `review.linkedIssueSatisfaction` (#2173,
+     *  below) in type and storage -- but as of #4149 (`src/signals/focus-manifest.ts`'s
+     *  `resolveEffectiveSettings`, ~line 611-618) `review.linkedIssueSatisfaction` IS folded in as a
+     *  fallback alias whenever this `gate:` field is unset, so setting either spelling drives the same real
+     *  merge/close decision. See `src/types.ts`'s `linkedIssueSatisfactionGateMode` doc for the authoritative
+     *  cross-reference. */
+    linkedIssueSatisfaction: GateRuleMode | null;
+    dryRun: boolean | null;
+    firstTimeContributorGrace: boolean | null;
+    /** `gate.premergeContentRecheck` (#2550): for a PR touching `migrations/**`, re-verify against a live,
+     *  freshly-fetched tip of the base branch — unioned with this PR's own new migration filenames — for a
+     *  migration-number collision immediately before an agent-driven merge, not just at CI time against the
+     *  PR's own stale branch snapshot. On a live collision, the merge is suppressed and the PR is held with a
+     *  rebase-needed comment instead of merging blind. null (unset) ⇒ off (byte-identical to today) — this
+     *  costs one extra, uncached GitHub Trees-API call for any PR that touches migrations/**, so it is opt-in
+     *  rather than a new default. */
+    premergeContentRecheck: boolean | null;
+    /** `gate.requireFreshRebaseWindow` (#2552, anti-race): minutes. When the base branch has advanced within
+     *  this window of the actual merge-decision moment, an agent-driven merge forces an `update_branch` +
+     *  fresh CI recheck cycle before merging, instead of trusting a `mergeableState: clean` read that may
+     *  already be stale relative to a sibling commit that just landed on the base. null (unset) ⇒ never force
+     *  (byte-identical to today) — a discrete positive-minutes count, not a score, so it is neither clamped
+     *  nor rounded; an invalid value (fractional, non-positive, non-finite) is dropped with a warning. */
+    requireFreshRebaseWindowMinutes: number | null;
+    /** `gate.claMode` (#2564): off/advisory/block. null (unset) ⇒ off (byte-identical to today) — a repo must
+     *  explicitly opt in before any CLA consent check runs. */
+    claMode: GateRuleMode | null;
+    /** `gate.cla.consentPhrase` (#2564): the required PR-body consent phrase. null (unset) ⇒ phrase-match
+     *  detection is not configured. */
+    claConsentPhrase: string | null;
+    /** `gate.cla.checkRunName` (#2564): the CLA-bot check-run name to trust. null (unset) ⇒ check-run
+     *  detection is not configured. */
+    claCheckRunName: string | null;
+    /** `gate.cla.checkRunAppSlug`: the trusted GitHub App slug that must produce `checkRunName`. null (unset) ⇒
+     *  check-run detection remains unresolved rather than trusting a spoofable name-only match. */
+    claCheckRunAppSlug: string | null;
+    /** `gate.expectedCiContexts` (#selfhost-ci-verification): CI check/status context names to treat as
+     *  required when GitHub branch-protection required-status-checks are unreadable or unconfigured. null
+     *  (unset) ⇒ no generic fallback configured — the live-CI aggregate keeps today's fold-all behavior
+     *  when branch protection is also unreadable. See {@link RepositorySettings.expectedCiContexts}. */
+    expectedCiContexts: ReadonlyArray<string> | null;
+    /** `gate.aiJudgmentBlockers` (#3907): "gate" | "advisory", null (unset) ⇒ "advisory" (byte-identical to
+     *  today everywhere that doesn't opt in). Config-as-code only, YML-only (no DB column, no dashboard
+     *  toggle) — mirrors `contentLane`'s own YML-only shape, since this only has an effect for repos already
+     *  running the registry content lane. When "gate", a confident AI-judgment-only finding that
+     *  applySurfaceGate's default "advisory" behavior would otherwise let a decisive surface merge override
+     *  instead SURVIVES into the deterministic gate's own blockers array, demoting `decision` away from
+     *  `merge` — see content-lane-wire.ts's `applySurfaceGate` guard #3 and `evaluateWithSurfaceLane` for the
+     *  wiring. This deliberately reopens exactly the risk #2592 accepted for the general case (an AI
+     *  hallucination can one-shot-close a structurally-clean PR) as an explicit, per-repo, documented
+     *  trade-off — never the default. */
+    aiJudgmentBlockersMode: "gate" | "advisory" | null;
+    /** `gate.copycat.mode` (#1969): off|warn|label|block, off by default. Config-as-code only -- no DB column
+     *  or dashboard toggle. Deliberately a DEDICATED 4-value enum, not the shared `GateRuleMode` tri-state: the
+     *  issue's tiered response is warn -> label -> block -> strikes, where "strikes" is a separate escalation
+     *  action (reusing the existing cross-repo banned-contributors ledger once wired) rather than a 5th mode
+     *  value. THIS FIELD IS CURRENTLY INERT -- the similarity/containment detection engine that would actually
+     *  compute a copycat finding does not exist yet (tracked as later, separate PRs against #1969); parsing and
+     *  threading this config end-to-end first proves the plumbing and lets an operator's `.gittensory.yml`
+     *  already declare intent without waiting on the detection engine. */
+    copycatMode: CopycatGateMode | null;
+    /** `gate.copycat.minScore` (#1969): containment/similarity score (0-100) at/above which `copycatMode` acts.
+     *  null (unset) ⇒ the (also currently inert) engine's own default threshold once it exists. Same 0-100
+     *  clamp-and-round normalization as `slopMinScore`/`readinessMinScore` above. */
+    copycatMinScore: number | null;
+};
+/** `gate.copycat.mode` (#1969) -- see {@link FocusManifestGateConfig.copycatMode}'s doc comment for why this
+ *  is a dedicated enum rather than the shared `GateRuleMode`. */
+export type CopycatGateMode = "off" | "warn" | "label" | "block";
+export declare const CONVERGED_FEATURE_KEYS: readonly ["rag", "reputation", "unifiedComment", "safety", "grounding", "e2eTests", "screenshots", "improvementSignal"];
+export type ConvergedFeatureKey = (typeof CONVERGED_FEATURE_KEYS)[number];
+/** Per-repo activation overrides for the converged review features (`features:` block). `true`/`false` force the
+ *  feature on/off for THIS repo (subject to the env kill-switch); `null` (unset) ⇒ the resolver falls back to the
+ *  `GITTENSORY_REVIEW_REPOS` allowlist default, so an operator who sets nothing keeps today's behavior. */
+export type FocusManifestFeaturesConfig = {
+    present: boolean;
+} & Record<ConvergedFeatureKey, boolean | null>;
+/** 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 declare const EXPERIMENTAL_PLUGIN_KEYS: readonly ["gittensor"];
+export type ExperimentalPluginKey = (typeof EXPERIMENTAL_PLUGIN_KEYS)[number];
+/** Per-repo activation for `experimental:` plugins. Unlike `features:`, there is no `GITTENSORY_REVIEW_REPOS`
+ *  allowlist fallback for ANY key here — every plugin is the "manifestOnly" precedence shape
+ *  (`resolveManifestOnlyFeature`): OFF unless the operator's global env kill-switch AND an explicit per-repo
+ *  `true` are BOTH set. So an instance that never opts in has zero footprint from any experimental plugin. */
+export type FocusManifestExperimentalConfig = {
+    present: boolean;
+} & Record<ExperimentalPluginKey, boolean | null>;
+/**
+ * Per-repo registry-review lane configuration (`contentLane:` block, #2435) — lets a self-hosted maintainer
+ * configure their OWN registry (structural file-scope patterns + entry-count cap + dedup fields) without a
+ * gittensory code change. `entryFileGlob` and `collectionField` are the two REQUIRED fields to build a usable
+ * spec; `present` is true only when both are set (a partial config degrades to "not configured," not a broken
+ * half-spec — see `parseContentLaneConfig`). `validatorId` optionally references a code-registered domain
+ * validator (`review/content-lane/spec-resolver.ts`'s `REGISTRY_VALIDATORS`); omitted ⇒ structural gating only
+ * (scope/count/dedup), no domain-specific semantic check — see `RegistryLaneSpec.assessAppendedEntry`.
+ */
+export type FocusManifestContentLaneConfig = {
+    present: boolean;
+    entryFileGlob: string | null;
+    providerFileGlob: string | null;
+    artifactGlob: string | null;
+    collectionField: string | null;
+    maxAppendedEntries: number | null;
+    duplicateKeyFields: string[];
+    validatorId: string | null;
+};
+/** Which generated-file types the repo-doc generation roadmap (#2993) is allowed to touch for a repo.
+ *  "agents" covers AGENTS.md/CLAUDE.md (#3000/#3004); "skills" covers generated Claude Code/Codex skill
+ *  files once that generator lands (#3001) -- listed here now so a maintainer can opt in ahead of time. */
+export type FocusManifestRepoDocGenerationScope = "agents" | "skills";
+/**
+ * Per-repo opt-in for the repo-doc generation roadmap (#2993/#3002), declared as code under
+ * `repoDocGeneration:`. Purely a `.gittensory.yml` surface -- there is no DB-backed dashboard counterpart,
+ * so precedence is simply "the manifest value, or the default below when unset" (no DB layer to overlay).
+ * Defaults to fully disabled: a repo with no `repoDocGeneration:` block, or an explicit `enabled: false`,
+ * is never touched by the generator. `allowOverwriteExisting` is a SEPARATE opt-in specifically for a repo
+ * that already has a hand-maintained AGENTS.md/CLAUDE.md (no recognizable generated-content marker block,
+ * per generated-doc-refresh.ts's `manual-review-required` outcome) -- without it, that repo is left alone
+ * rather than proposed for a wholesale overwrite, even when `enabled` is true.
+ */
+export type FocusManifestRepoDocGenerationConfig = {
+    present: boolean;
+    enabled: boolean;
+    scope: FocusManifestRepoDocGenerationScope[];
+    allowOverwriteExisting: boolean;
+    /** How many days must elapse between scheduled refresh attempts for this repo (#3003). Default 7 (weekly).
+     *  Purely a rate-limiting knob on the SCHEDULED sweep -- it never affects correctness, since
+     *  openRepoDocPullRequest's own no-change short-circuit already prevents a redundant PR regardless of how
+     *  often it's invoked; this just avoids re-checking a stable repo more often than the operator wants. */
+    refreshIntervalDays: number;
+};
+/**
+ * Per-repo opt-in for the periodic maintainer review-recap digest (#1963), declared as code under
+ * `reviewRecap:`. Mirrors `repoDocGeneration:` exactly: no DB-backed dashboard counterpart, so the parsed
+ * value (or the default below when unset) IS the effective value — there is no DB layer to overlay onto.
+ * Defaults to fully disabled: a repo with no `reviewRecap:` block, or an explicit `enabled: false`, never
+ * gets a recap posted. Discord delivery ONLY for now (reuses the SAME per-repo webhook resolution as the
+ * per-event notifier in notify-discord.ts, `resolveDiscordWebhook`) — Slack is a follow-up.
+ */
+export type FocusManifestReviewRecapConfig = {
+    present: boolean;
+    enabled: boolean;
+    /** How many days of review activity each recap covers, and (once the scheduler follow-up lands) how often
+     *  it is posted. Default 7 (weekly). A purely descriptive/rate-limiting knob today — this PR ships only
+     *  the manually-triggerable builder + delivery, so `cadenceDays` currently just sets the report WINDOW;
+     *  the scheduled cron trigger is a scoped follow-up (see the PR description). */
+    cadenceDays: number;
+};
+/**
+ * Config-as-code override for the CROSS-repo maintainer recap digest's cron knobs (#1963, #2250), declared
+ * under `maintainerRecap:`. Distinct from `reviewRecap:` above (that is the single-repo digest's own window/
+ * enable knob); this instead overrides the GITTENSORY_MAINTAINER_RECAP / GITTENSORY_RECAP_CADENCE env vars
+ * that gate the cron-scheduled cross-repo digest (buildMaintainerRecap, #2239 / #2248) — read from the
+ * gittensory self-repo's manifest (resolveGittensorySelfRepoFullName), since the digest is an operator-level
+ * setting, not a per-contributor-repo one. Mirrors `reviewRecap:` exactly: no DB-backed counterpart, so the
+ * parsed value (or the default below when unset) IS the effective value. Not present (or present with no
+ * fields set) ⇒ the caller falls back to the env vars, byte-identical to before this override existed.
+ */
+export type FocusManifestMaintainerRecapConfig = {
+    present: boolean;
+    enabled: boolean;
+    cadence: "daily" | "weekly";
+    /** Delivery channel for the digest. Discord-only for now (mirrors deliverRecapToDiscord, #2245) — Slack
+     *  delivery for this cross-repo digest is a follow-up, so any other value falls back to "discord". */
+    channel: "discord";
+};
+/**
+ * Generic repository-settings override declared in `.gittensory.yml` under `settings:`. A partial of
+ * {@link RepositorySettings} — every behaviour a maintainer can toggle in the dashboard can be set here
+ * as code. Unset fields are omitted so the resolver layers it OVER the DB-backed settings
+ * (`.gittensory.yml` > dashboard settings > safe defaults). The friendly `gate:` block is a typed alias
+ * for the gate-related subset and wins over `settings:` for those fields.
+ */
+export type FocusManifestSettings = Partial<Pick<RepositorySettings, "commentMode" | "publicAudienceMode" | "publicSignalLevel" | "checkRunMode" | "checkRunDetailLevel" | "regateSweepOrderMode" | "reviewCheckMode" | "autoProjectMilestoneMatch" | "autoProjectMilestoneMatchBackend" | "linkedIssueGateMode" | "duplicatePrGateMode" | "selfAuthoredLinkedIssueGateMode" | "qualityGateMode" | "qualityGateMinScore" | "aiReviewMode" | "aiReviewByok" | "aiReviewProvider" | "aiReviewModel" | "aiReviewAllAuthors" | "closeOwnerAuthors" | "autoLabelEnabled" | "typeLabelsEnabled" | "badgeEnabled" | "publicQualityMetrics" | "gittensorLabel" | "createMissingLabel" | "publicSurface" | "includeMaintainerAuthors" | "requireLinkedIssue" | "backfillEnabled" | "autonomy" | "autoMaintain" | "agentPaused" | "agentDryRun" | "agentGlobalFreezeOverride" | "commandAuthorization" | "contributorBlacklist" | "blacklistLabel" | "contributorOpenPrCap" | "contributorOpenIssueCap" | "contributorCapLabel" | "contributorCapCancelCi" | "reviewNagPolicy" | "reviewNagMaxPings" | "reviewNagCooldownDays" | "reviewNagLabel" | "reviewNagMonitoredMentions" | "autoCloseExemptLogins" | "hardGuardrailGlobs" | "manualReviewLabel" | "readyToMergeLabel" | "changesRequestedLabel" | "migrationCollisionLabel" | "pendingClosureLabel" | "accountAgeThresholdDays" | "newAccountLabel" | "commandRateLimitPolicy" | "commandRateLimitMaxPerWindow" | "commandRateLimitAiMaxPerWindow" | "commandRateLimitWindowHours" | "moderationGateMode" | "moderationRules" | "moderationWarningLabel" | "moderationBannedLabel" | "reviewEvasionProtection" | "reviewEvasionLabel" | "reviewEvasionComment" | "mergeTrainMode">> & {
+    typeLabels?: Partial<PrTypeLabelSet> | null | undefined;
+    linkedIssueLabelPropagation?: Partial<LinkedIssueLabelPropagationConfig> | undefined;
+    linkedIssueHardRules?: Partial<LinkedIssueHardRulesConfig> | undefined;
+    unlinkedIssueGuardrail?: Partial<UnlinkedIssueGuardrailConfig> | undefined;
+    screenshotTableGate?: Partial<ScreenshotTableGateConfig> | undefined;
+    advisoryAiRouting?: Partial<AdvisoryAiRoutingConfig> | undefined;
+};
+/** 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 declare const REVIEW_FIELD_KEYS: readonly ["linkedIssue", "relatedWork", "reviewLoad", "validationEvidence", "openPrQueue", "contributorContext", "gateResult", "improvementSignal"];
+export type ReviewFieldKey = (typeof REVIEW_FIELD_KEYS)[number];
+export declare const REVIEW_PROFILES: readonly ["chill", "balanced", "assertive"];
+export type ReviewProfile = (typeof REVIEW_PROFILES)[number];
+export type ReviewFindingSeverity = "critical" | "major" | "minor" | "nitpick";
+export declare const REVIEW_FINDING_SEVERITY_LADDER: readonly ["critical", "major", "minor", "nitpick"];
+/**
+ * Maintainer overrides for the public review-panel CONTENT, declared under `review:`. Customizes the
+ * panel without changing what gittensory measures: a custom public-safe footer lead line, a custom intro
+ * note, and per-row show/hide toggles. The Gittensor attribution + register link is ALWAYS appended to
+ * the footer regardless (the growth surface is preserved); maintainer text that fails the public-safe
+ * filter is dropped, never published.
+ */
+export type FocusManifestReviewConfig = {
+    present: boolean;
+    footerText: string | null;
+    note: string | null;
+    fields: Partial<Record<ReviewFieldKey, boolean>>;
+    /** `review.enrichment`: per-repo REES enrichment-analyzer toggles (analyzer name → on/off). Only known analyzer
+     *  keys are kept (unknown keys warn + drop at parse). Empty (default, absent) ⇒ the operator's default analyzer
+     *  set runs unchanged (byte-identical). (#2050) */
+    enrichmentAnalyzers: Partial<Record<ReesAnalyzerName, boolean>>;
+    /** `review.profile`: chill / balanced / assertive. null (absent) = balanced = byte-identical reviewer prompt. */
+    profile: ReviewProfile | null;
+    /** `review.tone`: a bounded public-safe voice brief complementing `review.profile` (e.g. "concise, cite line numbers").
+     *  Folded into the review-instructions slot at runtime. null (default, absent) ⇒ byte-identical prompt. (#2044) */
+    tone: string | null;
+    /** `review.security_focus`: when true, the AI reviewer is told to prioritize a security-defect category
+     *  (injection, authn/authz bypass, secret handling, unsafe deserialization, SSRF, path traversal) with
+     *  elevated scrutiny, ON TOP OF whatever `profile` volume is set — an orthogonal "what to prioritize" axis,
+     *  not a fourth profile level. null/false (default, absent) = byte-identical reviewer prompt. (#review-security-focus) */
+    securityFocus: boolean | null;
+    /** `review.inline_comments`: when true, the AI reviewer ALSO leaves quiet, non-blocking inline PR comments on
+     *  specific changed lines (in addition to the decision summary). null/false (default, absent) = no inline
+     *  comments = byte-identical behavior. Operator-gated too (GITTENSORY_REVIEW_INLINE_COMMENTS + allowlist).
+     *  (#inline-comments) */
+    inlineComments: boolean | null;
+    /** `review.fixHandoff`: when true, the reviewer emits fix-handoff blocks (copy-paste remediation guidance). null/
+     *  false (default, absent) = no fix-handoff blocks = byte-identical. Operator-gated too (GITTENSORY_REVIEW_FIX_HANDOFF
+     *  + the convergence cutover allowlist) — the manifest toggle is only one of the ANDed gates. (#2176, for #1962) */
+    fixHandoff: boolean | null;
+    /** `review.auto_merge_summary`: when true, the unified comment gains a READ-ONLY collapsible showing which
+     *  auto-merge conditions currently pass/fail (CI green, gate passing, mergeable-clean, valid linked issue),
+     *  rendered from already-computed readiness signals. SURFACE ONLY — never changes the merge/close decision.
+     *  null/false (default, absent) = no summary = byte-identical. (#2051, for #1959) */
+    autoMergeSummary: boolean | null;
+    /** `review.suggestions`: when true, an inline finding whose AI-provided fix is precise enough to anchor to a
+     *  single line is ALSO rendered as a GitHub-native ` ```suggestion ` block a contributor can commit in one
+     *  click. Only takes effect when inline comments are already on (a suggestion has nothing to attach to
+     *  otherwise) — this is an ADDITIONAL opt-in on top of `review.inline_comments`, not a replacement gate.
+     *  null/false (default, absent) = no suggestion blocks = byte-identical behavior. (#1956) */
+    suggestions: boolean | null;
+    /** `review.changed_files_summary`: when true, the unified review comment (only rendered at all when the
+     *  `unifiedComment` convergence feature is on) gains a deterministic, no-AI "Changed files" collapsible: one
+     *  row per file category (source/test/docs/config/generated), with file counts and +/- totals, via the
+     *  existing `classifyChangedFile` classifier (`src/review/changed-files-classify.ts`, built for this table
+     *  under #2143). null/false (default, absent) = no changed-files section = byte-identical behavior. (#1957) */
+    changedFilesSummary: boolean | null;
+    /** `review.effort_score`: when true, the unified review comment (only rendered when the `unifiedComment`
+     *  convergence feature is on) gains a compact "review effort: N/5 (~M min)" chip — a deterministic, no-AI
+     *  complexity/time estimate from `estimateReviewEffort` (`src/review/review-effort.ts`), weighting each
+     *  changed file's added lines by its category (source costs most; generated/vendored/lockfiles cost least)
+     *  plus a fixed per-file overhead. Mirrors `changedFilesSummary` exactly: same table, same deterministic
+     *  source, same display-only (never touches the AI prompt) shape. null/false (default, absent) = no chip =
+     *  byte-identical behavior. (#1955) */
+    effortScore: boolean | null;
+    /** `review.impact_map` (#2184, config slice of #1971): when true, gates BOTH the deterministic impact-map
+     *  computation (`computeImpactMap`, `src/review/impact-map.ts`) and its rendering as a compact section in
+     *  the unified review comment (#2185) / additive AI-review grounding context (#2186). Deterministic/display
+     *  + reference-context only — never touches the gate verdict. ALSO requires the global env kill-switch
+     *  (`isImpactMapEnabled`, mirroring `isRagEnabled` in `src/review/rag-wire.ts:27`) to be on; the manifest
+     *  flag alone cannot enable it for a self-host operator who hasn't opted in globally. null/false (default,
+     *  absent) ⇒ no impact-map computation at all = byte-identical behavior. (#2184) */
+    impactMap: boolean | null;
+    /** `review.culture_profile` (#2995): when true, the AI reviewer's USER prompt gains an ADDITIVE "REPO
+     *  QUALITY-CULTURE PROFILE" reference block — typical merged-PR size + common accepted labels, derived
+     *  deterministically from this repo's OWN `recent_merged_pull_requests` history (see
+     *  `src/review/repo-culture-profile.ts` / `repo-culture-profile-wire.ts`). Reference-only grounding, exactly
+     *  like RAG/CI-grounding context: it never becomes a gate/scoring input and never changes the structured
+     *  output contract. Also requires the global `GITTENSORY_REVIEW_CULTURE_PROFILE` kill-switch to be on (this
+     *  field only opts THIS repo in once the capability itself is enabled). null/false (default, absent) = no
+     *  section appended = byte-identical behavior. */
+    cultureProfile: boolean | null;
+    /** `review.selftune` (#4104): explicit per-repo FORCE-OFF for the self-improvement/auto-tune cron pass
+     *  (`runSelfTune`, `src/review/selftune-wire.ts`) — `false` excludes this repo from tuning even though it's
+     *  otherwise agent-configured (`isAgentConfigured`) and the global `GITTENSORY_REVIEW_SELFTUNE` kill-switch is
+     *  on. Deliberately FORCE-OFF-ONLY (no `true` override): forcing a NON-agent-configured repo INTO tuning would
+     *  bypass that separate, broader acting-autonomy consent boundary, which this key must not touch. Unlike
+     *  `impactMap`/`cultureProfile` above, there is no `GITTENSORY_REVIEW_REPOS` allowlist fallback for selftune —
+     *  its own scoping is `isAgentConfigured`, not the cutover allowlist — so this does NOT live under the generic
+     *  `features:` block/`resolveConvergedFeature` (see `CONVERGED_FEATURE_KEYS`'s own comment). null/true
+     *  (default, absent) ⇒ no change to today's agent-configured-repos-only behavior. */
+    selftune: boolean | null;
+    /** `review.memory` (#2179, config slice of #1964): when true, gates repeat-false-positive SUPPRESSION —
+     *  before an advisory (non-blocking) AI finding is surfaced in the unified review comment, it is matched
+     *  against this repo's stored `review_suppression` signals (a maintainer's own past false-positive
+     *  dismissals, `src/db/repositories.ts`'s `listReviewSuppressions`, migrations/0114) and demoted/dropped on a
+     *  match (`src/review/review-memory-match.ts`'s `matchSuppressions`). ADVISORY-ONLY BY CONSTRUCTION: it is
+     *  never applied to gate blockers, so it can never change the merge/close disposition — only which
+     *  non-blocking nits render. ALSO requires the global env kill-switch (`isReviewMemoryEnabled`, mirroring
+     *  `isImpactMapEnabled` in `src/review/impact-map-wire.ts`) to be on; the manifest flag alone cannot enable
+     *  it for a self-host operator who hasn't opted in globally. Fail-safe: a suppression-store read error or
+     *  matcher throw leaves findings untouched. null/false (default, absent) ⇒ no suppression lookup at all =
+     *  byte-identical behavior. */
+    reviewMemory: boolean | null;
+    /** `review.finding_categories`: when true, an inline finding is ALSO tagged with a category (security/
+     *  correctness/performance/maintainability/tests/style) — the AI reviewer is asked to self-categorize, with a
+     *  deterministic path/keyword fallback (`classifyFindingCategory`) covering whatever it omits. Only takes
+     *  effect when inline comments are already on (a category has nothing to categorize otherwise) — this is an
+     *  ADDITIONAL opt-in on top of `review.inline_comments`, not a replacement gate, mirroring `review.suggestions`.
+     *  null/false (default, absent) = no category tagging = byte-identical behavior. (#1958) */
+    findingCategories: boolean | null;
+    /** `review.inline_comments_per_category`: optional per-category sub-cap applied before the total inline-comment
+     *  cap so one category (e.g. style) cannot crowd out security/correctness findings. null (default, absent) ⇒
+     *  byte-identical first-seen selection with only the hard total cap. (#2159) */
+    inlineCommentsPerCategory: number | null;
+    /** `review.min_finding_severity`: display-only floor for AI findings with a severity tier. Findings below the
+     *  configured level are suppressed from inline comments — never from gate blockers. null (default, absent) ⇒ every
+     *  finding shown = byte-identical behavior. (#2048) */
+    minFindingSeverity: ReviewFindingSeverity | null;
+    /** `review.max_findings`: optional caps on how many blocker/nit lines render in the unified review comment.
+     *  Display-only — never removes a blocker from the gate decision. null sub-fields ⇒ no cap for that list.
+     *  Default { blockers: null, nits: null } ⇒ byte-identical. (#2049) */
+    maxFindings: MaxFindingsConfig;
+    /** `review.comment_verbosity`: how much of the unified review comment's collapsible detail renders. `quiet`
+     *  drops the Nits collapsible and every extra collapsible section (blockers/gate result/signals are never
+     *  gated by this — only decorative detail is); `detailed` renders every collapsible pre-expanded. null/normal
+     *  (default, absent) ⇒ byte-identical to today. Net-new vs the changed-files-summary (#1957) and effort-score
+     *  (#1955) knobs. (#2047) */
+    commentVerbosity: CommentVerbosity | null;
+    /** `review.e2e_test_delivery` (#4197, part of the #4189 epic): how a `@gittensory generate-tests` result is
+     *  delivered once `features.e2eTests` is on. `"comment"` (default, null/absent) posts the generated test as
+     *  a reply comment only — no write access to the PR branch. `"commit"` pushes it as a real commit onto the
+     *  PR's own head branch (git/trees -> git/commits -> a ref UPDATE, mirroring `repo-doc-pr.ts`'s write
+     *  chokepoint) — a materially bigger blast radius, so it stays opt-in per repo even with e2eTests already
+     *  on. `"commit"` mode is additionally blocked at runtime (regardless of this config) for a PR whose author
+     *  is a confirmed Gittensor miner, to protect the external, upstream-computed score from ever including a
+     *  maintainer-authored line the miner didn't write themselves — see `src/github/e2e-test-commit.ts`. */
+    e2eTestDelivery: E2eTestDeliveryMode | null;
+    /** `review.e2e_test_auto_trigger` (#4196, part of the #4189 epic): opts THIS repo into the `manifest_missing_tests`
+     *  auto-trigger, which promotes that advisory finding into an actual unprompted generation run whenever a PR looks
+     *  like it needs tests -- separate from `features.e2eTests`, which only unlocks the maintainer-initiated paths
+     *  (the `@gittensory generate-tests` command and the PR-panel checkbox). Deliberately independent and OFF by
+     *  default: enabling `e2eTests` for on-demand use must never, by itself, start firing generation unprompted on
+     *  every under-tested PR (the exact loophole this field closes) -- a maintainer who *wants* the auto-trigger opts
+     *  in explicitly per repo. null/false (default, absent) ⇒ the auto-trigger never fires, even with e2eTests on;
+     *  true additionally requires e2eTests to already be enabled (this field alone does nothing). */
+    e2eTestAutoTrigger: boolean | null;
+    /** `review.path_instructions`: per-path natural-language guidance handed to the AI reviewer when the PR's
+     *  changed files match the glob. Empty (default) ⇒ byte-identical reviewer prompt. Also consumed by
+     *  AI-generated E2E test coverage (`resolveE2eTestGenInstructions` in `ai-e2e-test-gen.ts`, #4200) when
+     *  that feature is enabled — the same maintainer-authored guidance steers both consumers, no separate
+     *  test-generation-specific instructions schema. (#review-path-instructions) */
+    pathInstructions: ReviewPathInstruction[];
+    /** `review.instructions`: a repo-level natural-language brief handed to the AI reviewer on EVERY review (vs the
+     *  per-path path_instructions) — the maintainer's conventions/voice for this repo. Bounded + public-safe at parse
+     *  time (so it stays cost-cheap, unlike ingesting a whole CLAUDE.md). Also consumed by AI-generated E2E test
+     *  coverage (#4200) for the same reason as pathInstructions above. null (default, absent) ⇒ byte-identical
+     *  reviewer prompt. (#review-instructions) */
+    instructions: string | null;
+    /** `review.exclude_paths`: globs whose matching files are EXCLUDED from the AI review (diff + grounding + RAG)
+     *  — generated/vendored/lockfiles the maintainer doesn't want reviewed. Empty (default) ⇒ every file is
+     *  reviewed (byte-identical). Gate/slop/secret-scan are UNAFFECTED — this only narrows the AI review.
+     *  (#review-exclude-paths) */
+    excludePaths: string[];
+    /** `review.path_filters`: include + `!`-negation globs that POSITIVELY scope the AI review AFTER
+     *  `exclude_paths`. Include entries restrict to matching paths; leading `!` entries subtract matches.
+     *  Both `*` and `**` cross slashes (see `compileManifestPathMatcher`). Empty (default) ⇒ every non-excluded
+     *  file is reviewed (byte-identical). Gate/slop/secret-scan are UNAFFECTED. (#2043) */
+    pathFilters: string[];
+    /** `review.pre_merge_checks`: maintainer-declared DETERMINISTIC content assertions (title/description must
+     *  contain a phrase, a label must be present), optionally gated to a path glob. Each FAILED check surfaces an
+     *  advisory finding; a check with `enforce: true` becomes a hard gate blocker. Empty (default) ⇒ no finding
+     *  (byte-identical). No AI judgment is involved. (#review-pre-merge-checks) */
+    preMergeChecks: PreMergeCheck[];
+    /** `review.auto_review`: deterministic eligibility filters that skip the AI review (never a gate failure).
+     *  Empty/default ⇒ every PR is reviewed (byte-identical). (#1954 / #2038–#2041) */
+    autoReview: AutoReviewConfig;
+    /** `review.ai_model`: per-repo self-host reviewer model/effort overrides (claude-code / codex). Self-host only
+     *  — a hosted (Workers-AI) repo ignores this entirely. All-null (default, absent) ⇒ the operator's global
+     *  CLAUDE_AI_MODEL/CLAUDE_AI_EFFORT/CODEX_AI_MODEL/CODEX_AI_EFFORT env vars apply unchanged (byte-identical).
+     *  (#selfhost-ai-model-override) */
+    aiModel: SelfHostAiModelConfig;
+    /** `review.visual`: per-repo before/after screenshot-capture config (#3609 preview / #3610 routes).
+     *  All-empty (default, absent) ⇒ byte-identical to today (GitHub-native preview discovery, automatic
+     *  file-to-route inference, built-in route cap). Only takes effect when the operator has also enabled
+     *  GITTENSORY_REVIEW_SCREENSHOTS + the repo cutover allowlist — this config narrows/redirects that
+     *  feature, it never turns it on by itself. */
+    visual: VisualConfig;
+    /** `review.linkedIssueSatisfaction`: how strictly a linked issue must actually be SATISFIED by the PR — `off`
+     *  (default; not evaluated), `advisory` (surface a finding), or `block` (can become a hard blocker). CONFIG SLICE
+     *  ONLY (#2173, for #1961): parsed + normalized here; the merge/close decision that reads this mode is a separate
+     *  maintainer-only slice. null (default, absent) ⇒ byte-identical to today. */
+    linkedIssueSatisfaction: LinkedIssueSatisfactionMode | null;
+    /** Runtime provenance when the container-private shared base (`review.shared_config`, #2046) filled review
+     *  fields from `GITTENSORY_REPO_CONFIG_DIR/_shared/.gittensory.yml`. Never parsed from maintainer YAML —
+     *  set by the private-config loader only. null (default) ⇒ no shared overlay was applied. */
+    sharedConfigSource: string | null;
+};
+/** `review.linkedIssueSatisfaction` modes (#2173). `off` = not evaluated (same as unset). */
+export declare const LINKED_ISSUE_SATISFACTION_MODES: readonly ["off", "advisory", "block"];
+export type LinkedIssueSatisfactionMode = (typeof LINKED_ISSUE_SATISFACTION_MODES)[number];
+/** `review.comment_verbosity` levels (#2047). `normal` = today's behavior (same as unset). */
+export declare const COMMENT_VERBOSITY_LEVELS: readonly ["quiet", "normal", "detailed"];
+export type CommentVerbosity = (typeof COMMENT_VERBOSITY_LEVELS)[number];
+/** `review.e2e_test_delivery` modes (#4197). `comment` = today's behavior (same as unset). */
+export declare const E2E_TEST_DELIVERY_MODES: readonly ["comment", "commit"];
+export type E2eTestDeliveryMode = (typeof E2E_TEST_DELIVERY_MODES)[number];
+/** `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 declare const AI_REVIEW_CADENCES: readonly ["one_shot", "continuous"];
+export type AiReviewCadence = (typeof AI_REVIEW_CADENCES)[number];
+/** Per-repo AI review eligibility knobs under `review.auto_review`. Unset fields are byte-identical defaults. */
+export type AutoReviewConfig = {
+    /** `review.auto_review.skip_drafts`: when true, draft PRs skip AI review. null (default) ⇒ drafts reviewed as today. (#2038) */
+    skipDrafts: boolean | null;
+    /** `review.auto_review.cadence`: per-repo override of the AI review re-trigger cadence. null (default) ⇒
+     *  inherit the operator's fleet-wide GITTENSORY_REVIEW_CONTINUOUS default (itself "one_shot" when unset).
+     *  (#one-shot-review-cadence) */
+    cadence: AiReviewCadence | null;
+    /** `review.auto_review.ignore_authors`: author-login globs whose PRs skip AI review. Empty ⇒ every author. (#2039) */
+    ignoreAuthors: string[];
+    /** `review.auto_review.ignore_title_keywords`: case-insensitive title substrings that skip AI review. Empty ⇒ no skip. (#2040) */
+    ignoreTitleKeywords: string[];
+    /** `review.auto_review.skip_labels`: case-insensitive PR label names that skip AI review. Empty ⇒ no skip. (#2062) */
+    skipLabels: string[];
+    /** `review.auto_review.skip_docs_only`: when true, PRs whose every changed file classifies as docs skip AI review.
+     *  null (default) ⇒ docs PRs reviewed as today. Empty changed-file list ⇒ NOT docs-only (fail-safe eligible). (#2063) */
+    skipDocsOnly: boolean | null;
+    /** `review.auto_review.max_added_lines`: skip AI review when total added lines exceed this cap. 0 (default) ⇒ no cap. (#2065) */
+    maxAddedLines: number;
+    /** `review.auto_review.max_files`: skip AI review when changed-file count exceeds this cap. 0 (default) ⇒ no cap. (#2065) */
+    maxFiles: number;
+    /** `review.auto_review.base_branches`: base-ref globs whose PRs ARE reviewed; empty/unset ⇒ every base. (#2041) */
+    baseBranches: string[];
+    /** `review.auto_review.auto_pause_after_reviewed_commits`: after N published AI reviews on this PR, pause further
+     *  re-reviews. null/0 ⇒ byte-identical (re-review every sync). (#2042) */
+    autoPauseAfterReviewedCommits: number | null;
+};
+export type MaxFindingsConfig = {
+    blockers: number | null;
+    nits: number | null;
+};
+export declare const EMPTY_MAX_FINDINGS_CONFIG: MaxFindingsConfig;
+export declare const EMPTY_AUTO_REVIEW_CONFIG: AutoReviewConfig;
+/** Per-repo self-host reviewer model/effort overrides under `review.ai_model`. Each field independently overrides
+ *  the matching global env var (CLAUDE_AI_MODEL / CLAUDE_AI_EFFORT / CODEX_AI_MODEL / CODEX_AI_EFFORT) for THIS
+ *  repo only — it never widens what the operator's own env already permits, only narrows/redirects it, so a
+ *  compromised repo config can change which model reviews it but not grant itself a new credential or provider.
+ *  (#selfhost-ai-model-override) */
+export type SelfHostAiModelConfig = {
+    /** `review.ai_model.claude_model`: overrides CLAUDE_AI_MODEL for this repo's claude-code reviewer. null (default) ⇒ the operator's global env var, then the provider's own default. */
+    claudeModel: string | null;
+    /** `review.ai_model.claude_effort`: overrides CLAUDE_AI_EFFORT for this repo's claude-code reviewer. null (default) ⇒ the operator's global env var, then "medium". */
+    claudeEffort: string | null;
+    /** `review.ai_model.codex_model`: overrides CODEX_AI_MODEL for this repo's codex reviewer. null (default) ⇒ the operator's global env var, then the account default. */
+    codexModel: string | null;
+    /** `review.ai_model.codex_effort`: overrides CODEX_AI_EFFORT for this repo's codex reviewer. null (default) ⇒ the operator's global env var, then "medium". */
+    codexEffort: string | null;
+    /** `review.ai_model.ollama_model` (#3902): overrides OLLAMA_AI_MODEL for this repo's ollama reviewer. null (default) ⇒ the operator's global env var, then the provider's own default. */
+    ollamaModel: string | null;
+    /** `review.ai_model.openai_model` (#3902): overrides OPENAI_AI_MODEL for this repo's openai reviewer. null (default) ⇒ the operator's global env var, then the provider's own default. */
+    openaiModel: string | null;
+    /** `review.ai_model.openai_compatible_model` (#3902): overrides OPENAI_COMPATIBLE_AI_MODEL for this repo's openai-compatible reviewer. null (default) ⇒ the operator's global env var, then the provider's own default. */
+    openaiCompatibleModel: string | null;
+    /** `review.ai_model.anthropic_model` (#3902): overrides ANTHROPIC_AI_MODEL for this repo's anthropic (BYOK Messages API) reviewer. null (default) ⇒ the operator's global env var, then the provider's own default. */
+    anthropicModel: string | null;
+};
+export declare const EMPTY_SELF_HOST_AI_MODEL_CONFIG: SelfHostAiModelConfig;
+/** Per-repo before/after screenshot-capture config under `review.visual` (#3609 / #3610). Generic by design —
+ *  every self-hoster wires their OWN repo's preview-deploy setup and route shape with config, not code. */
+export type VisualConfig = {
+    /** `review.visual.production_url`: the repo's "before" production URL — e.g. `https://metagraph.sh` for a
+     *  repo whose live site differs from the operator's own `PUBLIC_SITE_ORIGIN` env var (a single GLOBAL value
+     *  with no per-repo awareness, correct for at most one repo on a multi-repo self-host instance). ALWAYS wins
+     *  over `PUBLIC_SITE_ORIGIN` when set, mirroring `preview.url_template`'s precedence over GitHub-native
+     *  discovery. null (default) ⇒ byte-identical to today (falls back to `PUBLIC_SITE_ORIGIN`). Validated at
+     *  parse time against the same SSRF guard (`isSafeHttpUrl`) the renderer itself unconditionally applies. */
+    productionUrl: string | null;
+    preview: VisualPreviewConfig;
+    routes: VisualRoutesConfig;
+    themes: VisualTheme[];
+    /** `review.visual.gif`: capture a short scroll-through GIF (#3612) alongside the static before/after
+     *  screenshots — evidence for scroll-linked behavior (parallax, reveal-on-scroll, a sticky header) that a
+     *  single static shot can't show. Self-host only (see src/review/visual/scroll-gif.ts) and the heaviest
+     *  capture mode this pipeline has (up to 6 extra renders per side) — false (default, every existing
+     *  manifest) ⇒ byte-identical to today, no scroll frames captured at all. */
+    gif: boolean;
+    /** `review.visual.enabled` (#4083): a config-as-code override layered ON TOP OF the outer
+     *  `GITTENSORY_REVIEW_SCREENSHOTS` / `GITTENSORY_REVIEW_REPOS` env-var gate, not a replacement for it. null
+     *  (default, unset at every config layer) ⇒ defers entirely to that gate's own decision. `false` (settable at
+     *  the global-default layer, or overridden per-repo) ⇒ forces capture off for this repo even when the env-var
+     *  gate would otherwise allow it. `true` ⇒ no additional restriction — it does NOT bypass the env-var gate,
+     *  it only opts back in at a layer where a global default of `false` disabled this repo. This is what lets an
+     *  operator flip visual review on/off per-repo purely through the VPS config files, without a redeploy. */
+    enabled: boolean | null;
+    /** `review.visual.theme_storage_key` (#4109): the `localStorage` key the capture pipeline ALSO forces
+     *  `theme` into (plus a reload) before rendering, for a target whose theming reads an explicit stored
+     *  preference instead of consulting `prefers-color-scheme` — verified (against gittensory-ui's own
+     *  dark-mode-only build) that `emulateMediaFeatures` alone has zero effect on that class of app, since it
+     *  only changes what CSS media queries / `matchMedia` report. null (default) ⇒ no `localStorage` write, no
+     *  reload — byte-identical to today. Only takes effect when `themes` is also configured; the key name is
+     *  app-specific (there is no universal convention), so it is opaque, bounded, public-safe text, same shape
+     *  as `review.ai_model`'s free-text fields. */
+    themeStorageKey: string | null;
+    /** `review.visual.actions_fallback` (#4112): when true, and ONLY when the existing GitHub-native discovery
+     *  chain (Deployments API / commit checks / cloudflare-bot PR comment / an explicit `preview.url_template`)
+     *  finds no preview at all for this PR, dispatch `.github/workflows/visual-capture-fallback.yml` -- a
+     *  fork-safe GitHub Actions job that builds, serves, and screenshots the PR's own code with zero secrets --
+     *  and use its captured PNGs as the "after" shot instead. false (default) ⇒ byte-identical to today (no
+     *  dispatch, no change to the discovery order). Requires the target repo to have that workflow file present
+     *  (see the workflow's own header comment for setup); a repo without it just never gets a fallback run, same
+     *  as leaving this unset. (#3607 visual-capture convergence epic) */
+    actionsFallback: boolean;
+};
+/** A `prefers-color-scheme` value the capture pipeline can emulate before rendering (#3678). */
+export type VisualTheme = "light" | "dark";
+export type VisualPreviewConfig = {
+    /** `review.visual.preview.url_template`: the repo's "after" preview URL, with `{number}` (PR number),
+     *  `{head_sha}` (full commit SHA), and `{head_sha_short}` (first 7 chars) placeholders substituted at
+     *  capture time — e.g. `https://pr-{number}.myapp.workers.dev`. ALWAYS wins over GitHub-native preview
+     *  discovery (the Deployments API / commit checks / cloudflare-bot PR comment) when set — an explicit,
+     *  maintainer-configured template is a stronger signal than inference, and is the only option for a
+     *  provider (e.g. Cloudflare Workers Builds' non-production branch builds) that doesn't surface a
+     *  GitHub-visible deployment at all. null (default) ⇒ byte-identical to today (discovery unchanged).
+     *  Validated at parse time against the same SSRF guard the renderer itself applies (isSafeHttpUrl) with
+     *  placeholders substituted for a dummy value, so a malformed template warns at config-read time instead
+     *  of only failing silently at render time — this is redundant with (not a replacement for) the
+     *  renderer's own unconditional isSafeHttpUrl check on every resolved URL, regardless of source. */
+    urlTemplate: string | null;
+};
+export type VisualRoutesConfig = {
+    /** `review.visual.routes.paths`: an explicit, always-screenshotted route list. When non-empty, this
+     *  REPLACES automatic file-to-route inference entirely — for repos whose routing convention isn't
+     *  gittensory-ui's TanStack file-based one, an explicit list is simpler and more robust than trying to
+     *  infer one. Empty (default) ⇒ automatic inference (falling back to "/" when nothing matches). */
+    paths: string[];
+    /** `review.visual.routes.max_routes`: overrides the built-in cap (2) on how many routes get screenshotted
+     *  per PR. null (default) ⇒ built-in default. Applies whether routes come from `paths` above or from
+     *  automatic inference. */
+    maxRoutes: number | null;
+};
+export declare const EMPTY_VISUAL_CONFIG: VisualConfig;
+/** One `review.path_instructions[]` entry: a manifest path glob + the public-safe instructions to apply when a
+ *  changed file matches it. */
+export type ReviewPathInstruction = {
+    path: string;
+    instructions: string;
+};
+/** One `review.pre_merge_checks[]` entry — a DETERMINISTIC pre-merge assertion. `whenPaths` (empty ⇒ always
+ *  applies) gates the check to PRs that touch a matching path. The check PASSES only when EVERY configured
+ *  assertion holds: the PR title contains `titleContains`, the body contains `descriptionContains`, and the
+ *  `requireLabel` label is present (case-insensitive substring / label match). `enforce` ⇒ a failure is a hard
+ *  gate blocker; default (false) ⇒ advisory only. All strings are public-safe-filtered at parse time. */
+export type PreMergeCheck = {
+    name: string;
+    whenPaths: string[];
+    titleContains: string | null;
+    descriptionContains: string | null;
+    requireLabel: string | null;
+    enforce: boolean;
+};
+/**
+ * Normalized maintainer focus manifest. Repo owners declare which work areas are wanted,
+ * preferred, and how PRs should present validation. Path-based manual review is intentionally
+ * not part of this manifest anymore; use `settings.hardGuardrailGlobs` for that single
+ * authoritative control. `maintainerNotes` are private review context and must never reach a public
+ * GitHub surface; `publicNotes` are explicitly opted into public output by the maintainer.
+ */
+export type FocusManifest = {
+    present: boolean;
+    source: FocusManifestSource;
+    wantedPaths: string[];
+    preferredLabels: string[];
+    linkedIssuePolicy: FocusManifestLinkedIssuePolicy;
+    testExpectations: string[];
+    issueDiscoveryPolicy: FocusManifestIssueDiscoveryPolicy;
+    maintainerNotes: string[];
+    publicNotes: string[];
+    gate: FocusManifestGateConfig;
+    settings: FocusManifestSettings;
+    review: FocusManifestReviewConfig;
+    features: FocusManifestFeaturesConfig;
+    experimental: FocusManifestExperimentalConfig;
+    contentLane: FocusManifestContentLaneConfig;
+    repoDocGeneration: FocusManifestRepoDocGenerationConfig;
+    reviewRecap: FocusManifestReviewRecapConfig;
+    maintainerRecap: FocusManifestMaintainerRecapConfig;
+    warnings: string[];
+};
+export type FocusManifestFinding = {
+    code: "manifest_off_focus" | "manifest_preferred_path" | "manifest_missing_preferred_label" | "manifest_linked_issue_required" | "manifest_linked_issue_preferred" | "manifest_missing_tests" | "manifest_issue_discovery_discouraged" | "manifest_malformed";
+    severity: "info" | "warning" | "critical";
+    title: string;
+    detail: string;
+    action?: string | undefined;
+};
+export type FocusManifestGuidance = {
+    present: boolean;
+    source: FocusManifestSource;
+    linkedIssuePolicy: FocusManifestLinkedIssuePolicy;
+    issueDiscoveryPolicy: FocusManifestIssueDiscoveryPolicy;
+    matchedWantedPaths: string[];
+    preferredLabelHits: string[];
+    findings: FocusManifestFinding[];
+    publicNextSteps: string[];
+    warnings: string[];
+    summary: string;
+};
+export declare const MAX_FOCUS_MANIFEST_BYTES: number;
+/**
+ * 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 declare function isFocusManifestPublicSafe(text: string): boolean;
+/** `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 declare function normalizeReadinessGateMode(value: JsonValue | undefined, field: string, warnings: string[]): GateRuleMode | null;
+/**
+ * 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 declare function gateConfigToJson(gate: FocusManifestGateConfig): JsonValue;
+/** 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 declare function featuresConfigToJson(features: FocusManifestFeaturesConfig): JsonValue;
+/** 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 declare function experimentalConfigToJson(experimental: FocusManifestExperimentalConfig): JsonValue;
+/** 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 declare function contentLaneConfigToJson(contentLane: FocusManifestContentLaneConfig): JsonValue;
+/** 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 declare function repoDocGenerationConfigToJson(config: FocusManifestRepoDocGenerationConfig): JsonValue;
+/** 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 declare function reviewRecapConfigToJson(config: FocusManifestReviewRecapConfig): JsonValue;
+/** 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 declare function maintainerRecapConfigToJson(config: FocusManifestMaintainerRecapConfig): JsonValue;
+/** Serialize the settings override for the cache round-trip; returns null when nothing is set. */
+export declare function settingsOverrideToJson(settings: FocusManifestSettings): JsonValue;
+/** 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 declare function overlayReviewConfig(base: FocusManifestReviewConfig, override: FocusManifestReviewConfig): FocusManifestReviewConfig;
+/** Parse a raw `review:` mapping value. Exported for the private-config shared overlay (#2046). */
+export declare function parseReviewConfigMapping(value: JsonValue | undefined, warnings: string[]): FocusManifestReviewConfig;
+/** Serialize the review config for the cache round-trip; returns null when nothing is set. */
+export declare function reviewConfigToJson(review: FocusManifestReviewConfig): JsonValue;
+/**
+ * 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 declare function parseFocusManifest(raw: unknown, source?: FocusManifestSource): FocusManifest;
+/**
+ * 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 declare function parseFocusManifestContent(content: string | null | undefined, source?: FocusManifestSource): FocusManifest;
+/**
+ * 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 declare function formatManifestValidationNotice(warnings: string[]): string | null;
+/**
+ * Match a changed path against a manifest path pattern. Supports exact paths, directory
+ * prefixes (`src/` or `src`), and `*` wildcards (`**` collapses to `*`).
+ */
+export declare function matchesManifestPath(path: string, pattern: string): boolean;
+export type FocusManifestLanePreference = "preferred" | "neutral" | "discouraged";
+export type FocusManifestPolicyContributionLane = {
+    id: string;
+    preference: "preferred" | "neutral" | "discouraged";
+    title: string;
+    summary: string;
+    preferredPaths: string[];
+    discouragedPaths: string[];
+    validationExpectations: string[];
+    publicNotes: string[];
+};
+export type FocusManifestPolicyLabelPolicy = {
+    preferredLabels: string[];
+    required: boolean;
+};
+export type FocusManifestPolicyValidation = {
+    expectations: string[];
+    linkedIssuePolicy: FocusManifestLinkedIssuePolicy;
+};
+export type FocusManifestPolicy = {
+    repoFullName: string;
+    generatedAt: string;
+    source: FocusManifestSource;
+    present: boolean;
+    publicSafe: {
+        contributionLanes: FocusManifestPolicyContributionLane[];
+        labelPolicy: FocusManifestPolicyLabelPolicy;
+        validation: FocusManifestPolicyValidation;
+        issueDiscoveryPolicy: FocusManifestIssueDiscoveryPolicy;
+        publicNotes: string[];
+        readinessWarnings: string[];
+        entryGuidance: string[];
+        summary: string;
+    };
+    authenticated: {
+        manifestSource: FocusManifestSource;
+        privateNoteCount: number;
+        manifestWarningCount: number;
+        parseWarnings: string[];
+        readinessWarnings: string[];
+        maintainerContext: string[];
+    };
+};
+/**
+ * Compile a normalized {@link FocusManifest} into a deterministic, machine-readable
+ * {@link FocusManifestPolicy}. Public-safe fields are segregated from authenticated
+ * (owner-only) fields. No reward, wallet, hotkey, raw trust, or private scoring
+ * language is allowed in public-safe output — unsafe strings are silently dropped.
+ *
+ * `repoFullName` is optional — when omitted it defaults to an empty string. Callers
+ * that persist the policy should supply the full name; single-manifest analysis
+ * callers may omit it.
+ */
+export declare function compileFocusManifestPolicy(manifest: FocusManifest, options?: {
+    generatedAt?: string;
+}): FocusManifestPolicy;
+export declare function compileFocusManifestPolicy(repoFullName: string, manifest: FocusManifest, options?: {
+    generatedAt?: string;
+}): FocusManifestPolicy;