feat(review): add fix-handoff block renderer + follow-up-issue MCP spec

[JSONbored]

Summary

• Adds the render slice of Agent fix-handoff blocks + follow-up-issue suggestions #1962 (feat(review): fix-handoff block renderer for review findings (boundary-safe, content-only) #2175): a boundary-safe, content-only renderer (src/review/fix-handoff-render.ts) that turns a single review finding into a structured "apply this fix" block for a contributor's own local agent to consume -- path/line/severity/instruction plus an optional suggested change, a machine-readable HTML-comment marker, and the shared no-cloud-write boundary text. A finding with no commentable line still yields a valid path-only block (mirrors the existing line: 0 path-only sentinel used by review/safety.ts/review/secrets-scan.ts). No server-side write, no execution.
• Adds a follow-up-issue action spec builder (feat(mcp): follow-up-issue action spec builder for deferred review findings #2177) for deferred review findings -- composes a bounded, public-safe title/body from a single finding and delegates to the existing buildFileIssueSpec local-write spec, exposed as a new gittensory_file_follow_up_issue MCP tool. Optional point-bearing label support (empty-label branch when omitted).
• Documents the already-shipped GITTENSORY_REVIEW_FIX_HANDOFF feature flag (the config/gate slice for feat(config): add review.fixHandoff toggle (default off) for fix-handoff blocks #2176 merged separately in feat(config): add review.fixHandoff toggle (default off) for fix-handoff blocks (#2176) #3824) in src/env.d.ts and the docs pages, closing a docs-drift gap that PR left open.

Closes #2175. #2177 was already marked closed by #3836 (an earlier, unwired implementation); this PR supersedes it with the actual live, MCP-wired version -- see Notes. Advances #1962 (not closed -- this PR covers the render + follow-up-issue slices only; the config/gate slice already shipped in #3824).

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.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked an issue (Advances Agent fix-handoff blocks + follow-up-issue suggestions #1962; implements feat(review): fix-handoff block renderer for review findings (boundary-safe, content-only) #2175 and feat(mcp): follow-up-issue action spec builder for deferred review findings #2177), or this is small enough that the summary explains why an issue is not needed.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally -- 100% branch coverage on both changed source files (src/review/fix-handoff-render.ts, src/mcp/local-write-tools.ts)
• 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
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• 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 such changes in this PR.)
• API/OpenAPI/MCP behavior is updated and tested where needed. (New gittensory_file_follow_up_issue MCP tool, tested via the MCP client harness in test/unit/mcp-write-tools.test.ts.)
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. (N/A -- only two docs pages gained a feature-flag doc line; no dynamic UI behavior.)
• Visible UI changes include a UI Evidence section below. (N/A -- text-only docs additions, no visual/layout change.)
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

Notes

• src/review/fix-handoff.ts is already taken by the merged feat(config): add review.fixHandoff toggle (default off) for fix-handoff blocks #2176 config/gate slice (isFixHandoffEnabled/shouldEmitFixHandoff), so this PR's renderer lives at src/review/fix-handoff-render.ts instead -- a caller wires the two together by calling shouldEmitFixHandoff before invoking buildFixHandoffBlock.
• buildFollowUpIssueSpec strips any embedded HTML-comment marker or fenced code block from the finding text before composing the issue body, since a follow-up issue is read by a human triaging a backlog, not a harness expecting the fix-handoff marker.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	gittensory-ui	f527b49	Commit Preview URL Branch Preview URL	Jul 06 2026, 03:02 PM

[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 93.41%. Comparing base (7f84fa7) to head (f527b49).
⚠️ Report is 2 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3834      +/-   ##
==========================================
- Coverage   93.41%   93.41%   -0.01%     
==========================================
  Files         326      327       +1     
  Lines       32887    32879       -8     
  Branches    12044    12044              
==========================================
- Hits        30723    30715       -8     
  Misses       1530     1530              
  Partials      634      634              

Files with missing lines	Coverage Δ
src/mcp/local-write-tools.ts	100.00% <100.00%> (ø)
src/mcp/server.ts	95.83% <100.00%> (+0.01%)	⬆️
src/review/fix-handoff-render.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.

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-06 14:49:51 UTC}

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

⏸️ Suggested Action - Manual Review

• No linked issue detected — If this PR is intended to solve an issue, link it explicitly in the PR body.
• Maintainer requires a linked issue — Link the relevant issue (for example Closes #123) before opening the PR.

Review summary
This PR adds two independent, well-scoped slices of #1962 (fix-handoff render + follow-up-issue MCP tool) plus doc updates for the already-shipped GITTENSORY_REVIEW_FIX_HANDOFF flag; both new modules are pure/content-only with no server-side write or execution, matching the existing local-write-tools/no-cloud-write pattern. buildFixHandoffBlock correctly falls back to a path-only block via the existing line<=0 sentinel convention, and buildFollowUpIssueSpec correctly delegates to buildFileIssueSpec's existing spec shape rather than introducing a new write path. Tests are thorough (both branches of every optional field, label present/absent, line present/absent/invalid) and CI is green across typecheck/tests/coverage. The PR description explicitly ties the change to issue #1962 and its sub-slices #2175/#2177, satisfying the issue-link requirement.

Nits — 5 non-blocking

• src/mcp/local-write-tools.ts's stripMachineMarkers strips ALL fenced code blocks globally (not just the fix-handoff marker's own fence), so a legitimate code snippet embedded in a finding's body would be silently dropped from the filed issue — worth a comment noting this is intentional trade-off or scoping the strip to the specific marker pattern.
• src/mcp/server.ts:331-332 introduces bare numeric literals (3, 500) for the followUpIssueShape schema; consider reusing/naming a shared constant as done elsewhere (e.g. SCENARIO_MAX_REPO_FULL_NAME_CHARS) for consistency.
• buildFollowUpIssueSpec double-slices to FOLLOW_UP_ISSUE_BODY_MAX (once on safeFinding, again on the composed body) — redundant but harmless; could simplify to a single slice on the final composed string.
• src/mcp/server.ts continues to grow (now ~1508 lines per the size report) — consider extracting tool-registration blocks into per-tool modules in a follow-up, not blocking for this PR.
• Consider scoping stripMachineMarkers's fenced-block removal to only the known machine markers (HTML comment + the specific fix-handoff fence) rather than every fenced block, to avoid losing legitimate code context in filed issues.

Concerns raised — review before merging

• No linked issue detected — If this PR is intended to solve an issue, link it explicitly in the PR body.
• Maintainer requires a linked issue — Link the relevant issue (for example Closes #123) before opening the PR.

Signal	Result	Evidence
Code review	❌ 2 blockers	1 reviewer
Linked issue	⚠️ Missing	No linked issue or no-issue rationale found.
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 (no linked issue context).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 54 registered-repo PR(s), 46 merged, 399 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 54 PR(s), 399 issue(s).
Gate result	❌ Blocking	Repo-configured hard 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, JavaScript, Ruby, Go, Kotlin, MDX, Shell
• Official Gittensor activity: 54 PR(s), 399 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Explain no-issue PR.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.

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