feat(mcp): expose submitted PR AI-review findings via MCP

[andriypolanski]

Closes #4519

Summary

Adds gittensory_get_pr_ai_review_findings, a post-submission MCP tool that returns a contributor's own published AI-review inline findings as structured JSON (category, path, severity, line, body) — the same categorization used in the PR comment's "Finding categories" collapsible.

Persists inlineFindings in ai_review_cache.metadata_json when a fresh review is cached so MCP can read them back after publish.

Motivation

Pre-submission tools (gittensory_predict_gate, gittensory_explain_gate_disposition, static gittensory_finding_taxonomy) never expose the real dual-AI-review inline findings on an already-submitted PR. Miners blocked by a consensus defect or reviewer-disagreement HOLD only had PR-comment prose to parse. This closes the gap for a future iterate loop (#2333/#2334).

Changes

Area	Change
src/mcp/pr-ai-review-findings.ts	Pure parse/normalize/load helpers + contributor PR ownership guard
src/mcp/server.ts	Register gittensory_get_pr_ai_review_findings with contributor + repo access scoping
src/queue/processors.ts	Persist inlineFindings in review cache metadata on fresh reviews
src/db/repositories.ts	Return headSha from getLatestPublishedAiReview
src/services/subnet-interface.ts	Surface tool in contribution MCP subset
.claude/skills/.../reference.md	MCP tool reference entry
Tests	test/unit/pr-ai-review-findings.test.ts, test/unit/mcp-pr-ai-review-findings.test.ts

MCP tool

Name: gittensory_get_pr_ai_review_findings

Input: { login, owner, repo, pullNumber }

Output:

{
  "status": "ready",
  "repoFullName": "acme/widgets",
  "pullNumber": 42,
  "login": "miner1",
  "headSha": "sha-reviewed",
  "findings": [
    {
      "category": "security",
      "path": "src/db.ts",
      "severity": "blocker",
      "line": 12,
      "body": "This is vulnerable to SQL injection."
    }
  ],
  "categoryCounts": { "security": 1, "correctness": 1 }
}

Status values:

• ready — published review found (findings may be empty)
• not_found — no published AI review for this PR
• ai_review_off — repo has AI review disabled

Access: requireContributorAccess(login) + requireRepoAccess(owner/repo) + PR author must match login.

Test plan

• npx vitest run test/unit/pr-ai-review-findings.test.ts test/unit/mcp-pr-ai-review-findings.test.ts
• Structured categoryCounts match buildFindingCategoryCollapsible for the same findings
• Access scoping: wrong login, wrong PR author, inaccessible repo
• Empty / not_found / ai_review_off cases
• npm run test:ci before push
• npm run test:coverage — 99% patch on changed src/** lines

Notes

• Only published reviews are returned (published_at set).
• Reviews cached before this change lack inlineFindings metadata → tool returns ready with an empty findings array until the PR is re-reviewed.
• Inline comments are still posted only on cache miss; metadata persistence does not change comment replay behavior.

[superagent-security]

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

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-10 00:19:19 UTC}

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

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review: This PR changes guardrail-protected path(s): src/queue/processors.ts (matched src/queue/**), src/services/subnet-interface.ts (matched src/services/**).

Review summary
Adds a post-submission MCP tool that returns a contributor's own AI-review inline findings as structured JSON, backed by persisting `inlineFindings` in `ai_review_cache.metadata_json` and surfacing `headSha` from `getLatestPublishedAiReview`. The change closes #4519, requires no schema/migration since `head_sha` already existed on `ai_review_cache`, and is properly scoped with contributor-ownership + repo-access guards verified by dedicated tests (own-PR-only, repo-access-denied cases). Wiring is read-only and additive (metadata write is gated on non-empty findings), so it doesn't touch gate/disposition logic or queue idempotency.

Nits — 6 non-blocking

• codecov/patch is at 82.75% against a 99% target — worth identifying which branches in `src/mcp/pr-ai-review-findings.ts` (e.g. the deep-nesting flagged around line 117) are uncovered before merge.
• src/mcp/server.ts:2998 (`getPrAiReviewFindings`) fetches the pull request via `getPullRequest` and then `loadPrAiReviewFindings` separately calls `resolveRepositorySettings` — consider whether the extra round trip is worth collapsing, though it's not a correctness issue.
• src/queue/processors.ts comment above the `inlineFindings` spread is a bit long for a one-line-preferred convention; consider trimming to the load-bearing sentence only.
• Confirm the uncovered branches driving the codecov/patch shortfall and add a couple of targeted unit tests (e.g. an inline finding with a category that fails `isFindingCategory` combined with a missing line) to close the gap.
• Since `getLatestPublishedAiReview`'s return type now includes optional `headSha`, double check any other callers of this repository function (outside this diff) don't destructure it in a way that assumes it's always present.
• 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	✅ Linked	#4519
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: 136 registered-repo PR(s), 84 merged, 25 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	andriypolanski; Gittensor profile; 136 PR(s), 25 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Linked issue satisfaction

Addressed
The PR adds a self/repo-scoped MCP tool (gittensory_get_pr_ai_review_findings) that returns structured category/path/severity/line findings sourced from the same data feeding the PR-comment collapsible, persists inlineFindings into the review cache for readback, and includes tests for parity with the rendered comment, ownership/access scoping, and empty/off/not_found cases, plus a docs entry along

Review context

• Author: andriypolanski
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 136 PR(s), 25 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

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 94.05%. Comparing base (b069dde) to head (8874b8e).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4532   +/-   ##
=======================================
  Coverage   94.04%   94.05%           
=======================================
  Files         422      423    +1     
  Lines       37574    37632   +58     
  Branches    13724    13746   +22     
=======================================
+ Hits        35335    35393   +58     
  Misses       1583     1583           
  Partials      656      656           

Files with missing lines	Coverage Δ
src/db/repositories.ts	96.72% <100.00%> (+<0.01%)	⬆️
src/mcp/pr-ai-review-findings.ts	100.00% <100.00%> (ø)
src/mcp/server.ts	95.57% <100.00%> (+0.08%)	⬆️
src/queue/processors.ts	95.39% <100.00%> (+<0.01%)	⬆️
src/services/subnet-interface.ts	100.00% <ø> (ø)

🚀 New features to boost your workflow:

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