fix(review): mark gate.firstTimeContributorGrace as reserved/inert

[JSONbored]

What

.gittensory.yml.example documents gate.firstTimeContributorGrace: true as softening a would-be BLOCK to advisory 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 (src/rules/advisory.ts) never reads policy.firstTimeContributorGrace or its authorMergedPrCount/authorClosedUnmergedPrCount companions anywhere in its body. A nearby code comment confirms this was a deliberate removal ("blocker findings must remain closure/rejection outcomes"); an existing test already asserts a newcomer with grace=true still gets conclusion: "failure". The public docs were simply never updated to match.

This is not a guard weakening — the actual behavior is stricter than advertised — 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.

Fix

• Rewrote the .gittensory.yml.example entry, the RepositorySettings.firstTimeContributorGrace doc in types.ts, and the GateCheckPolicy field docs (all three: the flag plus its two companion counts) in advisory.ts to state the setting is reserved/currently inert, rather than describing softening behavior that no longer runs.
• Added a manifest-parse warning (FocusManifest.warnings) when a repo explicitly sets gate.firstTimeContributorGrace: true, so a maintainer relying on it gets a visible signal instead of silent inertness. Unset or explicit false — the default, and also the effective runtime behavior — does not warn.

The field itself is kept (not deleted): the design comment frames the removal as deliberate-but-field-retained, and a warning needs a field to warn about.

Tests

• New test: setting gate.firstTimeContributorGrace: true produces a manifest warning matching "reserved/inert".
• New test: leaving it unset, or explicitly false, produces no such warning.
• npx tsc --noEmit clean.
• npx vitest run test/unit/focus-manifest.test.ts — 138/138 pass.
• Diff-range coverage check: all three changed source files fully covered, zero gaps.
• Regression sweep across focus-manifest/predicted-gate/gate-check-policy/settings-preview/api suites — 315/315 pass.
• Full unsharded npm run test:coverage — 309 files / 5685 tests pass.
• npm audit --audit-level=moderate — 0 vulnerabilities.

Advances #1936. Closes #2266.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.78%. Comparing base (a8030ca) to head (a9b7b34).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2411   +/-   ##
=======================================
  Coverage   95.78%   95.78%           
=======================================
  Files         224      224           
  Lines       24917    24919    +2     
  Branches     9056     9057    +1     
=======================================
+ Hits        23867    23869    +2     
  Misses        428      428           
  Partials      622      622           

Files with missing lines	Coverage Δ
src/rules/advisory.ts	97.64% <ø> (ø)
src/signals/focus-manifest.ts	99.18% <100.00%> (+<0.01%)	⬆️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-01 20:04:38 UTC}

5 files · 1 AI reviewer · no blockers · readiness 75/100 · CI green · clean

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review

Review summary
The diff correctly limits the change to documentation plus manifest feedback: the runtime gate behavior is untouched, the public example/type comments now describe `firstTimeContributorGrace` as inert, and `parseFocusManifest` warns when the gate flag is explicitly true. The added tests cover the true warning path and the false/unset non-warning paths. No blocking runtime defect is visible in the provided diff; the main remaining risk is incomplete cleanup of older documentation surfaces.

Nits — 6 non-blocking

• nit: `migrations/0039_first_time_contributor_grace.sql:1` still documents the old softening behavior, so one repository-visible source continues to advertise the stale contract.
• nit: `src/signals/focus-manifest.ts:440` adds the warning on the `gate.firstTimeContributorGrace` path, but I could not verify from the provided full files whether a generic `settings.firstTimeContributorGrace: true` manifest path can set the same inert value silently.
• Update or clearly annotate `migrations/0039_first_time_contributor_grace.sql:1` if this repository treats migration comments as current docs, or add a pointer to the current inert behavior elsewhere that supersedes it.
• If `settings.firstTimeContributorGrace` is still accepted in manifests, mirror the warning there and add a focused test next to `test/unit/focus-manifest.test.ts:797`.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2266
Related work	⚠️ 2 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 67 registered-repo PR(s), 57 merged, 589 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 67 PR(s), 589 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 67 PR(s), 589 issue(s).
• Related work: Items reference the same linked issue fix(review): gate.firstTimeContributorGrace is documented as softening blockers but is dead/inert #2266. (issue #2266)
• Related work: Open PR work references issue fix(review): gate.firstTimeContributorGrace is documented as softening blockers but is dead/inert #2266. (issue #2266)

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Review top overlaps.
• Add a concise scope and risk note.
• Triage stale or unlinked PRs.
• No action.
• Check active issues and PRs before submitting.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review