From a492d6132190183df8d9c6a37e0b9df13271bdb6 Mon Sep 17 00:00:00 2001
From: JSONbored <49853598+JSONbored@users.noreply.github.com>
Date: Sun, 12 Jul 2026 06:54:19 -0700
Subject: [PATCH] fix(ui): disclose the inert firstTimeContributorGrace
 dashboard toggle

firstTimeContributorGrace is explicitly RESERVED/inert (#2266) --
the gate evaluator never reads it. #2411 already fixed the
config-as-code half of this exact problem: a parse-time warning plus
a rewritten .gittensory.yml.example correctly disclose inertness.
But #2411 never touched the dashboard/API surface -- the live
maintainer-dashboard toggle still read "Soften a newcomer's block to
advisory" with zero disclosure, the one surface a non-technical
maintainer is most likely to actually use.

Applies the same disclose-don't-remove treatment #2411 gave the yml
surface: the toggle now renders greyed-out and non-interactive with
a "Reserved -- currently has no effect (#2266)" hint (new `disabled`
prop on ToggleControl/ToggleFieldDef), and the same disclosure is
added as a .describe() on all 3 API/openapi occurrences. Kept the
field itself in the schema (not removed) to match the #2411
precedent and avoid an API-breaking change for a field that is
genuinely harmless to still accept.

Regenerated openapi.json.

Refs #5292
---
 apps/gittensory-ui/public/openapi.json              |  6 ++++--
 .../site/app-panels/maintainer-settings.tsx         | 13 +++++++++++--
 src/api/routes.ts                                   |  4 +++-
 src/openapi/schemas.ts                              |  8 ++++++--
 4 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/apps/gittensory-ui/public/openapi.json b/apps/gittensory-ui/public/openapi.json
index a9eb9eb9dc..bdd385c0b4 100644
--- a/apps/gittensory-ui/public/openapi.json
+++ b/apps/gittensory-ui/public/openapi.json
@@ -8918,7 +8918,8 @@
             ]
           },
           "firstTimeContributorGrace": {
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Reserved (#2266) -- the gate evaluator never reads this field. Currently has no effect on gate decisions."
           },
           "slopGateMinScore": {
             "type": "number",
@@ -10279,7 +10280,8 @@
                 ]
               },
               "firstTimeContributorGrace": {
-                "type": "boolean"
+                "type": "boolean",
+                "description": "Reserved (#2266) -- the gate evaluator never reads this field. Currently has no effect on gate decisions."
               },
               "slopGateMinScore": {
                 "type": "number",
diff --git a/apps/gittensory-ui/src/components/site/app-panels/maintainer-settings.tsx b/apps/gittensory-ui/src/components/site/app-panels/maintainer-settings.tsx
index 00f24589f8..9822408163 100644
--- a/apps/gittensory-ui/src/components/site/app-panels/maintainer-settings.tsx
+++ b/apps/gittensory-ui/src/components/site/app-panels/maintainer-settings.tsx
@@ -123,6 +123,10 @@ type ToggleFieldDef = {
   label: string;
   kind: "toggle";
   hint?: string;
+  // Renders greyed-out and non-interactive with the hint as the disclosure -- for a field that is real
+  // and DB-backed but currently wired to nothing (e.g. firstTimeContributorGrace, #2266/#2411), so a
+  // maintainer can't be misled into thinking the toggle has an effect.
+  disabled?: boolean;
 };
 type NumberFieldDef = {
   key: keyof MaintainerSettings;
@@ -184,7 +188,8 @@ const GATE_FIELDS: FieldDef[] = [
     key: "firstTimeContributorGrace",
     label: "First-time-contributor grace",
     kind: "toggle",
-    hint: "Soften a newcomer's block to advisory",
+    hint: "Reserved — currently has no effect on gate decisions (#2266)",
+    disabled: true,
   },
 ];
 
@@ -623,6 +628,7 @@ function FieldGroup({
                 key={field.key}
                 label={field.label}
                 hint={field.hint}
+                disabled={field.disabled}
                 value={settings[field.key] as boolean}
                 onChange={(value) =>
                   setField(field.key, value as MaintainerSettings[typeof field.key])
@@ -682,17 +688,20 @@ function ToggleControl({
   hint,
   value,
   onChange,
+  disabled,
 }: {
   label: string;
   hint?: string;
   value: boolean;
   onChange: (value: boolean) => void;
+  disabled?: boolean;
 }) {
   return (
-    <label className="flex items-start gap-2 text-token-sm">
+    <label className={`flex items-start gap-2 text-token-sm ${disabled ? "opacity-60" : ""}`}>
       <input
         type="checkbox"
         checked={value}
+        disabled={disabled}
         onChange={(event) => onChange(event.target.checked)}
         className="mt-0.5 size-4 accent-mint"
       />
diff --git a/src/api/routes.ts b/src/api/routes.ts
index e4544c5d35..6b299af0cb 100644
--- a/src/api/routes.ts
+++ b/src/api/routes.ts
@@ -737,7 +737,9 @@ const maintainerSettingsSchema = z
     selfAuthoredLinkedIssueGateMode: z.enum(["off", "advisory", "block"]),
     linkedIssueSatisfactionGateMode: z.enum(["off", "advisory", "block"]),
     mergeTrainMode: z.enum(["off", "audit", "enforce"]),
-    firstTimeContributorGrace: z.boolean(),
+    firstTimeContributorGrace: z
+      .boolean()
+      .describe("Reserved (#2266) -- the gate evaluator never reads this field. Currently has no effect on gate decisions."),
     slopGateMode: z.enum(["off", "advisory", "block"]),
     slopGateMinScore: z.number().int().min(0).max(100).nullable(),
     slopAiAdvisory: z.boolean(),
diff --git a/src/openapi/schemas.ts b/src/openapi/schemas.ts
index e92af604c0..571f1e06c0 100644
--- a/src/openapi/schemas.ts
+++ b/src/openapi/schemas.ts
@@ -697,7 +697,9 @@ export const RepositorySettingsSchema = z
     manifestPolicyGateMode: z.enum(["off", "advisory", "block"]),
     selfAuthoredLinkedIssueGateMode: z.enum(["off", "advisory", "block"]),
     linkedIssueSatisfactionGateMode: z.enum(["off", "advisory", "block"]),
-    firstTimeContributorGrace: z.boolean(),
+    firstTimeContributorGrace: z
+      .boolean()
+      .describe("Reserved (#2266) -- the gate evaluator never reads this field. Currently has no effect on gate decisions."),
     slopGateMinScore: z.number().nullable().optional(),
     slopAiAdvisory: z.boolean(),
     aiReviewMode: z.enum(["off", "advisory", "block"]),
@@ -880,7 +882,9 @@ export const RepoSettingsPreviewSchema = z
       manifestPolicyGateMode: z.enum(["off", "advisory", "block"]),
       selfAuthoredLinkedIssueGateMode: z.enum(["off", "advisory", "block"]),
       linkedIssueSatisfactionGateMode: z.enum(["off", "advisory", "block"]),
-      firstTimeContributorGrace: z.boolean(),
+      firstTimeContributorGrace: z
+        .boolean()
+        .describe("Reserved (#2266) -- the gate evaluator never reads this field. Currently has no effect on gate decisions."),
       slopGateMinScore: z.number().nullable().optional(),
       autoLabelEnabled: z.boolean(),
       typeLabelsEnabled: z.boolean(),