feat(gate): first-time-contributor grace softens block to advisory (#552)

[JSONbored]

Closes #552.

What

Opt-in per-repo firstTimeContributorGrace setting (default off). When on, a would-be hard BLOCK is softened to a neutral/advisory Gittensory Gate for a genuine newcomer, while repeat low-quality contributors still gate normally.

Grace applies iff: firstTimeContributorGrace === true && authorMergedPrCount === 0 && authorClosedUnmergedPrCount < 3

• newcomer = 0 merged PRs in this repo
• repeat offender (grace does NOT apply) = ≥ 3 closed-unmerged PRs in this repo
• authors with merge history, repeat offenders, and the setting-off path are all unchanged

How

• evaluateGateCheck (src/rules/advisory.ts): after the existing confirmed-contributor neutral-return and before the no-blockers check, if grace applies and there are blockers, return a neutral, non-blocking result titled "first-contribution grace". Findings stay visible; the gate applies normally once the author has merge history. Public-safe summary — advisory-vs-block only, no trust/reward internals.
• The author's per-repo merged / closed-unmerged counts are computed in-memory from the already-loaded repo PRs (no extra DB load), excluding the current PR, using the same merged/closed semantics as the signals engine (mergedAt || state === 'merged' ; state === 'closed' && !mergedAt), and threaded into gateCheckPolicy → evaluateGateCheck.
• Setting wired through types / schema / migration 0039 / repositories / openapi / settings-preview, mirroring slopGateMode and mergeReadinessGateMode. Reads from the merge-readiness-adjusted effective policy, so grace correctly softens regardless of which gate mode produced the block.

Tests

4 new cases in test/unit/gate-check-policy.test.ts: newcomer→neutral, repeat-offender→failure, grace-off→failure, has-merges→failure, plus a threading test through gateCheckPolicy.

Verification

• migration guard: contiguous 0001..0039, no new duplicate ✓
• typecheck clean ✓
• full suite: 1962 passed, 1 skipped (only the pre-existing pngjs visual-agent skip) ✓
• openapi drift clean (regenerated) ✓ · UI lint clean ✓

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	gittensory-ui	4496707	Commit Preview URL Branch Preview URL	Jun 17 2026, 10:42 AM

[ghost]

Note

Gittensory Gate skipped

PR closed before full evaluation. No late first comment was created.

Signal	Result	Evidence	Action
Gate result	⚠️ Skipped	#825 is no longer open.	No action.

---

💰 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.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

❌ Patch coverage is 90.90909% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 96.64%. Comparing base (c7d8020) to head (4496707).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/queue/processors.ts	80.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #825      +/-   ##
==========================================
- Coverage   96.64%   96.64%   -0.01%     
==========================================
  Files          97       97              
  Lines       14058    14068      +10     
  Branches     5121     5126       +5     
==========================================
+ Hits        13587    13596       +9     
  Misses         95       95              
- Partials      376      377       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ghost]

gittensory · advisory review

Reviewed 19 changed file(s) — two independent AI reviewers.

Changed files (19)

• apps/gittensory-ui/public/openapi.json
• migrations/0039_first_time_contributor_grace.sql
• src/db/repositories.ts
• src/db/schema.ts
• src/openapi/schemas.ts
• src/queue/processors.ts
• src/rules/advisory.ts
• src/signals/settings-preview.ts
• src/types.ts
• test/unit/gate-check-policy.test.ts
• test/unit/maintainer-activation.test.ts
• test/unit/policy-sanitizer.test.ts
• test/unit/registration-readiness.test.ts
• test/unit/repo-policy-readiness.test.ts
• test/unit/self-dogfood-registration-pack.test.ts
• test/unit/settings-preview.test.ts
• test/unit/signals-coverage.test.ts
• test/unit/signals-v2.test.ts
• test/unit/signals.test.ts

Suggested action: 🛠️ Request changes. (reviewers split: request changes / merge) Address the suggestions below before merging.

Reviewer A · gpt-oss-120b — recommends 🛠️ request changes
This PR adds a first‑time‑contributor grace feature, extending repository settings, DB schema, OpenAPI, and gate evaluation logic, with comprehensive test coverage. However, the new authorHistory parameter in gateCheckPolicy is not optional, which will cause TypeScript compile errors in existing call sites that omit it.

Suggestions

• Make the authorHistory parameter optional (e.g., authorHistory?: { mergedPrCount: number; closedUnmergedPrCount: number }) or provide a default value of undefined.
• Run the full TypeScript type‑check suite to confirm no other call sites are broken by the signature change.
• Consider adding a unit test for the case where gateCheckPolicy is called without the new argument to ensure default behavior remains unchanged.

Worth double-checking

• Compilation failures in parts of the codebase that still call gateCheckPolicy with four arguments.
• Potential runtime undefined handling if the parameter is omitted and later accessed without null checks.

Reviewer B · mistral-small-3.1-24b-instruct — recommends ✅ merge
This PR adds a feature to soften the gate check for first-time contributors, converting a block to an advisory. The changes are well-documented and include necessary updates to the database schema, types, and tests. The implementation is thorough and maintains the project's conventions.

Suggestions

• Consider adding a comment in the migration file explaining the default value and its rationale.
• Ensure that the new feature is covered in the documentation, especially in the CONTRIBUTING.md file.
• Review the tests to ensure they cover all edge cases, especially around the new firstTimeContributorGrace logic.

Worth double-checking

• Verify that the new logic does not introduce any regressions in existing gate check policies.
• Ensure that the new feature is correctly handled in all parts of the application, including the UI and API.
• Check that the migration script is correctly applied and does not cause any issues in the database.

Warning

Could not capture a preview of the changed route(s) — review the rendered page manually before merging.

Before = production · After = this PR's preview deploy.

Route	Viewport	Before	After
/	desktop
	mobile