feat(scoring): wire valid-issue token floor into lifecycle and preview (#808)

[bohdansolovie]

Summary

Rebases #1617 onto current main after #1284 (contributor validity floors) and #1453 (open-issue breakdown) landed.

Wires MIN_TOKEN_SCORE_FOR_VALID_ISSUE (#808) into contributor-facing scoring and issue-discovery lifecycle:

• Score preview surfaces validIssueTokenFloor / validIssueTokenGatePassed and a context blocker (valid_issue_token_floor) when linked-issue mode is active and planned source tokens are below the upstream floor.
• Issue-discovery lifecycle downgrades valid_solved → solved when the official solver PR's Gittensor tokenScore is below the floor; outcome history uses the same classifier path.
• solverTokenScoreIndexFromGittensor indexes official PR token scores from the Gittensor snapshot embedded in contributor profiles.
• Score breakdown adds validIssueTokenGate, mergedHistoryMultiplier, and issueDiscoveryHistoryMultiplier explanations (keeps main's existing openIssueMultiplier copy from feat(scoring): explain the open-issue spam gate in the score breakdown #1453).
• OpenAPI schema and scenario blocker text updated for the new gate.

Fixes #808 (partial — valid-issue token floor; other #808 gates already merged via #1284 / #1453).

Test plan

• npx vitest run test/unit/scoring.test.ts test/unit/signals.test.ts test/unit/score-breakdown.test.ts
• Preview warns with valid_issue_token_floor when sourceTokenScore is below floor in linked-issue mode
• Preview passes gate at or above floor
• Lifecycle downgrades valid_solved when solver PR tokenScore is below floor
• solverTokenScoreIndexFromGittensor maps official PR rows
• Score breakdown includes validIssueTokenGate component
• npm run ui:openapi:check

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.59%. Comparing base (a39a340) to head (46e3654).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1700   +/-   ##
=======================================
  Coverage   95.58%   95.59%           
=======================================
  Files         204      204           
  Lines       22295    22337   +42     
  Branches     8053     8076   +23     
=======================================
+ Hits        21310    21352   +42     
  Misses        408      408           
  Partials      577      577           

Files with missing lines	Coverage Δ
src/openapi/schemas.ts	100.00% <ø> (ø)
src/scenarios/scenario-summary.ts	100.00% <ø> (ø)
src/scoring/preview.ts	99.07% <100.00%> (+0.01%)	⬆️
src/services/score-breakdown.ts	99.00% <100.00%> (+0.30%)	⬆️
src/signals/engine.ts	97.08% <100.00%> (+0.02%)	⬆️

🚀 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 — held for maintainer review

9 files · 1 AI reviewer · 1 blocker · readiness 73/100 · CI green · clean

⏸️ Held for maintainer review — This is a first-time contribution to this repo, so the gate stays advisory rather than blocking. The findings remain visible, and the gate will apply normally once this author has merge history here.

Review summary
The change correctly threads the new valid-issue token floor through preview schemas and adds lifecycle support, but two user-facing paths are now wrong on reachable inputs. The lifecycle token lookup is keyed too coarsely for GitHub PR numbers, and the score breakdown treats a non-applicable gate as if the source change passed the floor.

Blockers

• src/signals/engine.ts:650 indexes official solver token scores by bare PR number, so buildContributorOutcomeHistory can downgrade a valid solved issue in repo A because an unrelated official PR with the same number in repo B is below the floor; key the index by repoFullName plus PR number or build a per-repo index before calling cachedSolvedIssueCounts.
• src/services/score-breakdown.ts:150 reports that source change size meets the valid-issue token floor whenever validIssueTokenGatePassed is true, but src/scoring/preview.ts:422 sets that flag true for every non-linked preview even when sourceTokenScore is below the floor, so direct-PR breakdowns emit false copy.

Concerns raised — review before merging

• AI reviewers agree on a likely critical defect: src/signals/engine.ts:650 indexes official solver token scores by bare PR number, so buildContributorOutcomeHistory can downgrade a valid solved issue in repo A because an unrelated official PR with the same number in repo B is below the floor; key the index by repoFullName plus PR number or build a per-repo index before calling cachedSolvedIssueCounts.: src/signals/engine.ts:650 indexes official solver token scores by bare PR number, so buildContributorOutcomeHistory can downgrade a valid solved issue in repo A because an unrelated official PR with the same number in repo B is below the floor; key the index by repoFullName plus PR number or build a per-repo index before calling cachedSolvedIssueCounts.

Signal	Result	Evidence
Code review	❌ 1 blocker	1 reviewer
Linked issue	✅ Linked	#808
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Review load	✅ 20/20	Readiness component derived from cached public PR metadata and labels; size label size:L.
Validation evidence	❌ 5/25	Cached preflight status is hold.
Open PR queue	❌ 3/10	16 open PR(s), 12 likely reviewable, 4 unlinked.
Contributor context	✅ Confirmed Gittensor contributor	bohdansolovie; Gittensor profile; 125 PR(s), 23 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Nits — 6 non-blocking

• test/unit/signals.test.ts should add a regression with two repositories sharing the same PR number and different token scores so the lifecycle index cannot regress back to PR-number-only keying.
• src/signals/engine.ts:1669 rebuilds solverTokenScoreIndexFromGittensor inside the per-repo outcome loop; build it once before mapping repoOutcomes after the keying fix.
• src/services/score-breakdown.ts:144 should distinguish not-applicable from passed for the validIssueTokenGate component instead of using only a boolean gate result.
• Change IssueDiscoveryLifecycleOptions to carry a repo-scoped token lookup, for example `${repoFullName.toLowerCase()}#${number}`, and pass repoFullName through classifyIssueDiscoveryLifecycle.
• In validIssueTokenBreakdown, branch on preview.linkedIssueMultiplier.mode or add an explicit validIssueTokenGateApplicable gate field so non-linked previews get neutral copy.
• Readiness score is below the configured threshold — Use the readiness panel as advisory maintainer context; the score does not block this PR.

Review context

• Author: bohdansolovie
• Role context: outside_contributor
• 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: 125 PR(s), 23 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Fix blocker.
• Expect slower review.
• Refresh registry data or choose a registered active repo.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Review load = cached public PR metadata such as size labels, changed paths, and preflight status.
• Open PR queue = repo-wide review pressure; it is not a PR quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

Review details

Generated from public PR metadata and the diff. Advisory only; deterministic signals remain authoritative.

The change correctly threads the new valid-issue token floor through preview schemas and adds lifecycle support, but two user-facing paths are now wrong on reachable inputs. The lifecycle token lookup is keyed too coarsely for GitHub PR numbers, and the score breakdown treats a non-applicable gate as if the source change passed the floor.

Blockers

• src/signals/engine.ts:650 indexes official solver token scores by bare PR number, so buildContributorOutcomeHistory can downgrade a valid solved issue in repo A because an unrelated official PR with the same number in repo B is below the floor; key the index by repoFullName plus PR number or build a per-repo index before calling cachedSolvedIssueCounts.
• src/services/score-breakdown.ts:150 reports that source change size meets the valid-issue token floor whenever validIssueTokenGatePassed is true, but src/scoring/preview.ts:422 sets that flag true for every non-linked preview even when sourceTokenScore is below the floor, so direct-PR breakdowns emit false copy.

Nits (5)

• test/unit/signals.test.ts should add a regression with two repositories sharing the same PR number and different token scores so the lifecycle index cannot regress back to PR-number-only keying.
• src/signals/engine.ts:1669 rebuilds solverTokenScoreIndexFromGittensor inside the per-repo outcome loop; build it once before mapping repoOutcomes after the keying fix.
• src/services/score-breakdown.ts:144 should distinguish not-applicable from passed for the validIssueTokenGate component instead of using only a boolean gate result.
• Change IssueDiscoveryLifecycleOptions to carry a repo-scoped token lookup, for example `${repoFullName.toLowerCase()}#${number}`, and pass repoFullName through classifyIssueDiscoveryLifecycle.
• In validIssueTokenBreakdown, branch on preview.linkedIssueMultiplier.mode or add an explicit validIssueTokenGateApplicable gate field so non-linked previews get neutral copy.

_{🟩 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

[JSONbored]

See review comments for things that need to be fixed before resubmitting.