fix(settings): preserve an explicit yml null clearing a contributor cap (#2467)

parseSettingsOverride collapsed an explicit `settings.contributorOpenPrCap:
null` in .gittensory.yml to the same outcome as omitting the key, so a
maintainer had no way to force a DB-configured cap back to disabled via
config-as-code, contradicting the documented yml > DB > null precedence.
Distinguish the three states (omitted / explicit null / invalid) before
normalizing. Also corrects .gittensory.yml.example, which described these
fields as already closing over-cap PRs; enforcement lands in a follow-up PR.

Author: JSONbored

.gittensory.yml.example

@@ -263,9 +263,10 @@ settings:
   #     gate-override: [maintainer, collaborator]
 
   # 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(s) above the cap are closed with a clear reason;
-  # their oldest items up to the cap stay open and reviewable. Positive whole number, or omit/null for
-  # no cap. Default: null (disabled) for both.
+  # non-owner/non-admin/non-bot contributor may have open on this repo at once. These fields are
+  # currently INERT (stored and parsed, not yet enforced) — enforcement (closing the newest item(s)
+  # above the cap with a clear reason) lands in a follow-up PR; see #2270 for status. 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

src/signals/focus-manifest.ts

@@ -796,11 +796,25 @@ function parseSettingsOverride(value: JsonValue | undefined, warnings: string[])
   }
   // Per-contributor open PR/issue caps (#2270): discrete counts, not scores — reuse the same positive-integer
   // normalizer as contentLane.maxAppendedEntries so a fractional/non-positive typo is dropped with a warning
-  // instead of configuring a nonsensical cap.
-  const contributorOpenPrCap = normalizeOptionalPositiveInteger(r.contributorOpenPrCap, "settings.contributorOpenPrCap", warnings);
-  if (contributorOpenPrCap !== null) out.contributorOpenPrCap = contributorOpenPrCap;
-  const contributorOpenIssueCap = normalizeOptionalPositiveInteger(r.contributorOpenIssueCap, "settings.contributorOpenIssueCap", warnings);
-  if (contributorOpenIssueCap !== null) out.contributorOpenIssueCap = contributorOpenIssueCap;
+  // instead of configuring a nonsensical cap. UNLIKE contributorBlacklist above, an explicit yml `null` here is
+  // load-bearing (not the same as omitting the key): the documented `yml > DB > null` precedence means a
+  // maintainer must be able to force a DB-configured cap back to "no cap" via `.gittensory.yml` without deleting
+  // the DB row. `normalizeOptionalPositiveInteger` collapses "absent" and "null" to the same silent `null`
+  // return, so that distinction has to be made HERE, before calling it: a literal `null` sets the key to `null`
+  // (clears); omitted (`undefined`) leaves the key unset (preserves the DB value via the resolver's spread); an
+  // invalid non-null value (fractional/non-positive/wrong type) warns and also leaves the key unset.
+  if (r.contributorOpenPrCap === null) {
+    out.contributorOpenPrCap = null;
+  } else {
+    const contributorOpenPrCap = normalizeOptionalPositiveInteger(r.contributorOpenPrCap, "settings.contributorOpenPrCap", warnings);
+    if (contributorOpenPrCap !== null) out.contributorOpenPrCap = contributorOpenPrCap;
+  }
+  if (r.contributorOpenIssueCap === null) {
+    out.contributorOpenIssueCap = null;
+  } else {
+    const contributorOpenIssueCap = normalizeOptionalPositiveInteger(r.contributorOpenIssueCap, "settings.contributorOpenIssueCap", warnings);
+    if (contributorOpenIssueCap !== null) out.contributorOpenIssueCap = contributorOpenIssueCap;
+  }
   return out;
 }
 

test/unit/focus-manifest.test.ts

@@ -1344,6 +1344,18 @@ describe("parseFocusManifest settings override + resolveEffectiveSettings", () =
     expect(nonNumber.settings.contributorOpenPrCap).toBeUndefined();
   });
 
+  it("an EXPLICIT yml null force-clears a DB-configured cap, distinct from an omitted key (regression, gate finding on #2467)", () => {
+    // Omitted key preserves the DB value (already covered above); an explicit `null` must ALSO be able to
+    // override a DB-configured cap back to "no cap" — the documented `yml > DB > null` precedence otherwise
+    // has no way to un-set a cap without a separate dashboard/DB write, which contradicts config-as-code.
+    const explicitNull = parseFocusManifest({ settings: { contributorOpenPrCap: null, contributorOpenIssueCap: null } });
+    expect(explicitNull.settings.contributorOpenPrCap).toBeNull();
+    expect(explicitNull.settings.contributorOpenIssueCap).toBeNull();
+    const eff = resolveEffectiveSettings({ contributorOpenPrCap: 4, contributorOpenIssueCap: 4 } as unknown as RepositorySettings, explicitNull);
+    expect(eff.contributorOpenPrCap).toBeNull();
+    expect(eff.contributorOpenIssueCap).toBeNull();
+  });
+
   it("resolves contributor blacklist by unioning the shared/global list with effective per-repo settings", () => {
     const manifest = parseFocusManifest({ settings: { contributorBlacklist: [{ login: "repo-only", reason: "manifest" }, { login: "Global-Repo", reason: "manifest-overrides-global" }] } });
     const eff = resolveEffectiveSettings(