feat(mcp): add gittensory_check_improvement_potential pre-submit tool

[JSONbored]

Summary

• Adds a new MCP pre-submit tool, gittensory_check_improvement_potential, mirroring the existing
  gittensory_check_slop_risk tool but for the positive structural-improvement axis (sub-issue I of
  epic Epic: PR improvement signal — quality-delta scoring as the positive-axis counterpart to slop-risk #4737). It calls buildStructuralImprovementAssessment (src/signals/improvement.ts, already
  shipped by Aggregate deterministic structural-improvement sub-score #4742/feat(signals): add deterministic structural-improvement assessment #4822) directly from the MCP layer — no re-derived copy of the scoring math.
• Input is metadata-only, same contract family as checkSlopRiskShape: changedFiles/tests/
  testFiles are reused verbatim, plus optional patchCoverageDeltaPercent, complexityDeltas
  (mirrors ComplexityDeltaLike), and duplicationDeltas (mirrors DuplicationDeltaLike) — all
  already-derived structured deltas the calling agent supplies from its own local working tree. The
  tool never reads file content or diffs itself.
• Output is the same banded shape the deterministic aggregate already returns: improvementScore +
  band (insufficient-signal/none/minor/moderate/significant) + findings. Unlike
  checkSlopRisk (which blunts/omits its raw score to prevent reverse-engineering a gate evasion),
  the raw improvementScore is returned here — improvementScore carries no gate/blocker power
  (advisory-only per improvement.ts's own header comment), so there is nothing to protect, and the
  whole point of a supply-side value signal is to let a contributor see how close a planned change is
  to the next band.
• No auth required, matching checkSlopRisk: this is a pure function over caller-supplied structured
  data with no owner/repo/login to scope. Documented inline in the code comment above the new shape.
• Updates .claude/skills/contributing-to-gittensory/reference.md §5's numbered tool list: new entry
  placed immediately after check_slop_risk (its closest sibling), items renumbered. Also fixes a
  stale doc line found while editing this exact list: the existing check_slop_risk entry still
  described a slopRisk 0-100 return value that the handler stopped returning under the
  #mcp-slop-blunt change — corrected to match the real, current output shape.

Explicit non-goal: the LLM-tier judgment (ModelReview.valueAssessment, #4743) is intentionally
not attempted in this PR. It's designed to piggyback on the live AI-review call against an
already-opened PR, which does not exist at pre-submit time — see improvement.ts's own header
comment and the parent issue's "technical wrinkle" section. Scoping this tool to the deterministic
tier only is a deliberate choice, not an oversight.

Closes #4746

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy
  changes (3 files: the MCP server, its reference doc, and one new test file).
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or
  CNAME.
• I linked a currently open issue this PR resolves (Closes #4746).

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally — 703 test files / 13925 tests passed (2 skipped), 100% of
  every line and branch added in this diff (verified directly against coverage/lcov.info's
  DA/BRDA records for the new shape/registration/handler line ranges — zero 0-hit entries).
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate — 0 vulnerabilities
• New behavior has tests for the new branch/registration path, including the
  complexityDeltas/duplicationDeltas-omitted degraded path (insufficient-signal), a
  changedFiles-only path (minor), a combined-structural-signals path (significant), and a
  patch-coverage + duplication combination (moderate) — plus an explicit assertion that
  improvementScore is present (documenting the deliberate divergence from checkSlopRisk's
  blunted output).
• Full npm run test:ci run completed end-to-end (all ~40 chained steps, ending in ui:build)
  with no failures anywhere.

If any required check was skipped, explain why:

• Nothing was skipped, but one full npm run test:ci run's embedded test:coverage step showed a
  transient anomaly (702 test files instead of the expected 703, missing exactly this PR's new test
  file, with no error/crash logged and the file untouched on disk). Two independent standalone
  npm run test:coverage re-runs (before and after rebasing onto latest main) both cleanly showed
  703/705 files passing, including the new file at 100% line/branch coverage. Flagging this
  transparently in case it recurs in CI; I could not identify a root cause tied to this PR's code
  (which has no forking/pooling/environment interaction — it's a schema declaration, a tool
  registration, and a straight-line handler with zero branches of its own).

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores,
  private rankings, or private maintainer evidence are exposed (new tests assert the JSON output
  never matches a forbidden-terms pattern; all MCP tool output already passes through the shared
  redactSensitiveForMcp redaction in toolResult).
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or
  optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests —
  N/A, no auth/session changes in this PR.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states — N/A, no UI changes.
• Visible UI changes include a UI Evidence section — N/A, no UI/frontend surface touched by
  this PR (backend MCP tool + a reference doc's text list).
• Public docs updated where needed (reference.md §5); CHANGELOG.md intentionally not touched.

Notes

• No UI Evidence section included: this PR has no visible UI/frontend component (no apps/** files
  touched).
• Followed src/mcp/server.ts's gittensory_check_slop_risk registration/handler as the exact
  template per the parent issue's guidance, including its comment style, rate-limiting call
  (enforceToolRateLimit), and toolResult wrapping.

[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 94.26%. Comparing base (4a662c8) to head (f65a221).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4963   +/-   ##
=======================================
  Coverage   94.26%   94.26%           
=======================================
  Files         447      447           
  Lines       38884    38891    +7     
  Branches    14167    14167           
=======================================
+ Hits        36653    36660    +7     
  Misses       1574     1574           
  Partials      657      657           

Flag	Coverage Δ
shard-1	46.53% <42.85%> (-0.29%)	⬇️
shard-2	33.58% <42.85%> (+0.27%)	⬆️
shard-3	31.56% <42.85%> (+0.14%)	⬆️
shard-4	32.61% <100.00%> (-0.41%)	⬇️
shard-5	34.14% <42.85%> (+0.60%)	⬆️
shard-6	45.85% <42.85%> (+0.61%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/mcp/server.ts	95.62% <100.00%> (+0.03%)	⬆️

🚀 New features to boost your workflow:

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

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-11 04:16:13 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds a thin MCP wrapper (`gittensory_check_improvement_potential`) around the already-shipped `buildStructuralImprovementAssessment` (src/signals/improvement.ts), following the exact registration/handler/rate-limit pattern of the existing `checkSlopRisk` tool with no re-derived scoring logic. The new zod input/output schemas mirror `checkSlopRiskShape`'s field shapes and bounds, the handler at src/mcp/server.ts:2954-2966 just forwards input to the existing pure function and shapes the result, and the four new tests exercise real bands (insufficient-signal, minor, significant, moderate) rather than fabricated states, all passing in CI. The doc update in reference.md renumbers the tool list and also opportunistically fixes a stale line for the neighboring `checkSlopRisk` entry, which is in-scope since it's the same list being edited.

Nits — 6 non-blocking

• src/mcp/server.ts:936-964 repeats the `400`/`2000` length bounds inline several times for the new shape; consider extracting shared constants (e.g. MAX_PATH_LEN, MAX_ARRAY_LEN) reused from `checkSlopRiskShape` so the two contract families can't silently drift apart.
• reference.md's `check_slop_risk` entry (item 3) drops the 'slopRisk 0-100' wording as an incidental fix — worth double-checking that `checkSlopRiskOutputSchema`'s current blunting truly no longer exposes a raw numeric score, since this line describes a tool this diff doesn't otherwise touch.
• src/mcp/server.ts is already ~2971 lines and this PR adds another inline tool definition/handler rather than extracting tool contracts to a submodule — pre-existing pattern, not introduced here, but worth a future cleanup pass.
• External history brief flagged only 'partial' coverage of linked issue MCP pre-submit value-potential tool #4746 — confirm this PR fully closes or clearly links that issue per the epic Epic: PR improvement signal — quality-delta scoring as the positive-axis counterpart to slop-risk #4737 sub-issue I scope before merge.
• Factor the shared `400`/`2000` bounds into named constants used by both `checkSlopRiskShape` and `checkImprovementPotentialShape` (src/mcp/server.ts) to keep the sibling contracts in lockstep as either evolves.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4746
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 48 registered-repo PR(s), 40 merged, 423 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 48 PR(s), 423 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, TypeScript, Ruby, Go, JavaScript, MDX, Shell, Solidity
• Official Gittensor activity: 48 PR(s), 423 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.

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