feat(review): render AI-suggested fixes as GitHub suggested-change blocks

[JSONbored]

Closes #1956

Summary

• Found already half-wired: InlineFinding.suggestion already existed end to end on the generation side — src/services/ai-review.ts's system prompt explicitly asks the model for "suggestion": optional replacement text for that line, parseModelReview extracts it, and it's threaded through toPublicSafe filtering — but src/review/inline-comments.ts's formatInlineBody (the function that actually builds the posted GitHub comment) never read it. A generated fix was silently dropped before it ever reached a contributor.
• Fix: render finding.suggestion as a native ```suggestion block a contributor can commit in one click, appended after the finding text.
• New opt-in gate: .gittensory.yml's review.suggestions (default off), layered on top of the existing review.inline_comments three-gate — a suggestion has nothing to attach to without the inline comment it rides on, so shouldRenderSuggestions can never be true when inline comments are off, regardless of the manifest toggle. The AI is still always asked for a suggestion (cheap, already happening); only rendering it into the posted comment is gated, so no AI-review-cache fingerprint change is needed.
• Fails safe: a suggestion whose own text contains a triple-backtick run is dropped (keeping the finding text) rather than risking a corrupted comment — a real, deliberately-covered edge case, not a hypothetical.
• Line/range validation: already covered by the existing per-finding commentable-line check in selectInlineComments — a suggestion shares its parent finding's single anchored line, so if the line isn't valid, neither the finding nor its suggestion reaches GitHub (no 422).
• Config-as-code parity: review.suggestions is wired through FocusManifestReviewConfig (type, parse, the three "empty manifest" defaults, serialize/round-trip, resolveReviewPromptOverrides) mirroring review.inline_comments's exact existing pattern. No DB/migration/OpenAPI surface — review.* knobs are manifest-only (self-host .gittensory.yml), same as inline_comments today.
• Docs: extended the existing inline-comments bullet in README.md.

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• 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, or this is small enough that the summary explains why an issue is not needed.

Validation

• git diff --check
• npm run typecheck (clean)
• npx vitest run test/unit/inline-comments.test.ts test/unit/focus-manifest.test.ts test/unit/signals-coverage.test.ts — 349/349 passing
• npm run test:changed (every test file whose import graph touches this diff, against main) — 242 files, 6358 tests, all passing
• Scoped coverage: src/review/inline-comments.ts 100% statements/branches/functions/lines; my specific changed lines in src/signals/focus-manifest.ts are outside that file's small set of pre-existing, unrelated uncovered lines.
• npm run test:workers / npm run build:mcp / npm run test:mcp-pack / npm run ui:openapi:check / npm run ui:build — not run individually; no worker/MCP/OpenAPI/UI surface touched.
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries — shouldRenderSuggestions's full 4-combination truth table, formatInlineBody's default-off/explicit-off/enabled-with-suggestion/enabled-without-suggestion/backtick-fence-escape branches, manifest parse/serialize/round-trip + non-boolean-warns for review.suggestions, and an end-to-end maybePostInlineComments test threading the flag all the way to the posted comment body.

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 auth/session/CORS surface touched.
• API/OpenAPI/MCP behavior is updated and tested where needed. — N/A, manifest-only config (no DB/API surface), matching review.inline_comments's own precedent.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. — N/A, no UI change (posts to GitHub's native review-comment UI, not apps/gittensory-ui).
• Visible UI changes include a UI Evidence section below. — N/A, not an apps/gittensory-ui change.
• Public docs/changelogs are updated where needed. — extended the existing inline-comments bullet in README.md.

[superagent-security]

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

[loopover-orb]

Tip

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

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-05 18:01:23 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR closes the gap where `InlineFinding.suggestion` was already generated and threaded through `parseModelReview`/`toPublicSafe` but silently dropped by `formatInlineBody`, which never rendered it. The fix appends the suggestion as a GitHub-native ` ```suggestion ` fence, gated by a new opt-in `review.suggestions` manifest field that is correctly ANDed with the existing inline-comments gate (`shouldRenderSuggestions`), defaults to off everywhere (backward-compatible via the `suggestionsEnabled = false` default param and optional `suggestionsEnabled?` fields), and fails safe by dropping a suggestion whose text itself contains a triple-backtick run rather than corrupting the comment fence. The manifest wiring (type, parse, both empty-manifest defaults, serialize round-trip, `resolveReviewPromptOverrides`) mirrors the existing `inlineComments` pattern exactly, and `processors.ts` computes `inlineCommentsEnabledForReview` before deriving `suggestionsEnabledForReview` from it, so the dependency ordering is correct.

Nits — 6 non-blocking

• The `formatInlineBody`/`safeSuggestionBlock` fence check only detects a literal triple-backtick anywhere in the suggestion text — correct and conservative, but worth a one-line note that it can drop legitimate suggestions containing a nested code fence in a string literal, not just malicious ones.
• src/review/inline-comments.ts and focus-manifest.ts repeat the `(One-click suggested-change blocks on inline review comments #1956)` issue tag across several doc comments; consider consolidating into one top-of-file reference rather than restating it per function.
• README.md only documents `review.suggestions` in the inline-comments bullet — confirm the `.gittensory.yml` reference docs (linked at the bottom of that section) are updated too, since that's the canonical schema reference for operators.
• Consider a short integration-style test in test/unit/inline-comments.test.ts that also runs a suggestion through `rightSideLinesFromPatch`-based line-invalidity to explicitly document (not just assert via comment) that the shared line-anchoring check covers the suggestion case.
• In src/signals/focus-manifest.ts, the four `EMPTY_MANIFEST`/`emptyManifest`/`parseReviewConfig` object literals duplicating the same long field list are a pre-existing pattern (not introduced by this PR) but each now needs one more field kept in sync by hand — a small helper or spread-based default would reduce future one-off omissions like this one.
• 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	#1956
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: 56 registered-repo PR(s), 46 merged, 521 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 56 PR(s), 521 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 registration is not available in the local Gittensory cache.
• Public profile languages: Python, TypeScript, JavaScript, Ruby, Go, Kotlin, MDX, Shell
• Official Gittensor activity: 56 PR(s), 521 issue(s).
• PR-specific overlap: none found.

Contributor next steps

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

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 93.17%. Comparing base (7d0e2c4) to head (fc0260f).
⚠️ Report is 6 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3577   +/-   ##
=======================================
  Coverage   93.16%   93.17%           
=======================================
  Files         311      311           
  Lines       31750    31759    +9     
  Branches    11612    11616    +4     
=======================================
+ Hits        29581    29590    +9     
  Misses       1517     1517           
  Partials      652      652           

Files with missing lines	Coverage Δ
src/queue/processors.ts	93.58% <100.00%> (+<0.01%)	⬆️
src/review/inline-comments.ts	100.00% <100.00%> (ø)
src/signals/focus-manifest.ts	99.00% <100.00%> (+<0.01%)	⬆️

🚀 New features to boost your workflow:

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

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.