feat(github-app): first-time-contributor-aware gating

[kiannidev]

Summary

• Adds a per-repo firstTimeContributorGrace setting (default off) with migration 0026_first_time_contributor_grace.sql.
• Introduces src/rules/gate-grace.ts to detect repeat closed-unmerged authors and downgrade configured block gates to advisory for eligible newcomers.
• Threads author RoleContext and outcome history into gate evaluation via resolveGateCheckPolicy in the queue processor.

Closes #552

Test plan

• npm run validate (typecheck + test:coverage at 97%+ branch coverage)
• Unit tests for newcomer vs repeat-offender grace decisions (test/unit/gate-grace.test.ts)
• Queue integration test confirming a newcomer's borderline PR passes the gate when grace is enabled (test/unit/queue.test.ts)

Made with Cursor

[ghost]

Note

Gittensory Gate skipped

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

Signal	Result	Evidence	Action
Gate result	⚠️ Skipped	#631 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.

[ghost]

Gittensory review · advisory — a maintainer merges

0 actionable · 6 nitpick(s) · 19 file(s) · two independent AI reviewers

Suggested action: 🔍 Manual review. The changed route's preview could not be captured — review the rendered page manually before merging.

📋 Walkthrough

Adds a firstTimeContributorGrace boolean flag to repository settings, updates DB schema and OpenAPI, implements logic to downgrade gate modes for first‑time contributors, and updates all related tests and defaults.

Changes

File	Summary
apps/gittensory-ui/public/openapi.json	Adds firstTimeContributorGrace boolean property to RepositorySettings schema and required list.
migrations/0026_first_time_contributor_grace.sql	Adds first_time_contributor_grace integer column with default 0 to repository_settings table.
src/api/routes.ts	Extends repository settings validation schema and handling to include firstTimeContributorGrace.
src/db/repositories.ts	Updates default values, query mapping, and upsert logic for the new flag.
src/db/schema.ts	Adds firstTimeContributorGrace column definition with boolean mode.
src/openapi/schemas.ts	Adds firstTimeContributorGrace to the Zod schema for RepositorySettings.
src/queue/processors.ts	Introduces resolveGateCheckPolicy to apply grace logic and uses it when the flag is enabled.
src/rules/gate-grace.ts	New module implementing grace eligibility checks and policy transformation.
src/types.ts	Adds firstTimeContributorGrace boolean to RepositorySettings type.
test/unit/gate-grace.test.ts	Adds comprehensive unit tests for the new grace rule logic.
test/unit/policy-sanitizer.test.ts	Updates test fixtures to include the new flag.
test/unit/queue.test.ts	Adds test verifying grace behavior for a newcomer PR.
test/unit/registration-readiness.test.ts	Updates settings fixture with the new flag.
test/unit/repo-policy-readiness.test.ts	Updates settings fixture with the new flag.
test/unit/self-dogfood-registration-pack.test.ts	Updates settings fixture with the new flag.
test/unit/settings-preview.test.ts	Updates settings fixture with the new flag.
test/unit/signals-coverage.test.ts	Updates repository settings fixture with the new flag.
test/unit/signals-v2.test.ts	Updates repository settings fixture with the new flag.
test/unit/signals.test.ts	Updates repository settings fixtures with the new flag.

🔍 Reviewer notes

Reviewer A · gpt-oss-120b — recommends ✅ merge
This PR introduces a first‑time‑contributor grace setting, adds the corresponding DB column and API schema, implements gate‑check policy logic, and provides comprehensive tests. The changes are well‑scoped, type‑safe, and do not affect public privacy constraints.

Suggestions

• Confirm that buildContributorProfile, buildRoleContext, and buildContributorOutcomeHistory are imported in src/queue/processors.ts (they were likely already present).
• Add a brief comment in the migration file documenting the purpose of the new column.
• Consider adding a test for the resolveGateCheckPolicy helper to ensure it returns the base policy when the grace flag is disabled.

Worth double-checking

• The migration must be applied before the new code runs; ensure deployment order respects this.
• Verify that the SQLite integer‑boolean mapping aligns with the TypeScript boolean type (0/1 ↔ false/true).

Reviewer B · nemotron-3-120b-a12b — recommends ✅ merge
This PR adds first-time contributor aware gating functionality. When enabled, it downgrades blocking gate modes (linked issue, duplicate PR, quality gate) to advisory for qualifying newcomers. Changes include database schema updates, API schema extensions, backend logic modifications, and comprehensive tests. The implementation follows existing patterns, respects the public/private boundary (no forbidden terms introduced), and includes adequate test coverage.

Suggestions

• Consider adding a comment in src/rules/gate-grace.ts explaining why the maintainer lane is excluded from grace (though the test already covers this).
• In test/unit/gate-grace.test.ts, the test case for 'low-history contributors with multiple open attempts' could use a clarifying comment about why mixed open/closed scenarios are handled as they are.
• Ensure the migration note in the PR description mentions that this is a non-breaking additive change (though the SQL is straightforward).

Worth double-checking

• Verify that the additional computations in resolveGateCheckPolicy (building contributor profile, role context, outcome history) don't introduce noticeable latency in gate evaluation during high load.
• Double-check that the downgrade logic in applyFirstTimeContributorGrace correctly handles undefined gate modes (though current usage shows they're always set).
• Confirm that the OpenAPI schema update in public/openapi.json doesn't inadvertently expose internal-only fields (it doesn't, as it's just a boolean flag).

Warning

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

---

🤖 Automated advisory review · a maintainer makes the final call.

[ghost]

gittensory · advisory review

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

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

Reviewer A · gpt-oss-120b — recommends 🛠️ request changes
The PR adds a first‑time‑contributor grace feature, introducing a new boolean flag in repository settings, updating the database, API schemas, routing, and gate logic, and provides extensive test coverage. The implementation is clean and well‑tested, but the OpenAPI JSON marks the new flag as required, which could break existing clients that do not supply it.

Suggestions

• Change the firstTimeContributorGrace entry in apps/gittensory-ui/public/openapi.json to be optional (remove it from the required array) or provide a default value to avoid breaking existing API consumers.
• Verify that the migration 0026_first_time_contributor_grace.sql is applied in all deployment environments.
• Update any UI components or external integrations to include the new firstTimeContributorGrace field, ensuring they initialize it to false by default.

Worth double-checking

• Potential regression for existing clients due to the new required field in the OpenAPI spec.
• Ensuring the new database column is correctly initialized for legacy records.

Reviewer B · nemotron-3-120b-a12b — recommends ✅ merge
The PR adds first-time-contributor-aware gating, allowing repositories to opt-in to grace periods that downgrade certain gate blocks to advisories for newcomers. Changes include DB migration, TypeScript updates, new gate-grace logic, and updated tests. The implementation is well-tested, maintains the public/private boundary (no forbidden terms introduced), and follows project conventions.

Suggestions

• Consider adding a comment in resolveGateCheckPolicy explaining why author and repo are required (to avoid confusion about the conditional).
• In test/unit/gate-grace.test.ts, the test 'preserves non-block gate modes when applying grace' could be renamed for clarity (e.g., 'does not modify non-block gate modes').

Worth double-checking

• Verify that the migration first_time_contributor_grace INTEGER NOT NULL DEFAULT 0 works correctly with existing SQLite databases (should be safe as it's a simple additive change).
• Ensure the grace logic doesn't inadvertently affect performance for repositories with very high PR/issue volumes from a single author (though filtering by author login should keep it manageable).

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

[JSONbored]

Thanks for this — but it needs a rethink rather than a rebase, since it predates #644 and conflicts with the model we settled on.

1. It softens the wrong population. The grace path targets non-confirmed newcomers — but #644 already forces the gate to neutral for every non-confirmed author. So downgrading their block→advisory is a no-op for them; the only authors it can affect are confirmed contributors with no merges yet (opposite of intent).
2. It drops confirmedContributor from the gateCheckPolicy call — if force-merged, that regresses #644.
3. Non-deterministic. Eligibility keys off thin repo-local cache (repoStats: [], no official snapshot), so it default-grants on a newcomer's first webhook and is trivially gamed.

If we want a contributor on-ramp, let's design it on top of confirmedContributor, keyed on official gittensor merge history, layered after the contributor check. Suggest closing and reopening with that approach — your commits/credit carry over.