ContribGate

Know whether a GitHub issue is worth pursuing before you start coding.

ContribGate is a deterministic, read-only CLI that checks a candidate GitHub issue for contribution blockers and uncertainty before you spend engineering time or model compute.

• UNKNOWN ≠ SAFE — missing or partial evidence never reads as permission.
• Read-only — it never comments, assigns, claims, or opens PRs. Ever.
• No LLM required — the verdict is pure logic with cited evidence: GO NOW / INVESTIGATE / WAIT / SKIP.
• Honest about blindness — it cannot see private maintainer work, GitHub search may lag, and it does NOT guarantee maintainers will accept a PR.

Unlike dashboards that rank whole backlogs or bots that act on your behalf, ContribGate does one narrow thing: it gates a single candidate issue with deterministic, fail-closed, policy-aware checks (including optional same-file collision awareness) — and shows its work so you can disagree with it.

contribgate https://github.com/cline/cline/issues/13781

Real output (abridged — policy/collision lines vary with API rate limits, but the verdict is stable):

Repository        cline/cline
Issue             #13781 Cline: Immediate history of task will not get generated ...
State             OPEN
Assignees         none
Referencing PRs   open: #13790 · merged: none found in GitHub search · closed-unmerged: none found in GitHub search
Recommendation    WAIT

Why:
  - open PR #13790 explicitly references this issue — already owned/covered

The issue looked free at a glance (open, unassigned) but was already covered — exactly the wasted effort this tool exists to prevent.

This tool helps investigate contribution viability. It does NOT guarantee maintainers will accept a PR.

Installation

GitHub-only soft launch — no npm package yet, so install from source. Requires Node 20+. Zero runtime dependencies.

git clone https://github.com/Bsibz/contribgate.git
cd contribgate
npm ci
npm run build
node ./bin/contribgate.js https://github.com/owner/repo/issues/123

Optional: npm link puts a contribgate command on your PATH. An npm release may follow later; until then, ignore any install snippet that claims otherwise.

Usage

contribgate <github-issue-url> [--json] [--path <repo/path>] [--verbose]

  --json              stable JSON output (schema "oss-preflight/v1", kept as the
                      historical V0 schema ID — see note below) for automation
  --path <repo/path>  a file the fix would touch; repeatable.
                      Sharpens collision detection AND the current-main check.
  --verbose           progress on stderr (URLs only — never credentials)

GITHUB_TOKEN (optional): sets an Authorization header for higher rate limits. Public repos work without it. The token is never printed — not in output, errors, or verbose logs.

The tool is read-only. It never comments, assigns, forks, branches, opens PRs, or modifies anything.

What the classifications mean

Precedence is fixed and documented in src/classify.ts: critical fetch failure → archived → closed → merged ref → open ref → assigned → truncated search → same-file collision → AI disallowed → autonomous ban → assignment gate → approval gate → AI disclosure → closed-unmerged history → symbol signal → unknowns → GO NOW.

Schema note: machine output carries "schema": "oss-preflight/v1". That identifier is kept verbatim for V0 compatibility — renaming it would break existing consumers for purely cosmetic reasons. Treat it as a historical internal schema ID, not the product name.

Evidence and limitations — read this

• UNKNOWN ≠ SAFE. Missing policy is reported as UNKNOWN, never as permission. Unmeasurable collision is UNKNOWN, never none. Any network/API failure blocks GO NOW.
• "No referencing PRs" means "none found in GitHub search" — nothing more. GitHub search indexing can lag, and private maintainer work, draft PRs, or plans are invisible to the public API. A clean search result is measurable evidence, not proof that no competing work exists.
• Truncation fails closed. Reference search examines the first 10 PRs; if more results exist, the result is flagged incomplete and GO NOW is impossible. Likewise, any open PR whose file list can't be fully measured (fetch failure, >100-file pagination cap) forces collision to UNKNOWN.
• A closed-unmerged PR is not proof the issue is free. It usually means a prior attempt failed — read it first.
• Collision detection is file-path based. It only compares paths named in the issue (or passed via --path) against open-PR file lists. Symbol matches are reported separately as explicitly weak evidence.
• Current-main is evidence, not proof. "Evidence found" means issue text still appears in the file on the default branch — not that the bug reproduces. Anything else is UNVERIFIED.
• Search-based reference lookup uses GitHub's PR search and verifies merged state per PR (first 10 examined; truncation is reported and blocks GO NOW); open-PR file listing is capped at 20 PRs and reports truncation instead of silently degrading.
• GO NOW is deliberately rare. It requires ALL of: open, unassigned, complete (untruncated) search with zero references, no gates pending, no AI prohibition, explicitly welcoming policy, and fully measured collision evidence. Anything less caps at INVESTIGATE or below.

Privacy

• Only public GitHub API reads (plus whatever GITHUB_TOKEN you provide).
• No telemetry, no analytics, no network calls anywhere else.
• Token handling is covered by tests: errors and logs are asserted to never contain the token.

Development

npm install
npm run typecheck   # tsc --noEmit
npm test            # build + node --test (71 tests, all mocked — no network)

Architecture (one concern per module):

src/url.ts        issue-URL parsing (pure)
src/transport.ts  read-only GitHub API client (injectable fetch for tests)
src/policy.ts     policy-file extraction (pure, regex + evidence)
src/collision.ts  path/symbol extraction + same-file detection (pure)
src/maincheck.ts  current-main needle search (pure logic, injected fetch)
src/classify.ts   deterministic classifier (pure, fully tested)
src/present.ts    human + JSON formatting
src/cli.ts        arg parsing + orchestration + exit codes

Testing

Tests never touch live GitHub — all HTTP is mocked, all fixtures live in fixtures/ (sanitized, inspired by real contribution patterns: clean issue, same-file collision, strict issue-first policy, autonomous-agent prohibition). The suite covers all 14 required cases: open/permissive, closed, open-ref, merged-ref, same-file, gate policy, agent ban, disclosure, absent policy, API failure, archived repo, JSON stability, bad URLs, and token non-emission — plus fail-closed hardening regressions: search truncation, partial PR-file evidence, explicit AI prohibition, and the narrowed external-PR-welcome heuristic.

License

MIT — see LICENSE.