feat(signals): add queue burden score breakdown with weighted contributors and top lever

[GildardoDev]

What

A new pure service, explainQueueBurden, that decomposes the queue burdenScore carried on a computed QueueHealth into its weighted, observable contributors and names the single highest-leverage lever a maintainer can pull to bring queue pressure down fastest. It is a sibling of score-breakdown.ts, miner-dashboard-recommendations.ts, and agent-action-explanation-card.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 burdenScore in buildQueueHealth but nothing explains how it is composed, so a maintainer sees a single opaque number with no breakdown of which factor is driving queue pressure or which lever helps most. This adds that explanation without changing the score.

Data source

Pure compute over an already-computed QueueHealth object. No network, no GitHub fetch, no I/O, no database access. Every contribution is derived from the observable signal counts already present on the queue health snapshot.

Behavior

Each penalty factor (unlinked PRs, collision clusters, open PRs, stale PRs, PRs aged past 30 days, open issues) is reported with its observable count, its signed per-unit weight, its point contribution, its share of total queue pressure, a band (none, low, moderate, high), and a specific lever. The readily-reviewable PRs are reported as a credit that offsets burden. The module also reports the pre-clamp raw sum and a clamped flag for when the engine pinned the score to the zero-to-one-hundred band, and it elects the single highest-leverage lever from the dominant penalty. The per-unit weights mirror buildQueueHealth in src/signals/engine.ts, and a drift-guard test rebuilds a QueueHealth through that function 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 observable counts, relative shares, and bands, and routes every rendered string through sanitizePublicComment.

Tests

Vitest cases cover the all-zero no-lever case, a dominant high-band contributor, a moderate band with the largest-remaining lever, both clamp directions (raw sum above one hundred and the reviewable credit driving it below zero), repo and timestamp passthrough, a public-safe check that no rendered string leaks reward or private terminology, and the engine-parity drift guard that pins the weights to buildQueueHealth. Branch coverage on the new file is 100 percent.

Validation

• npm run test:coverage for the new file: 100 percent branch coverage (32/32).
• 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.

[gittensory-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-01 05:38:20 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 pure QueueHealth explanation service and targeted unit coverage, and the implementation does recompute the engine burden formula from the visible signals while avoiding the stale zero-lever bug called out by CI. The highest-leverage no-op path is guarded after sorting, and the drift test exercises the real buildQueueHealth path rather than only fabricated fixtures. The main remaining concerns are polish and future-proofing rather than a visible correctness break in this diff.

Nits — 5 non-blocking

• nit: src/services/queue-burden-breakdown.ts:253 only reports `clamped` for `rawBurden > 100`; if this helper is ever fed a non-engine QueueHealth fixture with a negative raw sum, the metadata disagrees with the stated 0-100 clamp contract.
• nit: src/services/queue-burden-breakdown.ts:184 ranks by rounded `sharePercent`, so near-ties can be resolved by per-unit weight even when one component has a slightly larger raw contribution.
• src/services/queue-burden-breakdown.ts:253 could compute `clamped` as `rawBurden !== health.burdenScore` or `rawBurden < 0 || rawBurden > 100` to mirror the documented clamp directly.
• 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	⚠️ 2 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; address the blocker before review.
Contributor workload	✅ 10/10	Author activity: 214 registered-repo PR(s), 159 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	GildardoDev; Gittensor profile; 214 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: 214 PR(s), 0 issue(s).
• Related work: Titles/paths share 6 meaningful terms. (PR #1935, PR #1984)
• Related work: Titles/paths share 7 meaningful terms. (PR #1978, PR #1984)

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Fix the blocker.
• 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