feat(signals): add contributor intake score breakdown with weighted deductions and top lever

[GildardoDev]

What

A new pure service, explainContributorIntake, that decomposes the contributor-intake score carried on a computed ContributorIntakeHealth into the weighted deductions that lowered it from a perfect 100, and names the single highest-leverage lever a maintainer can pull to make the repo more attractive to contributors. It is a sibling of queue-burden-breakdown.ts and score-breakdown.ts in the same explanation-service family.

No linked issue

no issue because: this is net-new analytical work that fills a real gap, and there is no open issue for it. The engine computes the intake score in buildContributorIntakeHealth but nothing explains how it breaks down, so a maintainer sees a single opaque number and its band with no view of which factor (queue burden, duplicate clusters, or config quality) is dragging intake down or which lever helps most. This adds that explanation without changing the score.

Data source

Pure compute over an already-computed ContributorIntakeHealth object. No network, no GitHub fetch, no I/O, no database access. Every deduction is derived from fields already present on the object: queueHealth.burdenScore, duplicateClusters, and configLevel.

Behavior

The intake score is a base of 100 minus three weighted deductions, mirroring buildContributorIntakeHealth: queue burden times 0.55, duplicate clusters times 8, and a fixed config-quality penalty by band (fragile 30, needs_attention 18, good 6, else 0). Each factor is reported with its observable driver, the points it removed, its share of the total deduction, a band (none, low, moderate, high), and a specific lever, plus the single highest-leverage lever. When nothing is deducted the lever is an explicit no-op rather than an arbitrary factor, and a clamped flag marks when the deductions exceeded 100 and the engine floored the score at 0. The weights mirror the engine, and a drift-guard test rebuilds a ContributorIntakeHealth through buildContributorIntakeHealth and asserts this module recomposes the exact same score, so an engine weight change fails the suite instead of silently producing a wrong breakdown. Public-safe by construction: it reports the same observable drivers the intake summary already prints (queue burden out of 100, duplicate-cluster count, config band) and routes every rendered string through sanitizePublicComment.

Tests

Vitest cases cover a perfect-intake no-deduction case with an honest no-op lever, a dominant high-band drag with a small low-band factor, a moderate top drag with the largest-remaining lever, each config band mapping to its fixed penalty, the deductions-exceed-100 clamp, repo and timestamp passthrough, a public-safe check that no rendered string leaks reward or private terminology, and the engine-parity drift guard that recomposes the exact score from buildContributorIntakeHealth. Branch coverage on the new file is 100 percent.

Validation

• npm run test:coverage for the new file: 100 percent branch coverage (35/35).
• npm run typecheck: no errors introduced by these files.
• Purely additive: one new service module and one new test file, no changes to existing code, no new dependencies.

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-01 18:52:29 UTC}

2 files · 1 AI reviewer · no blockers · readiness 55/100 · CI green · clean

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review

Review summary
The change adds a focused pure breakdown service for contributor-intake health and covers the main deduction paths, clamping marker, passthrough metadata, and a drift guard against the engine calculation. The implementation is coherent with the described score formula, and the visible code does not introduce a reachable correctness break. The main rough edges are polish and maintainability: the output exposes internal component ids in user-facing reason/summary strings, and the test file has a small unused type import.

Nits — 7 non-blocking

• nit: test/unit/contributor-intake-breakdown.test.ts:4 imports IssueRecord but never uses it; remove it or type the issues fixture explicitly.
• nit: src/services/contributor-intake-breakdown.ts:96 and src/services/contributor-intake-breakdown.ts:176 render internal ids like queueBurden/configQuality into public-facing text; use human labels so the explanation reads like the rest of the service family.
• nit: src/services/contributor-intake-breakdown.ts:66 rounds each component share independently, so component shares can total 99 or 101 in some mixes; document that these are approximate shares or normalize the last component if callers display them as a total.
• src/services/contributor-intake-breakdown.ts:96 and src/services/contributor-intake-breakdown.ts:176: add a tiny label map for component names and use it in reason/summary rendering.
• test/unit/contributor-intake-breakdown.test.ts:4: drop the unused IssueRecord import to keep the test fixture clean.
• Readiness score is below the configured threshold — Use the readiness panel as advisory maintainer context; the score does not block this PR.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ No-issue rationale	PR body explains why no issue is linked.
Related work	⚠️ 3 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High review scope from cached public metadata (size label size:L; no linked issue context).
Validation posture	❌ 5/25	Preflight is holding this PR: the review lane is unavailable, so it is not ready for automated review.
Contributor workload	✅ 10/10	Author activity: 219 registered-repo PR(s), 161 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	GildardoDev; Gittensor profile; 219 PR(s), 0 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Review context

• Author: GildardoDev
• 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: 219 PR(s), 0 issue(s).
• Related work: Titles/paths share 7 meaningful terms. (PR #2392)
• Related work: Titles/paths share 6 meaningful terms. (PR #2389)
• Related work: Items reference the same linked issue feat(review): review.suggestions config toggle (default off) gating suggested-change blocks #2142. (issue #2142, PR #2362)
• Additional title-only matches omitted; title-only overlap does not block.

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Await review-lane availability.
• Triage stale or unlinked PRs.
• Refresh registry data or choose a registered active repo.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.
• Check active issues and PRs before submitting.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.73%. Comparing base (8b0ac26) to head (dc9a988).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2122   +/-   ##
=======================================
  Coverage   95.73%   95.73%           
=======================================
  Files         223      224    +1     
  Lines       24741    24779   +38     
  Branches     8969     8986   +17     
=======================================
+ Hits        23685    23723   +38     
  Misses        433      433           
  Partials      623      623           

Files with missing lines	Coverage Δ
src/services/contributor-intake-breakdown.ts	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[superagent-security]

🚨 Contributor flagged. Click here for more info: Superagent Dashboard

[JSONbored]

Some issues:

The main rough edges are polish and maintainability: the output exposes internal component ids in user-facing reason/summary strings, and the test file has a small unused type import.