.loopover.yml.example

# ============================================================================
# .loopover.yml — per-repo configuration for loopover CI & loopover review
# ============================================================================
#
# Drop this file at the root of any repo loopover watches to tune how the
# review engine scores, gates, and comments on its pull requests — as
# config-as-code, versioned alongside the project it governs.
#
# STARTER TEMPLATES (also shipped under config/examples/ for self-host operators):
#   config/examples/loopover.minimal.yml — smallest safe starter (gate off, observe-only autonomy)
#   config/examples/loopover.full.yml    — exhaustive reference (body synced with this file)
#   .loopover.minimal.yml                — same minimal starter at repo root
#   .loopover.yml.example                  — this file
#
# WHERE IT LIVES (first match wins):
#   .loopover.yml  →  .github/loopover.yml  →  .loopover.json  →  .github/loopover.json
#
# PRECEDENCE (most specific wins):
#   this file  >  per-repo dashboard/API settings  >  built-in safe defaults
#   The typed `gate:` block below is an alias for the gate fields and wins over
#   the generic `settings:` block for those same fields.
#   Hard path guardrails are an explicit config-as-code exception: omitted or
#   [] means no path guardrails, never hidden engine defaults.
#
# SAFE BY DEFAULT: with no file and no dashboard row, a repo falls back to a
# quiet, non-blocking profile — gate off, AI review off, slop scoring off,
# comments only to detected contributors, no check-run published. Everything
# here is an explicit opt-in; every value shown is the documented default
# unless a comment says otherwise. Delete any block to inherit the default.
#
# WHO CAN BE BLOCKED: gate modes choose *which* deterministic checks run, never
# *who* gets blocked. A hard block is always confirmed-contributor-gated.
#
# MANIFEST VALIDATION: any parse warning from this file (an unrecognized field, a
# malformed value that got dropped) is surfaced as a single grouped "Manifest
# validation" section in the unified PR review comment, so a misconfigured value
# fails clearly instead of silently falling back to its default. A fully valid
# manifest shows nothing here (byte-identical). Always on; not a config knob.
#
# NOTE: some capabilities (safety scanning, CI/full-file grounding, RAG,
# reputation control, the unified comment) are switched on at the deployment
# level by the operator's LOOPOVER_REVIEW_* feature flags AND a per-repo
# cutover allowlist. This file tunes behavior; it does not enable those
# deployment-wide capabilities.
# ============================================================================


# ----------------------------------------------------------------------------
# 1. FOCUS / GUARDRAILS (focus manifest)
# ----------------------------------------------------------------------------
# Declares the repo's work areas. wantedPaths feeds advisory-only guidance findings;
# testExpectations/linkedIssuePolicy feed manifest_missing_tests and manifest_linked_issue_required,
# which — when `gate.manifestPolicy: block` is set below — can become enforceable blockers. Hard path
# HOLDS are a separate mechanism: settings.hardGuardrailGlobs, below.

# Work areas the maintainer wants. PRs touching these are preferred/encouraged.
# Glob list. Default: [] (no preference).
wantedPaths:
  - "src/**"

# blockedPaths is LEGACY and fully retired (#2974, 2026-07-04): the FocusManifest parser no longer
# reads this key at all, it produces zero findings, and it is not enforceable under any
# gate.manifestPolicy mode. A key left over from an older config has no runtime effect other than a
# migration warning from `npm run selfhost:config-lint`. Use settings.hardGuardrailGlobs below for
# real, enforceable path-based holds.

# Labels the maintainer prefers on incoming PRs; a missing preferred label is
# surfaced (never blocks). String list. Default: [].
preferredLabels:
  - bug
  - enhancement

# How strongly a linked issue is expected on a PR.
# Values: required | preferred | optional. Default: optional.
# `required` also auto-promotes gate.linkedIssue to `block` if it's still `off` (same convergence as the
# dashboard "Require linked issue" toggle) -- this alone is enough to make a missing issue a real gate
# blocker, no need to separately configure gate.linkedIssue too.
linkedIssuePolicy: optional

# Test paths/areas expected to change alongside code. When code changes without
# them, a manifest_missing_tests finding fires. String list. Default: [].
testExpectations:
  - "tests/**"

# Whether opening discovery issues is encouraged for this repo.
# Values: encouraged | neutral | discouraged. Default: neutral.
issueDiscoveryPolicy: neutral

# PRIVATE review context — never published to any public GitHub surface.
# Use for triage hints the engine should know but contributors should not see.
# String list. Default: [].
maintainerNotes:
  - "Private triage context only — never appears on a public comment."

# Notes explicitly opted into public output. Each line is public-safe filtered;
# unsafe lines are silently dropped. String list. Default: [].
publicNotes:
  - "Prefer backend changes that tie to safety or release readiness."


# ----------------------------------------------------------------------------
# 2. GATE POLICY (`gate:`) — refines the deterministic gate
# ----------------------------------------------------------------------------
# Most gate dimensions are tri-state modes:
#   off      — the dimension is not evaluated.
#   advisory — the finding is surfaced (comment/context) but never blocks.
#   block    — the finding can become a hard `LoopOver Gate` blocker
#              (always confirmed-contributor-gated).
gate:
  # Legacy check-run publish switch (#5355) — despite the name, this does NOT turn the deterministic
  # gate itself on or off. Gate evaluation, comments, labels, audit records, spend, and autonomous
  # merge/close all run identically whether this is true, false, or unset; the per-dimension modes
  # below are what actually configure gate evaluation. `enabled` is only a boolean shorthand for
  # `checkMode` below: true maps to `required`, false maps to `disabled`, and it cannot express
  # `checkMode`'s third state (`visible`). Prefer setting `checkMode` explicitly instead of this field.
  # Bool. Default: unset (falls through to `checkMode`, then to the dashboard `reviewCheckMode` setting).
  enabled: true

  # Review-CHECK publish mode (#2852) — controls ONLY whether/how the "LoopOver Orb Review Agent"
  # check-run is created/updated on GitHub. Never affects gate evaluation, comments, labels, audit
  # records, or autonomous merge/close — all of those run identically in every mode (the autonomous
  # decision engine already excludes the bot's own check-run from the live CI it merges/closes against,
  # specifically to avoid a self-deadlock). Takes precedence over the legacy `enabled` boolean above
  # when both are set; when unset, `enabled: true` maps to `required` and `enabled: false` maps to
  # `disabled` for backward compatibility.
  #   required — legacy/current behavior: publish/update the check exactly as before. Use this if you
  #              intentionally keep it as a required branch-protection status check.
  #   visible  — publish/update the SAME check-run, but for UI visibility only. Never add this check as
  #              a required branch-protection status check — behaves identically to `required` on the
  #              publish side (same API calls); the distinction is purely how you configure GitHub.
  #   disabled — never create/update the check-run at all. RECOMMENDED for high-volume autonomous
  #              self-hosting: avoids GitHub showing "Expected — Waiting for status to be reported"
  #              under review-queue pressure, and reduces GitHub API calls (no check-run create/update).
  #              Before switching to `disabled`, remove "LoopOver Orb Review Agent" from this repo's
  #              branch-protection / ruleset required-status-checks list — LoopOver cannot do this on
  #              your behalf (it is a GitHub branch-protection setting), and leaving it required with
  #              nothing to satisfy it means GitHub will show a pending status forever. Keep your real
  #              CI/codecov/security checks required — this only ever affects LoopOver's own check.
  # required | visible | disabled. Default: disabled for a never-configured repo (matches the existing
  # opt-in default); an already-configured repo keeps its current effective behavior. RECOMMENDED for
  # high-volume autonomous self-hosting: `visible` or `disabled`, not `required` — LoopOver's own
  # merge/close decisions never depend on this check either way.
  checkMode: visible

  # Policy pack.
  #   gittensor      — confirmed-contributor-gated, registry-aware.
  #   oss-anti-slop  — runs the deterministic rules against ANY author on ANY repo.
  # Default: gittensor.
  pack: gittensor

  # Linked-issue gate — what happens when a PR has NO linked issue at all. off | advisory | block.
  # Default: advisory (a missing issue is surfaced in the review panel but never blocks the gate; issues
  # aren't always available, e.g. small/self-evident fixes). Set `block` here, or turn on the dashboard
  # "Require linked issue" toggle, to make a missing issue an explicit opt-in blocker.
  # (If the dashboard toggle is on, OR the top-level linkedIssuePolicy: required below is set, and this is
  # still `off`, it is auto-promoted to `block` — all three knobs converge on this one gate.)
  # This is UNRELATED to closing a PR that links an INELIGIBLE issue (owner-assigned, wrong label, etc.) —
  # that is a separate, deterministic rule, not this gate.
  linkedIssue: advisory

  # Duplicate-PR gate — detects duplicate/superseding PRs.
  # off | advisory | block. Default: block.
  duplicates: block

  # Quality / merge-readiness score gate (the PR-quality score).
  readiness:
    # off | advisory. Default: advisory. Informational only — this dimension can
    # never hard-block a PR, so "block" is not an accepted value (a config that
    # still says "block" is downgraded to "advisory" with a warning). For an
    # enforceable quality floor, use mergeReadiness or manifestPolicy below.
    mode: advisory
    # At/above this score the quality dimension passes.
    # Number 0–100, or null for the engine default band. Default: null.
    minScore: null

  # Deterministic anti-slop signal. Opt-in.
  slop:
    # off | advisory | block. Default: off.
    #   advisory — surfaces the slop score + warnings.
    #   block    — also hard-blocks at/above minScore.
    mode: off
    # Slop-risk threshold at/above which `block` blocks.
    # Number 0–100, or null. Default: null (engine uses 60, the "high" band).
    minScore: null
    # When true AND slop is not off, a free Workers-AI pass adds an
    # advisory-only ai_slop_advisory finding. It never feeds the slop score or
    # the gate. Bool. Default: false.
    aiAdvisory: false

  # Copycat/plagiarism detection (#1969): a deterministic code-containment check against prior art
  # (earlier open or recently merged PRs on the same repo), direction resolved by submission
  # timestamp so the earlier (original) author is never flagged.
  copycat:
    # off | warn | label | block. Default: off. A dedicated 4-tier scale (not the
    # shared off/advisory/block used elsewhere): warn surfaces an advisory finding
    # only; label also applies a label; block also closes the PR and counts toward
    # a further "strikes" escalation that reuses the existing moderation-rules
    # violation ledger (escalating to the global contributor blacklist at the
    # configured ban threshold).
    mode: off
    # Containment/similarity threshold (0-100) at/above which mode acts.
    # null uses the engine default (85).
    minScore: null

  # Oversized-PR gate. A PR at/above EITHER the file-count or line-count threshold
  # gets a manual-review HOLD finding — never a hard blocker; mode only turns this
  # hold signal on or off. off | advisory | block. Default: off. Config-as-code
  # only — no DB column or dashboard toggle; this can only be set here.
  size:
    mode: off
    # File-count threshold. Positive integer. Default: 10.
    # maxFiles: 10
    # Changed (added+deleted) line-count threshold. Positive integer. Default: 1000.
    # maxLines: 1000

  # Lockfile-tamper-risk gate. Scans a changed package-lock.json diff for a
  # resolved/integrity value that changed WITHOUT the same package's version
  # changing in a changed package.json, or a resolved URL outside
  # registry.npmjs.org — the classic supply-chain hand-edit tell. Distinct
  # from the OSV.dev known-CVE dependency scan (a different threat model).
  # off | advisory | block. Default: off. Config-as-code only — no DB column
  # or dashboard toggle; this can only be set here.
  lockfileIntegrity: off

  # CLA / license-compatibility gate (#2564). Confirms contributor license-agreement consent before a PR
  # can auto-merge — the loopover analog of a "CLA assistant" bot. off | advisory | block. Default: off.
  #   advisory — surfaces a cla_consent_missing finding but never blocks.
  #   block    — also hard-blocks (one-shot close for a contributor) when neither detection method
  #              below confirms consent.
  # Config-as-code only — no DB column or dashboard toggle; this can only be set here.
  claMode: off
  cla:
    # A phrase loopover looks for in the PR description (case-insensitive substring match), mirroring
    # review.pre_merge_checks' descriptionContains. String or null. Default: null (not configured).
    consentPhrase: "I have read and agree to the CLA"
    # Name of a separate CLA-bot check-run this repo also runs (e.g. a CLA Assistant GitHub Action). A
    # success/neutral conclusion for a check-run with this exact name also satisfies consent only when the
    # run was produced by checkRunAppSlug. Either method configured is enough; both may be set. String or
    # null. Default: null (not configured).
    checkRunName: null
    # Trusted GitHub App slug that must have produced checkRunName. Required for check-run detection so a
    # contributor-controlled same-name check-run cannot satisfy a blocking CLA/legal gate. String or null.
    # Default: null (not configured).
    checkRunAppSlug: null

  # CI check/status context names to treat as REQUIRED when GitHub branch protection returns no
  # readable required-status-checks (unconfigured, or a 403 from a token lacking
  # administration:read — common for GitHub App installations, especially self-host). Merged with
  # any branch-protection required contexts when both are readable; used ALONE when branch
  # protection is null/empty. A context listed here that never appears on the commit stays
  # pending; a completed red check for a listed context fails the gate; every listed context
  # settled clean resolves to a verified "passed" (no completeness warning). List of strings, or
  # omit. Default: not configured (keeps today's fold-all fail-closed behavior when branch
  # protection is also unreadable). Config-as-code only — no DB column or dashboard toggle.
  expectedCiContexts:
    - build
    - test

  # Third-party check-runs to treat as ADVISORY (#4372). Any GitHub App you install alongside loopover
  # (a security scanner, a contributor-trust analyzer, a license/CLA bot, ...) can post a check-run whose
  # terminal conclusion is outside GitHub's normal pass/fail vocabulary — most commonly a durable
  # "action_required" that only a human can clear in that app's own UI, never on GitHub. Left alone, such a
  # check freezes the gate: it never turns green, so the PR is held pending forever with no signal. List the
  # check here (matched by name AND the trusted producing app slug — a name-only match is spoofable and is
  # ignored, exactly like cla.checkRunAppSlug) to make it advisory: a matched, COMPLETED run is excluded from
  # CI pass/fail entirely and never counts as "still running", so it can never block or stall the gate. It is
  # NOT silently swallowed either — a non-passing conclusion routes the PR to the manual-review hold (the
  # manualReviewLabel) with the triggering check/app named, so a maintainer can act on it. Generic: name the
  # app(s) YOU run; loopover hardcodes no vendor. List of { name, appSlug }, or omit. Default: not
  # configured (byte-identical behavior for every repo that doesn't opt in). Config-as-code only — no DB
  # column or dashboard toggle.
  advisoryCheckRuns:
    - name: Contributor trust
      appSlug: example-security-app

  # Promote a confident AI-judgment-only finding (one the reviewer itself placed under "Blockers", never
  # a "Nit") into a real, deterministic gate blocker instead of leaving it advisory (#3907). Only matters
  # for repos already running the registry content lane (see contentLane below) — content/registry repos
  # have no schema/lint/codecov net to catch a semantically-wrong-but-structurally-valid defect, so their
  # own AI reviewer's judgment is the only thing that ever catches it.
  #   advisory — today's behavior: a decisive deterministic content-lane merge overrides an AI-judgment-only
  #              failure (an AI opinion alone never one-shot-closes a structurally-clean submission).
  #   gate     — the AI-judgment finding survives into the gate's own blockers, demoting the decision away
  #              from merge. Reopens the risk an AI hallucination can one-shot-close a clean PR — an
  #              explicit, per-repo trade-off, never the default.
  # gate | advisory. Default: advisory. Config-as-code only — no DB column or dashboard toggle.
  aiJudgmentBlockers: advisory

  # Composite merge-readiness gate (no min score).
  # off | advisory | block. Default: off.
  mergeReadiness: off

  # Manifest-policy gate. When `block`, this repo's declared policy from
  # section 1 (required linked issue, testExpectations) becomes an
  # enforceable blocker. Independent of mergeReadiness.
  # off | advisory | block. Default: off.
  manifestPolicy: off

  # Self-authored-linked-issue gate — blocks (or advises on) a PR whose only
  # linked issue was opened by the PR's own author, which the readiness/quality
  # signals can't otherwise catch. off | advisory | block. Default: advisory.
  # DB-backed (dashboard-settable too); this overrides the stored value.
  selfAuthoredLinkedIssue: advisory

  # Linked-issue satisfaction gate (#1961/#3906) — an AI assessment of whether
  # this PR's diff actually satisfies its PRIMARY linked issue's intent/
  # acceptance criteria (distinct from linkedIssue above, which only checks a
  # link EXISTS). off = the assessment never runs; advisory = it runs and
  # renders as a collapsible "Linked issue satisfaction" section in the review
  # comment, but never blocks; block = a confidence-floor-passing "unaddressed"
  # verdict ALSO becomes a hard blocker (linked_issue_scope_mismatch).
  # off | advisory | block. Default: off. DB-backed (dashboard-settable too);
  # this overrides the stored value. When unset, the review.linkedIssueSatisfaction
  # knob further below is used as a fallback instead (#4149) -- setting either
  # spelling has the same real effect; this one wins if both are set.
  linkedIssueSatisfaction: off

  # Content-lane linked-issue deliverable gate — only meaningful for a repo with
  # a registry content-lane spec resolved (see review/content-lane/spec-resolver.ts);
  # a no-op otherwise. When the PR's primary linked issue's own text names a path
  # matching that spec's entry/provider file pattern, the PR's changed files must
  # touch at least one matching file -- a PR that never touches the content lane
  # at all (e.g. adds only a regression test) cannot silently close a content-
  # delivery issue via a bare "Closes #N" reference. off = never checked;
  # advisory = a miss renders as a warning but never blocks; block = a miss
  # ALSO becomes a hard blocker (content_lane_deliverable_missing). Fully
  # deterministic (a text/path match, no AI call). off | advisory | block.
  # Default: off. DB-backed (dashboard-settable too); this overrides the stored
  # value.
  contentLaneDeliverable: off

  # Gate-check dry-run. When true, the posted check conclusion remains the real
  # non-enforcing verdict while comments/check text may also show the would-be
  # stricter verdict for AI-review blocker mode. It does not disable downstream
  # merge/close planning for failures from already-enforced gates. Bool.
  # Default: false. Config-as-code only — no DB column or dashboard toggle;
  # this can only be set here. Unrelated to settings.agentDryRun below despite
  # the shared "dry run" name -- this only affects the check-run's display
  # conclusion; it does NOT stop the agent action layer from real writes.
  dryRun: false

  # Live premerge migrations/** collision recheck (#2550, anti-abuse-adjacent safety net). When true, a PR
  # touching migrations/** gets a fresh GitHub read of the base branch's CURRENT migration filenames
  # immediately before an agent-driven merge (not just at CI time against this PR's own branch snapshot) —
  # catching the case where a DIFFERENT PR merged a same-numbered migration file in the meantime. A live
  # collision holds the PR (rebase-needed label + comment) instead of merging blind. Config-as-code only (no
  # dashboard/DB equivalent). Bool. Default: false. Costs one extra GitHub API call per migrations/**-touching
  # PR, so it is opt-in rather than a new default.
  premergeContentRecheck: false

  # Force-rebase-before-merge window in minutes (#2552, anti-race). When the base branch has advanced within
  # this many minutes of the actual merge-decision moment, an agent-driven merge forces an update_branch +
  # fresh CI recheck cycle before merging, instead of trusting a mergeable_state: clean read that may already
  # be stale relative to a sibling commit that just landed on the base. A bounded retry cap prevents a
  # fast-moving base from live-locking the PR — after a few forced attempts it falls through to a normal
  # merge with an audit note. Positive integer (minutes), or omit/null. Default: null (never force).
  # DB-backed (dashboard-settable too); this overrides the stored value.
  requireFreshRebaseWindow: 10

  # Stale-base auto-rebase threshold. When the repository's current default branch is at least this many
  # commits ahead of a PR's own base commit, the pre-review readiness gate forces an update_branch before
  # review runs — independent of GitHub's own mergeable_state "behind" signal, which only fires when the
  # repo's branch protection requires branches to be up to date before merging (a repo without that setting
  # can have a branch genuinely dozens of commits behind and never see it auto-rebased otherwise). Positive
  # integer (commit count), or omit/null. Default: null (never force via this path). Costs one extra GitHub
  # compare-API call per non-"behind" readiness check, so it is opt-in rather than a new default.
  # DB-backed (dashboard-settable too); this overrides the stored value.
  staleBaseAheadByThreshold: 10

  # AI maintainer review. Opt-in; the AI capabilities are switched on at the
  # deployment level.
  aiReview:
    # off | advisory | block. Default: off.
    #   advisory — posts AI review notes only.
    #   block    — a dual-model high-confidence consensus defect may become a
    #              blocker.
    mode: off
    # Use the maintainer's frontier model for the *advisory* write-up when a
    # provider key is configured. The consensus blocker always uses the free
    # Workers-AI pair, so BYOK never changes who can be blocked.
    # Bool. Default: false.
    byok: false
    # Review every PR author when AI review is enabled. Only has an effect
    # when `settings.aiReviewConfirmedContributorsOnly` (below) is also true --
    # otherwise every author is already reviewed by default.
    # Bool. Default: false.
    allAuthors: false
    # BYOK provider. anthropic | openai | null. Default: null (use the stored
    # key's own provider). Must match the stored key's provider or BYOK is
    # skipped (Workers-AI fallback). The key itself lives only in the encrypted
    # key store — never in this file.
    provider: null
    # Model override for the BYOK advisory write-up (e.g. claude-3-5-sonnet-latest).
    # String or null. Default: null (the key record's model, else a conservative
    # per-provider default).
    model: null
    # Minimum calibrated AI-reviewer confidence (0-1). Under `mode: block`,
    # consensus and split AI-review defects still BLOCK the gate regardless of
    # this floor — what varies below it is `lowConfidenceDisposition` below.
    # Number 0-1, or null. Default: null (engine uses 0.93). Config-as-code
    # only — no DB column or dashboard toggle; this can only be set here.
    closeConfidence: null
    # Disposition for a sub-closeConfidence-floor consensus/split defect (#4603).
    #   one_shot         — ignore the floor; always one-shot-close (today's
    #                      pre-#4603 behavior). Opt-in only.
    #   hold_for_review  — DEFAULT. Still blocks the merge, but holds for a
    #                      maintainer instead of one-shot-closing.
    #   advisory_only    — drop to a fully non-blocking advisory below the floor.
    # one_shot | hold_for_review | advisory_only, or null. Default: null (engine
    # uses hold_for_review). DB-backed (dashboard-settable too, via the
    # maintainer AI-review settings); this overrides the stored value.
    lowConfidenceDisposition: null
    # Per-repo override of the self-host operator's dual-AI combine strategy (#2567).
    # single | consensus | synthesis, or null. Default: null (the operator's own
    # AI_REVIEW_PLAN.combine env default, itself "consensus" if unset). A refinement
    # only -- not floor-clamped like onMerge below, since the three strategies aren't
    # ordered by strictness.
    combine: null
    # Per-repo override of the synthesis merge mode (#2567): "either" is STRICTER (any
    # one reviewer's blocker blocks/holds); "both" is more permissive (every reviewer
    # must agree). either | both, or null. Default: null (the operator's own plan). A
    # repo may only TIGHTEN the operator's floor -- it can never loosen "either" down
    # to "both".
    onMerge: null
    # Per-repo override of the named reviewer pair(s) to run, in place of the
    # operator's own AI_REVIEW_PLAN.reviewers (or the free Workers-AI pair when the
    # operator configured none). List of {model, fallback?}, or null. Default: null
    # (the operator's plan). No operator floor applies to which reviewers run.
    # reviewers:
    #   - model: claude-3-5-sonnet-latest
    #     fallback: claude-3-haiku-latest


# ----------------------------------------------------------------------------
# 3. REVIEW OUTPUT (`review:`) — tune review behavior + comment content
# ----------------------------------------------------------------------------
# These tune review output/behavior and PR-comment content, without changing the
# deterministic gate policy above. All values shown as `# key: value` comments are the
# safe defaults; omit or delete a line to keep the byte-identical default.
#
# SELF-HOST ONLY (`review.shared_config`, #2046): when `LOOPOVER_REPO_CONFIG_DIR` is mounted,
# place a shared review base at `${LOOPOVER_REPO_CONFIG_DIR}/_shared/.loopover.yml` (see
# `config/examples/shared.loopover.yml`). Per-repo `review:` keys overlay it field-by-field —
# repo value wins when set, shared fills gaps, defaults stay byte-identical. Absent shared base is
# the common case and changes nothing. A malformed shared base warns and is ignored (never blocks a
# review). The loader records provenance at runtime in `review.sharedConfigSource` (not a YAML key).
review:
  # Deterministic AI review eligibility filters (`review.auto_review`, #1954 / #2038–#2065). Each knob quietly
  # skips the advisory AI review for matching PRs — never a gate failure. When the Orb review check is enabled,
  # skipped PRs complete as "skipped" with a human-readable reason (see `evaluateAutoReviewSkipReason` in
  # `src/signals/focus-manifest.ts` and the public-surface `SKIP_SUMMARY.ignored_author` mapping in
  # `src/signals/settings-preview.ts`).
  #
  # Invariant: every field below defaults to off/empty/null, which is byte-identical to today's behavior — every
  # PR is reviewed exactly as before. Skips are quiet and never block merge on their own.
  auto_review:
    # Bool | null. Default: null (draft PRs are reviewed as today). When true, draft PRs skip AI review.
    # skip_drafts: true

    # Glob list of PR author logins whose PRs skip AI review. Useful for dependency bump or release automation
    # that already has separate policy/CI. `*` and `**` match any run; matching is case-insensitive.
    # Default: [] (every author remains review-eligible).
    ignore_authors:
      - "*[bot]"
      - dependabot
      - renovate

    # Case-insensitive title substrings that skip AI review (e.g. WIP/DRAFT markers). Default: [].
    # ignore_title_keywords:
    #   - WIP
    #   - DRAFT

    # Base-ref globs whose PRs ARE reviewed. When non-empty, PRs targeting other bases skip review.
    # Default: [] (every base branch is in scope).
    # base_branches:
    #   - main
    #   - release/**

    # Non-negative integer. After N published AI reviews on this PR, pause further re-reviews.
    # Default: null / 0 (re-review every sync, byte-identical).
    # auto_pause_after_reviewed_commits: 3

    # Case-insensitive PR label names that skip AI review (e.g. maintenance or do-not-review markers).
    # Default: [] (no label-based skip). (#2062)
    # skip_labels:
    #   - do-not-review
    #   - wip

    # Bool | null. Default: null (docs-only PRs are reviewed as today). When true, PRs whose every
    # changed file classifies as documentation skip AI review. Empty changed-file list is NOT docs-only. (#2063)
    # skip_docs_only: true

    # Non-negative integer. Skip AI review when total added lines across the PR diff exceed this cap.
    # Default: 0 (no cap — reviewed regardless of size). (#2065)
    # max_added_lines: 500

    # Non-negative integer. Skip AI review when changed-file count exceeds this cap.
    # Default: 0 (no cap). (#2065)
    # max_files: 25

  # Unified-comment display toggles (#1957 / #1955 / #2069). Bool | null. Default: null/false — byte-identical.
  # changed_files_summary: false
  # When true, the unified review comment gains a deterministic "Changed files" summary table.
  # effort_score: false
  # When true, the unified review comment gains a compact "review effort: N/5 (~M min)" chip.

  # Bool | null. Default: null/false — byte-identical (#2184, part of #1971). Also requires the operator's
  # LOOPOVER_REVIEW_IMPACT_MAP env flag to be on — this manifest field alone cannot enable it. When both are
  # on, a deterministic impact map (which other repo files plausibly need re-checking, from the RAG index +
  # changed symbols) is computed, rendered as a compact section in the unified review comment, and fed to the
  # AI reviewer as additive reference context.
  # impact_map: false

  # When true, the AI reviewer's prompt gains an additive "repo quality-culture profile" reference block --
  # typical merged-PR size + common accepted labels, derived from this repo's own merge history. Reference-only
  # grounding; never a gate/scoring input. Requires operator flag LOOPOVER_REVIEW_CULTURE_PROFILE. Bool or
  # null. Default: null/false — byte-identical. (#2995)
  # culture_profile: false

  # Per-repo FORCE-OFF for the self-improvement/auto-tune cron pass (#4104) -- `false` excludes this repo from
  # tuning even though it's otherwise agent-configured and the operator's LOOPOVER_REVIEW_SELFTUNE flag is on.
  # Deliberately FORCE-OFF-ONLY (no `true` override): unlike most `review.*` toggles above, this does NOT live
  # under a per-repo allowlist -- selftune's own scoping is whether the repo already opted into the
  # acting-autonomy surface, a separate consent boundary this key must not bypass. Bool or null. Default:
  # null/true -- no change to today's agent-configured-repos-only behavior.
  # selftune: false

  # Per-repo FORCE-OFF for the sweep-liveness watchdog cron pass (#6275) -- `false` excludes this repo from the
  # watchdog's scan even though it's otherwise watched (convergence-allowlisted, or agent-configured with a real
  # installation) and the operator's LOOPOVER_SWEEP_WATCHDOG flag is on. Deliberately FORCE-OFF-ONLY (no `true`
  # override), mirroring `selftune` above: forcing a repo the watchdog wouldn't otherwise watch INTO the scan
  # would bypass that separate repo-selection boundary. Bool or null. Default: null/true -- no change to today's
  # watched-repo-set behavior.
  # sweepWatchdog: false

  # Per-repo FORCE-OFF for the fast open-PR reconciliation cron pass (#6275) -- `false` excludes this repo from
  # the reconciliation scan even though it's otherwise watched and the operator's LOOPOVER_PR_RECONCILIATION
  # flag is on. Deliberately FORCE-OFF-ONLY (no `true` override), mirroring `selftune`/`sweepWatchdog` above.
  # Bool or null. Default: null/true -- no change to today's watched-repo-set behavior.
  # prReconciliation: false

  # Per-repo FORCE-OFF for the active-review-tracking reconciliation sweep (#webhook-reorder-clobber) --
  # `false` excludes just this repo's rows from the sweep's scan even though the operator's
  # LOOPOVER_ACTIVE_REVIEW_RECONCILIATION flag is on. Deliberately FORCE-OFF-ONLY (no `true` override),
  # mirroring `prReconciliation` immediately above. Bool or null. Default: null/true -- no change to today's
  # scanned-row-set behavior.
  # activeReviewReconciliation: false

  # Repeat-false-positive suppression (#2179, part of #1964). Bool | null. Default: null/false — byte-identical
  # (no suppression-store read, no matching). Also requires the operator's LOOPOVER_REVIEW_MEMORY env flag to
  # be on -- this manifest field alone cannot enable it. When both are on, an advisory (non-blocking) AI finding
  # is matched against this repo's stored review_suppression signals (a maintainer's own past false-positive
  # dismissals) before it is surfaced, and demoted/dropped on a match. ADVISORY-ONLY: never applied to gate
  # blockers -- it can never change the merge/close disposition.
  # memory: false

  # Display-only floor for inline AI findings. Findings below the configured level are suppressed from inline
  # comments — never from gate blockers. Default: null (show all). NOTE: inline findings currently occupy only
  # two of the four severity tiers — `blocker` (ranked `critical`) and `nit` (ranked `nitpick`) — so only two
  # floors are actually distinguishable: `critical` shows blockers only, and `nitpick` shows everything. `major`
  # and `minor` behave identically to `critical` (blocker-only) today, NOT an intermediate level.
  # min_finding_severity: critical

  # Display-only caps on how many blocker/nit lines render in the unified comment (#2049).
  # Never removes a blocker from the gate decision — truncation applies to display only.
  # max_findings:
  #   blockers: 5
  #   nits: 8

  # How much of the unified review comment's collapsible detail renders (#2047). `quiet` drops the Nits
  # collapsible and every extra collapsible section (blockers/gate result/signals are unaffected — this only
  # trims decorative detail); `detailed` renders every collapsible pre-expanded instead of collapsed.
  # quiet | normal | detailed. Default: null/normal (byte-identical).
  # comment_verbosity: normal

  # How a `@loopover generate-tests` result is delivered, once features.e2eTests is on (#4197, part of
  # the #4189 E2E-test-generation epic). `comment` (default, null/absent) posts the generated test as a
  # reply comment only. `commit` pushes it as a real commit onto the PR's own head branch instead -- a
  # bigger blast radius, so it stays opt-in even with e2eTests already enabled. `commit` mode is ALSO
  # blocked at runtime (regardless of this setting) for a PR whose author is a confirmed Gittensor miner,
  # to protect the externally-computed score from ever including a maintainer-authored line the miner
  # didn't write themselves.
  # comment | commit. Default: null/comment (byte-identical -- no write access to any PR branch).
  # e2e_test_delivery: comment

  # Opts THIS repo into the manifest_missing_tests AUTO-TRIGGER (#4196, part of the #4189 epic) -- an
  # unprompted generation run whenever a PR looks like it needs tests. Separate from features.e2eTests, which
  # only unlocks the maintainer-initiated paths (the `@loopover generate-tests` command and the PR-panel
  # checkbox). Bool | null. Default: null/false -- the auto-trigger never fires, even with e2eTests already
  # on; a maintainer who wants unprompted generation opts in here explicitly, per repo.
  # e2e_test_auto_trigger: false

  # Inline-comment layer toggles (#1956 / #1958). Bool | null. Default: null/false — byte-identical.
  # Requires operator flag LOOPOVER_REVIEW_INLINE_COMMENTS + cutover allowlist + review.inline_comments: true.
  # inline_comments: false
  # When true, the AI reviewer ALSO leaves quiet, non-blocking inline PR comments on specific changed lines.
  # suggestions: false
  # When true, inline findings with precise fixes render as one-click suggestion blocks (requires inline_comments).
  # finding_categories: false
  # inline_comments_per_category: 3

  # Fix-handoff blocks (#2176). Bool | null. Default: null/false — byte-identical.
  # Requires operator flag LOOPOVER_REVIEW_FIX_HANDOFF + cutover allowlist AND this toggle.
  # fixHandoff: false

  # Read-only auto-merge readiness summary (#2051). Bool | null. Default: null/false — byte-identical.
  # When true, the unified comment gains a collapsible showing which auto-merge conditions currently pass/fail
  # (CI green, gate passing, mergeable-clean, valid linked issue). SURFACE ONLY — never changes the decision.
  # auto_merge_summary: false

  # Maintainer AI review-prompt + panel-content tuning (#6071 -- merged in from a second,
  # disconnected `review:` block that used to live ~500 lines further down in this file).
  # These shape the advisory AI review prompt/file-selection/panel content only -- gate/
  # slop/secret-scan are unaffected.
#   # Globs whose matching files are dropped from the AI review (lockfiles, generated output, etc.).
#   # Applied before path_filters. Empty/default ⇒ every file is reviewed.
#   exclude_paths:
#     - "**/*.lock"
#     - "dist/**"
#   # Include + `!`-negation globs that positively scope the AI review AFTER exclude_paths.
#   # Plain entries restrict to matching paths; a leading `!` subtracts matches. Both `*` and `**` cross
#   # directory slashes. Empty/default ⇒ every non-excluded file is reviewed (byte-identical).
#   path_filters:
#     - "src/**"
#     - "!src/generated/**"
#   # Public-safe voice brief complementing review.profile (e.g. concise, cite line numbers). null/unset ⇒ byte-identical prompt.
#   tone: "Be concise and cite line numbers."
#   # How nitpicky the AI maintainer review is. chill | balanced | assertive. Default: balanced (absent).
#   # chill = only blocking defects; assertive = also minor nits. Never changes the gate verdict.
#   profile: balanced
#   # When true, the reviewer prioritizes a security-defect category with elevated scrutiny, on top of
#   # whatever `profile` volume is set. Bool or null. Default: null/false (byte-identical prompt).
#   security_focus: false
#   # A repo-level natural-language brief handed to the AI reviewer on EVERY review (vs the per-path
#   # path_instructions below) -- the maintainer's conventions/voice. Bounded + public-safe at parse time.
#   # String or null. Default: null (byte-identical prompt). Also feeds AI-generated E2E test coverage
#   # (features.e2eTests, #4190/#4189) when that feature is enabled -- the same conventions brief steers
#   # both the AI reviewer and the AI test generator, so you only write it once.
#   instructions: "Prefer small, focused PRs. Flag any missing test for a bug fix."
#   # Per-path natural-language guidance handed to the AI reviewer when a changed file matches the glob.
#   # Empty/default ⇒ byte-identical prompt. Also feeds AI-generated E2E test coverage the same way as
#   # `instructions` above, for path-scoped rules ("always test the payment-failure retry path").
#   path_instructions:
#     - path: "src/db/**"
#       instructions: "Flag any migration missing a matching down-path note."
#   # How strictly a linked issue must actually be SATISFIED by the PR (distinct from linkedIssuePolicy,
#   # which only checks a link EXISTS). off = not evaluated; advisory = surface a finding; block = can
#   # become a hard blocker (confirmed-contributor-gated). Fallback alias for gate.linkedIssueSatisfaction
#   # above (#4149) -- used only when that field is unset; setting either spelling has the same real effect.
#   # off | advisory | block. Default: off (byte-identical when unset).
#   linkedIssueSatisfaction: off
#   # Maintainer-declared DETERMINISTIC content assertions (title/description must contain a phrase, a
#   # label must be present), optionally gated to a path glob. A failed check is advisory by default;
#   # `enforce: true` makes it a hard gate blocker. Empty/default ⇒ no finding (no AI judgment involved).
#   pre_merge_checks:
#     - name: "require a linked issue reference in the description"
#       description_contains: "Fixes #"
#       enforce: false
#   # Per-repo REES enrichment-analyzer toggles (analyzer name -> on/off). Unknown keys warn + drop at
#   # parse. Empty/default ⇒ the operator's default analyzer set runs unchanged.
#   enrichment:
#     deep-nesting: true
#     error-swallow: false
#   # 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 ⇒ the operator's global env vars apply.
#   ai_model:
#     claude_model: null   # Overrides CLAUDE_AI_MODEL for this repo. String or null.
#     claude_effort: null  # Overrides CLAUDE_AI_EFFORT for this repo. String or null. Default (env unset): medium.
#     codex_model: null    # Overrides CODEX_AI_MODEL for this repo. String or null.
#     codex_effort: null   # Overrides CODEX_AI_EFFORT for this repo. String or null. Default (env unset): medium.
#     ollama_model: null   # Overrides OLLAMA_AI_MODEL for this repo's ollama reviewer. String or null. (#3902)
#     openai_model: null   # Overrides OPENAI_AI_MODEL for this repo's openai reviewer. String or null. (#3902)
#     openai_compatible_model: null  # Overrides OPENAI_COMPATIBLE_AI_MODEL for this repo. String or null. (#3902)
#     anthropic_model: null  # Overrides ANTHROPIC_AI_MODEL for this repo's BYOK Messages API reviewer. String or null. (#3902)
#   # Per-repo before/after screenshot-capture config (#3609 preview / #3610 routes). Only takes effect when
#   # the operator has ALSO enabled LOOPOVER_REVIEW_SCREENSHOTS + this repo's cutover allowlist -- this
#   # config narrows/redirects that feature, it never turns it on by itself. All-null/empty/default ⇒
#   # byte-identical to today (GitHub-native preview discovery, automatic file-to-route inference).
#   visual:
#     # 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 below. Must resolve
#     # to a valid HTTPS URL targeting a public host (same SSRF guard as preview.url_template). String or null.
#     # Default: null (falls back to PUBLIC_SITE_ORIGIN).
#     production_url: "https://example.com"
#     preview:
#       # The repo's "after" preview URL, with {number}/{head_sha}/{head_sha_short} placeholders substituted
#       # at capture time. ALWAYS wins over GitHub-native preview discovery (Deployments API / commit checks /
#       # cloudflare-bot PR comment) when set -- the only option for a provider (e.g. Cloudflare Workers
#       # Builds' non-production branch builds) that never surfaces a GitHub-visible deployment at all. Must
#       # resolve to a valid HTTPS URL targeting a public host. String or null. Default: null (discovery unchanged).
#       url_template: "https://pr-{number}.myapp.workers.dev"
#     routes:
#       # An explicit, always-screenshotted route list. When non-empty, REPLACES automatic file-to-route
#       # inference entirely -- for a repo whose routing convention isn't loopover-ui's TanStack file-based
#       # one. Empty/default ⇒ automatic inference (falling back to "/" when nothing matches).
#       paths:
#         - "/pricing"
#         - "/docs"
#       # Overrides the built-in cap (2) on how many routes get screenshotted per PR, whether they come from
#       # `paths` above or automatic inference. Positive integer or null. Default: null (built-in default).
#       max_routes: 3
#     # Which `prefers-color-scheme` variants to capture (#3678). List of "light"/"dark", each rendered as a
#     # separate before/after row. Empty/default ⇒ a single light-theme capture, byte-identical to today.
#     themes:
#       - light
#       - dark
#     # The localStorage key to ALSO force `theme` into (plus a reload) before rendering (#4109) -- a
#     # fallback for a target whose theming reads an explicit stored preference instead of consulting
#     # `prefers-color-scheme` (VERIFIED: emulateMediaFeatures alone has zero effect on that class of app,
#     # since it only changes what CSS media queries / matchMedia report -- it never touches localStorage).
#     # Only takes effect when `themes` above is also configured. String or null. Default: null (no
#     # localStorage write, no reload -- byte-identical to today).
#     theme_storage_key: "theme"
#     # Also capture a short scroll-through GIF per route (desktop only) — evidence for scroll-linked behavior
#     # (parallax, reveal-on-scroll, a sticky header) that a static screenshot can't show (#3612). Rendered as
#     # a separate "Scroll preview" section alongside the static before/after table, never replacing it.
#     # SELF-HOST ONLY (no effect on the hosted service) and the heaviest capture mode here — up to 6 extra
#     # renders per side, ~4s wall-clock per side measured in practice. Bool. Default: false (no scroll capture).
#     gif: false
#     # Specific elements to interact with (hover/click/drag) and capture as animated evidence — for
#     # behavior a static screenshot AND a scroll-through GIF can't show: a hover-triggered popover, a
#     # click-triggered state change, a drag-and-drop reorder, a CSS transition. Rendered as its own
#     # "Interaction preview" section, one row per entry (never multiplied by viewport/theme, unlike the
#     # static matrix above — an interaction is rarely breakpoint- or theme-dependent). Empty/default ⇒
#     # byte-identical to today, no interaction capture. SELF-HOST ONLY (same gate as `gif` above) and
#     # capped at 5 configured / 3 actually captured per PR.
#     interactions:
#       - selector: ".blocks-table-row"  # CSS selector for the element to interact with (drag SOURCE for "drag"). Required.
#         action: hover                  # "hover", "click", or "drag". Required.
#         path: "/blocks"                # Route this interaction lives on. String or null. Default: "/".
#         label: "Blocks table row hover" # PR-comment row caption. String or null. Default: the selector itself.
#       - selector: ".kanban-card"       # A second entry showing the "drag" shape:
#         action: drag
#         drag_to: ".done-column"        # Drag DESTINATION selector. Required when action is "drag"; an entry
#                                         #   missing it is dropped at parse time. Ignored for hover/click.
#         label: "Reorder card into Done"
#     # Zero-configuration alternative to interactions above: capture a hover-interaction GIF for any CSS
#     # selector THIS PR'S OWN DIFF newly adds a `:hover`/`:focus-visible` rule for -- no maintainer selector-
#     # authoring needed at all. Scoped to plain .css/.scss/.sass/.less files (a Tailwind utility class or
#     # CSS-in-JS `:hover` state has no selector to extract this way). Composes with interactions above (a
#     # manually-configured selector always wins over the same one auto-detected); both draw from the SAME
#     # 3-per-PR cap. Bool. Default: false (byte-identical to today, no auto-detection). SELF-HOST ONLY (same
#     # gate as interactions/gif above).
#     auto_detect_interactions: true
#     # Config-as-code enable/disable for this repo, layered ON TOP OF (never a replacement for) the
#     # LOOPOVER_REVIEW_SCREENSHOTS + per-repo cutover-allowlist env-var gate above (#4083). Bool or null.
#     # Default: null (unset) ⇒ defers entirely to that env-var gate's own decision -- byte-identical to today.
#     # Explicit `false` (set once at the global-default `.loopover.yml`, or overridden per-repo here) forces
#     # capture off for this repo even when the env-var gate would otherwise allow it. Explicit `true` opts this
#     # repo back in at a layer where a broader default disabled it -- it does NOT bypass the env-var gate
#     # itself, so the env vars remain the outer infra-availability switch.
#     enabled: true
#     # When true, and ONLY when the discovery above finds no preview at all for a PR, dispatch
#     # .github/workflows/visual-capture-fallback.yml -- a fork-safe GitHub Actions job (contents: read, no
#     # secrets) that builds, serves, and screenshots the PR's own code, and use its captured PNGs as the
#     # "after" shot instead. Requires that workflow file to be present in this repo (copy it from
#     # JSONbored/loopover unmodified -- see the workflow's own header for setup). Bool. Default: false (no
#     # dispatch, byte-identical to today). Not needed for loopover-ui / metagraphed, which already have
#     # their own preview-deploy pipeline. (#4112, part of the #3607 visual-capture convergence epic)
#     actions_fallback: false
#     # PR-intent-aware vision analysis + out-of-scope issue flagging. When true, the SAME before/after
#     # vision call above (gated on pixel-diff + reputation + a vision-capable provider, see
#     # evaluateVisualVisionGate) uses an enhanced prompt that also sees this PR's own stated title/
#     # description, and separates a genuine defect THIS PR introduced ("regression", rendered exactly as
#     # today) from a pre-existing problem the screenshots happen to reveal that has nothing to do with the
#     # PR's stated change ("unrelated" — its own advisory finding, suggesting a NEW issue be opened for it
#     # rather than reading like something this PR broke). Never a gate blocker either way. Bool. Default:
#     # false (the original regression-only prompt, no PR context sent, byte-identical to pre-bugAnalysis).
#     bug_analysis: false
#     # GitHub logins to @-mention on the standalone follow-up comment posted when a PR with a recorded
#     # "unrelated" bug_analysis finding above is merged OR closed — describes each finding with its before/
#     # after screenshots, formatted so GitHub's own "..." -> "Reference in new issue" action can spin one off
#     # in one click. List of strings. Default: [] (empty) -- NOT hardcoded to a specific user; falls back at
#     # RUNTIME to this repo's owner + the ADMIN_GITHUB_LOGINS fleet-operator allowlist, the same "maintainer"
#     # resolution used elsewhere. Capped at 10 entries. (#7372)
#     bug_analysis_notify: []
#   # Maintainer overrides for the public review-panel CONTENT (not what loopover measures). The
#   # Gittensor attribution + register link is always appended to the footer regardless; maintainer text
#   # failing the public-safe filter is dropped, never published.
#   footer:
#     text: "Reviewed by the Acme maintainer bot."  # Custom lead line. String or null. Default: null.
#   note: "Run the test suite before requesting review."  # Short intro line shown above the panel. String or null.
#   # Per-row show/hide toggles for the panel. Keys: linkedIssue | relatedWork | reviewLoad |
#   # validationEvidence | openPrQueue | contributorContext | gateResult | improvementSignal. Default: all
#   # shown (true). improvementSignal (#4744) only ever renders content when the `improvementSignal` converged
#   # feature (see `features:` below) is ALSO active for this repo -- this toggle just hides that row/section
#   # like any other; it never turns the feature itself on.
#   fields:
#     relatedWork: false
#     openPrQueue: false

# ----------------------------------------------------------------------------
# 4. GENERIC SETTINGS (`settings:`) — dashboard-equivalent overrides
# ----------------------------------------------------------------------------
# Everything a maintainer can toggle in the dashboard can be set here as code.
# All values shown are the safe defaults; delete any line to inherit it.
settings:
  # The 11 fields below each have a friendlier `gate.<name>` alias documented in section 2 above
  # (`gate.checkMode`/`gate.enabled`, `gate.linkedIssue`, `gate.duplicates`, `gate.readiness.mode`/
  # `gate.readiness.minScore`, `gate.selfAuthoredLinkedIssue`, `gate.aiReview.mode`/`.byok`/`.provider`/
  # `.model`/`.allAuthors`). `gate.*` is the RECOMMENDED spelling going forward and wins whenever both
  # forms are set for the same field (see PRECEDENCE at the top of this file). The generic names below
  # remain fully supported (no functional deprecation, still DB-backed) and are shown here, commented
  # out, only so this reference stays discoverable for a config written before the `gate:` alias
  # existed. Prefer `gate.*` above for anything new.
  # reviewCheckMode: visible                   # alias of gate.checkMode / gate.enabled
  # linkedIssueGateMode: advisory               # alias of gate.linkedIssue
  # duplicatePrGateMode: block                  # alias of gate.duplicates
  # qualityGateMode: advisory                   # alias of gate.readiness.mode
  # qualityGateMinScore: null                   # alias of gate.readiness.minScore
  # selfAuthoredLinkedIssueGateMode: advisory   # alias of gate.selfAuthoredLinkedIssue
  # aiReviewMode: off                           # alias of gate.aiReview.mode
  # aiReviewByok: false                         # alias of gate.aiReview.byok
  # aiReviewProvider: null                      # alias of gate.aiReview.provider
  # aiReviewModel: null                         # alias of gate.aiReview.model
  # aiReviewAllAuthors: false                   # alias of gate.aiReview.allAuthors

  # Who receives the public PR comment.
  # off | detected_contributors_only | all_prs. Default: detected_contributors_only.
  commentMode: detected_contributors_only

  # Public audience framing. oss_maintainer | gittensor_only. Default: oss_maintainer.
  publicAudienceMode: oss_maintainer

  # How much signal the public surface shows. minimal | standard. Default: standard.
  publicSignalLevel: standard

  # Publish a GitHub check-run. off | enabled. Default: off.
  # Independent, legacy advisory surface (#2691) -- separate from, and not gated
  # by, the required `LoopOver Orb Review Agent` gate check under `gate:`
  # above. At the default `checkRunDetailLevel: minimal` below it posts no
  # findings at all; at standard/deep it only re-renders findings already shown
  # in the gate check and the PR comment. One-shot self-host installs should
  # leave this at the default `off` unless you specifically want a second,
  # low-detail check-run surface alongside the required gate check.
  checkRunMode: off

  # Check-run detail. minimal | standard | deep. Default: minimal.
  checkRunDetailLevel: minimal

  # Sweep order. staleness | oldest-first. Default: staleness.
  regateSweepOrderMode: staleness

  # Which public surfaces are used.
  # off | comment_and_label | comment_only | label_only. Default: comment_and_label.
  publicSurface: comment_and_label

  # Apply the gittensor label automatically. Bool. Default: true.
  autoLabelEnabled: true

  # The label name to apply. String. Default: gittensor.
  gittensorLabel: gittensor

  # Apply the per-PR TYPE/taxonomy label -- bug/feature by the PR title, or priority via
  # `linkedIssueLabelPropagation` below (#label-decoupling). Independent of `autoLabelEnabled` above
  # (which only governs the base `gittensorLabel` context label): a type label is internal triage
  # metadata, so it applies to every PR regardless of author type (bot/maintainer/missing author) or
  # `publicAudienceMode`/`publicSurface`, UNLESS `publicAudienceMode: gittensor_only` is muting this
  # PR's author entirely (that mode's whole point is total silence for a non-confirmed-miner author).
  # Bool. Default: true.
  typeLabelsEnabled: true

  # Per-repo TYPE label config: an open `category -> label name` map, not fixed to three names.
  # `bug`/`feature`/`priority` are the built-in categories `deriveKindFromTitle` and
  # `linkedIssueLabelPropagation` classify (default gittensor:bug / gittensor:feature /
  # gittensor:priority, shown below as an EXAMPLE, not an engine requirement) -- omit any of the three
  # to keep its default. Add any number of your OWN categories beyond them (they are never chosen by
  # title-classification, only ever by a `linkedIssueLabelPropagation` mapping below, but registering
  # the name here makes it participate in the same mutual-exclusivity cleanup). An explicit `{}` means
  # zero configured categories for this repo -- distinct from omitting `typeLabels` entirely, which
  # inherits whatever the dashboard/API has stored.
  # typeLabels:
  #   bug: gittensor:bug
  #   feature: gittensor:feature
  #   priority: gittensor:priority
  #   security: area:security
  #   docs: area:docs
  #   dependency: area:dependency
  #   custom: maintainer:custom

  # Per-repo opt-out for `loopover_plan_repo_issues` (#7429), the selfhoster-facing AI issue-planning MCP
  # tool -- when false, the tool returns a `disabled` status without ever calling the model. The tool is
  # already gated behind MCP maintainer access and the fleet-wide AI_SUMMARIES_ENABLED/
  # AI_PUBLIC_COMMENTS_ENABLED switches, so this is an additional per-repo layer, not the primary gate.
  # Bool. Default: true.
  issuePlanEnabled: true

  # Additional label names `loopover_plan_repo_issues` suggests to the model alongside the repo's real
  # GitHub labels and (when gittensor-enrolled) its type-label taxonomy -- e.g. a project-specific
  # category not yet created as a real label. Purely additive; never removes or replaces the repo's own
  # labels. Array of strings. Default: [].
  # issuePlanExtraLabels:
  #   - area:docs
  #   - needs-triage

  # Whether `loopover_plan_repo_issues` attempts to reuse an existing OPEN milestone by exact
  # normalized-title match before creating a new one. A repo that always wants a fresh milestone per
  # planning session (e.g. date-stamped titles) can set this false to skip the reuse lookup entirely.
  # Bool. Default: true.
  issuePlanMilestoneReuse: true

  # Linked-issue label propagation (#priority-linked-issue-gate): the ONLY mechanism that can select a
  # label like `gittensor:priority` -- it is NEVER inferred from a PR's title, changed files, AI
  # output, or existing PR labels, only ever copied from a linked/closing issue ("Fixes #123") that
  # ALREADY carries the configured issue label. Generic beyond the priority use case: any issue label
  # can map to any PR label. `removeOtherTypeLabels: true` marks the mapping EXCLUSIVE -- it REPLACES
  # the type label entirely (bug/feature are removed), for genuinely mutually-exclusive categories; when
  # more than one applies, the LAST-configured exclusive match wins -- declare exclusive mappings in
  # ASCENDING precedence order (lowest-value category first, e.g. bug before feature) so the highest-
  # precedence one you actually want is declared last. `false` (e.g. `gittensor:priority`,
  # which is a reward tag that coexists WITH whichever type already applies, not a type of its own) applies
  # the mapped label ADDITIVELY alongside whichever exclusive match (or the normal title-based bug/feature
  # label) already won -- every additive match composes together rather than competing for a single slot.
  # Each mapping normally requires the PR author to be the linked issue's own author or a GitHub assignee of
  # it (`trustMaintainerAuthoredIssue: true` relaxes this for a routine, non-reward category like bug/feature
  # -- see the field's own doc comment in `types.ts`). `trustMaintainerAuthoredIssueForReward: true` opts a
  # REWARD mapping like `gittensor:priority` into that same relaxation: without it, a mapping like this can
  # structurally never propagate to most external contributors, since GitHub silently refuses to assign
  # anyone lacking push/triage access to the repo -- so if your issues are open-pickup (maintainer-authored,
  # rarely formally assigned to a specific contributor), the reward label needs this flag to ever reach them.
  # Disabled by default (no mappings) -- a self-hoster opts in per repo. If your labels carry reward or
  # moderation weight, configure this in PRIVATE per-repo/global config (see `config/examples/README.md`)
  # rather than the public `.loopover.yml`, so contributors cannot see the exact mapping rules. A per-repo
  # `mappings` override in the private-config layer REPLACES the global default list wholesale -- it does
  # not merge with it.
  # linkedIssueLabelPropagation:
  #   enabled: true
  #   mode: exclusive_type_label
  #   mappings:
  #     - issueLabel: gittensor:priority
  #       prLabel: gittensor:priority
  #       removeOtherTypeLabels: false
  #       trustMaintainerAuthoredIssueForReward: true

  # Create the label if it does not yet exist. Bool. Default: true.
  createMissingLabel: true

  # Auto-assign a merged/linked-issue PR to a matching GitHub Project/Milestone (#3186). off | suggest |
  # auto. Default: off. "suggest" posts an advisory note only; "auto" applies the match directly.
  # autoProjectMilestoneMatch: off
  # Which backend the match runs against. github | linear. Default: github. "linear" matches against a
  # Linear workspace via a per-repo encrypted API key (set via the dashboard, never here).
  # autoProjectMilestoneMatchBackend: github

  # Also review PRs authored by maintainers (not just detected contributors).
  # Bool. Default: false.
  includeMaintainerAuthors: false

  # Standing rule: the repo OWNER's own PRs (and ADMIN_GITHUB_LOGINS fleet-operator PRs, #2133) are NEVER
  # auto-closed by default -- they may still auto-merge when clean + passing, or fall to a manual hold.
  # Set true to make owner/admin-authored PRs eligible for auto-close like a contributor's (still gated by
  # the `close` autonomy class below + adverse-signal conditions). Automation-bot PRs stay exempt regardless
  # of this setting. Bool. Default: false.
  closeOwnerAuthors: false

  # AI review, gate evaluation, and public-surface publish are skipped ENTIRELY for a PR/event genuinely
  # triggered by a known automation bot (release-please, Renovate, Dependabot). "inherit" defers to the
  # self-host operator's LOOPOVER_SKIP_AUTOMATION_BOT_PRS env default (itself default-ON); "off"/"enabled"
  # override that default in either direction for this repo. inherit | off | enabled. Default: inherit.
  # skipAutomationBotAuthors: inherit

  # Duplicate-winner adjudication (#dup-winner): when several open PRs link the same
  # issue, off (the legacy default) closes EVERY sibling as a duplicate; on spares the
  # earliest claimant. "inherit" defers to the self-host operator's
  # LOOPOVER_DUPLICATE_WINNER env default (itself off by default); "off"/"enabled"
  # override that default in either direction for this repo.
  # inherit | off | enabled. Default: inherit.
  # duplicateWinnerMode: inherit

  # Open-PR file-path collision annotations (#2653): enriches preflight/queue-health
  # output with which open PRs touch overlapping files -- display-only, never a
  # close/gate blocker. Costs an extra GitHub API round-trip per open PR, so this is
  # opt-in and off by default. "inherit" defers to the self-host operator's
  # LOOPOVER_OPEN_PR_FILE_COLLISION env default (itself off by default); "off"/"enabled"
  # override that default in either direction for this repo.
  # inherit | off | enabled. Default: inherit.
  # openPrFileCollisionMode: inherit

  # `@loopover plan` issue command (#issue-coding-plan): on a maintainer's request, generates a concise
  # implementation plan from an issue's text and posts it as a comment. "inherit" defers to the self-host
  # operator's LOOPOVER_REVIEW_PLANNER env default (itself off by default); "off"/"enabled" override that
  # default in either direction for this repo.
  # inherit | off | enabled. Default: inherit.
  # plannerMode: inherit

  # Hard manual-review path guardrails are config-as-code only. Safe by default (#3943): whatever you list
  # here is ADDED to a fixed, built-in invariant set (CI workflows/scripts, deploy config, config-as-code
  # files, core engine-decision paths — see DEFAULT_HARD_GUARDRAIL_GLOBS in src/review/guardrail-config.ts)
  # that an ordinary edit here can only ever widen, never shrink. Bool. Default: [].
  hardGuardrailGlobs: []

  # Opt-in escape hatch: set true to make hardGuardrailGlobs above REPLACE (not add to) the built-in
  # invariant set, including using [] to disable path guardrails entirely. A deliberate, separately-visible
  # decision — only set this if you specifically want full control over your own guardrail list instead of
  # the safe-by-default add-only behavior. Bool. Default: false.
  hardGuardrailGlobsOverridesInvariants: false

  # Restrict AI review (gate.aiReview.mode above) to confirmed Gittensor contributors only. Default:
  # false -- AI review runs for EVERY PR author once aiReview.mode is not off, since security/quality
  # review should not be weaker for a new or unconfirmed contributor's PR than for an established one's.
  # Set true only if you deliberately want to bound AI spend to registered miners; gate.aiReview.allAuthors
  # above can then still widen back out to every author within that narrowed mode. Bool. Default: false.
  aiReviewConfirmedContributorsOnly: false

  # Require a linked issue on every PR (dashboard equivalent of the toggle that
  # can auto-promote gate.linkedIssue to block). Bool. Default: false.
  requireLinkedIssue: false

  # Backfill review of pre-existing open PRs when first installed.
  # Bool. Default: true.
  backfillEnabled: true

  # Render a README status badge for the repo. Bool. Default: false. Config-as-code only (Batch A
  # follow-up, loopover#6442) -- no DB column or dashboard toggle.
  badgeEnabled: false

  # Publish a public per-repo review-quality page. Bool. Default: false. Config-as-code only (Batch A
  # follow-up, loopover#6442) -- no DB column or dashboard toggle.
  publicQualityMetrics: false

  # Per-repo kill-switch: when true, the agent does nothing on this repo.
  # Bool. Default: false.
  agentPaused: false

  # Dry-run / shadow mode: suppresses the terminal GitHub-side write only. AI/LLM review calls still
  # execute and still incur their normal provider cost -- this is NOT a cost-free preview.
  # Independent of gate.dryRun above -- the two "dry run" fields gate entirely disjoint layers.
  # Bool. Default: false.
  agentDryRun: false

  # Four independent label families, none of which gates or silently disables another (#label-decoupling,
  # #label-scoping):
  #   1. Context label (`gittensorLabel`, gated by `autoLabelEnabled` above) — the base per-PR marker shown
  #      to the public surface, subject to `publicAudienceMode`/`publicSurface`/author-qualification.
  #   2. Taxonomy/type labels (`typeLabels` above, gated by `typeLabelsEnabled`) — internal triage
  #      metadata, applied independently of #1. Shown above with the gittensor:* default names, but
  #      the category set itself is config, not fixed to three (#label-modularity): bug/feature come
  #      from the PR title; priority (or any other category you register) ONLY from
  #      `linkedIssueLabelPropagation` above — never inferred from title, files, AI, or existing PR
  #      labels (#priority-linked-issue-gate).
  #   3. Autonomy-outcome labels (`loopover:ready-to-merge` etc.) — gated by the `review_state_label`
  #      autonomy class below, advisory commentary on the bot's own verdict.
  #   4. Anti-abuse enforcement labels (blacklist/contributor-cap/review-nag) — gated by the `close`
  #      autonomy class below, applied alongside the close action they accompany.
  #
  # Autonomy dial — per-action-class level (observe … auto). Classes: review, request_changes, approve,
  # merge, close, label, review_state_label, update_branch. Map. Default: {} (= observe everywhere,
  # deny-by-default).
  #
  # `label` vs `review_state_label` (#label-scoping): these are SEPARATE, independent dials.
  #   - `label` alone no longer applies any planner-driven label by itself. The anti-abuse enforcement
  #     labels (blacklist/contributor-cap/review-nag) ride on the SAME dial as their accompanying close
  #     (`close`, below) — set `close: auto` and they close-and-label together with no `label` grant needed.
  #   - `review_state_label` gates the bot's own disposition-communication labels only:
  #     loopover:ready-to-merge / loopover:changes-requested / loopover:needs-human-review /
  #     loopover:migration-collision. These are advisory signals about the bot's own verdict, not
  #     enforcement — for a one-shot review model (merge/close/hold through the required gate check, no
  #     back-and-forth) leave this at the default `observe` so they never appear; set it to `auto` only if
  #     you specifically want that running commentary as GitHub labels.
  autonomy: {}

  # Names for the 4 disposition-outcome labels the `review_state_label` autonomy class above applies.
  # Each is a plain string, or explicit `null` to disable that ONE label without disabling the underlying
  # merge/close/hold decision it accompanies.
  # readyToMergeLabel: ready-to-merge          # Default: ready-to-merge.
  # changesRequestedLabel: changes-requested   # Default: changes-requested.
  # manualReviewLabel: manual-review           # Default: manual-review. Also the fallback hold label used
  #                                             # when review_state_label is off but merge/close is acting
  #                                             # (guardrail holds, migration collisions, etc.).
  # migrationCollisionLabel: migration-collision  # Default: migration-collision.

  # Auto-maintain policy for merges the agent is allowed to perform.
  # Defaults: mergeMethod = squash, requireApprovals = 1.
  autoMaintain:
    mergeMethod: squash
    requireApprovals: 1

  # Command authorization role policy — which roles (maintainer | collaborator | pr_author |
  # confirmed_miner) may invoke each bot command. Map. Default: the built-in policy.
  # Omit to inherit the DB-stored policy, or the built-in default if neither is set. An
  # invalid top-level shape (not a mapping) is ignored with a warning rather than
  # overwriting an existing DB-stored policy with the built-in default.
  # commandAuthorization:
  #   default: [maintainer, collaborator, confirmed_miner]
  #   commands:
  #     gate-override: [maintainer, collaborator]

  # Config-driven contributor ban list (#1425, anti-abuse): a banned login's PR/issue is closed
  # BEFORE any merit/CI/AI analysis (deterministic, zero-hallucination). `reason`/`evidence`/`addedAt`
  # are maintainer-only metadata, never published in the automated close comment. Default: [] (no bans).
  # contributorBlacklist:
  #   - login: some-banned-login
  #     reason: "plagiarized PR content"
  #     evidence: ["https://github.com/owner/repo/pull/123"]
  #     addedAt: "2026-01-01"

  # Label applied alongside a blacklist close above. String. Gated on `autonomy.close` (#label-scoping);
  # set to explicit `null` to close without any label. Default: slop.
  # blacklistLabel: slop

  # Per-contributor open-PR/open-issue caps (#2270, anti-abuse): the max PRs/issues a single
  # non-owner/non-admin/non-bot contributor may have open on this repo at once. Uncomment and set a
  # number to opt in — a contributor's newest item above the cap is closed with a clear reason on the
  # PR-opened/issue-opened webhook; their oldest items up to the cap stay open and reviewable.
  # Both contributorOpenPrCap and contributorOpenIssueCap ARE ENFORCED. Positive whole number, or
  # omit/null for no cap. Default: null (disabled) for both. Set explicitly to `null` (not just omitted)
  # to force-clear a cap that a dashboard/DB write previously set.
  # contributorOpenPrCap: 2
  # contributorOpenIssueCap: 5

  # Label applied to a PR/issue closed for exceeding a cap above. String. Default: over-contributor-limit.
  # Gated on `autonomy.close` (#label-scoping), not `autonomy.label` — closing WITHOUT this label is
  # available too: set this to explicit `null` (not just omitted) to close silently, with no label.
  # contributorCapLabel: over-contributor-limit

  # Cancel in-flight CI runs when a PR is auto-closed for exceeding contributorOpenPrCap above (#2462).
  # Requires the App installation to have granted the `actions: write` permission -- degrades gracefully
  # (skipped + logged, the close itself still succeeds) when it hasn't. Bool or omit/null to fall back to
  # the CONTRIBUTOR_CAP_CANCEL_CI_DEFAULT env var. Default: null (falls back to the env var, itself off
  # by default).
  # contributorCapCancelCi: true

  # Review-request nagging cooldown (#2463, anti-abuse): throttle a non-owner/non-admin/non-bot
  # contributor who repeatedly pings @loopover for review on the same PR/issue. "hold" replies with a
  # cooldown notice and takes no further action; "close" closes the PR (issues degrade to "hold" until
  # a dedicated closeIssue primitive lands) with a clear reason. Off by default.
  # reviewNagPolicy: off      # off | hold | close. Default: off.
  # reviewNagMaxPings: 3      # Positive integer. Pings above this within the cooldown window trigger the policy. Default: 3.
  # reviewNagCooldownDays: 5  # Positive integer up to 365. Window the ping count is measured over. Default: 5.
  # reviewNagLabel: review-nag-cooldown  # Label applied alongside the hold/close action. Default: review-nag-cooldown.
  #                                       # Gated on autonomy.close (#label-scoping); set to explicit `null` to
  #                                       # close/hold without any label.

  # Maintainer-mention nag moderation (#label-scoping): GitHub logins ALSO throttled under the SAME
  # reviewNagPolicy/reviewNagMaxPings/reviewNagCooldownDays/reviewNagLabel cooldown above, on top of the
  # bot's own @loopover handle — e.g. a contributor who keeps tagging a specific maintainer for review
  # instead of (or in addition to) pinging @loopover. Counted independently per mentioned login and
  # independently of the @loopover counter. Only fires for the thread's OWN author, never a third party
  # commenting on someone else's thread; owner/admin/automation-bot/autoCloseExemptLogins are always exempt.
  # List of GitHub logins. Default: [] (no logins watched).
  # reviewNagMonitoredMentions: [your-maintainer-login]

  # Shared repo-scoped exemption list (#2463): GitHub logins never throttled/closed by loopover's
  # deterministic anti-abuse mechanisms (review-nag cooldown today; the per-contributor open-item cap
  # above will reuse this list too), on top of the standing owner/admin/automation-bot exemption.
  # List of GitHub logins. Default: [] (no additional exemptions).
  # autoCloseExemptLogins: [some-trusted-regular]

  # Account-age throttle (#2561, anti-abuse): a PR from an account younger than this many days gets
  # the newAccountLabel below -- friction/visibility only, NEVER an automatic close on account age alone.
  # Never fires for the repo owner, admin logins, or automation bots. PR-path only. Off by default.
  # accountAgeThresholdDays: null  # Positive integer, or null/omitted to disable. Default: null (off).
  # newAccountLabel: new-account  # Label applied to a below-threshold-age account's PR. Default: new-account.

  # Per-command @loopover rate limit (#2560, anti-abuse): generalizes review-nag's cooldown pattern to
  # EVERY @loopover command (help/ask/preflight/blockers/... and the maintainer queue-digest commands),
  # not just review-request pings — independent of review-nag's own thread-author-only scope. "hold"
  # replies with a cooldown notice and skips the command's own dispatch. Off by default.
  # commandRateLimitPolicy: off             # off | hold. Default: off.
  # commandRateLimitMaxPerWindow: 20        # Positive integer. Per-command invocation limit for a CHEAP command (cache-only, no AI call) within the window. Default: 20.
  # commandRateLimitAiMaxPerWindow: 5       # Positive integer. Tighter limit for an AI-cost-bearing command (ask/blockers/preflight/reviewability/packet/duplicate-check/next-action/repo-fit). Default: 5.
  # commandRateLimitWindowHours: 24         # Positive integer. Rolling window (hours) both limits above count against. Default: 24.

  # Moderation-rules engine (#selfhost-mod-engine): a single shared, cross-repo violation tally across the
  # anti-abuse mechanisms below that already short-circuit a PR/issue's disposition (contributor cap,
  # blacklist, review-nag, review-evasion). Off by default; the global config (dashboard/API, not this file)
  # holds the master switch, threshold, and label text. This per-repo override only opts THIS repo in/out and
  # narrows which mechanisms feed the tally for it.
  # moderationGateMode: inherit   # inherit | off | enabled. Default: inherit (defer to the global master switch).
  # moderationRules: [contributor_cap, blacklist, review_nag, review_evasion]  # Replaces (not unions with) the global rule set for this repo. Default: inherit the global list.
  # moderationWarningLabel: mod:warning  # Label applied at >=1 lifetime violation. Default: the global config's warningLabel.
  # moderationBannedLabel: mod:banned    # Label applied at >= the ban threshold. Default: the global config's bannedLabel.

  # Contributor trust profiles (#fairness-analytics): whether THIS repo's gate decisions and moderation history
  # participate in the internal, bearer-gated cross-repo contributor fairness/accuracy analytics -- never
  # exposed publicly. Independent of the fleet-wide fairnessAnalytics: block below, which gates whether the
  # internal routes exist at all.
  # fairnessAnalyticsMode: inherit  # inherit | off | enabled. Default: inherit (participate).

  # Review-evasion protection (#review-evasion-protection, anti-abuse): a contributor closing or converting
  # their own PR to draft while loopover has an ACTIVE review pass running against it is dodging the
  # one-shot review process, not making an ordinary close. When enabled, loopover reopens (if needed) and
  # re-closes the PR as the App -- a close the contributor cannot themselves reopen (#one-shot-reopen) --
  # posts an explanation comment, applies the configured label, and records a `review_evasion` moderation
  # strike (subject to moderationRules above including it). CLOSE BY DEFAULT as of #4011 -- "off" is an
  # explicit opt-out, not the default. Note: "off" only suppresses the enforcement close -- the
  # ready<->draft cycling counter keeps incrementing regardless, so re-enabling can immediately treat a
  # historical off-period cycle as "repeated."
  # reviewEvasionProtection: close     # off | close. Default: close.
  # reviewEvasionLabel: review-evasion # Label applied alongside the enforcement close. Gated on autonomy.close
  #                                     # (#label-scoping); set to explicit `null` to close without any label.
  #                                     # Default: review-evasion.
  # reviewEvasionComment: true         # Post the public explanation comment before the enforcement close. Default: true.

  # Draft-PR close policy (#draft-pr-close-policy, anti-abuse): distinct from reviewEvasionProtection above --
  # that family only enforces AFTER a review has already run against the PR's current head, or on the 2nd+
  # ready<->draft conversion. "close" enforces on ANY draft, including the very first one opened directly as a
  # draft or converted to draft before any review pass runs, closing it immediately -- stops a contributor
  # farming bot labels/AI-review/CI feedback for free while never reaching a real one-shot disposition. OFF BY
  # DEFAULT (opt-in, unlike reviewEvasionProtection's default-close): closing every draft PR is a much harsher
  # posture than reviewEvasionProtection's narrower abuse-pattern detection and can catch ordinary
  # WIP-signaling contributors, so choose this deliberately. Shares reviewEvasionLabel/reviewEvasionComment and
  # autoCloseExemptLogins with the family above. Deliberately does NOT record a moderation strike (unlike
  # reviewEvasionProtection) -- this is a blanket policy against ordinary GitHub draft usage, not a detected
  # abuse pattern.
  # draftPrClosePolicy: off  # off | close. Default: off.

  # One-shot synchronize-amendment close policy (#synchronize-close-policy): distinct from
  # reviewEvasionProtection and draftPrClosePolicy above -- those enforce on closing/converting-to-draft or on
  # draft usage; this one enforces on the contributor's OWN PR receiving an ADDITIONAL commit (a
  # `synchronize` push) before the PR has been merged or closed, regardless of what CI/review state that push
  # interrupts. This repo's review is one-shot: the PR must be correct as originally opened, not iterated on
  # while the first push's CI/review is still working -- "close" closes the PR immediately on that next push
  # rather than letting a contributor use a slow CI run as a free window to land fixups. OFF BY DEFAULT
  # (opt-in, unlike reviewEvasionProtection's default-close): it can catch ordinary, well-intentioned
  # contributors who simply push a follow-up commit with no gaming intent, so choose this deliberately. Never
  # fires for a push that isn't from the PR's own author (the engine's own rebase-if-behind push never
  # matches), nor for the repo owner/admin, a protected automation author, or anyone with write+ collaborator
  # access. Shares reviewEvasionLabel/reviewEvasionComment and autoCloseExemptLogins with the family above.
  # Deliberately does NOT record a moderation strike (unlike reviewEvasionProtection) -- this is a blanket
  # policy against an otherwise-ordinary GitHub action, not a detected abuse pattern. Config-as-code only --
  # no dashboard/DB column.
  # synchronizeClosePolicy: off  # off | close. Default: off.

  # Merge-train FIFO gate (#selfhost-merge-train): without this, a PR merges the instant its OWN gate clears,
  # with zero awareness of an older sibling PR still open in the same repo -- proven live to cause out-of-order
  # merges and the conflicts that follow. "audit" logs what the gate WOULD hold, without actually holding
  # anything -- validate the fix before enabling it for real. "enforce" actually defers a merge behind a
  # still-viable older sibling, bounded by a 24h staleness cap so one stuck old PR can never block newer ones
  # forever. Off by default.
  # mergeTrainMode: off # off | audit | enforce. Default: off.

  # Linked-issue HARD-RULE auto-close (#linked-issue-hard-rules): a DETERMINISTIC verdict about the
  # linked issue itself (not an AI verdict), gated per-rule to block|off. Fires regardless of
  # `guardrailHit`; still respects the `close` autonomy class and the owner/automation exemption. Off
  # by default for every rule.
  # linkedIssueHardRules:
  #   ownerAssignedClose: off        # Close when the linked issue is assigned to the repo owner. block | off.
  #   assignedIssueClose: off        # Close when it's assigned to someone other than the PR author. block | off.
  #   missingPointLabelClose: off    # Close when a default-label repo's issue carries none of pointBearingLabels. block | off.
  #   maintainerOnlyLabelClose: off  # Close when the issue carries a maintainerOnlyLabels entry. block | off.
  #   pointBearingLabels: [gittensor:bug, gittensor:feature, gittensor:priority]
  #   maintainerOnlyLabels: [maintainer-only]
  #   defaultLabelRepo: false        # Whether this repo's default label set makes missingPointLabelClose meaningful.
  #   verifyBeforeClose: true        # Two-pass flag-then-close instead of an immediate close (#linked-issue-verify-before-close).
  #   closeDelaySeconds: 30          # Verification window before Pass 2 closes, when verifyBeforeClose is true.
  # Label applied by Pass 1 of the flag-then-close verification above (present ⇒ Pass 2 may close on the
  # next check). Gated on `autonomy.review_state_label`. String. Default: pending-closure.
  # pendingClosureLabel: pending-closure

  # Unlinked-issue-match guardrail (#unlinked-issue-guardrail): when a contributor PR links no issue, a
  # deterministic pre-filter + AI verification checks whether it silently solves an existing open issue
  # anyway (a way to dodge linked-issue scrutiny while still farming merge-ratio credibility upstream).
  # A first confirmed match HOLDS the PR for manual review; a confirmed REPEAT by the same contributor
  # escalates to a close. Off by default.
  # unlinkedIssueGuardrail:
  #   mode: off          # off | hold. Default: off.
  #   minConfidence: 0.85  # Number 0-1. Minimum AI-verifier confidence to treat a candidate as a real match.

  # Before/after screenshot-table gate (#2006): deterministic check that a visual/frontend PR's body has a
  # before/after image table -- OR (#4110) that the bot's own visual-capture pipeline (review.visual.enabled)
  # already produced a real before/after render for this PR's head, which satisfies the gate on its own.
  # Scoped to whenLabels OR whenPaths (either matches); both empty = every PR. Off by default.
  # screenshotTableGate:
  #   enabled: false                        # Default: false.
  #   whenLabels: [frontend, visual]         # Default: [] (no label scoping).
  #   whenPaths: ["apps/ui/**", "src/**/*.tsx"]  # Default: [] (no path scoping).
  #   action: close                          # close is the only supported value. Default: close.
  #   message: "Custom close reason..."      # Default: null (built-in message).

  # Advisory-AI routing (#4364): per-capability opt-in to the local-inference AI_ADVISORY binding for these
  # four capabilities, none of which are ever gate-blocking, so none need frontier-model accuracy. Set a
  # global default here (or in the shared/root config) and override per-repo; a capability only actually
  # routes through AI_ADVISORY when BOTH this is true AND the AI_ADVISORY_BASE_URL binding is configured --
  # absent either one, it stays on the shared frontier env.AI chain (byte-identical to before). All off by
  # default.
  # advisoryAiRouting:
  #   slop: false          # gate.slop.aiAdvisory's second opinion. Default: false.
  #   e2eTestGen: false    # Auto-generated E2E test scaffolding. Default: false.
  #   planner: false       # The @loopover plan / issue-planner completion. Default: false.
  #   summaries: false     # AI summaries/rewrite text. Default: false.
  #   chatQa: false        # @loopover chat <question> grounded LLM Q&A. Ollama-first (never the frontier env.AI unless chatQaFrontierFallback below is also true); needs env.AI_ADVISORY set. Co-requisite: commandRateLimitPolicy: hold (defaults off). Default: false.
  #   chatQaFrontierFallback: false  # Opt-in only: falls back to the frontier env.AI chain if env.AI_ADVISORY is unconfigured, instead of declining. Meaningless unless chatQa is also true. Default: false.
  #   intentRouting: false # Closed-set intent classifier for unrecognized @loopover mentions -> existing Q&A commands only. Ollama-ONLY, same as chatQa (never uses chatQaFrontierFallback). Co-requisite: commandRateLimitPolicy: hold. Default: false.

# Per-repo activation overrides for the converged review features that ship behind a deployment-wide
# LOOPOVER_REVIEW_* env kill-switch (rag/reputation/safety/grounding/e2eTests/screenshots/
# improvementSignal/amsReputationBridge). Each key is `true` (force on for this repo, subject to the env flag still being
# enabled), `false` (force off), or omitted (falls back to the LOOPOVER_REVIEW_REPOS allowlist default --
# an operator who sets nothing keeps today's behavior). Exception: `safety` is force-on-only -- an untrusted
# repo-controlled `false` is treated as "no opinion" rather than an active force-off (#2269), since a
# lower-trust actor must never be able to silently defeat the operator's own security-hardening enablement.
# `screenshots` (#4616) is ALSO asymmetric as of #4990: allowlisted is now a hard requirement for force-ON,
# the same as safety/grounding -- real Browserless rendering cost and a publicly-rendered PR image mean a
# lower-trust repo must not be able to self-activate capture just by setting this to `true` in its own
# config; a repo-level `false` can still force it OFF within an allowlisted repo. `screenshots` sits UNDER
# the separate, richer `review.visual.*` block further below (route/preview-URL config, and
# `review.visual.enabled: false` as an always-available additional force-off); this key only answers "does
# capture run for this repo at all," the same question its siblings answer for their own feature.
# `e2eTests` (#4190) and `improvementSignal` (#4738, foundation phase of the #4737 PR-improvement-signal
# epic) remain plain symmetric overrides like rag/reputation -- neither carries a
# security-hardening or full-file-fetch rationale that would justify a force-on/force-off asymmetry.
# `improvementSignal` is activation wiring only for now -- no tier reads the resolved
# value yet.
# `amsReputationBridge` (#6485, per #6208's decided design) is a plain symmetric override too. It lets a
# submitter's genuine track record on a LOCAL AMS instance UPGRADE their reputation standing here -- toward
# `trusted` only, never toward `low`, so an AMS record can never be used punitively against a contributor.
# ORB pulls from AMS (never AMS pushing in), so an arbitrary AMS instance cannot write trust signals into
# this one. Needs BOTH the LOOPOVER_REVIEW_AMS_REPUTATION_BRIDGE env kill-switch AND
# LOOPOVER_AMS_TRACK_RECORD_URL (the AMS base URL to pull from) -- with either unset the bridge applies no
# bonus signal and the reputation path is byte-identical to today. An unreachable/slow/absent AMS degrades
# the same way: no bonus, never a throw into the gate.
# features:
#   rag: true
#   reputation: false
#   safety: true
#   grounding: true
#   e2eTests: false
#   screenshots: false
#   improvementSignal: false
#   amsReputationBridge: false

# Optional ecosystem/network PLUGINS -- distinct from `features:` above, which only toggles loopover's own
# converged review capabilities. Each key here couples this instance to an external system and is OFF unless
# BOTH a deployment-wide LOOPOVER_EXPERIMENTAL_* env kill-switch AND an explicit per-repo `true` are set (no
# LOOPOVER_REVIEW_REPOS allowlist fallback -- unlike `features:`, there is no default-on path). `gittensor`
# is the first plugin: loopover's original subnet mining-registry/scoring integration (per-repo emission
# share, maintainer cut, label multipliers pulled from the gittensor subnet's registry), now opt-in rather
# than a core dependency -- a self-host instance that never sets this has zero footprint from it: no fetch
# from the gittensor subnet registry, no local tracking/backfill of other repos on that subnet. Future
# plugins land in this same block as loopover broadens beyond gittensor.
# experimental:
#   gittensor: true

# Registry-review lane (#2435): lets a self-hosted maintainer point loopover at their OWN structured
# registry (e.g. a subnet/plugin/package catalog) without a loopover code change -- reviewing additions
# to a data file the same way it reviews code. Uncomment and set at least entryFileGlob + collectionField
# (both required; the block is ignored with a warning if either is missing).
# contentLane:
#   entryFileGlob: registry/*.json      # Glob for the structured entry files this lane reviews. Required.
#   collectionField: entries            # The JSON field holding the collection this lane diffs. Required.
#   providerFileGlob: providers/*.ts    # Optional glob for source files the entries are validated against.
#   artifactGlob: dist/registry.json    # Optional glob for a generated/build artifact to cross-check.
#   maxAppendedEntries: 1               # Positive integer cap on new entries per PR. Default: unbounded.
#   duplicateKeyFields: [slug]          # Field name(s) used to detect a duplicate entry. Default: [] (no dedup check).
#   validatorId: my-registry-validator  # Optional identifier for a custom per-entry validator. Default: none.

# Repo-doc generation (#2993/#3002): opt-in only, off by default. Uncomment to let LoopOver open a PR
# generating/refreshing AGENTS.md/CLAUDE.md (and later, skill files) from this repo's own profile. There
# is no DB-backed dashboard counterpart -- precedence is simply this manifest value, or fully disabled
# when the block (or `enabled`) is absent.
# repoDocGeneration:
#   enabled: true            # Bool. Default: false (never touched by the generator).
#   scope: [agents]          # agents | skills, one or more. Default: [] ("skills" is not shipped yet).
#   allowOverwriteExisting: false  # Bool. Opt-in to propose overwriting a hand-maintained, non-generated
#                                   # AGENTS.md/CLAUDE.md. Default: false (left alone if not recognizably generated).
#   refreshIntervalDays: 7   # Positive integer. Minimum days between scheduled refresh attempts. Default: 7.

# Maintainer review recap digest (#1963): opt-in only, off by default. Uncomment to let LoopOver build a
# periodic summary of recent review activity (PRs merged/closed, gate merge precision) for this repo. Discord
# delivery only for now (reuses the same per-repo webhook resolution as the per-PR notifier); Slack is a
# follow-up. There is no DB-backed dashboard counterpart -- precedence is simply this manifest value, or
# fully disabled when the block (or `enabled`) is absent. This PR ships the builder + a manually-triggerable
# delivery only -- the scheduled cron trigger is a scoped follow-up.
# reviewRecap:
#   enabled: true    # Bool. Default: false (no recap is ever built or posted).
#   cadenceDays: 7   # Positive integer. Days of activity each recap covers. Default: 7 (weekly).

# Cross-repo maintainer recap digest (#1963, #2250): config-as-code override for the CRON-scheduled digest
# that folds gate-precision + outcome-calibration across every scanned repo into one report (distinct from
# the single-repo reviewRecap above). Operator-level, not per-repo -- only meaningful on the loopover
# self-repo's own manifest (the repo this instance identifies as); a present block there wins over the
# LOOPOVER_MAINTAINER_RECAP / LOOPOVER_RECAP_CADENCE env vars, which stay the fallback when absent.
# maintainerRecap:
#   enabled: true         # Bool. Default: false (env vars decide instead).
#   cadence: weekly        # daily | weekly. Default: weekly. Invalid values fall back to weekly.
#   channel: discord       # discord (only supported channel today). Invalid values fall back to discord.

# Fleet-wide ops-alert scanning cron (#6275): config-as-code override for the hourly anomaly scan over
# loopover's own review-outcome data (LOOPOVER_REVIEW_OPS). Operator-level, not per-repo -- there is no
# per-repo activation check for this cron, so this block is only meaningful on the loopover self-repo's own
# manifest (the repo this instance identifies as); a present block there wins over the LOOPOVER_REVIEW_OPS
# env var, which stays the fallback when absent.
# ops:
#   enabled: true   # Bool. Default: false (the env var decides instead).

# Public "proof of power" stats API (#6275): config-as-code override for the LOOPOVER_PUBLIC_STATS flag
# gating the unauthenticated `/v1/public/stats` endpoint. Same shape and precedence as `ops:` above --
# fleet-wide, only meaningful on the loopover self-repo's own manifest; a present block there wins over the
# LOOPOVER_PUBLIC_STATS env var, which stays the fallback when absent.
# publicStats:
#   enabled: true   # Bool. Default: false (the env var decides instead).

# Contributor trust profiles / fairness analytics (#fairness-analytics): config-as-code override for the
# LOOPOVER_FAIRNESS_ANALYTICS flag gating the internal, bearer-gated per-contributor fairness/accuracy routes
# (GET /v1/internal/fairness/contributors[/:login], POST .../jobs/backfill-contributor-gate-history/run). Same
# shape and precedence as `publicStats:`/`ops:` above -- fleet-wide, only meaningful on the loopover self-repo's
# own manifest; a present block there wins over the LOOPOVER_FAIRNESS_ANALYTICS env var, which stays the
# fallback when absent. NEVER exposed publicly regardless of this flag -- see settings.fairnessAnalyticsMode
# above for the separate PER-REPO participation override.
# fairnessAnalytics:
#   enabled: true   # Bool. Default: false (the env var decides instead).

# Fleet-wide AI-drafted-PR creation capability (#6275): config-as-code override for the LOOPOVER_REVIEW_DRAFT
# env flag that gates the public OAuth draft-submission flow (POST /v1/drafts and friends). Operator-level,
# not per-repo -- there is no repo context at any of its activation checks -- so only meaningful on the
# loopover self-repo's own manifest; a present block there wins over the env var, which stays the fallback
# when absent.
# draftFlow:
#   enabled: true   # Bool. Default: false (the env var decides instead).

# Scheduled upstream-drift-issue-filing job (#6275): config-as-code override for the
# LOOPOVER_AUTO_FILE_DRIFT_ISSUES env flag that gates fileUpstreamDriftIssues (files/updates GitHub issues
# against loopover's own tracking repo when the upstream gittensor ruleset drifts). Operator-level, not
# per-repo -- only meaningful on the loopover self-repo's own manifest; a present block there wins over the
# env var, which stays the fallback when absent.
# upstreamDriftIssues:
#   enabled: true   # Bool. Default: false (the env var decides instead).

# Fleet-wide sweep-liveness watchdog cron (#6558 / #6275 / #6594): config-as-code override for the
# LOOPOVER_SWEEP_WATCHDOG flag that gates the hourly sweep-liveness check. Operator-level, not per-repo --
# only meaningful on the loopover self-repo's own manifest; a present block there wins over the env var.
# Distinct from the per-repo FORCE-OFF under `review.sweepWatchdog` (which only excludes one repo from the
# scan set once the fleet gate is ON).
# sweepWatchdog:
#   enabled: true              # Bool. Default: false (the env var decides instead).
#   staleAfterMinutes: 90      # Optional positive int (#6594). Minutes without a sweep-marker advance before
#                              # a repo with open PRs is treated as stale. Omit ⇒ hardcoded 45-minute default.

# Fleet-wide open-PR reconciliation cron (#6558 / #6275): config-as-code override for the
# LOOPOVER_PR_RECONCILIATION flag that gates the fast open-PR reconciliation pass. Same shape and
# precedence as `sweepWatchdog:` above. Distinct from the per-repo FORCE-OFF under `review.prReconciliation`.
# prReconciliation:
#   enabled: true   # Bool. Default: false (the env var decides instead).

# Fleet-wide active_review_tracking reconciliation sweep (#webhook-reorder-clobber): config-as-code override
# for the LOOPOVER_ACTIVE_REVIEW_RECONCILIATION flag. A delayed webhook job can leave a PR's review-tracking
# row stuck "active" after the PR has actually already closed on GitHub (queue backpressure widens the race).
# This sweep re-checks stale "active" rows against LIVE GitHub state and terminalizes the ones confirmed
# closed. Same shape and precedence as `prReconciliation:` above.
# activeReviewReconciliation:
#   enabled: true   # Bool. Default: false (the env var decides instead).

# Opt-in federated fleet intelligence export (#1970): packages this instance's OWN calibration signals into a
# signed, anonymized bundle an operator can choose to hand to a peer (or to a collector they run). Exports
# AGGREGATE figures only -- gate precision, reversal/slop/copycat rates over a window -- never source code,
# diffs, GitHub logins, repo names, PR ids, or raw gate reason text. Operator-level, not per-repo, so only
# meaningful on the loopover self-repo's own manifest. OFF unless you explicitly enable it here: with the block
# absent nothing is bundled and nothing leaves the instance. Distinct from the always-on Orb telemetry (#1255,
# suppressed by ORB_AIR_GAP), which streams per-PR events UP to loopover's central collector -- this one is
# peer-to-peer and assumes no central service at all.
# federatedIntelligence:
#   enabled: true   # Bool. Default: false (nothing is exported).
#   # The collector YOU run or trust (#6479). There is deliberately NO default and no auto-discovery -- with
#   # this unset, `enabled: true` still sends nothing, because there is nowhere to send it. Must be a public
#   # HTTPS URL: it is validated at config-read time against the same SSRF guard every other URL field here
#   # uses, so an http:// or localhost/private-range endpoint is dropped with a warning.
#   collectorUrl: https://collector.example.org/v1/federated
#   collectorMode: both   # push | pull | both. Default: both.
#   # WHICH PEERS YOU TRUST (#6480). A pulled bundle is only ever folded into your calibration if its signature
#   # verifies against one of these keys -- trust is explicit and operator-configured, exactly like
#   # MCP_READ_REPO_ALLOWLIST: there is no auto-discovery, no PKI, and no default peer. Unset or empty means you
#   # trust no peer, so EVERY inbound bundle is rejected; `enabled: true` on its own never starts importing.
#   # Each entry is a peer's 64-char hex verification key, which that operator gives you out of band. This is
#   # shared verification material, not a password: treat it the way you treat the rest of this file.
#   # To stop trusting a peer, remove its key -- that is the whole revocation story, by design.
#   peerKeys:
#     - 0000000000000000000000000000000000000000000000000000000000000000