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

[bohdansolovie]

Summary

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 explains the valid-issue token gate alongside open-PR, merged-history, and issue-discovery history multipliers.
• OpenAPI schema and scenario blocker text updated for the new gate.

Fixes #808 (partial — valid-issue token floor alongside prior contributor validity and open-issue spam work).

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

[superagent-security]

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.52%. Comparing base (050e751) to head (e65d513).
⚠️ Report is 7 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1617   +/-   ##
=======================================
  Coverage   95.51%   95.52%           
=======================================
  Files         204      204           
  Lines       22041    22090   +49     
  Branches     7963     7989   +26     
=======================================
+ Hits        21052    21101   +49     
  Misses        413      413           
  Partials      576      576           

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.43%)	⬆️
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 reviewers · no blockers · readiness 55/100 · CI green · clean

⏸️ Held for maintainer review — Large change — held for manual review; Touches a guarded path — held for manual review

Review summary
This PR correctly wires MIN_TOKEN_SCORE_FOR_VALID_ISSUE through three distinct paths: the score-preview gate (validIssueTokenGatePassed), the lifecycle classifier (valid_solved → solved downgrade), and the score-breakdown explainer. The fail-open design in solverMeetsValidIssueTokenFloor (absent score returns true) is the right default for cache-incomplete data, and the state-machine rewrite from solvedByPullRequests.length > 0 to mergedSolverPrs.length > 0 && tokenQualifiedSolverPrs.length > 0 is semantically equivalent on the pre-existing path while correctly gating valid_solved on the token floor. The three previously-missing breakdown components (openIssueMultiplier, mergedHistoryMultiplier, issueDiscoveryHistoryMultiplier) are mentioned in the description but expand scope beyond the floor wiring itself.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewers, synthesized
Linked issue	✅ Linked	#808
Related work	⚠️ 3 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Review load	❌ 8/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	28 open PR(s), 14 likely reviewable, 14 unlinked.
Contributor context	✅ Confirmed Gittensor contributor	bohdansolovie; Gittensor profile; 123 PR(s), 23 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Nits — 7 non-blocking

• buildContributorOutcomeHistory constructs lifecycleOptions without minValidIssueTokenScore (engine.ts ~1671), so the outcome-history classification always falls back to DEFAULT_SCORING_CONSTANTS.MIN_TOKEN_SCORE_FOR_VALID_ISSUE; if the snapshot-driven constant ever diverges from the compiled default, preview and cached outcome history would classify identical solver PRs differently.
• tokenFloorDowngrade guard (engine.ts ~3383) — the condition mergedSolverPrs.some((pr) => lifecycleOptions?.solverTokenScoreByPr?.has(pr.number)) encodes 'at least one solver PR has an explicit score in the index'; this intent (warn only on explicit low-score evidence, not on missing score) deserves a one-line comment since the negation of the fail-open default is non-obvious.
• issueDiscoveryHistoryBreakdown blocked-branch summary (score-breakdown.ts ~136) — the ?? 0 fallbacks for validSolvedIssues and issueCredibility produce a string that sanitizePublicComment converts to 'private context' in every test that reaches this branch, so the nullish arms are executed but never directly asserted; the coverage reporter may flag these as partially-covered ternary branches, which likely explains the codecov/patch miss at 96.22%.
• The three new breakdown functions (openIssueBreakdown, mergedHistoryBreakdown, issueDiscoveryHistoryBreakdown) are bundled alongside the validIssueTokenFloor gate and represent independent, previously-missing feature work; reviewable here, but they would have been cleaner as a follow-on PR scoped to 'surface all multiplier explanations.'
• Pass minValidIssueTokenScore from the caller's scoring-model constants into buildContributorOutcomeHistory's lifecycleOptions — the function already knows the repo, and the snapshot constant is the authoritative floor; using the compiled default here creates a latent divergence risk.
• Large change — held for manual review — Split this into smaller, focused PRs, or a maintainer reviews and merges it manually.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

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: Python, C++, JavaScript
• Official Gittensor activity: 123 PR(s), 23 issue(s).
• Related work: Items reference the same linked issue MCP CLI: add PowerShell shell completion #1452. (issue #1452, PR #1448)
• Related work: Open PR work references issue MCP CLI: add PowerShell shell completion #1452. (issue #1452, PR #1448)
• Related work: Titles/paths share 5 meaningful terms. (PR #1444, PR #1448)

Contributor next steps

• Review top overlaps.
• Add scope summary.
• Fix blocker.
• Expect slower review.
• Refresh registry data or choose a registered active repo.
• Check active issues and PRs before submitting.

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.

This PR correctly wires MIN_TOKEN_SCORE_FOR_VALID_ISSUE through three distinct paths: the score-preview gate (validIssueTokenGatePassed), the lifecycle classifier (valid_solved → solved downgrade), and the score-breakdown explainer. The fail-open design in solverMeetsValidIssueTokenFloor (absent score returns true) is the right default for cache-incomplete data, and the state-machine rewrite from solvedByPullRequests.length > 0 to mergedSolverPrs.length > 0 && tokenQualifiedSolverPrs.length > 0 is semantically equivalent on the pre-existing path while correctly gating valid_solved on the token floor. The three previously-missing breakdown components (openIssueMultiplier, mergedHistoryMultiplier, issueDiscoveryHistoryMultiplier) are mentioned in the description but expand scope beyond the floor wiring itself.

Nits (5)

• buildContributorOutcomeHistory constructs lifecycleOptions without minValidIssueTokenScore (engine.ts ~1671), so the outcome-history classification always falls back to DEFAULT_SCORING_CONSTANTS.MIN_TOKEN_SCORE_FOR_VALID_ISSUE; if the snapshot-driven constant ever diverges from the compiled default, preview and cached outcome history would classify identical solver PRs differently.
• tokenFloorDowngrade guard (engine.ts ~3383) — the condition mergedSolverPrs.some((pr) => lifecycleOptions?.solverTokenScoreByPr?.has(pr.number)) encodes 'at least one solver PR has an explicit score in the index'; this intent (warn only on explicit low-score evidence, not on missing score) deserves a one-line comment since the negation of the fail-open default is non-obvious.
• issueDiscoveryHistoryBreakdown blocked-branch summary (score-breakdown.ts ~136) — the ?? 0 fallbacks for validSolvedIssues and issueCredibility produce a string that sanitizePublicComment converts to 'private context' in every test that reaches this branch, so the nullish arms are executed but never directly asserted; the coverage reporter may flag these as partially-covered ternary branches, which likely explains the codecov/patch miss at 96.22%.
• The three new breakdown functions (openIssueBreakdown, mergedHistoryBreakdown, issueDiscoveryHistoryBreakdown) are bundled alongside the validIssueTokenFloor gate and represent independent, previously-missing feature work; reviewable here, but they would have been cleaner as a follow-on PR scoped to 'surface all multiplier explanations.'
• Pass minValidIssueTokenScore from the caller's scoring-model constants into buildContributorOutcomeHistory's lifecycleOptions — the function already knows the repo, and the snapshot constant is the authoritative floor; using the compiled default here creates a latent divergence risk.

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

merge conflicts/issue has already been resolved.

[bohdansolovie]

Hi, @JSONbored
Thank you for your review.
Do I have to create another PR for these changes after fix conflicts?
Or can you reopen this PR to let me fix conflicts.
Thanks.