Parent: #1936
Problem
.gittensory.yml.example documents gate.firstTimeContributorGrace: true as softening a would-be BLOCK to advisory/neutral for a genuine newcomer. The value is faithfully parsed, clamped, and threaded end-to-end through RepositorySettings into GateCheckPolicy at every call site — but evaluateGateCheckCore in src/rules/advisory.ts never reads policy.firstTimeContributorGrace (or its companions authorMergedPrCount/authorClosedUnmergedPrCount) anywhere in its body. A code comment confirms this was intentionally removed ("blocker findings must remain closure/rejection outcomes"), and an existing test (gate-check-policy.test.ts, "first-time-contributor grace compatibility") explicitly asserts a newcomer with grace=true still gets conclusion: "failure". The public-facing example config was simply never updated to reflect the removal.
This is not a guard weakening — the effective behavior is stricter than advertised, i.e. fails toward safe — but it's a real config-as-code correctness gap: a maintainer's mental model of their own gate's leniency toward newcomers is wrong.
Failure scenario: a repo owner reads the example file and sets gate.firstTimeContributorGrace: true believing it will give first-time contributors a grace period before a blocker auto-closes their PR. Nothing changes — a first-time contributor with a real blocker is still one-shot closed exactly as a repeat contributor would be, with no warning that the setting is inert.
Requirements
- The documented behavior of every config-as-code field must match its actual runtime effect — or the field must be removed/marked reserved with a runtime warning.
Deliverables
- Remove/update the
.gittensory.yml.example entry (and corresponding descriptions in types.ts/OpenAPI/settings-preview) to state the flag is currently inert/reserved, since the design comment indicates the removal was deliberate.
- Consider emitting a one-time warning in
manifest.warnings when a repo sets firstTimeContributorGrace to a non-default value, so maintainers relying on it get a visible signal rather than silent inertness.
Acceptance criteria
- The example config and public docs no longer claim
firstTimeContributorGrace softens a blocker outcome.
- A repo that sets this field gets a visible signal (doc note and/or runtime warning) that it currently has no effect.
Expected outcome
A maintainer configuring gate leniency for newcomers can trust that what they read in the docs matches what actually happens at gate time.
Parent: #1936
Problem
.gittensory.yml.exampledocumentsgate.firstTimeContributorGrace: trueas softening a would-be BLOCK to advisory/neutral for a genuine newcomer. The value is faithfully parsed, clamped, and threaded end-to-end throughRepositorySettingsintoGateCheckPolicyat every call site — butevaluateGateCheckCoreinsrc/rules/advisory.tsnever readspolicy.firstTimeContributorGrace(or its companionsauthorMergedPrCount/authorClosedUnmergedPrCount) anywhere in its body. A code comment confirms this was intentionally removed ("blocker findings must remain closure/rejection outcomes"), and an existing test (gate-check-policy.test.ts, "first-time-contributor grace compatibility") explicitly asserts a newcomer with grace=true still getsconclusion: "failure". The public-facing example config was simply never updated to reflect the removal.This is not a guard weakening — the effective behavior is stricter than advertised, i.e. fails toward safe — but it's a real config-as-code correctness gap: a maintainer's mental model of their own gate's leniency toward newcomers is wrong.
Failure scenario: a repo owner reads the example file and sets
gate.firstTimeContributorGrace: truebelieving it will give first-time contributors a grace period before a blocker auto-closes their PR. Nothing changes — a first-time contributor with a real blocker is still one-shot closed exactly as a repeat contributor would be, with no warning that the setting is inert.Requirements
Deliverables
.gittensory.yml.exampleentry (and corresponding descriptions intypes.ts/OpenAPI/settings-preview) to state the flag is currently inert/reserved, since the design comment indicates the removal was deliberate.manifest.warningswhen a repo setsfirstTimeContributorGraceto a non-default value, so maintainers relying on it get a visible signal rather than silent inertness.Acceptance criteria
firstTimeContributorGracesoftens a blocker outcome.Expected outcome
A maintainer configuring gate leniency for newcomers can trust that what they read in the docs matches what actually happens at gate time.