fix: consistent url.PathEscape across all Gitea client endpoints

Apply url.PathEscape to owner, repo, and sha path segments in all methods that were previously interpolating raw values. Methods already using PathEscape (ListReviews, DeleteReview, GetTimelineReviewCommentID, EditComment) are unchanged. This eliminates an inconsistency flagged in PRs #17, #20, and #22 and prevents potential path-injection bugs for names with special characters. Closes #24
Merge pull request 'feat: inline review comments on specific lines' (#26 ) from feat/inline-review-comments into main
2026-05-02 02:41:51 -07:00 · 2026-05-02 06:13:02 +00:00 · 2026-05-01 23:01:32 -07:00 · 2026-05-01 22:50:13 -07:00 · 2026-05-01 22:46:45 -07:00 · 2026-05-01 22:17:36 -07:00
18 changed files with 2145 additions and 87 deletions
@@ -66,6 +66,14 @@ inputs:
    description: 'Print review to stdout instead of posting'
    required: false
    default: 'false'
+  update-existing:
+    description: 'Delete previous review from same bot after posting new one. Accepts: true/1/yes or false/0/no (default true)'
+    required: false
+    default: 'true'
+  system-prompt-file:
+    description: 'Local file with additional system prompt instructions (e.g. security review focus)'
+    required: false
+    default: ''

 runs:
  using: 'composite'
@@ -145,6 +153,8 @@ runs:
        LLM_TEMPERATURE: ${{ inputs.temperature }}
        LLM_TIMEOUT: ${{ inputs.timeout }}
        LLM_PROVIDER: ${{ inputs.llm-provider }}
+        UPDATE_EXISTING: ${{ inputs.update-existing }}
+        SYSTEM_PROMPT_FILE: ${{ inputs.system-prompt-file }}
      run: |
        ARGS=""
        if [ "${{ inputs.dry-run }}" = "true" ]; then
@@ -31,7 +31,11 @@ jobs:
            model: gpt-5
          - name: gpt
            token_secret: GPT_REVIEW_TOKEN
-            model: gpt-5-mini
+            model: gpt-4.1
+          - name: security
+            token_secret: SONNET_REVIEW_TOKEN
+            model: gpt-5
+            system_prompt_file: SECURITY_REVIEW.md
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
@@ -44,10 +48,13 @@ jobs:
          GITEA_REPO: ${{ github.repository }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          REVIEWER_TOKEN: ${{ secrets[matrix.token_secret] }}
+          REVIEWER_NAME: ${{ matrix.name }}
          LLM_BASE_URL: ${{ secrets.LLM_BASE_URL }}
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
          LLM_MODEL: ${{ matrix.model }}
          CONVENTIONS_FILE: "CONVENTIONS.md"
          PATTERNS_REPO: "rodin/go-patterns"
-          PATTERNS_FILES: "README.md,docs/"
+          PATTERNS_FILES: "README.md,patterns/"
+          LLM_TIMEOUT: "600"
+          SYSTEM_PROMPT_FILE: ${{ matrix.system_prompt_file }}
        run: ./review-bot
@@ -1,17 +1,242 @@
 # review-bot

-Automated code review bot for Gitea. Fetches a pull request diff, sends it to an LLM for analysis, and posts a structured review back to the PR.
+AI-powered code review bot for Gitea pull requests. Fetches diff + context, sends to an LLM, and posts a structured review (APPROVE / REQUEST_CHANGES) back to the PR.

 ## Features

- Fetches PR metadata, diff, and CI status from Gitea API
- Sends context-rich prompts to any OpenAI-compatible LLM
- Parses structured JSON review responses
- Posts formatted reviews (APPROVE / REQUEST_CHANGES) back to Gitea
- Supports custom coding conventions via repo files
- Zero external dependencies — Go stdlib only
+- **Multi-provider**: OpenAI-compatible and Anthropic Messages API
+- **Context-aware**: Fetches full file content, conventions, language patterns, CI status
+- **Smart budget**: Automatically trims context to fit model token limits
+- **Idempotent reviews**: Posts new review, then cleans up stale ones (one review per bot)
+- **Custom prompts**: Load additional instructions from a file (e.g. security-focused review)
+- **Zero dependencies**: Go stdlib only

-## Usage
+## Quick Start: Composite Action
+
+The easiest way to use review-bot in your Gitea CI:
+
+```yaml
+# .gitea/workflows/review.yml
+name: Review
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  review:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: https://gitea.weiker.me/rodin/review-bot/.gitea/actions/review@v0.1.0
+        with:
+          reviewer-token: ${{ secrets.REVIEW_TOKEN }}
+          reviewer-name: code-review
+          llm-base-url: ${{ secrets.LLM_BASE_URL }}
+          llm-api-key: ${{ secrets.LLM_API_KEY }}
+          llm-model: gpt-4.1
+```
+
+That's it. Every PR gets an automated review.
+
+## Examples
+
+### Single reviewer with conventions
+
+```yaml
+jobs:
+  review:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: https://gitea.weiker.me/rodin/review-bot/.gitea/actions/review@v0.1.0
+        with:
+          reviewer-token: ${{ secrets.REVIEW_TOKEN }}
+          reviewer-name: reviewer
+          llm-base-url: ${{ secrets.LLM_BASE_URL }}
+          llm-api-key: ${{ secrets.LLM_API_KEY }}
+          llm-model: gpt-4.1
+          conventions-file: CONVENTIONS.md
+          timeout: '600'
+```
+
+### Two reviewers with different models (diversity of opinion)
+
+```yaml
+jobs:
+  review:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        include:
+          - name: gpt
+            model: gpt-4.1
+            token_secret: GPT_REVIEW_TOKEN
+          - name: claude
+            model: claude-sonnet-4-20250514
+            token_secret: CLAUDE_REVIEW_TOKEN
+            provider: anthropic
+    steps:
+      - uses: actions/checkout@v4
+      - uses: https://gitea.weiker.me/rodin/review-bot/.gitea/actions/review@v0.1.0
+        with:
+          reviewer-token: ${{ secrets[matrix.token_secret] }}
+          reviewer-name: ${{ matrix.name }}
+          llm-base-url: ${{ secrets.LLM_BASE_URL }}
+          llm-api-key: ${{ secrets.LLM_API_KEY }}
+          llm-model: ${{ matrix.model }}
+          llm-provider: ${{ matrix.provider }}
+          conventions-file: CONVENTIONS.md
+```
+
+Each reviewer posts independently and only cleans up its own stale reviews.
+
+### Multiple review types from a single bot account
+
+Use the same Gitea token but different `reviewer-name` values to run specialized reviews without needing multiple bot accounts:
+
+```yaml
+jobs:
+  review:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        include:
+          - name: code-quality
+            model: gpt-4.1
+          - name: security
+            model: gpt-4.1
+            system_prompt_file: .review/SECURITY.md
+          - name: performance
+            model: gpt-4.1
+            system_prompt_file: .review/PERFORMANCE.md
+    steps:
+      - uses: actions/checkout@v4
+      - uses: https://gitea.weiker.me/rodin/review-bot/.gitea/actions/review@v0.1.0
+        with:
+          reviewer-token: ${{ secrets.REVIEW_TOKEN }}
+          reviewer-name: ${{ matrix.name }}
+          llm-base-url: ${{ secrets.LLM_BASE_URL }}
+          llm-api-key: ${{ secrets.LLM_API_KEY }}
+          llm-model: ${{ matrix.model }}
+          system-prompt-file: ${{ matrix.system_prompt_file }}
+```
+
+The sentinel `<!-- review-bot:security -->` ensures the security review only replaces previous security reviews, never the code-quality or performance reviews.
+
+### With language patterns from another repo
+
+```yaml
+- uses: https://gitea.weiker.me/rodin/review-bot/.gitea/actions/review@v0.1.0
+  with:
+    reviewer-token: ${{ secrets.REVIEW_TOKEN }}
+    reviewer-name: reviewer
+    llm-base-url: ${{ secrets.LLM_BASE_URL }}
+    llm-api-key: ${{ secrets.LLM_API_KEY }}
+    llm-model: gpt-4.1
+    conventions-file: CLAUDE.md
+    patterns-repo: rodin/go-patterns,rodin/kubernetes-conventions
+    patterns-files: "README.md,patterns/"
+```
+
+Pattern repos are fetched at review time. The reviewer uses them as criteria for idiomatic code.
+
+### Dry run (test without posting)
+
+```yaml
+- uses: https://gitea.weiker.me/rodin/review-bot/.gitea/actions/review@v0.1.0
+  with:
+    reviewer-token: ${{ secrets.REVIEW_TOKEN }}
+    reviewer-name: test
+    llm-base-url: ${{ secrets.LLM_BASE_URL }}
+    llm-api-key: ${{ secrets.LLM_API_KEY }}
+    llm-model: gpt-4.1
+    dry-run: 'true'
+```
+
+Prints the review to CI logs without posting to the PR. Useful for testing prompt changes.
+
+### Using Anthropic directly
+
+```yaml
+- uses: https://gitea.weiker.me/rodin/review-bot/.gitea/actions/review@v0.1.0
+  with:
+    reviewer-token: ${{ secrets.REVIEW_TOKEN }}
+    reviewer-name: claude
+    llm-base-url: https://api.anthropic.com
+    llm-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
+    llm-model: claude-sonnet-4-20250514
+    llm-provider: anthropic
+```
+
+## Action Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `reviewer-token` | Yes | — | Gitea token for posting reviews (needs `write:issue`, `write:repository`) |
+| `reviewer-name` | No | `""` | Logical identity for this reviewer. Used as sentinel for idempotent cleanup. Set this when running multiple review bots on the same PR. |
+| `llm-base-url` | Yes | — | LLM API base URL |
+| `llm-api-key` | Yes | — | LLM API key |
+| `llm-model` | Yes | — | Model name |
+| `llm-provider` | No | `openai` | API provider: `openai` or `anthropic` |
+| `conventions-file` | No | `""` | Path to coding conventions file in the repo |
+| `patterns-repo` | No | `""` | Comma-separated repos with language patterns (e.g. `rodin/go-patterns`) |
+| `patterns-files` | No | `README.md` | Files/directories to fetch from pattern repos |
+| `system-prompt-file` | No | `""` | Local file with additional system prompt instructions |
+| `temperature` | No | `0` | LLM temperature (0 = server default) |
+| `timeout` | No | `300` | LLM request timeout in seconds |
+| `dry-run` | No | `false` | Print review to stdout instead of posting |
+| `update-existing` | No | `true` | Delete previous review from same bot before posting. Accepts: true/1/yes or false/0/no |
+| `version` | No | `latest` | review-bot version to install |
+
+## How Review Cleanup Works
+
+When `reviewer-name` is set, the bot embeds a hidden sentinel in each review:
+
+```html
+<!-- review-bot:code-review -->
+```
+
+On the next run, it finds and deletes any review containing its own sentinel (except the one it just posted). This means:
+
+- **One review per bot per PR** — no clutter from repeated pushes
+- **Multiple bots coexist** — each only cleans up its own reviews
+- **Same token, different roles** — a single bot account can post "code-review" and "security" reviews without conflict
+- **No extra permissions** — identity comes from the sentinel, not the API
+
+If `reviewer-name` is empty, cleanup is skipped (reviews stack like before).
+
+### Shared Token: Worst-Wins Behavior
+
+When multiple review types share the same Gitea bot account (e.g. code-quality and security), Gitea determines the user's approval state from their **most recent review**. This creates a race condition: if security finds issues (REQUEST_CHANGES) but code-quality finishes last (APPROVE), the PR appears approved.
+
+review-bot handles this automatically with **worst-wins reconciliation**: before posting, each job checks whether any sibling review from the same user already has REQUEST_CHANGES. If so and this job would post APPROVE, it posts as REQUEST_CHANGES instead — maintaining the block. This ensures the PR stays blocked until all checks pass, regardless of execution order.
+
+**If you need independent approval/block per review type**, use separate Gitea bot accounts with their own tokens.
+
+## Custom Review Prompts
+
+Use `system-prompt-file` to specialize the review focus. The file contents are appended to the base system prompt as "Additional Review Instructions."
+
+Example `SECURITY_REVIEW.md`:
+
+```markdown
+You are performing a security-focused code review.
+
+Focus areas:
+- Injection attacks (SQL, command, path traversal, template)
+- Authentication/Authorization (missing checks, privilege escalation)
+- Secrets exposure (hardcoded credentials, tokens in logs)
+- Input validation (unsanitized input, unsafe deserialization)
+- Race conditions (TOCTOU, unsynchronized shared state)
+
+Rules:
+- Only report findings with security implications
+- Ignore style, naming, and general code quality
+- MAJOR = exploitable vulnerability, MINOR = hardening opportunity, NIT = theoretical risk
+- If no security-relevant changes exist, APPROVE with empty findings
+```
+
+## CLI Usage

 ```bash
 review-bot \
@@ -19,71 +244,74 @@ review-bot \
  --repo owner/name \
  --pr 42 \
  --reviewer-token "$GITEA_TOKEN" \
+  --reviewer-name "code-review" \
  --llm-base-url https://api.openai.com/v1 \
  --llm-api-key "$OPENAI_API_KEY" \
-  --llm-model gpt-4 \
-  --reviewer-name "Sonnet" \
-  --conventions-file CONVENTIONS.md \
-  --dry-run
+  --llm-model gpt-4.1 \
+  --conventions-file CONVENTIONS.md
 ```

 ## Environment Variables

-All flags can be set via environment variables:
+All flags have environment variable equivalents:

-| Flag | Env Var | Required | Description |
-|------|---------|----------|-------------|
-| `--gitea-url` | `GITEA_URL` | Yes | Gitea instance base URL |
-| `--repo` | `GITEA_REPO` | Yes | Repository in `owner/name` format |
-| `--pr` | `PR_NUMBER` | Yes | Pull request number |
-| `--reviewer-token` | `REVIEWER_TOKEN` | Yes | Gitea API token for posting reviews |
-| `--llm-base-url` | `LLM_BASE_URL` | Yes | OpenAI-compatible API base URL |
-| `--llm-api-key` | `LLM_API_KEY` | Yes | LLM API key |
-| `--llm-model` | `LLM_MODEL` | Yes | Model identifier |
-| `--reviewer-name` | `REVIEWER_NAME` | No | Display name in review footer |
-| `--conventions-file` | `CONVENTIONS_FILE` | No | Path to conventions file in repo |
-| `--dry-run` | — | No | Print review to stdout instead of posting |
+| Flag | Env Var |
+|------|---------|
+| `--gitea-url` | `GITEA_URL` |
+| `--repo` | `GITEA_REPO` |
+| `--pr` | `PR_NUMBER` |
+| `--reviewer-token` | `REVIEWER_TOKEN` |
+| `--reviewer-name` | `REVIEWER_NAME` |
+| `--llm-base-url` | `LLM_BASE_URL` |
+| `--llm-api-key` | `LLM_API_KEY` |
+| `--llm-model` | `LLM_MODEL` |
+| `--llm-provider` | `LLM_PROVIDER` |
+| `--conventions-file` | `CONVENTIONS_FILE` |
+| `--patterns-repo` | `PATTERNS_REPO` |
+| `--patterns-files` | `PATTERNS_FILES` |
+| `--system-prompt-file` | `SYSTEM_PROMPT_FILE` |
+| `--llm-temperature` | `LLM_TEMPERATURE` |
+| `--llm-timeout` | `LLM_TIMEOUT` |
+| `--update-existing` | `UPDATE_EXISTING` |

-## Adding to a Gitea Repository
+## Setup

-1. Build the binary or use the CI workflow approach (build in CI).
+1. **Create a Gitea bot account** (e.g. `review-bot`)
+2. **Generate a token** with scopes: `write:issue`, `write:repository`
+3. **Add secrets** to your Gitea repo (Settings → Actions → Secrets):
+   - `REVIEW_TOKEN` — the bot's Gitea token
+   - `LLM_BASE_URL` — your LLM endpoint
+   - `LLM_API_KEY` — your LLM key
+4. **Add the workflow** (see Quick Start above)

-2. Add secrets to your Gitea repo (Settings → Actions → Secrets):
-   - `SONNET_REVIEW_TOKEN` — Gitea token for the Sonnet reviewer account
-   - `GPT_REVIEW_TOKEN` — Gitea token for the GPT reviewer account
-   - `LLM_BASE_URL` — Your LLM API endpoint
-   - `LLM_API_KEY` — Your LLM API key
+### Token Scopes Required

-3. Copy `.gitea/workflows/ci.yml` to your repo (or adapt it).
+| Scope | Purpose |
+|-------|---------|
+| `write:issue` | Post and delete reviews |
+| `write:repository` | Read PR diffs, file content, commit statuses |

-4. On every PR, the bot will:
-   - Run tests and vet
-   - Build review-bot
-   - Post reviews from each configured LLM reviewer
+No `read:user` scope needed — the bot identifies itself from the review response.

 ## Development

 ```bash
-# Run tests
-go test ./...
-
-# Run vet
-go vet ./...
-
-# Build
+go test ./...        # Unit tests
+go vet ./...         # Static analysis
 go build -o review-bot ./cmd/review-bot

-# Integration tests (requires env vars)
+# Integration tests (requires env vars set)
 go test -tags=integration ./...
 ```

 ## Architecture

 ```
-cmd/review-bot/     CLI entrypoint
-gitea/              Gitea API client
-llm/                OpenAI-compatible LLM client
+cmd/review-bot/     CLI entrypoint + orchestration
+gitea/              Gitea API client (reviews, PRs, files)
+llm/                Multi-provider LLM client (OpenAI + Anthropic)
 review/             Prompt building, response parsing, formatting
+budget/             Token estimation + context trimming
 ```

 ## License
@@ -0,0 +1,18 @@
+You are performing a security-focused code review. Your primary concern is identifying vulnerabilities, not general code quality.
+
+Focus areas:
+- **Injection attacks**: SQL injection, command injection, path traversal, template injection
+- **Authentication/Authorization**: Missing auth checks, privilege escalation, IDOR
+- **Secrets exposure**: Hardcoded credentials, API keys in code, tokens in logs
+- **Input validation**: Untrusted input used without sanitization, unsafe deserialization
+- **Cryptography**: Weak algorithms, predictable randomness, improper key management
+- **Error handling**: Information leakage in error messages, stack traces exposed
+- **Dependencies**: Known vulnerable patterns, unsafe use of external libraries
+- **Race conditions**: TOCTOU bugs, unsynchronized shared state
+- **Resource exhaustion**: Unbounded allocations, missing timeouts, denial-of-service vectors
+
+Rules for this review:
+- Only report findings with actual security implications. Ignore style, naming, and general code quality.
+- Severity mapping: MAJOR = exploitable vulnerability or data exposure. MINOR = defense-in-depth improvement or hardening opportunity. NIT = theoretical concern with low practical risk.
+- If the code has no security-relevant changes, APPROVE with an empty findings list.
+- Do not duplicate findings that a standard code review would catch (logic bugs, missing error checks) unless they have a security dimension.
@@ -0,0 +1,226 @@
+// Package budget manages LLM context window budgeting for review-bot.
+//
+// It estimates token usage and progressively trims context content to fit
+// within model-specific limits. The trimming order (least important first):
+// patterns → conventions → file context → diff truncation.
+package budget
+
+import (
+	"fmt"
+	"strings"
+	"unicode/utf8"
+)
+
+// modelLimit pairs a model name prefix with its context window size.
+type modelLimit struct {
+	prefix string
+	limit  int
+}
+
+// Known model context limits (in tokens), ordered longest-prefix-first
+// for deterministic matching.
+var modelLimits = []modelLimit{
+	{"claude-haiku-3.5-20241022", 200_000},
+	{"claude-sonnet-4-20250514", 200_000},
+	{"claude-opus-4-20250514", 200_000},
+	{"gpt-4.1-mini", 128_000},
+	{"gpt-5-mini", 200_000},
+	{"gpt-4.1", 128_000},
+	{"gpt-5", 200_000},
+}
+
+const defaultLimit = 128_000
+
+// reserveTokens is headroom for the response generation.
+const reserveTokens = 4_000
+
+const diffTruncMarker = "\n\n... [diff truncated due to context limit] ..."
+const diffTooLargeMarker = "... [diff too large for context window — review manually] ..."
+const userMetaTruncMarker = "\n... [description truncated] ..."
+
+// EstimateTokens estimates the number of tokens in a string.
+// Uses the rough heuristic of ~4 bytes per token, which is
+// conservative for English text and code.
+func EstimateTokens(s string) int {
+	return len(s) / 4
+}
+
+// LimitForModel returns the context window size for the given model.
+// Uses longest-prefix-first matching for deterministic results.
+func LimitForModel(model string) int {
+	for _, ml := range modelLimits {
+		if model == ml.prefix || strings.HasPrefix(model, ml.prefix) {
+			return ml.limit
+		}
+	}
+	return defaultLimit
+}
+
+// Sections holds the prompt content sections in trim priority order.
+// When the total exceeds the budget, sections are trimmed from least
+// important (Patterns) to most important (Diff).
+type Sections struct {
+	SystemBase  string // Core instructions (never trimmed)
+	Patterns    string // Language patterns (trimmed first)
+	Conventions string // Repo conventions (trimmed second)
+	FileContext string // Full file content (trimmed third)
+	Diff        string // The actual diff (trimmed last, only truncated)
+	UserMeta    string // PR title, description, CI status (truncated only if base exceeds budget)
+}
+
+// Result holds the trimmed content and metadata about what was dropped.
+type Result struct {
+	SystemPrompt string
+	UserPrompt   string
+	Trimmed      []string // Human-readable descriptions of what was trimmed
+	EstTokens    int      // Estimated total tokens after trimming
+}
+
+// Fit trims sections to fit within the model's context limit.
+// Returns the assembled prompts and a list of what was trimmed.
+func Fit(model string, sections Sections) Result {
+	limit := LimitForModel(model) - reserveTokens
+
+	baseTokens := EstimateTokens(sections.SystemBase) + EstimateTokens(sections.UserMeta)
+	available := limit - baseTokens
+	if available < 0 {
+		// Base content alone exceeds budget. Truncate UserMeta (keep first ~1000 tokens).
+		if len(sections.UserMeta) > 4000 {
+			sections.UserMeta = truncateUTF8(sections.UserMeta, 4000) + userMetaTruncMarker
+			baseTokens = EstimateTokens(sections.SystemBase) + EstimateTokens(sections.UserMeta)
+			available = limit - baseTokens
+		}
+		if available < 0 {
+			available = 0
+		}
+	}
+
+	// Trimmable sections in priority order (first = dropped first)
+	type entry struct {
+		name    string
+		content *string
+	}
+	entries := []entry{
+		{"patterns", &sections.Patterns},
+		{"conventions", &sections.Conventions},
+		{"file context", &sections.FileContext},
+	}
+
+	// Check if everything fits
+	totalTrimmable := EstimateTokens(sections.Diff)
+	for _, e := range entries {
+		totalTrimmable += EstimateTokens(*e.content)
+	}
+
+	var trimmed []string
+	if totalTrimmable > available {
+		// Trim from least important
+		for i := range entries {
+			tokens := EstimateTokens(*entries[i].content)
+			if tokens == 0 {
+				continue
+			}
+			trimmed = append(trimmed, fmt.Sprintf("%s (~%dK tokens)", entries[i].name, tokens/1000))
+			*entries[i].content = ""
+
+			// Recalculate
+			totalTrimmable = EstimateTokens(sections.Diff)
+			for _, e := range entries {
+				totalTrimmable += EstimateTokens(*e.content)
+			}
+			if totalTrimmable <= available {
+				break
+			}
+		}
+	}
+
+	// If still too large, truncate the diff
+	if totalTrimmable > available {
+		diffBudget := available
+		for _, e := range entries {
+			diffBudget -= EstimateTokens(*e.content)
+		}
+		if diffBudget < 0 {
+			diffBudget = 0
+		}
+		// Reserve space for truncation marker
+		markerBudget := EstimateTokens(diffTruncMarker)
+		effectiveBudget := diffBudget - markerBudget
+		if effectiveBudget < 0 {
+			effectiveBudget = 0
+		}
+		maxChars := effectiveBudget * 4
+		if maxChars < len(sections.Diff) {
+			removed := EstimateTokens(sections.Diff) - diffBudget
+			trimmed = append(trimmed, fmt.Sprintf("diff truncated (~%dK tokens removed)", removed/1000))
+			if maxChars > 0 {
+				if diffBudget >= markerBudget {
+					sections.Diff = truncateUTF8(sections.Diff, maxChars) + diffTruncMarker
+				} else {
+					sections.Diff = truncateUTF8(sections.Diff, maxChars)
+				}
+			} else {
+				sections.Diff = diffTooLargeMarker
+			}
+		}
+	}
+
+	finalTokens := baseTokens
+	for _, e := range entries {
+		finalTokens += EstimateTokens(*e.content)
+	}
+	finalTokens += EstimateTokens(sections.Diff)
+
+	return buildResult(sections, trimmed, finalTokens)
+}
+
+func buildResult(s Sections, trimmed []string, estTokens int) Result {
+	var sys strings.Builder
+	sys.WriteString(s.SystemBase)
+	if s.Patterns != "" {
+		sys.WriteString("\n\n## Language Patterns & Idioms\n\nUse the following patterns as review criteria. Code that violates these established patterns is a finding:\n\n")
+		sys.WriteString(s.Patterns)
+	}
+	if s.Conventions != "" {
+		sys.WriteString("\n\n## Repository Conventions\n\nThe repository has the following coding conventions that must be respected:\n\n")
+		sys.WriteString(s.Conventions)
+	}
+
+	var usr strings.Builder
+	usr.WriteString(s.UserMeta)
+	if s.FileContext != "" {
+		usr.WriteString("\n### Full File Context (modified files)\n\n")
+		usr.WriteString(s.FileContext)
+		usr.WriteString("\n")
+	}
+	if s.Diff != "" {
+		usr.WriteString("\n### Diff (changes to review)\n\n```diff\n")
+		usr.WriteString(s.Diff)
+		usr.WriteString("\n```\n")
+	}
+
+	if len(trimmed) > 0 {
+		usr.WriteString("\n⚠️ Note: Context was trimmed to fit model limits. Dropped: ")
+		usr.WriteString(strings.Join(trimmed, ", "))
+		usr.WriteString("\n")
+	}
+
+	return Result{
+		SystemPrompt: sys.String(),
+		UserPrompt:   usr.String(),
+		Trimmed:      trimmed,
+		EstTokens:    estTokens,
+	}
+}
+
+// truncateUTF8 truncates s to at most maxBytes without splitting multi-byte
+// UTF-8 characters. Returns a valid UTF-8 string of at most maxBytes bytes.
+func truncateUTF8(s string, maxBytes int) string {
+	if len(s) <= maxBytes {
+		return s
+	}
+	for maxBytes > 0 && !utf8.RuneStart(s[maxBytes]) {
+		maxBytes--
+	}
+	return s[:maxBytes]
+}
@@ -0,0 +1,203 @@
+package budget
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestEstimateTokens(t *testing.T) {
+	tests := []struct {
+		input string
+		want  int
+	}{
+		{"", 0},
+		{"abcd", 1},
+		{"12345678", 2},
+		{strings.Repeat("x", 400), 100},
+	}
+	for _, tt := range tests {
+		got := EstimateTokens(tt.input)
+		if got != tt.want {
+			t.Errorf("EstimateTokens(%d chars) = %d, want %d", len(tt.input), got, tt.want)
+		}
+	}
+}
+
+func TestLimitForModel(t *testing.T) {
+	tests := []struct {
+		model string
+		want  int
+	}{
+		{"gpt-4.1", 128_000},
+		{"gpt-5", 200_000},
+		{"gpt-5-mini", 200_000},
+		{"unknown-model", defaultLimit},
+		{"gpt-4.1-2026-01-01", 128_000}, // prefix match
+	}
+	for _, tt := range tests {
+		got := LimitForModel(tt.model)
+		if got != tt.want {
+			t.Errorf("LimitForModel(%q) = %d, want %d", tt.model, got, tt.want)
+		}
+	}
+}
+
+func TestFit_AllFits(t *testing.T) {
+	s := Sections{
+		SystemBase:  "system instructions",
+		Patterns:    "some patterns",
+		Conventions: "some conventions",
+		FileContext: "file content",
+		Diff:        "diff content",
+		UserMeta:    "PR: title\n",
+	}
+	result := Fit("gpt-5", s)
+
+	if len(result.Trimmed) != 0 {
+		t.Errorf("expected no trimming, got %v", result.Trimmed)
+	}
+	if !strings.Contains(result.SystemPrompt, "some patterns") {
+		t.Error("expected patterns in system prompt")
+	}
+	if !strings.Contains(result.SystemPrompt, "some conventions") {
+		t.Error("expected conventions in system prompt")
+	}
+	if !strings.Contains(result.UserPrompt, "file content") {
+		t.Error("expected file context in user prompt")
+	}
+}
+
+func TestFit_TrimsPatterns(t *testing.T) {
+	// Create content that exceeds 128K token budget for gpt-4.1
+	// Budget ≈ 128K - 4K reserve = 124K tokens = ~496K chars
+	// Fill patterns with enough to push over
+	bigPatterns := strings.Repeat("x", 500_000) // ~125K tokens
+	s := Sections{
+		SystemBase:  "base",
+		Patterns:    bigPatterns,
+		Conventions: "conventions",
+		FileContext: "files",
+		Diff:        "diff",
+		UserMeta:    "meta",
+	}
+	result := Fit("gpt-4.1", s)
+
+	if len(result.Trimmed) == 0 {
+		t.Fatal("expected trimming")
+	}
+	if !strings.Contains(result.Trimmed[0], "patterns") {
+		t.Errorf("expected patterns to be trimmed first, got %v", result.Trimmed)
+	}
+	if strings.Contains(result.SystemPrompt, bigPatterns[:100]) {
+		t.Error("expected patterns to be removed from output")
+	}
+	// Conventions should survive
+	if !strings.Contains(result.SystemPrompt, "conventions") {
+		t.Error("expected conventions to survive after patterns trimmed")
+	}
+}
+
+func TestFit_TrimsConventions(t *testing.T) {
+	// Patterns + conventions + diff all exceed budget even after patterns removed
+	big := strings.Repeat("y", 520_000) // ~130K tokens each (exceeds 124K budget even alone)
+	s := Sections{
+		SystemBase:  "base",
+		Patterns:    big,
+		Conventions: big,
+		FileContext: "files",
+		Diff:        "diff",
+		UserMeta:    "meta",
+	}
+	result := Fit("gpt-4.1", s)
+
+	if len(result.Trimmed) < 2 {
+		t.Fatalf("expected at least 2 trimmed, got %v", result.Trimmed)
+	}
+	if !strings.Contains(result.Trimmed[0], "patterns") {
+		t.Errorf("expected patterns trimmed first, got %s", result.Trimmed[0])
+	}
+	if !strings.Contains(result.Trimmed[1], "conventions") {
+		t.Errorf("expected conventions trimmed second, got %s", result.Trimmed[1])
+	}
+}
+
+func TestFit_TruncatesDiff(t *testing.T) {
+	// Only diff is huge, no patterns/conventions
+	hugeDiff := strings.Repeat("z", 600_000) // ~150K tokens > 128K limit
+	s := Sections{
+		SystemBase: "base",
+		Diff:       hugeDiff,
+		UserMeta:   "meta",
+	}
+	result := Fit("gpt-4.1", s)
+
+	if len(result.Trimmed) == 0 {
+		t.Fatal("expected diff truncation")
+	}
+	if !strings.Contains(result.Trimmed[len(result.Trimmed)-1], "diff truncated") {
+		t.Errorf("expected diff truncation note, got %v", result.Trimmed)
+	}
+	if !strings.Contains(result.UserPrompt, "[diff truncated due to context limit]") {
+		t.Error("expected truncation marker in user prompt")
+	}
+}
+
+func TestFit_PreservesNoteInOutput(t *testing.T) {
+	big := strings.Repeat("w", 500_000)
+	s := Sections{
+		SystemBase: "base",
+		Patterns:   big,
+		Diff:       "small diff",
+		UserMeta:   "meta",
+	}
+	result := Fit("gpt-4.1", s)
+
+	if !strings.Contains(result.UserPrompt, "⚠️ Note: Context was trimmed") {
+		t.Error("expected trimming note in user prompt")
+	}
+}
+
+
+func TestFit_HugeUserMeta(t *testing.T) {
+	// UserMeta so large that base alone exceeds limit
+	// Use a unique marker past the truncation point
+	hugeDesc := strings.Repeat("d", 5000) + "UNIQUE_MARKER_PAST_TRUNCATION" + strings.Repeat("d", 595_000)
+	s := Sections{
+		SystemBase: "base",
+		Diff:       "small diff",
+		UserMeta:   hugeDesc,
+	}
+	result := Fit("gpt-4.1", s)
+
+	limit := LimitForModel("gpt-4.1") - reserveTokens
+	if result.EstTokens > limit {
+		t.Errorf("EstTokens %d exceeds limit %d", result.EstTokens, limit)
+	}
+	// Content past truncation point should not be present
+	if strings.Contains(result.UserPrompt, "UNIQUE_MARKER_PAST_TRUNCATION") {
+		t.Error("expected UserMeta to be truncated but found content past truncation point")
+	}
+	// Truncation marker should be present
+	if !strings.Contains(result.UserPrompt, "[description truncated]") {
+		t.Error("expected truncation marker in output")
+	}
+}
+
+func TestFit_NeverExceedsLimit(t *testing.T) {
+	// All sections huge — verify final tokens never exceed limit
+	big := strings.Repeat("a", 200_000)
+	s := Sections{
+		SystemBase:  strings.Repeat("s", 8000),
+		Patterns:    big,
+		Conventions: big,
+		FileContext: big,
+		Diff:        big,
+		UserMeta:    strings.Repeat("m", 8000),
+	}
+	result := Fit("gpt-4.1", s)
+
+	limit := LimitForModel("gpt-4.1") - reserveTokens
+	if result.EstTokens > limit {
+		t.Errorf("EstTokens %d exceeds limit %d (trimmed: %v)", result.EstTokens, limit, result.Trimmed)
+	}
+}
@@ -6,10 +6,12 @@ import (
 	"fmt"
 	"log"
 	"os"
+	"path/filepath"
 	"strconv"
 	"strings"
 	"time"

+	"gitea.weiker.me/rodin/review-bot/budget"
 	"gitea.weiker.me/rodin/review-bot/gitea"
 	"gitea.weiker.me/rodin/review-bot/llm"
 	"gitea.weiker.me/rodin/review-bot/review"
@@ -29,9 +31,11 @@ func main() {
 	llmAPIKey := flag.String("llm-api-key", envOrDefault("LLM_API_KEY", ""), "LLM API key")
 	llmModel := flag.String("llm-model", envOrDefault("LLM_MODEL", ""), "LLM model name")
 	conventionsFile := flag.String("conventions-file", envOrDefault("CONVENTIONS_FILE", ""), "Conventions file path in repo (e.g. CLAUDE.md)")
+	systemPromptFile := flag.String("system-prompt-file", envOrDefault("SYSTEM_PROMPT_FILE", ""), "Local file with additional system prompt instructions")
 	patternsRepo := flag.String("patterns-repo", envOrDefault("PATTERNS_REPO", ""), "Repo with language patterns (e.g. rodin/elixir-patterns)")
 	patternsFiles := flag.String("patterns-files", envOrDefault("PATTERNS_FILES", "README.md"), "Comma-separated file paths to fetch from patterns repo")
 	dryRun := flag.Bool("dry-run", false, "Print review to stdout instead of posting")
+	updateExisting := flag.Bool("update-existing", envOrDefaultBool("UPDATE_EXISTING", true), "Delete previous review from same bot before posting (default true)")
 	llmTemp := flag.Float64("llm-temperature", envOrDefaultFloat("LLM_TEMPERATURE", 0), "LLM temperature (0 = server default)")
 	llmTimeout := flag.Int("llm-timeout", envOrDefaultInt("LLM_TIMEOUT", 300), "LLM request timeout in seconds (default 300)")
 	llmProvider := flag.String("llm-provider", envOrDefault("LLM_PROVIDER", "openai"), "LLM API provider: openai or anthropic")
@@ -53,6 +57,11 @@ func main() {
 		os.Exit(1)
 	}

+	// Validate reviewer-name: only safe characters allowed in sentinel
+	if err := validateReviewerName(*reviewerName); err != nil {
+		log.Fatalf("%v", err)
+	}
+
 	// Parse repo owner/name
 	parts := strings.SplitN(*repo, "/", 2)
 	if len(parts) != 2 {
@@ -148,15 +157,62 @@ func main() {
 		log.Printf("Loaded patterns from %s (%d bytes)", *patternsRepo, len(patterns))
 	}

-	// Step 7: Build prompts
-	systemPrompt := review.BuildSystemPrompt(conventions, patterns)
-	userPrompt := review.BuildUserPrompt(pr.Title, pr.Body, diff, fileContext, ciPassed, ciDetails)
+	// Step 6b: Load additional system prompt if specified
+	additionalPrompt := ""
+	if *systemPromptFile != "" {
+		workspace := os.Getenv("GITHUB_WORKSPACE")
+		if workspace == "" {
+			workspace, _ = os.Getwd()
+		}
+		absWorkspace, err := filepath.Abs(workspace)
+		if err != nil {
+			log.Fatalf("Failed to resolve workspace path: %v", err)
+		}
+		promptPath := filepath.Join(absWorkspace, *systemPromptFile)
+		promptPath = filepath.Clean(promptPath)
+		if !strings.HasPrefix(promptPath, absWorkspace+string(filepath.Separator)) && promptPath != absWorkspace {
+			log.Fatalf("system-prompt-file resolves outside workspace (got %q, workspace %q)", promptPath, absWorkspace)
+		}
+		// Resolve symlinks and re-validate to prevent symlink traversal
+		resolvedPath, err := filepath.EvalSymlinks(promptPath)
+		if err != nil {
+			log.Fatalf("Failed to resolve system prompt file %q: %v", promptPath, err)
+		}
+		if !strings.HasPrefix(resolvedPath, absWorkspace+string(filepath.Separator)) && resolvedPath != absWorkspace {
+			log.Fatalf("system-prompt-file symlink resolves outside workspace (got %q, workspace %q)", resolvedPath, absWorkspace)
+		}
+		data, err := os.ReadFile(resolvedPath)
+		if err != nil {
+			log.Fatalf("Failed to read system prompt file %q: %v", promptPath, err)
+		}
+		additionalPrompt = string(data)
+		log.Printf("Loaded system prompt file: %s (%d bytes)", *systemPromptFile, len(additionalPrompt))
+	}
+
+	// Step 7: Budget-aware prompt assembly
+	systemBase := review.BuildSystemBase()
+	if additionalPrompt != "" {
+		systemBase += "\n\n## Additional Review Instructions\n\n" + additionalPrompt
+	}
+	sections := budget.Sections{
+		SystemBase:  systemBase,
+		Patterns:    patterns,
+		Conventions: conventions,
+		FileContext: fileContext,
+		Diff:        diff,
+		UserMeta:    review.BuildUserMeta(pr.Title, pr.Body, ciPassed, ciDetails),
+	}
+	budgetResult := budget.Fit(*llmModel, sections)
+	log.Printf("Token estimate: ~%dK (limit: %dK)", budgetResult.EstTokens/1000, budget.LimitForModel(*llmModel)/1000)
+	if len(budgetResult.Trimmed) > 0 {
+		log.Printf("Context trimmed: %v", budgetResult.Trimmed)
+	}

 	// Step 8: Call LLM
 	log.Printf("Sending to LLM (%s)...", *llmModel)
 	messages := []llm.Message{
-		{Role: "system", Content: systemPrompt},
-		{Role: "user", Content: userPrompt},
+		{Role: "system", Content: budgetResult.SystemPrompt},
+		{Role: "user", Content: budgetResult.UserPrompt},
 	}

 	response, err := llmClient.Complete(ctx, messages)
@@ -183,11 +239,112 @@ func main() {
 		return
 	}

+	sentinel := fmt.Sprintf("<!-- review-bot:%s -->", *reviewerName)
+
+	// Map findings to inline comments for lines present in the diff
+	diffRanges := gitea.ParseDiffNewLines(diff)
+	var inlineComments []gitea.ReviewComment
+	for _, f := range result.Findings {
+		if f.File != "" && f.Line > 0 && diffRanges.Contains(f.File, f.Line) {
+			inlineComments = append(inlineComments, gitea.ReviewComment{
+				Path:        f.File,
+				NewPosition: int64(f.Line),
+				Body:        fmt.Sprintf("**[%s]** %s", f.Severity, f.Finding),
+			})
+		}
+	}
+	if len(inlineComments) > 0 {
+		log.Printf("Attaching %d inline comments", len(inlineComments))
+	}
+
+	// --- Review update strategy ---
+	// 1. No existing review → POST new
+	// 2. Existing review, same state → PATCH body in place (preserves threads)
+	// 3. Existing review, state change → PATCH old to "Superseded", POST new
+	if *updateExisting && *reviewerName != "" {
+		existingReviews, err := giteaClient.ListReviews(ctx, owner, repoName, prNumber)
+		if err != nil {
+			log.Printf("Warning: could not list existing reviews: %v", err)
+		} else {
+			// Worst-wins: escalate if a sibling blocks (need own login from existing review)
+			ownLogin := ""
+			existing := findOwnReview(existingReviews, sentinel)
+			if existing != nil {
+				ownLogin = existing.User.Login
+			}
+			if event == "APPROVED" && shouldEscalate(existingReviews, 0, ownLogin, sentinel) {
+				log.Printf("Sibling review has REQUEST_CHANGES; escalating to REQUEST_CHANGES")
+				event = "REQUEST_CHANGES"
+			}
+
+			if existing != nil {
+				if reviewUnchanged(existingReviews, reviewBody, event, sentinel) {
+					log.Printf("Review unchanged from previous run; skipping to preserve threads")
+					return
+				}
+
+				// Same state → PATCH in place
+				if existing.State == event {
+					commentID, err := giteaClient.GetTimelineReviewCommentID(ctx, owner, repoName, prNumber, sentinel)
+					if err != nil {
+						log.Printf("Warning: could not find review comment ID, falling back to new post: %v", err)
+					} else {
+						if err := giteaClient.EditComment(ctx, owner, repoName, commentID, reviewBody); err != nil {
+							log.Printf("Warning: could not edit review, falling back to new post: %v", err)
+						} else {
+							log.Printf("Review updated in place (comment_id=%d)", commentID)
+							return
+						}
+					}
+				} else {
+					// State change → mark old as superseded, post new below
+					commentID, err := giteaClient.GetTimelineReviewCommentID(ctx, owner, repoName, prNumber, sentinel)
+					if err != nil {
+						log.Printf("Warning: could not find old review comment ID: %v", err)
+					} else {
+						supersededBody := fmt.Sprintf("~~*This review has been superseded by a newer review below.*~~\n\n%s", sentinel)
+						if err := giteaClient.EditComment(ctx, owner, repoName, commentID, supersededBody); err != nil {
+							log.Printf("Warning: could not mark old review as superseded: %v", err)
+						} else {
+							log.Printf("Marked old review as superseded (state was %s, now %s)", existing.State, event)
+						}
+					}
+				}
+			}
+		}
+	}
+
+	// POST new review (first run, or state transition fallthrough)
 	log.Printf("Posting review (event=%s)...", event)
-	if err := giteaClient.PostReview(ctx, owner, repoName, prNumber, event, reviewBody); err != nil {
+	posted, err := giteaClient.PostReview(ctx, owner, repoName, prNumber, event, reviewBody, inlineComments)
+	if err != nil {
 		log.Fatalf("Failed to post review: %v", err)
 	}
-	log.Printf("Review posted successfully!")
+	log.Printf("Review posted (id=%d, user=%s)", posted.ID, posted.User.Login)
+
+	// Post-posting escalation: if we just posted APPROVED but a sibling
+	// from the same user has REQUEST_CHANGES, mark ours as superseded and
+	// re-post as REQUEST_CHANGES. This handles the first-run case where
+	// we don't know our login until after posting.
+	if event == "APPROVED" && *updateExisting && *reviewerName != "" {
+		reviews, err := giteaClient.ListReviews(ctx, owner, repoName, prNumber)
+		if err == nil && shouldEscalate(reviews, posted.ID, posted.User.Login, sentinel) {
+			log.Printf("Post-posting escalation: sibling has REQUEST_CHANGES")
+			// Mark our just-posted review as superseded
+			commentID, err := giteaClient.GetTimelineReviewCommentID(ctx, owner, repoName, prNumber, sentinel)
+			if err == nil {
+				supersededBody := fmt.Sprintf("~~*This review has been superseded by a newer review below.*~~\n\n%s", sentinel)
+				giteaClient.EditComment(ctx, owner, repoName, commentID, supersededBody)
+			}
+			// Re-post as REQUEST_CHANGES
+			_, err = giteaClient.PostReview(ctx, owner, repoName, prNumber, "REQUEST_CHANGES", reviewBody, inlineComments)
+			if err != nil {
+				log.Printf("Warning: could not re-post as REQUEST_CHANGES: %v", err)
+			} else {
+				log.Printf("Review escalated to REQUEST_CHANGES")
+			}
+		}
+	}
 }

 // fetchFileContext fetches the full content of modified files from the PR branch.
@@ -250,12 +407,12 @@ func fetchPatterns(ctx context.Context, client *gitea.Client, patternsRepo, patt
 				continue
 			}

-			for filepath, content := range files {
+			for filePath, content := range files {
 				// Only include markdown and text files as patterns
-				if !isPatternFile(filepath) {
+				if !isPatternFile(filePath) {
 					continue
 				}
-				sb.WriteString(fmt.Sprintf("### %s/%s\n\n%s\n\n", repoRef, filepath, content))
+				sb.WriteString(fmt.Sprintf("### %s/%s\n\n%s\n\n", repoRef, filePath, content))
 			}
 		}
 	}
@@ -321,3 +478,73 @@ func envOrDefaultInt(key string, defaultVal int) int {
 	}
 	return defaultVal
 }
+
+func envOrDefaultBool(key string, defaultVal bool) bool {
+	v := strings.TrimSpace(strings.ToLower(os.Getenv(key)))
+	if v == "" {
+		return defaultVal
+	}
+	return v == "true" || v == "1" || v == "yes"
+}
+
+// validateReviewerName checks that the name contains only safe characters
+// for embedding in an HTML comment sentinel ([a-zA-Z0-9_-]).
+func validateReviewerName(name string) error {
+	if name == "" {
+		return nil
+	}
+	for _, ch := range name {
+		if !((ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') || (ch >= '0' && ch <= '9') || ch == '-' || ch == '_') {
+			return fmt.Errorf("reviewer-name must contain only [a-zA-Z0-9_-] (got %q)", name)
+		}
+	}
+	return nil
+}
+
+// shouldEscalate checks if any sibling bot review from the same user
+// (different sentinel, same token) has REQUEST_CHANGES.
+// ownLogin is the bot user login; if empty, escalation check is skipped.
+// postedID is excluded from consideration (0 means no exclusion needed).
+func shouldEscalate(reviews []gitea.Review, postedID int64, ownLogin, ownSentinel string) bool {
+	if ownLogin == "" {
+		return false
+	}
+	for _, r := range reviews {
+		if r.ID == postedID || r.Stale {
+			continue
+		}
+		// Sibling = same user, has a review-bot sentinel, but not OUR sentinel
+		if r.User.Login == ownLogin && r.State == "REQUEST_CHANGES" && strings.Contains(r.Body, "<!-- review-bot:") && !strings.Contains(r.Body, ownSentinel) {
+			return true
+		}
+	}
+	return false
+}
+
+// reviewUnchanged checks if an existing review with the same sentinel
+// already has identical body and state. Returns true if a re-post would
+// produce the same result (skip to preserve conversation threads).
+func reviewUnchanged(reviews []gitea.Review, newBody, newEvent, sentinel string) bool {
+	for _, r := range reviews {
+		if r.Stale {
+			continue
+		}
+		if !strings.Contains(r.Body, sentinel) {
+			continue
+		}
+		if r.State == newEvent && r.Body == newBody {
+			return true
+		}
+	}
+	return false
+}
+
+// findOwnReview locates a review matching the given sentinel in its body.
+func findOwnReview(reviews []gitea.Review, sentinel string) *gitea.Review {
+	for i := range reviews {
+		if strings.Contains(reviews[i].Body, sentinel) {
+			return &reviews[i]
+		}
+	}
+	return nil
+}
@@ -0,0 +1,290 @@
+package main
+
+import (
+	"testing"
+
+	"gitea.weiker.me/rodin/review-bot/gitea"
+)
+
+func TestValidateReviewerName(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   string
+		wantErr bool
+	}{
+		{"valid simple", "sonnet", false},
+		{"valid with dash", "code-review", false},
+		{"valid with underscore", "my_bot", false},
+		{"valid alphanumeric", "bot123", false},
+		{"valid uppercase", "MyBot", false},
+		{"empty is valid", "", false},
+		{"invalid html close", "foo-->", true},
+		{"invalid space", "my bot", true},
+		{"invalid dot", "my.bot", true},
+		{"invalid slash", "my/bot", true},
+		{"invalid angle", "bot<script>", true},
+		{"invalid colon", "bot:name", true},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validateReviewerName(tc.input)
+			if tc.wantErr && err == nil {
+				t.Errorf("expected error for %q, got nil", tc.input)
+			}
+			if !tc.wantErr && err != nil {
+				t.Errorf("expected no error for %q, got %v", tc.input, err)
+			}
+		})
+	}
+}
+
+func makeReview(id int64, login, state string, stale bool, body string) gitea.Review {
+	r := gitea.Review{
+		ID:    id,
+		Body:  body,
+		State: state,
+		Stale: stale,
+	}
+	r.User.Login = login
+	return r
+}
+
+func TestShouldEscalate(t *testing.T) {
+	tests := []struct {
+		name        string
+		reviews     []gitea.Review
+		postedID    int64
+		ownLogin    string
+
+		ownSentinel string
+		want        bool
+	}{
+		{
+			name:        "no reviews",
+			reviews:     nil,
+			postedID:    100,
+			ownLogin:    "bot",
+			ownSentinel: "<!-- review-bot:sonnet -->",
+			want:        false,
+		},
+		{
+			name: "sibling same user has REQUEST_CHANGES",
+			reviews: []gitea.Review{
+				makeReview(101, "bot", "REQUEST_CHANGES", false, "bad\n<!-- review-bot:security -->"),
+			},
+			postedID:    100,
+			ownLogin:    "bot",
+			ownSentinel: "<!-- review-bot:sonnet -->",
+			want:        true,
+		},
+		{
+			name: "sibling different user has REQUEST_CHANGES (should NOT escalate)",
+			reviews: []gitea.Review{
+				makeReview(101, "other-bot", "REQUEST_CHANGES", false, "bad\n<!-- review-bot:gpt -->"),
+			},
+			postedID:    100,
+			ownLogin:    "bot",
+			ownSentinel: "<!-- review-bot:sonnet -->",
+			want:        false,
+		},
+		{
+			name: "same user REQUEST_CHANGES but stale (should NOT escalate)",
+			reviews: []gitea.Review{
+				makeReview(101, "bot", "REQUEST_CHANGES", true, "old\n<!-- review-bot:security -->"),
+			},
+			postedID:    100,
+			ownLogin:    "bot",
+			ownSentinel: "<!-- review-bot:sonnet -->",
+			want:        false,
+		},
+		{
+			name: "same user same sentinel (own stale review, should NOT escalate)",
+			reviews: []gitea.Review{
+				makeReview(101, "bot", "REQUEST_CHANGES", false, "old\n<!-- review-bot:sonnet -->"),
+			},
+			postedID:    100,
+			ownLogin:    "bot",
+			ownSentinel: "<!-- review-bot:sonnet -->",
+			want:        false,
+		},
+		{
+			name: "same user APPROVED sibling (should NOT escalate)",
+			reviews: []gitea.Review{
+				makeReview(101, "bot", "APPROVED", false, "good\n<!-- review-bot:security -->"),
+			},
+			postedID:    100,
+			ownLogin:    "bot",
+			ownSentinel: "<!-- review-bot:sonnet -->",
+			want:        false,
+		},
+		{
+			name: "human REQUEST_CHANGES no sentinel (should NOT escalate)",
+			reviews: []gitea.Review{
+				makeReview(101, "bot", "REQUEST_CHANGES", false, "please fix this"),
+			},
+			postedID:    100,
+			ownLogin:    "bot",
+			ownSentinel: "<!-- review-bot:sonnet -->",
+			want:        false,
+		},
+		{
+			name: "skip own posted ID",
+			reviews: []gitea.Review{
+				makeReview(100, "bot", "REQUEST_CHANGES", false, "x\n<!-- review-bot:security -->"),
+			},
+			postedID:    100,
+			ownLogin:    "bot",
+			ownSentinel: "<!-- review-bot:sonnet -->",
+			want:        false,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := shouldEscalate(tc.reviews, tc.postedID, tc.ownLogin, tc.ownSentinel)
+			if got != tc.want {
+				t.Errorf("shouldEscalate() = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestReviewUnchanged(t *testing.T) {
+	tests := []struct {
+		name     string
+		existing []gitea.Review
+		newBody  string
+		newEvent string
+		sentinel string
+		want     bool
+	}{
+		{
+			name:     "no existing review",
+			existing: nil,
+			newBody:  "new review",
+			newEvent: "APPROVED",
+			sentinel: "<!-- review-bot:sonnet -->",
+			want:     false,
+		},
+		{
+			name: "identical body and state",
+			existing: []gitea.Review{
+				makeReview(100, "bot", "APPROVED", false, "same body\n<!-- review-bot:sonnet -->"),
+			},
+			newBody:  "same body\n<!-- review-bot:sonnet -->",
+			newEvent: "APPROVED",
+			sentinel: "<!-- review-bot:sonnet -->",
+			want:     true,
+		},
+		{
+			name: "same body but different state",
+			existing: []gitea.Review{
+				makeReview(100, "bot", "APPROVED", false, "body\n<!-- review-bot:sonnet -->"),
+			},
+			newBody:  "body\n<!-- review-bot:sonnet -->",
+			newEvent: "REQUEST_CHANGES",
+			sentinel: "<!-- review-bot:sonnet -->",
+			want:     false,
+		},
+		{
+			name: "different body same state",
+			existing: []gitea.Review{
+				makeReview(100, "bot", "APPROVED", false, "old body\n<!-- review-bot:sonnet -->"),
+			},
+			newBody:  "new body\n<!-- review-bot:sonnet -->",
+			newEvent: "APPROVED",
+			sentinel: "<!-- review-bot:sonnet -->",
+			want:     false,
+		},
+		{
+			name: "stale review with same body (should still post)",
+			existing: []gitea.Review{
+				makeReview(100, "bot", "APPROVED", true, "same\n<!-- review-bot:sonnet -->"),
+			},
+			newBody:  "same\n<!-- review-bot:sonnet -->",
+			newEvent: "APPROVED",
+			sentinel: "<!-- review-bot:sonnet -->",
+			want:     false,
+		},
+		{
+			name: "different sentinel (not our review)",
+			existing: []gitea.Review{
+				makeReview(100, "bot", "APPROVED", false, "body\n<!-- review-bot:gpt -->"),
+			},
+			newBody:  "body\n<!-- review-bot:sonnet -->",
+			newEvent: "APPROVED",
+			sentinel: "<!-- review-bot:sonnet -->",
+			want:     false,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := reviewUnchanged(tc.existing, tc.newBody, tc.newEvent, tc.sentinel)
+			if got != tc.want {
+				t.Errorf("reviewUnchanged() = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestFindOwnReview(t *testing.T) {
+	tests := []struct {
+		name     string
+		reviews  []gitea.Review
+		sentinel string
+		wantID   int64
+		wantNil  bool
+	}{
+		{
+			name:     "no reviews",
+			reviews:  nil,
+			sentinel: "<!-- review-bot:sonnet -->",
+			wantNil:  true,
+		},
+		{
+			name: "found by sentinel",
+			reviews: []gitea.Review{
+				makeReview(42, "bot", "APPROVED", false, "review body\n<!-- review-bot:sonnet -->"),
+			},
+			sentinel: "<!-- review-bot:sonnet -->",
+			wantID:   42,
+		},
+		{
+			name: "wrong sentinel",
+			reviews: []gitea.Review{
+				makeReview(42, "bot", "APPROVED", false, "body\n<!-- review-bot:gpt -->"),
+			},
+			sentinel: "<!-- review-bot:sonnet -->",
+			wantNil:  true,
+		},
+		{
+			name: "multiple reviews, returns first match",
+			reviews: []gitea.Review{
+				makeReview(10, "bot", "APPROVED", false, "old\n<!-- review-bot:gpt -->"),
+				makeReview(20, "bot", "APPROVED", false, "new\n<!-- review-bot:sonnet -->"),
+			},
+			sentinel: "<!-- review-bot:sonnet -->",
+			wantID:   20,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := findOwnReview(tc.reviews, tc.sentinel)
+			if tc.wantNil {
+				if got != nil {
+					t.Errorf("findOwnReview() = %v, want nil", got)
+				}
+			} else {
+				if got == nil {
+					t.Fatal("findOwnReview() = nil, want non-nil")
+				}
+				if got.ID != tc.wantID {
+					t.Errorf("findOwnReview().ID = %d, want %d", got.ID, tc.wantID)
+				}
+			}
+		})
+	}
+}
@@ -0,0 +1,97 @@
+# Review Update Strategy
+
+review-bot uses an **edit-in-place** strategy for updating reviews. Reviews are never deleted — this preserves conversation threads on inline comments.
+
+## State Transition Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> NoExistingReview: First run
+
+    NoExistingReview --> POST_Review: Generate findings + event
+    POST_Review --> PostEscalationCheck: event == APPROVED?
+
+    PostEscalationCheck --> Done: No sibling blocks
+    PostEscalationCheck --> Supersede_And_Repost: Sibling has REQUEST_CHANGES
+    Supersede_And_Repost --> Done: Posted as REQUEST_CHANGES
+
+    [*] --> ExistingReviewFound: Subsequent run (sentinel match)
+
+    ExistingReviewFound --> CheckEscalation: Determine final event
+    CheckEscalation --> CompareState: Apply worst-wins if needed
+
+    CompareState --> SameState: existing.state == new event
+    CompareState --> StateChange: existing.state != new event
+
+    SameState --> Skip: Body unchanged
+    SameState --> PatchBody: Body changed → PATCH in place
+
+    StateChange --> Escalate: APPROVED → REQUEST_CHANGES
+    StateChange --> Downgrade: REQUEST_CHANGES → APPROVED
+
+    Escalate --> Supersede: PATCH old body → "Superseded"
+    Supersede --> POST_New_RC: POST new REQUEST_CHANGES
+
+    Downgrade --> POST_New_Approve: POST new APPROVED (old stays intact)
+
+    Skip --> Done
+    PatchBody --> Done
+    POST_New_RC --> Done
+    POST_New_Approve --> Done
+```
+
+## Rules
+
+| Scenario | Action | Reason |
+|----------|--------|--------|
+| No existing review | POST new | First run |
+| Same state, same body | Skip | Nothing changed — preserve threads |
+| Same state, body changed | PATCH body | Update findings without losing threads |
+| APPROVED → REQUEST_CHANGES | Supersede old + POST new | Can always escalate; old APPROVED is no longer valid |
+| REQUEST_CHANGES → APPROVED | POST new APPROVED | Can't edit state; old REQUEST_CHANGES stays as historical record |
+| Sibling has REQUEST_CHANGES (worst-wins) | Escalate to REQUEST_CHANGES | PR must stay blocked if ANY reviewer blocks |
+
+## Key Constraints
+
+1. **Review state is immutable after POST** — Gitea has no API to change APPROVED ↔ REQUEST_CHANGES
+2. **Never delete reviews** — Deleting cascades to inline comments and reply threads
+3. **"Last review per user" wins** — Gitea uses the most recent review from a user for merge decisions
+4. **REQUEST_CHANGES reviews are never touched** — Their inline comments and threads are preserved as historical record
+5. **APPROVED reviews can be superseded** — When escalation is needed, mark old as superseded and POST new
+
+## Worst-Wins (Shared Token)
+
+When multiple reviewer roles share a token (e.g., `sonnet` and `security` both use `sonnet-review-bot`):
+
+```
+CI Matrix Run:
+  sonnet  → REQUEST_CHANGES (findings)
+  security → APPROVED (no security issues)
+                ↓
+  security sees sibling REQUEST_CHANGES
+                ↓
+  security escalates → REQUEST_CHANGES
+                ↓
+  PR stays blocked ✓
+```
+
+The **first-run case** (no existing review to read login from) uses a post-posting fallback:
+POST APPROVED → check siblings → if blocked, supersede own APPROVED → re-POST as REQUEST_CHANGES.
+
+## Edit Mechanism
+
+Reviews are edited via `PATCH /repos/{owner}/{repo}/issues/comments/{id}`:
+
+- **Review body**: ID obtained from the timeline API (`/issues/{index}/timeline`, type `"review"`)
+- **Inline comments**: IDs obtained from `/pulls/{index}/reviews/{id}/comments`
+- **Both are editable** by the token that created them
+- **ListReviews always returns the original body** (reads from review table, not comment table) — sentinel matching works regardless of edits
+
+## Inline Comments Lifecycle
+
+| Event | Inline comments behavior |
+|-------|--------------------------|
+| First POST | Created on specific diff lines |
+| PATCH body (same state) | Unchanged — still current findings |
+| Supersede (state change) | Old inline comments stay (readable but on outdated code) |
+| New POST after supersede | Fresh inline comments on current diff |
@@ -57,9 +57,16 @@ type ChangedFile struct {
 	Status   string `json:"status"`
 }

+// ReviewComment represents an inline comment to attach to a review.
+type ReviewComment struct {
+	Path        string `json:"path"`
+	NewPosition int64  `json:"new_position"`
+	Body        string `json:"body"`
+}
+
 // GetPullRequest fetches PR metadata.
 func (c *Client) GetPullRequest(ctx context.Context, owner, repo string, number int) (*PullRequest, error) {
-	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/pulls/%d", c.baseURL, owner, repo, number)
+	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/pulls/%d", c.baseURL, url.PathEscape(owner), url.PathEscape(repo), number)
 	body, err := c.doGet(ctx, reqURL)
 	if err != nil {
 		return nil, fmt.Errorf("fetch PR: %w", err)
@@ -73,7 +80,7 @@ func (c *Client) GetPullRequest(ctx context.Context, owner, repo string, number

 // GetPullRequestDiff fetches the unified diff for a PR.
 func (c *Client) GetPullRequestDiff(ctx context.Context, owner, repo string, number int) (string, error) {
-	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/pulls/%d.diff", c.baseURL, owner, repo, number)
+	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/pulls/%d.diff", c.baseURL, url.PathEscape(owner), url.PathEscape(repo), number)
 	body, err := c.doGet(ctx, reqURL)
 	if err != nil {
 		return "", fmt.Errorf("fetch diff: %w", err)
@@ -83,7 +90,7 @@ func (c *Client) GetPullRequestDiff(ctx context.Context, owner, repo string, num

 // GetPullRequestFiles fetches the list of files changed in a PR.
 func (c *Client) GetPullRequestFiles(ctx context.Context, owner, repo string, number int) ([]ChangedFile, error) {
-	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/pulls/%d/files", c.baseURL, owner, repo, number)
+	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/pulls/%d/files", c.baseURL, url.PathEscape(owner), url.PathEscape(repo), number)
 	body, err := c.doGet(ctx, reqURL)
 	if err != nil {
 		return nil, fmt.Errorf("fetch PR files: %w", err)
@@ -97,7 +104,7 @@ func (c *Client) GetPullRequestFiles(ctx context.Context, owner, repo string, nu

 // GetCommitStatuses fetches CI statuses for a commit SHA.
 func (c *Client) GetCommitStatuses(ctx context.Context, owner, repo, sha string) ([]CommitStatus, error) {
-	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/commits/%s/statuses", c.baseURL, owner, repo, sha)
+	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/commits/%s/statuses", c.baseURL, url.PathEscape(owner), url.PathEscape(repo), url.PathEscape(sha))
 	body, err := c.doGet(ctx, reqURL)
 	if err != nil {
 		return nil, fmt.Errorf("fetch commit statuses: %w", err)
@@ -111,7 +118,7 @@ func (c *Client) GetCommitStatuses(ctx context.Context, owner, repo, sha string)

 // GetFileContent fetches a file from the default branch of a repo.
 func (c *Client) GetFileContent(ctx context.Context, owner, repo, filepath string) (string, error) {
-	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/raw/%s", c.baseURL, owner, repo, escapePath(filepath))
+	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/raw/%s", c.baseURL, url.PathEscape(owner), url.PathEscape(repo), escapePath(filepath))
 	body, err := c.doGet(ctx, reqURL)
 	if err != nil {
 		return "", fmt.Errorf("fetch file %s: %w", filepath, err)
@@ -121,7 +128,7 @@ func (c *Client) GetFileContent(ctx context.Context, owner, repo, filepath strin

 // GetFileContentRef fetches a file from a specific ref (branch/tag/sha) in a repo.
 func (c *Client) GetFileContentRef(ctx context.Context, owner, repo, filepath, ref string) (string, error) {
-	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/raw/%s?ref=%s", c.baseURL, owner, repo, escapePath(filepath), url.QueryEscape(ref))
+	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/raw/%s?ref=%s", c.baseURL, url.PathEscape(owner), url.PathEscape(repo), escapePath(filepath), url.QueryEscape(ref))
 	body, err := c.doGet(ctx, reqURL)
 	if err != nil {
 		return "", fmt.Errorf("fetch file %s@%s: %w", filepath, ref, err)
@@ -129,42 +136,54 @@ func (c *Client) GetFileContentRef(ctx context.Context, owner, repo, filepath, r
 	return string(body), nil
 }

-// PostReview submits a review to a PR.
+// PostReview submits a review to a PR and returns the created review.
 // event should be "APPROVED" or "REQUEST_CHANGES".
-func (c *Client) PostReview(ctx context.Context, owner, repo string, number int, event, body string) error {
-	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/pulls/%d/reviews", c.baseURL, owner, repo, number)
+// comments are optional inline comments attached to specific lines.
+func (c *Client) PostReview(ctx context.Context, owner, repo string, number int, event, body string, comments []ReviewComment) (*Review, error) {
+	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/pulls/%d/reviews", c.baseURL, url.PathEscape(owner), url.PathEscape(repo), number)

 	payload := struct {
-		Body  string `json:"body"`
-		Event string `json:"event"`
+		Body     string          `json:"body"`
+		Event    string          `json:"event"`
+		Comments []ReviewComment `json:"comments,omitempty"`
 	}{
-		Body:  body,
-		Event: event,
+		Body:     body,
+		Event:    event,
+		Comments: comments,
 	}

 	data, err := json.Marshal(payload)
 	if err != nil {
-		return fmt.Errorf("marshal review payload: %w", err)
+		return nil, fmt.Errorf("marshal review payload: %w", err)
 	}

 	req, err := http.NewRequestWithContext(ctx, http.MethodPost, reqURL, bytes.NewReader(data))
 	if err != nil {
-		return fmt.Errorf("create review request: %w", err)
+		return nil, fmt.Errorf("create review request: %w", err)
 	}
 	req.Header.Set("Authorization", "token "+c.token)
 	req.Header.Set("Content-Type", "application/json")

 	resp, err := c.http.Do(req)
 	if err != nil {
-		return fmt.Errorf("post review: %w", err)
+		return nil, fmt.Errorf("post review: %w", err)
 	}
 	defer resp.Body.Close()

 	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
 		respBody, _ := io.ReadAll(resp.Body)
-		return fmt.Errorf("post review failed (status %d): %s", resp.StatusCode, string(respBody))
+		return nil, fmt.Errorf("post review failed (status %d): %s", resp.StatusCode, string(respBody))
 	}
-	return nil
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read review response: %w", err)
+	}
+	var review Review
+	if err := json.Unmarshal(respBody, &review); err != nil {
+		return nil, fmt.Errorf("parse review response: %w", err)
+	}
+	return &review, nil
 }

 func (c *Client) doGet(ctx context.Context, reqURL string) ([]byte, error) {
@@ -211,9 +230,9 @@ type ContentEntry struct {
 func (c *Client) ListContents(ctx context.Context, owner, repo, path string) ([]ContentEntry, error) {
 	var reqURL string
 	if path == "" {
-		reqURL = fmt.Sprintf("%s/api/v1/repos/%s/%s/contents", c.baseURL, owner, repo)
+		reqURL = fmt.Sprintf("%s/api/v1/repos/%s/%s/contents", c.baseURL, url.PathEscape(owner), url.PathEscape(repo))
 	} else {
-		reqURL = fmt.Sprintf("%s/api/v1/repos/%s/%s/contents/%s", c.baseURL, owner, repo, escapePath(path))
+		reqURL = fmt.Sprintf("%s/api/v1/repos/%s/%s/contents/%s", c.baseURL, url.PathEscape(owner), url.PathEscape(repo), escapePath(path))
 	}
 	body, err := c.doGet(ctx, reqURL)
 	if err != nil {
@@ -266,3 +285,149 @@ func (c *Client) GetAllFilesInPath(ctx context.Context, owner, repo, path string
 	}
 	return results, nil
 }
+
+// Review represents a pull request review from the Gitea API.
+type Review struct {
+	ID   int64  `json:"id"`
+	Body string `json:"body"`
+	User struct {
+		Login string `json:"login"`
+	} `json:"user"`
+	State string `json:"state"`
+	Stale bool   `json:"stale"`
+}
+
+// ListReviews returns all reviews on a pull request.
+// Paginates through all pages to ensure no reviews are missed.
+func (c *Client) ListReviews(ctx context.Context, owner, repo string, number int) ([]Review, error) {
+	const pageSize = 50
+	var all []Review
+	for page := 1; ; page++ {
+		reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/pulls/%d/reviews?limit=%d&page=%d",
+			c.baseURL,
+			url.PathEscape(owner),
+			url.PathEscape(repo),
+			number,
+			pageSize,
+			page)
+		body, err := c.doGet(ctx, reqURL)
+		if err != nil {
+			return nil, fmt.Errorf("list reviews (page %d): %w", page, err)
+		}
+		var batch []Review
+		if err := json.Unmarshal(body, &batch); err != nil {
+			return nil, fmt.Errorf("parse reviews (page %d): %w", page, err)
+		}
+		all = append(all, batch...)
+		if len(batch) < pageSize {
+			break
+		}
+	}
+	return all, nil
+}
+
+// DeleteReview deletes a review by ID. The token must belong to the review author.
+func (c *Client) DeleteReview(ctx context.Context, owner, repo string, number int, reviewID int64) error {
+	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/pulls/%d/reviews/%d",
+		c.baseURL,
+		url.PathEscape(owner),
+		url.PathEscape(repo),
+		number,
+		reviewID)
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodDelete, reqURL, nil)
+	if err != nil {
+		return fmt.Errorf("create delete request: %w", err)
+	}
+	req.Header.Set("Authorization", "token "+c.token)
+
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return fmt.Errorf("delete review: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		respBody, _ := io.ReadAll(resp.Body)
+		return fmt.Errorf("delete review failed (status %d): %s", resp.StatusCode, string(respBody))
+	}
+	return nil
+}
+
+// TimelineEvent represents an entry from the issue timeline API.
+type TimelineEvent struct {
+	ID   int64  `json:"id"`
+	Type string `json:"type"`
+	Body string `json:"body"`
+	User struct {
+		Login string `json:"login"`
+	} `json:"user"`
+}
+
+// GetTimelineReviewCommentID finds the comment ID for a review body by
+// scanning the issue timeline for a review event containing the sentinel.
+func (c *Client) GetTimelineReviewCommentID(ctx context.Context, owner, repo string, number int, sentinel string) (int64, error) {
+	const pageSize = 50
+	for page := 1; ; page++ {
+		reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/issues/%d/timeline?limit=%d&page=%d",
+			c.baseURL,
+			url.PathEscape(owner),
+			url.PathEscape(repo),
+			number,
+			pageSize,
+			page)
+		body, err := c.doGet(ctx, reqURL)
+		if err != nil {
+			return 0, fmt.Errorf("get timeline (page %d): %w", page, err)
+		}
+		var events []TimelineEvent
+		if err := json.Unmarshal(body, &events); err != nil {
+			return 0, fmt.Errorf("parse timeline (page %d): %w", page, err)
+		}
+		for _, ev := range events {
+			if ev.Type == "review" && strings.Contains(ev.Body, sentinel) {
+				return ev.ID, nil
+			}
+		}
+		if len(events) < pageSize {
+			break
+		}
+	}
+	return 0, fmt.Errorf("no timeline event found with sentinel")
+}
+
+// EditComment updates the body of an issue/review comment.
+func (c *Client) EditComment(ctx context.Context, owner, repo string, commentID int64, newBody string) error {
+	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/issues/comments/%d",
+		c.baseURL,
+		url.PathEscape(owner),
+		url.PathEscape(repo),
+		commentID)
+
+	payload := struct {
+		Body string `json:"body"`
+	}{Body: newBody}
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("marshal edit payload: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPatch, reqURL, bytes.NewReader(data))
+	if err != nil {
+		return fmt.Errorf("create edit request: %w", err)
+	}
+	req.Header.Set("Authorization", "token "+c.token)
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return fmt.Errorf("edit comment: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return fmt.Errorf("edit comment failed (status %d): %s", resp.StatusCode, body)
+	}
+	return nil
+}
@@ -123,15 +123,21 @@ func TestPostReview(t *testing.T) {
 		}

 		w.WriteHeader(http.StatusOK)
-		w.Write([]byte(`{}`))
+		w.Write([]byte(`{"id":100,"user":{"login":"review-bot"},"state":"APPROVED","stale":false}`))
 	}))
 	defer server.Close()

 	client := NewClient(server.URL, "test-token")
-	err := client.PostReview(context.Background(), "owner", "repo", 3, "APPROVED", "LGTM")
+	review, err := client.PostReview(context.Background(), "owner", "repo", 3, "APPROVED", "LGTM", nil)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
+	if review.ID != 100 {
+		t.Errorf("expected review ID 100, got %d", review.ID)
+	}
+	if review.User.Login != "review-bot" {
+		t.Errorf("expected user login %q, got %q", "review-bot", review.User.Login)
+	}
 }

 func TestGetPullRequest_Non200(t *testing.T) {
@@ -169,7 +175,7 @@ func TestPostReview_Non200(t *testing.T) {
 	defer server.Close()

 	client := NewClient(server.URL, "test-token")
-	err := client.PostReview(context.Background(), "owner", "repo", 1, "APPROVED", "test")
+	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "APPROVED", "test", nil)
 	if err == nil {
 		t.Fatal("expected error for 403, got nil")
 	}
@@ -318,3 +324,184 @@ func TestEscapePath(t *testing.T) {
 		})
 	}
 }
+
+func TestListReviews(t *testing.T) {
+	pageCount := 0
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/v1/repos/owner/repo/pulls/5/reviews" {
+			t.Errorf("unexpected path: %s", r.URL.Path)
+		}
+		if r.URL.Query().Get("limit") != "50" {
+			t.Errorf("expected limit=50, got %s", r.URL.Query().Get("limit"))
+		}
+		pageCount++
+		w.Header().Set("Content-Type", "application/json")
+		// Return 2 results (less than page size) to signal end
+		w.Write([]byte(`[{"id":10,"user":{"login":"bot-a"},"state":"APPROVED","stale":false},{"id":11,"user":{"login":"bot-b"},"state":"REQUEST_CHANGES","stale":true}]`))
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-token")
+	reviews, err := client.ListReviews(context.Background(), "owner", "repo", 5)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(reviews) != 2 {
+		t.Fatalf("expected 2 reviews, got %d", len(reviews))
+	}
+	if reviews[0].User.Login != "bot-a" {
+		t.Errorf("expected bot-a, got %s", reviews[0].User.Login)
+	}
+	if pageCount != 1 {
+		t.Errorf("expected 1 page fetch (results < page size), got %d", pageCount)
+	}
+}
+
+func TestListReviews_Pagination(t *testing.T) {
+	pageCount := 0
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		pageCount++
+		page := r.URL.Query().Get("page")
+		w.Header().Set("Content-Type", "application/json")
+		if page == "1" {
+			// Return exactly 50 items to trigger next page fetch
+			items := "["
+			for i := 0; i < 50; i++ {
+				if i > 0 {
+					items += ","
+				}
+				items += fmt.Sprintf(`{"id":%d,"user":{"login":"bot"},"state":"APPROVED","stale":false}`, i+1)
+			}
+			items += "]"
+			w.Write([]byte(items))
+		} else {
+			// Page 2: return fewer than 50 to signal end
+			w.Write([]byte(`[{"id":51,"user":{"login":"bot"},"state":"APPROVED","stale":false}]`))
+		}
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-token")
+	reviews, err := client.ListReviews(context.Background(), "owner", "repo", 5)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(reviews) != 51 {
+		t.Fatalf("expected 51 reviews across 2 pages, got %d", len(reviews))
+	}
+	if pageCount != 2 {
+		t.Errorf("expected 2 page fetches, got %d", pageCount)
+	}
+}
+
+func TestDeleteReview(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/v1/repos/owner/repo/pulls/5/reviews/10" {
+			t.Errorf("unexpected path: %s", r.URL.Path)
+		}
+		if r.Method != "DELETE" {
+			t.Errorf("expected DELETE, got %s", r.Method)
+		}
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-token")
+	err := client.DeleteReview(context.Background(), "owner", "repo", 5, 10)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestDeleteReview_Forbidden(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusForbidden)
+		w.Write([]byte(`{"message":"forbidden"}`))
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-token")
+	err := client.DeleteReview(context.Background(), "owner", "repo", 5, 10)
+	if err == nil {
+		t.Fatal("expected error for 403, got nil")
+	}
+}
+
+func TestEditComment(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPatch {
+			t.Errorf("expected PATCH, got %s", r.Method)
+		}
+		if r.URL.Path != "/api/v1/repos/owner/repo/issues/comments/42" {
+			t.Errorf("unexpected path: %s", r.URL.Path)
+		}
+
+		var payload struct {
+			Body string `json:"body"`
+		}
+		json.NewDecoder(r.Body).Decode(&payload)
+		if payload.Body != "updated body" {
+			t.Errorf("unexpected body: %s", payload.Body)
+		}
+
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"id": 42, "body": "updated body"}`))
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-token")
+	err := client.EditComment(context.Background(), "owner", "repo", 42, "updated body")
+	if err != nil {
+		t.Fatalf("EditComment() error = %v", err)
+	}
+}
+
+func TestEditComment_Forbidden(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusForbidden)
+		w.Write([]byte(`{"message": "not allowed"}`))
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-token")
+	err := client.EditComment(context.Background(), "owner", "repo", 42, "new body")
+	if err == nil {
+		t.Fatal("expected error for 403 response")
+	}
+}
+
+func TestGetTimelineReviewCommentID(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/v1/repos/owner/repo/issues/5/timeline" {
+			t.Errorf("unexpected path: %s", r.URL.Path)
+		}
+		w.Write([]byte(`[
+			{"id": 100, "type": "comment", "body": "random"},
+			{"id": 200, "type": "review", "body": "other review <!-- review-bot:gpt -->"},
+			{"id": 300, "type": "review", "body": "our review <!-- review-bot:sonnet -->"}
+		]`))
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-token")
+	id, err := client.GetTimelineReviewCommentID(context.Background(), "owner", "repo", 5, "<!-- review-bot:sonnet -->")
+	if err != nil {
+		t.Fatalf("GetTimelineReviewCommentID() error = %v", err)
+	}
+	if id != 300 {
+		t.Errorf("got id=%d, want 300", id)
+	}
+}
+
+func TestGetTimelineReviewCommentID_NotFound(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(`[{"id": 100, "type": "review", "body": "no match"}]`))
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-token")
+	_, err := client.GetTimelineReviewCommentID(context.Background(), "owner", "repo", 5, "<!-- review-bot:sonnet -->")
+	if err == nil {
+		t.Fatal("expected error when sentinel not found")
+	}
+}
@@ -0,0 +1,85 @@
+package gitea
+
+import (
+	"strconv"
+	"strings"
+)
+
+// DiffLineRanges maps filenames to the set of new-file line numbers present in the diff.
+type DiffLineRanges struct {
+	files map[string]map[int]bool
+}
+
+// Contains reports whether the given file+line is within the diff hunks.
+func (d *DiffLineRanges) Contains(file string, line int) bool {
+	if d == nil || d.files == nil {
+		return false
+	}
+	lines, ok := d.files[file]
+	if !ok {
+		return false
+	}
+	return lines[line]
+}
+
+// ParseDiffNewLines parses a unified diff and extracts the new-file line numbers
+// that appear in each hunk (both added and context lines).
+func ParseDiffNewLines(diff string) *DiffLineRanges {
+	result := &DiffLineRanges{files: make(map[string]map[int]bool)}
+
+	var currentFile string
+	var newLine int
+
+	for _, line := range strings.Split(diff, "\n") {
+		// Track current file from +++ header
+		if strings.HasPrefix(line, "+++ b/") {
+			currentFile = strings.TrimPrefix(line, "+++ b/")
+			if result.files[currentFile] == nil {
+				result.files[currentFile] = make(map[int]bool)
+			}
+			continue
+		}
+		if strings.HasPrefix(line, "+++ /dev/null") {
+			currentFile = ""
+			continue
+		}
+
+		// Parse hunk header: @@ -old,count +new,count @@ or @@ -old +new @@
+		if strings.HasPrefix(line, "@@") && currentFile != "" {
+			// Extract the +N part — handle both "+10,8" and "+1" forms
+			parts := strings.Split(line, "+")
+			if len(parts) >= 2 {
+				// Take everything before comma or space
+				numStr := parts[1]
+				if idx := strings.IndexAny(numStr, ", "); idx != -1 {
+					numStr = numStr[:idx]
+				}
+				n, err := strconv.Atoi(numStr)
+				if err == nil {
+					newLine = n
+				}
+			}
+			continue
+		}
+
+		if currentFile == "" {
+			continue
+		}
+
+		// Skip diff metadata lines
+		if strings.HasPrefix(line, "\\") {
+			continue
+		}
+
+		// Count lines in hunk
+		if strings.HasPrefix(line, "+") || strings.HasPrefix(line, " ") {
+			result.files[currentFile][newLine] = true
+			newLine++
+		} else if strings.HasPrefix(line, "-") {
+			// Removed lines don't advance new line counter
+			continue
+		}
+	}
+
+	return result
+}
@@ -0,0 +1,115 @@
+package gitea
+
+import (
+	"testing"
+)
+
+func TestParseDiffLineRanges(t *testing.T) {
+	diff := `diff --git a/main.go b/main.go
+index abc1234..def5678 100644
+--- a/main.go
+++ b/main.go
+@@ -10,6 +10,8 @@ func main() {
+ 	fmt.Println("hello")
+	fmt.Println("new line 11")
+	fmt.Println("new line 12")
+ 	fmt.Println("existing")
+ }
+@@ -30,4 +32,5 @@ func other() {
+ 	return nil
+	// added at line 33
+ }
+diff --git a/util.go b/util.go
+new file mode 100644
+--- /dev/null
+++ b/util.go
+@@ -0,0 +1,5 @@
+package main
+
+func helper() string {
+	return "hi"
+}
+`
+
+	ranges := ParseDiffNewLines(diff)
+
+	// main.go should have lines 10-17 (first hunk) and 32-36 (second hunk)
+	if !ranges.Contains("main.go", 11) {
+		t.Error("expected main.go:11 to be in diff")
+	}
+	if !ranges.Contains("main.go", 12) {
+		t.Error("expected main.go:12 to be in diff")
+	}
+	if !ranges.Contains("main.go", 10) {
+		t.Error("expected main.go:10 to be in diff (context line)")
+	}
+	if !ranges.Contains("main.go", 33) {
+		t.Error("expected main.go:33 to be in diff")
+	}
+	if ranges.Contains("main.go", 25) {
+		t.Error("main.go:25 should NOT be in diff")
+	}
+
+	// util.go is entirely new, lines 1-5
+	if !ranges.Contains("util.go", 1) {
+		t.Error("expected util.go:1 to be in diff")
+	}
+	if !ranges.Contains("util.go", 5) {
+		t.Error("expected util.go:5 to be in diff")
+	}
+	if ranges.Contains("util.go", 6) {
+		t.Error("util.go:6 should NOT be in diff")
+	}
+
+	// Unknown file
+	if ranges.Contains("unknown.go", 1) {
+		t.Error("unknown.go should not be in diff")
+	}
+}
+
+func TestParseDiffNewLines_Empty(t *testing.T) {
+	ranges := ParseDiffNewLines("")
+	if ranges.Contains("any.go", 1) {
+		t.Error("empty diff should contain nothing")
+	}
+}
+
+func TestParseDiffNewLines_NoCommaHunk(t *testing.T) {
+	// Single-line hunks omit the comma: @@ -1 +1 @@
+	diff := `diff --git a/single.go b/single.go
+--- a/single.go
+++ b/single.go
+@@ -1 +1 @@
+-old line
+new line
+`
+	ranges := ParseDiffNewLines(diff)
+	if !ranges.Contains("single.go", 1) {
+		t.Error("expected single.go:1 to be in diff (no-comma hunk)")
+	}
+	if ranges.Contains("single.go", 2) {
+		t.Error("single.go:2 should NOT be in diff")
+	}
+}
+
+func TestParseDiffNewLines_NoNewlineMarker(t *testing.T) {
+	// "\ No newline at end of file" should not advance line counter
+	diff := `diff --git a/noeof.go b/noeof.go
+--- a/noeof.go
+++ b/noeof.go
+@@ -1,2 +1,2 @@
+line one
+line two
+\ No newline at end of file
+`
+	ranges := ParseDiffNewLines(diff)
+	if !ranges.Contains("noeof.go", 1) {
+		t.Error("expected noeof.go:1")
+	}
+	if !ranges.Contains("noeof.go", 2) {
+		t.Error("expected noeof.go:2")
+	}
+	if ranges.Contains("noeof.go", 3) {
+		t.Error("noeof.go:3 should NOT be in diff (no-newline marker)")
+	}
+}
@@ -0,0 +1,88 @@
+package gitea
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestPostReview_WithComments(t *testing.T) {
+	var gotPayload struct {
+		Body     string `json:"body"`
+		Event    string `json:"event"`
+		Comments []struct {
+			Path        string `json:"path"`
+			NewPosition int64  `json:"new_position"`
+			Body        string `json:"body"`
+		} `json:"comments"`
+	}
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		json.NewDecoder(r.Body).Decode(&gotPayload)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(200)
+		json.NewEncoder(w).Encode(map[string]any{
+			"id":   99,
+			"body": gotPayload.Body,
+			"user": map[string]any{"login": "bot"},
+		})
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-token")
+	comments := []ReviewComment{
+		{Path: "main.go", NewPosition: 42, Body: "[MAJOR] Something bad"},
+		{Path: "util.go", NewPosition: 10, Body: "[MINOR] Style issue"},
+	}
+
+	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "REQUEST_CHANGES", "summary", comments)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if len(gotPayload.Comments) != 2 {
+		t.Fatalf("expected 2 comments, got %d", len(gotPayload.Comments))
+	}
+	if gotPayload.Comments[0].Path != "main.go" {
+		t.Errorf("expected path main.go, got %s", gotPayload.Comments[0].Path)
+	}
+	if gotPayload.Comments[0].NewPosition != 42 {
+		t.Errorf("expected new_position 42, got %d", gotPayload.Comments[0].NewPosition)
+	}
+	if gotPayload.Comments[1].Body != "[MINOR] Style issue" {
+		t.Errorf("unexpected body: %s", gotPayload.Comments[1].Body)
+	}
+}
+
+func TestPostReview_NilComments(t *testing.T) {
+	var gotPayload map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		json.NewDecoder(r.Body).Decode(&gotPayload)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(200)
+		json.NewEncoder(w).Encode(map[string]any{
+			"id":   100,
+			"body": "test",
+			"user": map[string]any{"login": "bot"},
+		})
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-token")
+	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "APPROVED", "all good", nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// With nil comments, the field should be omitted (omitempty)
+	comments, ok := gotPayload["comments"]
+	if ok && comments != nil {
+		arr, isArr := comments.([]any)
+		if isArr && len(arr) > 0 {
+			t.Error("expected no comments in payload when nil passed")
+		}
+	}
+}
@@ -9,6 +9,11 @@ import (
 func FormatMarkdown(result *ReviewResult, reviewerName string) string {
 	var sb strings.Builder

+	if reviewerName != "" {
+		title := strings.ToUpper(reviewerName[:1]) + reviewerName[1:]
+		sb.WriteString(fmt.Sprintf("# %s Review\n\n", title))
+	}
+
 	sb.WriteString("## Summary\n\n")
 	sb.WriteString(result.Summary)
 	sb.WriteString("\n\n")
@@ -30,6 +35,8 @@ func FormatMarkdown(result *ReviewResult, reviewerName string) string {

 	if reviewerName != "" {
 		sb.WriteString(fmt.Sprintf("\n---\n*Review by %s*\n", reviewerName))
+		// Hidden sentinel for identifying this bot's reviews during cleanup
+		sb.WriteString(fmt.Sprintf("\n<!-- review-bot:%s -->\n", reviewerName))
 	}

 	return sb.String()
@@ -116,3 +116,46 @@ func TestGiteaEvent(t *testing.T) {
 		}
 	}
 }
+
+func TestFormatMarkdown_Sentinel(t *testing.T) {
+	result := &ReviewResult{
+		Verdict:        "APPROVE",
+		Summary:        "All good.",
+		Recommendation: "Merge it.",
+	}
+	output := FormatMarkdown(result, "security")
+	if !strings.Contains(output, "<!-- review-bot:security -->") {
+		t.Error("expected sentinel comment in output")
+	}
+
+	// Empty reviewer name should NOT have sentinel
+	output2 := FormatMarkdown(result, "")
+	if strings.Contains(output2, "<!-- review-bot") {
+		t.Error("should not contain sentinel when reviewer name is empty")
+	}
+}
+
+func TestFormatMarkdown_RoleTitle(t *testing.T) {
+	result := &ReviewResult{
+		Verdict:        "APPROVE",
+		Summary:        "All good.",
+		Recommendation: "Merge it.",
+	}
+
+	// With reviewer name: should have title header
+	output := FormatMarkdown(result, "security")
+	if !strings.Contains(output, "# Security Review\n") {
+		t.Error("expected '# Security Review' header when reviewer name is set")
+	}
+
+	output2 := FormatMarkdown(result, "gpt")
+	if !strings.Contains(output2, "# Gpt Review\n") {
+		t.Error("expected '# Gpt Review' header")
+	}
+
+	// Without reviewer name: no title header
+	output3 := FormatMarkdown(result, "")
+	if strings.Contains(output3, "# ") && strings.Contains(output3, " Review\n") {
+		t.Error("should not contain role title header when reviewer name is empty")
+	}
+}
@@ -7,8 +7,10 @@ import (
 	"strings"
 )

-// BuildSystemPrompt constructs the system prompt for the LLM reviewer.
-func BuildSystemPrompt(conventions, patterns string) string {
+// BuildSystemBase returns the core system prompt instructions without
+// patterns or conventions. Used by the budget package to separate
+// trimmable from non-trimmable content.
+func BuildSystemBase() string {
 	var sb strings.Builder

 	sb.WriteString("You are an expert code reviewer. Review the provided pull request diff carefully.\n\n")
@@ -42,6 +44,15 @@ func BuildSystemPrompt(conventions, patterns string) string {
 	sb.WriteString("- Line numbers should reference the new file line numbers from the diff headers.\n")
 	sb.WriteString("- If the diff is empty or trivial (only formatting/whitespace), APPROVE with no findings.\n")

+	return sb.String()
+}
+
+// BuildSystemPrompt constructs the full system prompt with patterns and conventions.
+// Deprecated: Use BuildSystemBase with budget.Fit for context-aware assembly.
+func BuildSystemPrompt(conventions, patterns string) string {
+	var sb strings.Builder
+	sb.WriteString(BuildSystemBase())
+
 	if patterns != "" {
 		sb.WriteString(fmt.Sprintf("\n\n## Language Patterns & Idioms\n\nUse the following patterns as review criteria. Code that violates these established patterns is a finding:\n\n%s\n", patterns))
 	}
@@ -53,8 +64,9 @@ func BuildSystemPrompt(conventions, patterns string) string {
 	return sb.String()
 }

-// BuildUserPrompt constructs the user message with PR context.
-func BuildUserPrompt(title, description, diff, fileContext string, ciPassed bool, ciDetails string) string {
+// BuildUserMeta returns the PR metadata header (title, description, CI status)
+// without the diff or file context. Used by the budget package.
+func BuildUserMeta(title, description string, ciPassed bool, ciDetails string) string {
 	var sb strings.Builder

 	sb.WriteString(fmt.Sprintf("## Pull Request: %s\n\n", title))
@@ -73,6 +85,16 @@ func BuildUserPrompt(title, description, diff, fileContext string, ciPassed bool
 		sb.WriteString(fmt.Sprintf("CI Details: %s\n", ciDetails))
 	}

+	return sb.String()
+}
+
+// BuildUserPrompt constructs the user message with PR context.
+// Deprecated: Use BuildUserMeta with budget.Fit for context-aware assembly.
+func BuildUserPrompt(title, description, diff, fileContext string, ciPassed bool, ciDetails string) string {
+	var sb strings.Builder
+
+	sb.WriteString(BuildUserMeta(title, description, ciPassed, ciDetails))
+
 	if fileContext != "" {
 		sb.WriteString("\n### Full File Context (modified files)\n\n")
 		sb.WriteString(fileContext)
@@ -116,3 +116,43 @@ func TestBuildUserPrompt_WithoutFileContext(t *testing.T) {
 		t.Error("should not include file context section when empty")
 	}
 }
+
+
+func TestBuildSystemBase(t *testing.T) {
+	result := BuildSystemBase()
+	if result == "" {
+		t.Fatal("BuildSystemBase returned empty string")
+	}
+	if !strings.Contains(result, "expert code reviewer") {
+		t.Error("expected reviewer role in system base")
+	}
+	if !strings.Contains(result, "REQUEST_CHANGES") {
+		t.Error("expected verdict format in system base")
+	}
+	if !strings.Contains(result, "JSON") {
+		t.Error("expected JSON output instruction in system base")
+	}
+}
+
+func TestBuildUserMeta(t *testing.T) {
+	result := BuildUserMeta("Fix bug", "Some description", true, "all checks passed")
+	if !strings.Contains(result, "Fix bug") {
+		t.Error("expected title in user meta")
+	}
+	if !strings.Contains(result, "Some description") {
+		t.Error("expected description in user meta")
+	}
+	if !strings.Contains(result, "PASSED") {
+		t.Error("expected CI PASSED status")
+	}
+}
+
+func TestBuildUserMeta_CIFailed(t *testing.T) {
+	result := BuildUserMeta("Title", "", false, "test job failed")
+	if !strings.Contains(result, "FAILED") {
+		t.Error("expected CI FAILED status")
+	}
+	if strings.Contains(result, "Description") {
+		t.Error("expected no description section when empty")
+	}
+}