feat(review-pr): emit and validate GitHub suggestion blocks (#24)

## Summary

Adds GitHub one-click suggestion blocks to PR reviews, plus a validator
that sanitizes them before posting. GitHub rejects an entire review
(HTTP 422) if any one inline suggestion anchors to an invalid line, so
the validator strips malformed suggestions while keeping the prose
finding, so one bad suggestion cannot lose the whole review.

## What changed

| Area | Change |
| --- | --- |
| Emission | The agent embeds a `suggestion` fenced block for findings
with an exact fix on contiguous changed lines
(`review-pr/agents/pr-review.yaml`, `refs/posting-format.md`) |
| Validation | New `src/validate-suggestions` module parses addressable
right-side diff lines and strips suggestions GitHub would reject |
| Build and wiring | `tsup` entry plus `action.yml` staging; the
validator runs before the `gh api` post; agent diff fallbacks redirect
into `pr.diff` |

## Robustness (covered by unit tests)

| Case | Handling |
| --- | --- |
| Path with a space (git trailing tab in the `+++` header) | tab
stripped so the key matches `comment.path`; suggestion kept |
| Non-ASCII path (git C-quoting) | header decoded back to UTF-8;
suggestion kept |
| Closing fence shorter than the opener | closer must be at least as
long; longer blocks are not truncated |
| Second opener before any closer | first block treated as unclosed and
stripped, not merged |
| Comment with no integer line anchor | fails closed (stripped) instead
of 422-ing the review |
| Prefetch failure | agent diff fallbacks write `pr.diff` so the
validator reads the same diff |

## Validation

| Check | Result |
| --- | --- |
| Unit tests | 649 passed (35 in `validate-suggestions`) |
| Build (`tsup`) | pass |
| `biome ci`, `tsc --noEmit` | pass |
| `actionlint` | pass |

Each robustness case was additionally reproduced against the
implementation and confirmed handled via an independent adversarial
verification pass.

Author: Sayt-0

review-pr/README.md

@@ -307,6 +307,33 @@ confidence: strong (92/100)
 <!-- docker-agent-review -->
 ```
 
+When a finding has a small, exact fix, the comment also carries a GitHub
+[suggestion block](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request)
+with the precise replacement code, so it can be applied in one click:
+
+````markdown
+**[medium] Timeout is never applied**
+
+`DefaultConfig()` returns a zero `Timeout`; set it before use.
+
+```suggestion
+	cfg := DefaultConfig()
+	cfg.Timeout = 30 * time.Second
+```
+
+confidence: moderate (68/100)
+
+<!-- docker-agent-review -->
+````
+
+GitHub is strict about the lines a suggestion can attach to: a suggestion
+anchored outside the diff, spanning more than one hunk, or on a deleted line
+makes the whole review fail (HTTP 422). Before posting, the agent runs a
+validator that checks every suggestion's line range against the diff and strips
+any malformed block (keeping the prose finding), so one bad suggestion can never
+lose the whole review. The validator is implemented and unit-tested in
+[`src/validate-suggestions/`](../src/validate-suggestions/validate-suggestions.ts).
+
 When no issues are found:
 
 ```markdown

review-pr/action.yml

@@ -746,7 +746,7 @@ runs:
           echo ""
           echo "Execute the review pipeline:"
           echo ""
-          echo "1. **Gather**: Read the pre-fetched \`pr.diff\` file. If missing, run \`gh pr diff https://github.com/${REPO}/pull/${PR_NUMBER}\` (use the full URL, not just the number)"
+          echo "1. **Gather**: Read the pre-fetched \`pr.diff\` file. If missing, run \`gh pr diff https://github.com/${REPO}/pull/${PR_NUMBER} > pr.diff\` (use the full URL, not just the number) so the validator reads the same diff"
           echo '2. **Draft**: Delegate to `drafter` agent to generate bug hypotheses'
           echo '3. **Verify**: For each hypothesis, delegate to `verifier` agent'
           echo '4. **Post**: Aggregate findings and post review via `gh api`'
@@ -779,6 +779,13 @@ runs:
       run: |
         mkdir -p /tmp/refs
         cp "$ACTION_PATH"/agents/refs/*.md /tmp/refs/
+        # Stage the suggestion-block validator where the agent can run it before
+        # posting (the agent's working dir is the consumer repo, not the action).
+        if [ -f "$ACTION_PATH/../dist/validate-suggestions.js" ]; then
+          cp "$ACTION_PATH/../dist/validate-suggestions.js" /tmp/validate-suggestions.js
+        else
+          echo "::warning::validate-suggestions.js not found in dist — suggestion validation will be skipped"
+        fi
 
     # ========================================
     # RUN REVIEW using root docker-agent-action

review-pr/agents/pr-review.yaml

@@ -75,12 +75,15 @@ agents:
            skip every step that reads from `REFS_DIR`. Never look in `/tmp/`.
       1. Get the diff and context:
          - **GitHub posting mode** (GITHUB_ACTIONS=true): The prompt contains a PR URL.
-           a. Get the diff using this priority order (stop at the first one that works):
-              1. Check if `pr.diff` exists in the working directory (pre-fetched by the CI workflow)
-              2. `gh pr diff <URL>` using the full PR URL (e.g., `https://github.com/owner/repo/pull/123`).
+           a. Get the diff into the file `pr.diff` using this priority order (stop at the
+              first one that works). The drafter and the suggestion validator both read
+              `pr.diff`, so a fallback MUST redirect into it, not just print to stdout —
+              otherwise the validator sees no diff and strips every suggestion:
+              1. Check if `pr.diff` already exists in the working directory (pre-fetched by the CI workflow)
+              2. `gh pr diff <URL> > pr.diff` using the full PR URL (e.g., `https://github.com/owner/repo/pull/123`).
                  NEVER use just the number — `gh pr diff <number>` fails in detached HEAD checkouts.
-              3. `git diff $(git merge-base origin/main HEAD)...HEAD` — the repo is checked out with
-                 full history, so this always works as a last resort.
+              3. `git diff $(git merge-base origin/main HEAD)...HEAD > pr.diff` — the repo is checked out
+                 with full history, so this always works as a last resort.
               Do NOT try `curl`, `gh repo clone`, or any other method. The three options above are sufficient.
               After obtaining the diff, log which method succeeded:
               ```bash
@@ -224,6 +227,8 @@ agents:
          - **Inline comments** — every finding whose disposition is `inline`. Each comment uses
            the finding's `issue` (one-line summary), `details` (full explanation), `severity`,
            `category`, `file`, `line`, and a confidence label, e.g. `confidence: moderate (68/100)`.
+           When the fix is a small, exact, contiguous line replacement, also embed a GitHub
+           suggestion block with the exact replacement code (see "Suggestion blocks" below).
          - **Lower-confidence summary** — non-forced findings scoring below the inline threshold T
            (plus any pushed past the comment cap), listed under "Lower-confidence findings (not
            posted inline)" with their scores. Never silently drop these.
@@ -412,6 +417,29 @@ agents:
       in the body text. Each finding becomes an inline comment with `<!-- docker-agent-review -->`
       marker on its own line. Do NOT include the marker in console mode.
 
+      ## Suggestion blocks (GitHub posting mode)
+
+      When an inline finding has a small, exact fix that replaces one or more contiguous
+      changed lines, embed a GitHub suggestion block in the comment body containing the
+      EXACT replacement code (not a description) so the author can apply it in one click:
+
+      ````
+      ```suggestion
+      <exact replacement for the anchored line(s)>
+      ```
+      ````
+
+      Before writing the block, read the current line(s) with `read_file`/`grep -n` and
+      reproduce their indentation exactly — the block replaces the whole anchored range.
+      Anchor on the RIGHT side only (added `+`/context ` ` lines); NEVER put a suggestion on
+      a deleted line (`side: "LEFT"`). For a multi-line fix set `start_line`/`start_side`
+      (`start_line < line`, same hunk). Emit a block ONLY for a clean mechanical drop-in;
+      otherwise keep the suggestion as prose. See `/tmp/refs/posting-format.md` for the exact
+      field layout. GitHub is strict: a suggestion anchored outside the diff or on a deleted
+      line makes the WHOLE review fail (422). The mandatory validation step in the posting
+      template (`node /tmp/validate-suggestions.js /tmp/review_comments.json pr.diff`) strips
+      any malformed suggestion block before posting — run it; do not skip it.
+
       ## Domain-Specific Review Output
 
       When drafter findings reference a domain-specific guide (identifiable by
@@ -919,3 +947,4 @@ permissions:
     - shell:cmd=gh *
     - shell:cmd=git *
     - shell:cmd=grep *
+    - shell:cmd=node *

review-pr/agents/refs/posting-format.md

@@ -66,6 +66,21 @@ jq --arg path "$file_path" --argjson line "$old_line_number" --arg side "LEFT" \
   /tmp/review_comments.json > /tmp/review_comments.tmp \
   && mv /tmp/review_comments.tmp /tmp/review_comments.json
 
+# For a MULTI-LINE suggestion (replacing lines start..end within one hunk), add
+# start_line and start_side. start_line < line, both on the RIGHT side:
+jq --arg path "$file_path" --argjson start "$start_line_number" --argjson line "$end_line_number" \
+  --rawfile body /tmp/comment_body.md \
+  '. += [{path: $path, start_line: $start, start_side: "RIGHT", line: $line, side: "RIGHT", body: $body}]' \
+  /tmp/review_comments.json > /tmp/review_comments.tmp \
+  && mv /tmp/review_comments.tmp /tmp/review_comments.json
+
+# Validate & sanitize suggestion blocks BEFORE posting. GitHub rejects the
+# ENTIRE review (HTTP 422) if any one suggestion anchors outside the diff or to a
+# deleted line, so this strips malformed suggestion blocks (keeping the prose
+# finding) so one bad suggestion can't lose the whole review. Safe to run even
+# when there are no suggestions. `pr.diff` is the pre-fetched diff in the workdir.
+node /tmp/validate-suggestions.js /tmp/review_comments.json pr.diff
+
 # Defensive: remove any comments with empty bodies before posting
 jq '[.[] | select(.body | length > 0)]' /tmp/review_comments.json > /tmp/review_comments.tmp \
   && mv /tmp/review_comments.tmp /tmp/review_comments.json
@@ -83,6 +98,47 @@ jq -n \
 The `<!-- docker-agent-review -->` marker MUST be on its own line, separated by a blank line
 from the content. Do NOT include it in console output mode.
 
+# Suggestion Blocks (actionable fixes)
+
+When an in-scope finding has a small, exact fix that REPLACES one or more contiguous
+changed lines, include a GitHub suggestion block in the comment body so the author can
+apply it in one click. Put the EXACT replacement code in the block — the verbatim lines
+that should replace the anchored range, never a description of the change:
+
+````markdown
+**[medium] One-line issue summary**
+
+Why this is wrong and what the fix does.
+
+```suggestion
+	cfg := DefaultConfig()
+	cfg.Timeout = 30 * time.Second
+```
+
+confidence: moderate (68/100)
+
+<!-- docker-agent-review -->
+````
+
+Because the comment body is written via a quoted heredoc (`<< 'EOF'`), the backticks and
+indentation inside the block are preserved verbatim — no extra escaping is needed.
+
+Rules GitHub enforces (a violation makes the ENTIRE review fail with HTTP 422):
+- **Right side only.** A suggestion replaces right-side content, so anchor it on an added
+  (`+`) or context (` `) line. NEVER attach a suggestion to a deleted line (`side: "LEFT"`).
+- **The anchor is the replaced range.** A single-line suggestion uses `line`; a multi-line
+  suggestion uses `start_line`..`line` with `start_line < line` and `start_side: "RIGHT"`,
+  and the whole range MUST stay inside ONE diff hunk.
+- **Match the real code.** Read the current line(s) with `read_file`/`grep -n` first and
+  reproduce the existing indentation exactly — the block replaces the entire line range.
+- **One block per comment, fence closed.** Open with ` ```suggestion ` and close with ` ``` `.
+- **Only when it is a clean drop-in.** If the fix needs prose, edits elsewhere, or spans
+  non-contiguous lines, describe it in prose instead — do not force a suggestion block.
+
+The validator (`node /tmp/validate-suggestions.js …`, run before posting above) strips any
+suggestion block whose anchor breaks these rules and keeps the prose finding, but emit valid
+suggestions in the first place so the actionable fix survives.
+
 # Comment Scope (REQUIRED)
 
 Each comment must address a problem this PR **introduces** — one that would not exist if