feat(review): make orb check publication configurable

Adds settings.reviewCheckMode / gate.checkMode ("required" | "visible" |
"disabled") so a repo can keep GitHub branch protection pinned to the
review check, publish it as advisory-only UI, or stop publishing it
entirely, without weakening real CI/codecov gating or the autonomous
merge/close decision engine. Legacy gate.enabled/gateCheckMode continue
to map to required/disabled for back-compat; an explicit reviewCheckMode
always wins over the legacy boolean, at both the .gittensory.yml layer
and the settings write routes.

The autonomous decision engine no longer depends on the check-run's
existence: gate evaluation now runs whenever the check is published OR
an automation agent is configured, decoupling "should we publish a
check-run" from "should we compute a gate verdict."

Also fixes a related CI-deferral staleness bug: a required status
context that never reports was being held under the same 30-minute
stale-CI cap as genuinely pending CI, leaving PRs looking stuck for up
to half an hour. Missing-required-context now defers under its own
short 2-minute cap so review proceeds promptly once real CI is clear,
without adding polling or extra GitHub API calls.

Author: JSONbored

.gittensory.yml.example

@@ -95,6 +95,32 @@ gate:
   # Bool. Default: false (gate off).
   enabled: true
 
+  # Review-CHECK publish mode (#2852) — controls ONLY whether/how the "Gittensory 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 "Gittensory Orb Review Agent" from this repo's
+  #              branch-protection / ruleset required-status-checks list — Gittensory 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 Gittensory'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` — Gittensory'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.

apps/gittensory-ui/public/openapi.json

@@ -3630,6 +3630,14 @@
                 "items": {
                   "type": "string"
                 }
+              },
+              "reviewCheckMode": {
+                "type": "string",
+                "enum": [
+                  "required",
+                  "visible",
+                  "disabled"
+                ]
               }
             },
             "required": [
@@ -3639,6 +3647,7 @@
               "publicAudienceMode",
               "checkRunMode",
               "gateCheckMode",
+              "reviewCheckMode",
               "quietByDefault",
               "behavior",
               "warnings"
@@ -9064,6 +9073,14 @@
             "items": {
               "type": "string"
             }
+          },
+          "reviewCheckMode": {
+            "type": "string",
+            "enum": [
+              "required",
+              "visible",
+              "disabled"
+            ]
           }
         },
         "required": [
@@ -9074,6 +9091,7 @@
           "checkRunMode",
           "checkRunDetailLevel",
           "gateCheckMode",
+          "reviewCheckMode",
           "gatePack",
           "linkedIssueGateMode",
           "duplicatePrGateMode",
@@ -9164,6 +9182,14 @@
                     },
                     "autoLabelEnabled": {
                       "type": "boolean"
+                    },
+                    "reviewCheckMode": {
+                      "type": "string",
+                      "enum": [
+                        "required",
+                        "visible",
+                        "disabled"
+                      ]
                     }
                   },
                   "required": [
@@ -9172,6 +9198,7 @@
                     "publicAudienceMode",
                     "checkRunMode",
                     "gateCheckMode",
+                    "reviewCheckMode",
                     "autoLabelEnabled"
                   ]
                 }
@@ -9734,6 +9761,14 @@
               },
               "typeLabelsEnabled": {
                 "type": "boolean"
+              },
+              "reviewCheckMode": {
+                "type": "string",
+                "enum": [
+                  "required",
+                  "visible",
+                  "disabled"
+                ]
               }
             },
             "required": [
@@ -9744,6 +9779,7 @@
               "checkRunMode",
               "checkRunDetailLevel",
               "gateCheckMode",
+              "reviewCheckMode",
               "gatePack",
               "linkedIssueGateMode",
               "duplicatePrGateMode",

config/examples/global.gittensory.yml

@@ -16,6 +16,13 @@
 # Baseline gate policy shared by every repo unless a per-repo file overrides it.
 gate:
   enabled: true
+  # Review-check publish mode (#2852): required | visible | disabled. RECOMMENDED fleet-wide default
+  # for high-volume autonomous self-hosting is `visible` or `disabled`, NOT `required` — Gittensory's
+  # own merge/close decisions never depend on this check either way. If you set this to `disabled`
+  # instance-wide, remove "Gittensory Orb Review Agent" from every repo's branch-protection required-
+  # status-checks list first (Gittensory cannot do this for you — it's a GitHub branch-protection
+  # setting), or GitHub will show a pending status forever on repos that still require it.
+  checkMode: visible
   duplicates: block
   linkedIssue: advisory
 

config/examples/repo-override.gittensory.yml

@@ -10,10 +10,16 @@
 # Replace `owner`/`repo` in the destination path with the real values before using this file.
 # ============================================================================
 
-# Overrides ONLY `gate.enabled` and `gate.expectedCiContexts` for this repo — every other `gate.*`
-# key (e.g. `duplicates`, `linkedIssue`) is inherited from the global default untouched.
+# Overrides ONLY `gate.enabled`, `gate.checkMode`, and `gate.expectedCiContexts` for this repo —
+# every other `gate.*` key (e.g. `duplicates`, `linkedIssue`) is inherited from the global default
+# untouched.
 gate:
   enabled: true
+  # This repo goes fully dark (#2852): no "Gittensory Orb Review Agent" check-run at all, overriding
+  # the global default above. Reviews/comments/labels/audit and autonomous merge/close all keep
+  # working — only the check-run publish is affected. Remove the check from THIS repo's branch-
+  # protection required-status-checks before relying on this, or GitHub will show it pending forever.
+  checkMode: disabled
   # This repo's own CI job/check names to trust as required when its branch protection is
   # unreadable (a common self-host case — see ../../.gittensory.yml.example). Each repo's CI
   # naming differs, so this is a per-repo override rather than a global default.

migrations/0107_repository_review_check_mode.sql

@@ -0,0 +1,11 @@
+-- Configurable review-check publish surface (#2852): `gateCheckMode` was a binary off/enabled switch for the
+-- "Gittensory Orb Review Agent" check-run, with no way to publish it non-required (visibility only) or to go
+-- fully dark without leaving a GitHub branch-protection required-status-check permanently unsatisfied. Defaults
+-- to 'disabled' (matches gate_check_mode's own 'off' default for never-configured repos -- opt-in, unchanged).
+-- Existing rows backfill from their CURRENT gate_check_mode so already-configured repos keep today's behavior
+-- exactly: 'enabled' -> 'required' (still publishes, still fine to require in branch protection); 'off' (or any
+-- other/legacy value) keeps the column default 'disabled' (still never publishes). gate_check_mode itself is
+-- left untouched -- read by settings-preview.ts/the dashboard for back-compat display; the runtime publish
+-- decision reads review_check_mode.
+ALTER TABLE repository_settings ADD COLUMN review_check_mode TEXT NOT NULL DEFAULT 'disabled';
+UPDATE repository_settings SET review_check_mode = 'required' WHERE gate_check_mode = 'enabled';

src/api/routes.ts

@@ -609,6 +609,13 @@ const repositorySettingsSchema = z.object({
   checkRunMode: z.enum(["off", "enabled"]).default("off"),
   checkRunDetailLevel: z.enum(["minimal", "standard", "deep"]).default("standard"),
   gateCheckMode: z.enum(["off", "enabled"]).default("off"),
+  // #2852: deliberately NO `.default()` here (unlike every sibling field above) -- this is a non-partial,
+  // full-replace schema (see upsertRepositorySettings call below, which passes every parsed field straight
+  // through with no read-merge of the current row), so an eager default would mask a legacy caller that only
+  // sends gateCheckMode: the value would already be "defined" (the default) by the time it reaches
+  // upsertRepositorySettings, and its own `settings.reviewCheckMode ?? (gateCheckMode==="enabled" ? ...)`
+  // fallback only fires on `undefined`. Leaving this genuinely optional lets that fallback do its job.
+  reviewCheckMode: z.enum(["required", "visible", "disabled"]).optional(),
   gatePack: z.enum(["gittensor", "oss-anti-slop"]).default("gittensor"),
   linkedIssueGateMode: z.enum(["off", "advisory", "block"]).default("advisory"),
   duplicatePrGateMode: z.enum(["off", "advisory", "block"]).default("block"),
@@ -658,6 +665,7 @@ const maintainerSettingsSchema = z
     checkRunMode: z.enum(["off", "enabled"]),
     checkRunDetailLevel: z.enum(["minimal", "standard", "deep"]),
     gateCheckMode: z.enum(["off", "enabled"]),
+    reviewCheckMode: z.enum(["required", "visible", "disabled"]),
     gatePack: z.enum(["gittensor", "oss-anti-slop"]),
     linkedIssueGateMode: z.enum(["off", "advisory", "block"]),
     duplicatePrGateMode: z.enum(["off", "advisory", "block"]),
@@ -2181,6 +2189,14 @@ export function createApp() {
     const current = await getRepositorySettings(c.env, fullName);
     const changes = Object.fromEntries(Object.entries(parsed.data).filter(([, value]) => value !== undefined)) as Partial<RepositorySettings>;
     if (changes.qualityGateMode !== undefined) changes.qualityGateMode = downgradeQualityGateMode(changes.qualityGateMode);
+    // #2852: a legacy client (the maintainer dashboard's "Review agent check" toggle) only ever sends
+    // gateCheckMode, never the newer reviewCheckMode -- which must keep its historical effect on the ACTUAL
+    // publish authority. Derive it here, before merging onto `current` (which always has a DEFINED
+    // reviewCheckMode already), because upsertRepositorySettings's own legacy-fallback only fires on
+    // `undefined` and would never see this change as unset once merged with the current row.
+    if (changes.gateCheckMode !== undefined && changes.reviewCheckMode === undefined) {
+      changes.reviewCheckMode = changes.gateCheckMode === "enabled" ? "required" : "disabled";
+    }
     const updated = await upsertRepositorySettings(c.env, { ...current, ...changes, repoFullName: fullName });
     await recordAuditEvent(c.env, {
       eventType: "repo.settings_updated",
@@ -2298,6 +2314,7 @@ export function createApp() {
     return c.json({
       repoFullName: fullName,
       gateCheckMode: updated.gateCheckMode,
+      reviewCheckMode: updated.reviewCheckMode,
       checkRunMode: updated.checkRunMode,
       linkedIssueGateMode: updated.linkedIssueGateMode,
       duplicatePrGateMode: updated.duplicatePrGateMode,
@@ -3505,6 +3522,11 @@ export function createApp() {
         checkRunMode: parsed.data.checkRunMode,
         checkRunDetailLevel: parsed.data.checkRunDetailLevel,
         gateCheckMode: parsed.data.gateCheckMode,
+        // #2852: this route is a full-replace, non-partial schema (every sibling field has a `.default()`),
+        // so a caller that only ever sends gateCheckMode must still get its historical effect on the actual
+        // publish authority -- derive it explicitly here rather than relying on a passthrough `undefined`
+        // (which `exactOptionalPropertyTypes` disallows assigning to RepositorySettings anyway).
+        reviewCheckMode: parsed.data.reviewCheckMode ?? (parsed.data.gateCheckMode === "enabled" ? "required" : "disabled"),
         gatePack: parsed.data.gatePack,
         linkedIssueGateMode: parsed.data.linkedIssueGateMode,
         duplicatePrGateMode: parsed.data.duplicatePrGateMode,

src/db/repositories.ts

@@ -478,6 +478,7 @@ export async function getRepositorySettings(env: Env, fullName: string): Promise
       checkRunMode: "off",
       checkRunDetailLevel: "minimal",
       gateCheckMode: "off",
+      reviewCheckMode: "disabled",
       gatePack: "gittensor",
       linkedIssueGateMode: "advisory",
       duplicatePrGateMode: "block",
@@ -546,6 +547,7 @@ export async function getRepositorySettings(env: Env, fullName: string): Promise
     checkRunMode: parseCheckRunMode(row.checkRunMode),
     checkRunDetailLevel: parseCheckRunDetailLevel(row.checkRunDetailLevel),
     gateCheckMode: parseGateCheckMode(row.gateCheckMode),
+    reviewCheckMode: parseReviewCheckMode(row.reviewCheckMode),
     gatePack: parseGatePack(row.gatePack),
     linkedIssueGateMode: parseGateRuleMode(row.linkedIssueGateMode),
     duplicatePrGateMode: parseGateRuleMode(row.duplicatePrGateMode),
@@ -650,6 +652,14 @@ export async function upsertRepositorySettings(env: Env, settings: Partial<Repos
     checkRunMode: settings.checkRunMode ?? "off",
     checkRunDetailLevel: settings.checkRunDetailLevel ?? "minimal",
     gateCheckMode: settings.gateCheckMode ?? "off",
+    // Legacy-write compatibility (#2852): a caller that sets ONLY gateCheckMode (never touching the newer,
+    // more expressive reviewCheckMode) must keep its historical effect -- "enabled" still means the check
+    // publishes. This is safe under this function's existing "no field is preserved from the DB, an absent
+    // field always gets a fresh default" contract (see the route-handler comment above): a true partial-update
+    // caller already read-merges the full current settings (including its persisted reviewCheckMode) before
+    // calling this, so `settings.reviewCheckMode` is never actually undefined for that path -- this fallback
+    // only fires for callers that never cared about reviewCheckMode at all.
+    reviewCheckMode: settings.reviewCheckMode ?? (settings.gateCheckMode === "enabled" ? "required" : "disabled"),
     gatePack: parseGatePack(settings.gatePack),
     linkedIssueGateMode: settings.linkedIssueGateMode ?? "advisory",
     duplicatePrGateMode: settings.duplicatePrGateMode ?? "block",
@@ -720,6 +730,7 @@ export async function upsertRepositorySettings(env: Env, settings: Partial<Repos
       checkRunMode: resolved.checkRunMode,
       checkRunDetailLevel: resolved.checkRunDetailLevel,
       gateCheckMode: resolved.gateCheckMode,
+      reviewCheckMode: resolved.reviewCheckMode,
       gatePack: resolved.gatePack,
       linkedIssueGateMode: resolved.linkedIssueGateMode,
       duplicatePrGateMode: resolved.duplicatePrGateMode,
@@ -789,6 +800,7 @@ export async function upsertRepositorySettings(env: Env, settings: Partial<Repos
         checkRunMode: resolved.checkRunMode,
         checkRunDetailLevel: resolved.checkRunDetailLevel,
         gateCheckMode: resolved.gateCheckMode,
+        reviewCheckMode: resolved.reviewCheckMode,
         gatePack: resolved.gatePack,
         linkedIssueGateMode: resolved.linkedIssueGateMode,
         duplicatePrGateMode: resolved.duplicatePrGateMode,
@@ -6118,6 +6130,10 @@ function parseGateCheckMode(value: string): RepositorySettings["gateCheckMode"]
   return value === "enabled" ? "enabled" : "off";
 }
 
+function parseReviewCheckMode(value: string): RepositorySettings["reviewCheckMode"] {
+  return value === "required" || value === "visible" ? value : "disabled";
+}
+
 function parseGatePack(value: string | null | undefined): RepositorySettings["gatePack"] {
   return value === "oss-anti-slop" ? "oss-anti-slop" : "gittensor";
 }

src/db/schema.ts

@@ -51,6 +51,7 @@ export const repositorySettings = sqliteTable("repository_settings", {
   checkRunMode: text("check_run_mode").notNull().default("off"),
   checkRunDetailLevel: text("check_run_detail_level").notNull().default("minimal"),
   gateCheckMode: text("gate_check_mode").notNull().default("off"),
+  reviewCheckMode: text("review_check_mode").notNull().default("disabled"),
   gatePack: text("gate_pack").notNull().default("gittensor"),
   // Missing a linked issue is advisory-only by default -- issues aren't always available, so it only
   // blocks when a repo explicitly opts in (linkedIssueGateMode: "block" or the requireLinkedIssue toggle;