fix(gate): downgrade readiness gate mode block to advisory

gate.readiness.mode accepted the shared off/advisory/block tri-state,
but buildQualityGateWarning always produces a warning-severity finding
and isConfiguredGateBlocker has no branch for it — readiness/quality is
intentionally informational-only and can never hard-block a PR. A
maintainer setting mode: block believed a real quality floor was
enforced when the effective behavior was silently advisory-only.

Add normalizeReadinessGateMode to downgrade block to advisory at the
config-as-code parse layer, with a deprecation warning pointing at
mergeReadiness/manifestPolicy for an enforceable floor. The shared
normalizeOptionalGateMode is untouched since other gate fields
legitimately support block.

Author: JSONbored

.gittensory.yml.example

@@ -112,7 +112,10 @@ gate:
 
   # Quality / merge-readiness score gate (the PR-quality score).
   readiness:
-    # off | advisory | block. Default: advisory.
+    # 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.

src/signals/focus-manifest.ts

@@ -357,6 +357,20 @@ function normalizeOptionalGateMode(value: JsonValue | undefined, field: string,
   return null;
 }
 
+/** `gate.readiness.mode` is documented and parsed as the shared off/advisory/block tri-state, but
+ *  buildQualityGateWarning (src/rules/advisory.ts) always produces a warning-severity finding — never a
+ *  blocker — and isConfiguredGateBlocker has no branch for it: readiness/quality is intentionally
+ *  informational-only and can never hard-block a PR. Without this, a maintainer who sets `mode: block`
+ *  believes a real quality floor is enforced when the effective behavior is silently advisory-only (#2267).
+ *  Downgrade "block" to "advisory" here, with a clear deprecation warning, so the parsed config always
+ *  matches what the gate actually does. */
+function normalizeReadinessGateMode(value: JsonValue | undefined, field: string, warnings: string[]): GateRuleMode | null {
+  const mode = normalizeOptionalGateMode(value, field, warnings);
+  if (mode !== "block") return mode;
+  warnings.push(`Manifest gate field "${field}" no longer accepts "block" — readiness/quality is informational-only and can never hard-block a PR; downgrading to "advisory". Use gate.manifestPolicy or another enforceable gate for a real quality floor.`);
+  return "advisory";
+}
+
 function normalizeOptionalBoolean(value: JsonValue | undefined, field: string, warnings: string[]): boolean | null {
   if (value === undefined || value === null) return null;
   if (typeof value === "boolean") return value;
@@ -422,7 +436,7 @@ function parseGateConfig(value: JsonValue | undefined, warnings: string[]): Focu
     pack: normalizeOptionalEnum(record.pack, "gate.pack", ["gittensor", "oss-anti-slop"] as const, warnings),
     linkedIssue: normalizeOptionalGateMode(record.linkedIssue, "gate.linkedIssue", warnings),
     duplicates: normalizeOptionalGateMode(record.duplicates, "gate.duplicates", warnings),
-    readinessMode: normalizeOptionalGateMode(readinessRecord?.mode, "gate.readiness.mode", warnings),
+    readinessMode: normalizeReadinessGateMode(readinessRecord?.mode, "gate.readiness.mode", warnings),
     readinessMinScore: normalizeOptionalScore(readinessRecord?.minScore, "gate.readiness.minScore", warnings),
     slopMode: normalizeOptionalGateMode(slopRecord?.mode, "gate.slop.mode", warnings),
     slopMinScore: normalizeOptionalScore(slopRecord?.minScore, "gate.slop.minScore", warnings),

test/unit/focus-manifest.test.ts

@@ -780,9 +780,11 @@ describe("public-safe invariant", () => {
 
 describe("parseFocusManifest gate config", () => {
   it("parses a full gate section including the readiness block", () => {
-    const m = parseFocusManifest({ gate: { linkedIssue: "block", duplicates: "advisory", readiness: { mode: "block", minScore: 70 } } });
+    // readiness.mode uses "advisory" here (not "block") — readiness/quality can never hard-block (#2267);
+    // the block→advisory deprecation-downgrade behavior itself is covered separately below.
+    const m = parseFocusManifest({ gate: { linkedIssue: "block", duplicates: "advisory", readiness: { mode: "advisory", minScore: 70 } } });
     expect(m.present).toBe(true);
-    expect(m.gate).toEqual({ present: true, enabled: null, pack: null, linkedIssue: "block", duplicates: "advisory", readinessMode: "block", readinessMinScore: 70, slopMode: null, slopMinScore: null, slopAiAdvisory: null, sizeMode: null, aiReviewMode: null, aiReviewByok: null, aiReviewProvider: null, aiReviewModel: null, aiReviewAllAuthors: null, aiReviewCloseConfidence: null, mergeReadiness: null, selfAuthoredLinkedIssue: null, manifestPolicy: null, dryRun: null, firstTimeContributorGrace: null });
+    expect(m.gate).toEqual({ present: true, enabled: null, pack: null, linkedIssue: "block", duplicates: "advisory", readinessMode: "advisory", readinessMinScore: 70, slopMode: null, slopMinScore: null, slopAiAdvisory: null, sizeMode: null, aiReviewMode: null, aiReviewByok: null, aiReviewProvider: null, aiReviewModel: null, aiReviewAllAuthors: null, aiReviewCloseConfidence: null, mergeReadiness: null, selfAuthoredLinkedIssue: null, manifestPolicy: null, dryRun: null, firstTimeContributorGrace: null });
   });
 
   it("parses gate.mergeReadiness + gate.firstTimeContributorGrace, round-trips them, and warns on bad values (#822)", () => {
@@ -892,6 +894,21 @@ describe("parseFocusManifest gate config", () => {
     expect(m.warnings.some((w) => /gate\.readiness\.mode/.test(w))).toBe(true);
   });
 
+  it("downgrades gate.readiness.mode: block to advisory with a deprecation warning (#2267)", () => {
+    // readiness/quality is informational-only (buildQualityGateWarning always produces a warning-severity
+    // finding; isConfiguredGateBlocker has no branch for it) — a config that says "block" is downgraded
+    // rather than silently accepted, so the parsed config always matches what the gate actually does.
+    const m = parseFocusManifest({ gate: { readiness: { mode: "block" } } });
+    expect(m.gate.readinessMode).toBe("advisory");
+    expect(m.gate.present).toBe(true);
+    expect(m.warnings.some((w) => /gate\.readiness\.mode.*no longer accepts "block"/.test(w))).toBe(true);
+    // Genuinely invalid values still take the ORIGINAL "must be one of" warning path, unchanged.
+    const bad = parseFocusManifest({ gate: { readiness: { mode: "sometimes" } } });
+    expect(bad.gate.readinessMode).toBeNull();
+    expect(bad.warnings.some((w) => /gate\.readiness\.mode.*must be one of/.test(w))).toBe(true);
+    expect(bad.warnings.some((w) => /no longer accepts "block"/.test(w))).toBe(false);
+  });
+
   it("clamps and rounds the readiness minScore to 0-100", () => {
     expect(parseFocusManifest({ gate: { readiness: { minScore: 250 } } }).gate.readinessMinScore).toBe(100);
     expect(parseFocusManifest({ gate: { readiness: { minScore: -10 } } }).gate.readinessMinScore).toBe(0);
@@ -915,9 +932,9 @@ describe("parseFocusManifest gate config", () => {
   });
 
   it("parses the gate section from YAML content", () => {
-    const m = parseFocusManifestContent("gate:\n  duplicates: block\n  readiness:\n    mode: block\n    minScore: 80\n", "repo_file");
+    const m = parseFocusManifestContent("gate:\n  duplicates: block\n  readiness:\n    mode: advisory\n    minScore: 80\n", "repo_file");
     expect(m.gate.duplicates).toBe("block");
-    expect(m.gate.readinessMode).toBe("block");
+    expect(m.gate.readinessMode).toBe("advisory");
     expect(m.gate.readinessMinScore).toBe(80);
   });
 

test/unit/gate-check-policy.test.ts

@@ -50,12 +50,14 @@ describe(".gittensory.yml settings override (resolveEffectiveSettings)", () => {
   it("overlays the friendly gate: alias over DB settings (incl. gate.enabled -> gateCheckMode)", () => {
     const eff = resolveEffectiveSettings(
       settings({ gateCheckMode: "enabled", linkedIssueGateMode: "advisory", duplicatePrGateMode: "block", qualityGateMode: "off", qualityGateMinScore: 10 }),
+      // readiness.mode: "block" is downgraded to "advisory" at parse time (#2267) — readiness/quality can
+      // never hard-block, so this exercises the SAME downgrade flowing through resolveEffectiveSettings.
       parseFocusManifest({ gate: { enabled: false, linkedIssue: "block", duplicates: "off", readiness: { mode: "block", minScore: 70 } } }),
     );
     expect(eff.gateCheckMode).toBe("off"); // gate.enabled: false disables from config
     expect(eff.linkedIssueGateMode).toBe("block");
     expect(eff.duplicatePrGateMode).toBe("off");
-    expect(eff.qualityGateMode).toBe("block");
+    expect(eff.qualityGateMode).toBe("advisory");
     expect(eff.qualityGateMinScore).toBe(70);
   });