fix(#123): add RFC6598 CGN check to Python SSRF validation in action.yml

Python's ipaddress module does NOT classify 100.64.0.0/10 (RFC6598
carrier-grade NAT) as private/loopback/link_local/multicast/reserved.
This means a SERVER_URL resolving to a CGN address would bypass the
Python SSRF check and reach curl with ACTION_TOKEN.

Add an explicit network membership check for 100.64.0.0/10 to both
Python validation blocks in action.yml:
  - _ssrf_check.py (VCS URL pre-flight check)
  - _ssrf_check_install.py (binary download URL check)

The Go-level IsBlockedIP already covers this range correctly (ipcheck.go);
this fix closes the gap in the action.yml Python layer.

Also update comments to mention RFC6598 explicitly.

.gitea/actions/review/action.yml

@@ -1,17 +1,43 @@
-# This composite action is designed for Gitea Actions runners.
-# Gitea Actions supports GitHub Actions syntax including $GITHUB_OUTPUT,
-# actions/cache, and actions/checkout.
+# This composite action supports both Gitea Actions and GitHub Actions runners.
+# It detects the VCS host type by checking whether github.api_url is set
+# (present on GitHub.com and GHES runners, absent on Gitea runners) and uses
+# the appropriate releases API for version resolution and binary download
+# (REST API on GitHub, direct URLs on Gitea).
+#
+# Security notes:
+# - On GitHub/GHES (VCS_TYPE=github), inputs.vcs-url is IGNORED to prevent
+#   token exfiltration. API calls use github.api_url; downloads use
+#   github.server_url. Tokens are never sent to user-supplied URLs.
+# - On Gitea (VCS_TYPE=gitea), inputs.vcs-url is validated (https scheme,
+#   no whitespace/newlines, and DNS resolution to a public IP) before use.
+#   Python3 resolves the hostname and rejects RFC1918, RFC6598 (carrier-grade
+#   NAT), loopback, link-local, and other reserved addresses to prevent SSRF attacks.
+#   The installed review-bot binary additionally uses a safe HTTP transport
+#   (DialContext-level IP check) for all Gitea API calls at runtime.
+#   The binary also exposes a `validate-url` subcommand for use in any future
+#   shell steps that need to validate a URL before passing it to curl.
+# - action-repo is validated against owner/repo pattern.
+# - Tokens are passed via masked environment variables, not step outputs.
+#
 # Requirements: python3, sha256sum, curl (all present on ubuntu-* runners).
 name: 'AI Code Review'
 description: 'Run AI-powered code review on a pull request using review-bot'
 
 inputs:
-  gitea-url:
-    description: 'Gitea instance URL (defaults to server_url)'
+  vcs-url:
+    description: 'VCS server URL (only used on Gitea runners; ignored on GitHub/GHES). Defaults to server_url.'
     required: false
     default: ''
   repo:
-    description: 'Repository (owner/name, defaults to current)'
+    description: 'Repository to review (owner/name, defaults to current)'
+    required: false
+    default: ''
+  action-repo:
+    description: 'Repository hosting review-bot releases (owner/name). Defaults to github.action_repository or rodin/review-bot.'
+    required: false
+    default: ''
+  action-repo-token:
+    description: 'Token for downloading release assets from action-repo (defaults to github.token on GitHub, reviewer-token on Gitea). Required for private repos.'
     required: false
     default: ''
   pr-number:
@@ -19,7 +45,7 @@ inputs:
     required: false
     default: ''
   reviewer-token:
-    description: 'Gitea token for posting the review'
+    description: 'Token for posting the review'
     required: true
   reviewer-name:
     description: 'Display name for the reviewer'
@@ -112,45 +138,325 @@ runs:
       id: version
       shell: bash
       run: |
-        GITEA_URL="${{ inputs.gitea-url || github.server_url }}"
-        REPO="${{ inputs.repo || 'rodin/review-bot' }}"
+        set -euo pipefail
+
+        # --- Input Validation ---
+
+        # Determine the repo hosting review-bot releases (not the repo being reviewed)
+        ACTION_REPO="${{ inputs.action-repo }}"
+        if [ -z "$ACTION_REPO" ]; then
+          # github.action_repository is the repo containing the running action
+          ACTION_REPO="${{ github.action_repository }}"
+        fi
+        if [ -z "$ACTION_REPO" ]; then
+          # Final fallback for Gitea (which may not set action_repository)
+          ACTION_REPO="rodin/review-bot"
+          echo "::notice::action-repo not specified and github.action_repository is empty; falling back to rodin/review-bot"
+        fi
+
+        # Validate ACTION_REPO matches owner/repo pattern (prevent path traversal)
+        if ! printf '%s' "$ACTION_REPO" | grep -qE '^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$'; then
+          echo "Error: action-repo '${ACTION_REPO}' does not match expected owner/repo format" >&2
+          exit 1
+        fi
+
+        # Detect VCS host type using github.api_url context.
+        # github.api_url is set on GitHub.com (https://api.github.com) and GHES
+        # (https://<host>/api/v3). It is empty/unset on Gitea Actions runners.
+        GITHUB_API_URL="${{ github.api_url }}"
+        if [ -n "$GITHUB_API_URL" ]; then
+          VCS_TYPE="github"
+        else
+          VCS_TYPE="gitea"
+        fi
+
+        # Determine SERVER_URL based on VCS type.
+        # SECURITY: On GitHub/GHES, ALWAYS use github.server_url — never trust
+        # inputs.vcs-url to prevent token exfiltration to attacker-controlled hosts.
+        if [ "$VCS_TYPE" = "github" ]; then
+          SERVER_URL="${{ github.server_url }}"
+          if [ -n "${{ inputs.vcs-url }}" ]; then
+            echo "::warning::inputs.vcs-url is ignored on GitHub/GHES runners (VCS_TYPE=github). Using github.server_url instead."
+          fi
+        else
+          SERVER_URL="${{ inputs.vcs-url || github.server_url }}"
+        fi
+        # Strip trailing slash if present
+        SERVER_URL="${SERVER_URL%/}"
+
+        # Validate SERVER_URL for Gitea path: must be https, no whitespace/newlines.
+        # The [^[:space:]] class already rejects newlines, so no separate newline check needed.
+        if [ "$VCS_TYPE" = "gitea" ]; then
+          if ! printf '%s' "$SERVER_URL" | grep -qE '^https://[^[:space:]]+$'; then
+            echo "Error: SERVER_URL '${SERVER_URL}' must be an https:// URL with no whitespace" >&2
+            exit 1
+          fi
+
+          # Additional IP-level SSRF defense: resolve the hostname and reject
+          # requests to RFC1918, RFC6598 (carrier-grade NAT), loopback, link-local,
+          # and other reserved addresses.
+          # python3 is required on ubuntu-* runners (see requirements comment above).
+          # Use printf to write the script to a temp file so the python lines are valid
+          # YAML (each indented line becomes a printf argument — no unindented code).
+          # SERVER_URL is passed via CHECK_URL env var, never interpolated into python code.
+          printf '%s\n' \
+            'import socket,ipaddress,sys,os' \
+            'from urllib.parse import urlparse' \
+            'u=os.environ["CHECK_URL"]; parsed=urlparse(u)' \
+            'if parsed.username or parsed.password:' \
+            '  print("Error: URL contains user-info — not allowed",file=sys.stderr); sys.exit(2)' \
+            'h=parsed.hostname' \
+            '(print("Error: no hostname",file=sys.stderr) or sys.exit(2)) if not h else None' \
+            'try: rs=socket.getaddrinfo(h,None)' \
+            'except socket.gaierror as e: print(f"DNS error: {e}",file=sys.stderr); sys.exit(1)' \
+            'if not rs: print("Error: no addresses",file=sys.stderr); sys.exit(1)' \
+            'for _,_,_,_,(a,*_) in rs:' \
+            '  ip=ipaddress.ip_address(a)' \
+            '  if isinstance(ip,ipaddress.IPv6Address) and ip.ipv4_mapped: ip=ip.ipv4_mapped' \
+            '  cgn=ipaddress.ip_network("100.64.0.0/10")' \
+            '  if ip.is_private or ip.is_loopback or ip.is_link_local or ip.is_multicast or ip.is_reserved or ip in cgn:' \
+            '    print(f"blocked: {a}",file=sys.stderr); sys.exit(1)' \
+            > /tmp/_ssrf_check.py
+          CHECK_URL="${SERVER_URL}" python3 /tmp/_ssrf_check.py || {
+            echo "Error: SERVER_URL '${SERVER_URL}' resolves to a private/reserved IP address" >&2
+            exit 1
+          }
+        fi
+
+        # Determine auth token for release API requests
+        ACTION_TOKEN="${{ inputs.action-repo-token }}"
+        if [ -z "$ACTION_TOKEN" ]; then
+          if [ "$VCS_TYPE" = "github" ]; then
+            ACTION_TOKEN="${{ github.token }}"
+          else
+            ACTION_TOKEN="${{ inputs.reviewer-token }}"
+          fi
+        fi
+
+        # Validate token contains no control characters (defense-in-depth against header injection)
+        if [ -n "$ACTION_TOKEN" ]; then
+          if printf '%s' "$ACTION_TOKEN" | LC_ALL=C grep -q '[^[:print:]]'; then
+            echo "Error: ACTION_TOKEN contains control characters" >&2
+            exit 1
+          fi
+        fi
+
         if [ "${{ inputs.version }}" = "latest" ]; then
-          VERSION=$(curl -sSf "${GITEA_URL}/api/v1/repos/${REPO}/releases?limit=1" \
-            | python3 -c "import sys, json; releases = json.load(sys.stdin); print(releases[0]['tag_name'] if releases else '')")
+          if [ "$VCS_TYPE" = "github" ]; then
+            # SECURITY: Use github.api_url which is a trusted platform-provided value.
+            # Never construct API URLs from user-supplied inputs on GitHub.
+            API_URL="${GITHUB_API_URL}/repos/${ACTION_REPO}/releases?per_page=1"
+          else
+            # Gitea API — SERVER_URL was validated above
+            API_URL="${SERVER_URL}/api/v1/repos/${ACTION_REPO}/releases?limit=1"
+          fi
+
+          # Fetch latest version with inline auth header (no intermediate variable)
+          if [ -n "$ACTION_TOKEN" ]; then
+            if [ "$VCS_TYPE" = "github" ]; then
+              VERSION=$(curl -sSf --connect-timeout 10 --max-time 30 \
+                -H "Authorization: Bearer ${ACTION_TOKEN}" "$API_URL" \
+                | python3 -c "import sys, json; releases = json.load(sys.stdin); print(releases[0]['tag_name'] if releases else '')")
+            else
+              VERSION=$(curl -sSf --connect-timeout 10 --max-time 30 \
+                -H "Authorization: token ${ACTION_TOKEN}" "$API_URL" \
+                | python3 -c "import sys, json; releases = json.load(sys.stdin); print(releases[0]['tag_name'] if releases else '')")
+            fi
+          else
+            VERSION=$(curl -sSf --connect-timeout 10 --max-time 30 "$API_URL" \
+              | python3 -c "import sys, json; releases = json.load(sys.stdin); print(releases[0]['tag_name'] if releases else '')")
+          fi
+
           if [ -z "$VERSION" ]; then
-            echo "Failed to determine latest version" >&2
+            echo "Failed to determine latest version from ${API_URL}" >&2
             exit 1
           fi
         else
           VERSION="${{ inputs.version }}"
         fi
+
+        # Validate VERSION: no slashes or whitespace (prevent path traversal).
+        # [:space:] includes newlines and carriage returns in POSIX.
+        if printf '%s' "$VERSION" | grep -qE '[/[:space:]]'; then
+          echo "Error: VERSION '${VERSION}' contains invalid characters (newline, slash, or whitespace)" >&2
+          exit 1
+        fi
+
+        # Detect OS and architecture for platform-specific binary download
+        OS_RAW=$(uname -s | tr '[:upper:]' '[:lower:]')
+        case "$OS_RAW" in
+          linux)  OS="linux" ;;
+          darwin) OS="darwin" ;;
+          *)
+            echo "Error: unsupported OS: $(uname -s)" >&2
+            exit 1
+            ;;
+        esac
+
+        RAW_ARCH=$(uname -m)
+        case "$RAW_ARCH" in
+          x86_64)           ARCH="amd64" ;;
+          aarch64 | arm64)  ARCH="arm64" ;;
+          *)
+            echo "Error: unsupported architecture: $RAW_ARCH" >&2
+            exit 1
+            ;;
+        esac
+
         echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+        echo "os=${OS}" >> "$GITHUB_OUTPUT"
+        echo "arch=${ARCH}" >> "$GITHUB_OUTPUT"
+        echo "action_repo=${ACTION_REPO}" >> "$GITHUB_OUTPUT"
+        echo "server_url=${SERVER_URL}" >> "$GITHUB_OUTPUT"
+        echo "vcs_type=${VCS_TYPE}" >> "$GITHUB_OUTPUT"
+
+        # SECURITY: Pass token via masked environment variable instead of step output.
+        # Step outputs can leak in debug logs; GITHUB_ENV with masking is safer.
+        if [ -n "$ACTION_TOKEN" ]; then
+          echo "::add-mask::${ACTION_TOKEN}"
+          echo "ACTION_TOKEN=${ACTION_TOKEN}" >> "$GITHUB_ENV"
+        fi
 
     - name: Cache review-bot binary
       id: cache
       uses: actions/cache@v4
       with:
         path: ${{ runner.temp }}/review-bot
-        key: review-bot-linux-amd64-${{ steps.version.outputs.version }}
+        key: review-bot-${{ steps.version.outputs.os }}-${{ steps.version.outputs.arch }}-${{ steps.version.outputs.version }}
 
     - name: Install review-bot
       if: steps.cache.outputs.cache-hit != 'true'
       shell: bash
       run: |
-        GITEA_URL="${{ inputs.gitea-url || github.server_url }}"
-        REPO="${{ inputs.repo || 'rodin/review-bot' }}"
-        VERSION="${{ steps.version.outputs.version }}"
-        BINARY="review-bot-linux-amd64"
+        set -euo pipefail
 
-        curl -sSfL "${GITEA_URL}/${REPO}/releases/download/${VERSION}/${BINARY}" \
-          -o "${{ runner.temp }}/review-bot"
-        curl -sSfL "${GITEA_URL}/${REPO}/releases/download/${VERSION}/checksums.txt" \
-          -o "${{ runner.temp }}/checksums.txt"
+        SERVER_URL="${{ steps.version.outputs.server_url }}"
+        ACTION_REPO="${{ steps.version.outputs.action_repo }}"
+        VERSION="${{ steps.version.outputs.version }}"
+        VCS_TYPE="${{ steps.version.outputs.vcs_type }}"
+        OS="${{ steps.version.outputs.os }}"
+        ARCH="${{ steps.version.outputs.arch }}"
+        # Read token from masked environment variable (set in Determine version step)
+        # Falls back to empty if not set (public repos don't need auth)
+        ACTION_TOKEN="${ACTION_TOKEN:-}"
+        BINARY="review-bot-${OS}-${ARCH}"
+
+        # SECURITY: Re-validate SERVER_URL at the start of this step to mitigate DNS
+        # rebinding attacks. A DNS TTL expiry between "Determine version" and here
+        # could allow an attacker to change the resolved IP to a private/reserved
+        # address, causing curl to send ACTION_TOKEN to an internal host.
+        # Only needed on Gitea path (VCS_TYPE=gitea); GitHub/GHES uses platform-controlled URLs.
+        if [ "$VCS_TYPE" = "gitea" ]; then
+          printf '%s\n' \
+            'import socket,ipaddress,sys,os' \
+            'from urllib.parse import urlparse' \
+            'u=os.environ["CHECK_URL"]; parsed=urlparse(u)' \
+            'if parsed.username or parsed.password:' \
+            '  print("Error: URL contains user-info — not allowed",file=sys.stderr); sys.exit(2)' \
+            'h=parsed.hostname' \
+            '(print("Error: no hostname",file=sys.stderr) or sys.exit(2)) if not h else None' \
+            'try: rs=socket.getaddrinfo(h,None)' \
+            'except socket.gaierror as e: print(f"DNS error: {e}",file=sys.stderr); sys.exit(1)' \
+            'if not rs: print("Error: no addresses",file=sys.stderr); sys.exit(1)' \
+            'for _,_,_,_,(a,*_) in rs:' \
+            '  ip=ipaddress.ip_address(a)' \
+            '  if isinstance(ip,ipaddress.IPv6Address) and ip.ipv4_mapped: ip=ip.ipv4_mapped' \
+            '  cgn=ipaddress.ip_network("100.64.0.0/10")' \
+            '  if ip.is_private or ip.is_loopback or ip.is_link_local or ip.is_multicast or ip.is_reserved or ip in cgn:' \
+            '    print(f"blocked: {a}",file=sys.stderr); sys.exit(1)' \
+              > /tmp/_ssrf_check_install.py
+          CHECK_URL="${SERVER_URL}" python3 /tmp/_ssrf_check_install.py || {
+            echo "Error: SERVER_URL '${SERVER_URL}' resolves to a private/reserved IP address" >&2
+            exit 1
+          }
+        fi
+
+        if [ "$VCS_TYPE" = "github" ]; then
+          # GitHub/GHES: Use REST API for release asset downloads.
+          # Web release URLs ({server}/.../releases/download/{tag}/{asset}) redirect
+          # to S3 and don't reliably support Authorization headers for private repos.
+          # The REST API endpoint with Accept: application/octet-stream is required.
+          # GITHUB_API_URL: trusted platform value, same as detected in "Determine version" step.
+          GITHUB_API_URL="${{ github.api_url }}"
+
+          if [ -n "$ACTION_TOKEN" ]; then
+            RELEASE_JSON=$(curl -sSf --connect-timeout 10 --max-time 30 \
+              -H "Authorization: Bearer ${ACTION_TOKEN}" \
+              "${GITHUB_API_URL}/repos/${ACTION_REPO}/releases/tags/${VERSION}")
+          else
+            RELEASE_JSON=$(curl -sSf --connect-timeout 10 --max-time 30 \
+              "${GITHUB_API_URL}/repos/${ACTION_REPO}/releases/tags/${VERSION}")
+          fi
+
+          # Extract asset IDs for binary and checksums
+          BINARY_ASSET_ID=$(printf '%s' "$RELEASE_JSON" | python3 -c "import sys, json; assets = json.load(sys.stdin).get('assets', []); matches = [a['id'] for a in assets if a['name'] == '${BINARY}']; print(matches[0] if matches else '')")
+          if [ -z "$BINARY_ASSET_ID" ]; then
+            echo "Error: could not find asset '${BINARY}' in release ${VERSION}" >&2
+            exit 1
+          fi
+
+          CHECKSUMS_ASSET_ID=$(printf '%s' "$RELEASE_JSON" | python3 -c "import sys, json; assets = json.load(sys.stdin).get('assets', []); matches = [a['id'] for a in assets if a['name'] == 'checksums.txt']; print(matches[0] if matches else '')")
+          if [ -z "$CHECKSUMS_ASSET_ID" ]; then
+            echo "Error: could not find asset 'checksums.txt' in release ${VERSION}" >&2
+            exit 1
+          fi
+
+          # Download assets via REST API with Accept: application/octet-stream
+          if [ -n "$ACTION_TOKEN" ]; then
+            curl -sSfL --connect-timeout 10 --max-time 120 \
+              -H "Authorization: Bearer ${ACTION_TOKEN}" \
+              -H "Accept: application/octet-stream" \
+              "${GITHUB_API_URL}/repos/${ACTION_REPO}/releases/assets/${BINARY_ASSET_ID}" \
+              -o "${{ runner.temp }}/review-bot"
+            curl -sSfL --connect-timeout 10 --max-time 30 \
+              -H "Authorization: Bearer ${ACTION_TOKEN}" \
+              -H "Accept: application/octet-stream" \
+              "${GITHUB_API_URL}/repos/${ACTION_REPO}/releases/assets/${CHECKSUMS_ASSET_ID}" \
+              -o "${{ runner.temp }}/checksums.txt"
+          else
+            curl -sSfL --connect-timeout 10 --max-time 120 \
+              -H "Accept: application/octet-stream" \
+              "${GITHUB_API_URL}/repos/${ACTION_REPO}/releases/assets/${BINARY_ASSET_ID}" \
+              -o "${{ runner.temp }}/review-bot"
+            curl -sSfL --connect-timeout 10 --max-time 30 \
+              -H "Accept: application/octet-stream" \
+              "${GITHUB_API_URL}/repos/${ACTION_REPO}/releases/assets/${CHECKSUMS_ASSET_ID}" \
+              -o "${{ runner.temp }}/checksums.txt"
+          fi
+        else
+          # Gitea: Direct download via web release URLs (Gitea serves assets
+          # directly without redirects — no -L needed).
+          # SECURITY: Omitting -L prevents forwarding Authorization header to
+          # unexpected hosts if Gitea ever introduces CDN redirects.
+          DOWNLOAD_URL="${SERVER_URL}/${ACTION_REPO}/releases/download/${VERSION}"
+
+          if [ -n "$ACTION_TOKEN" ]; then
+            curl -sSf --connect-timeout 10 --max-time 120 \
+              -H "Authorization: token ${ACTION_TOKEN}" \
+              "${DOWNLOAD_URL}/${BINARY}" -o "${{ runner.temp }}/review-bot"
+            curl -sSf --connect-timeout 10 --max-time 30 \
+              -H "Authorization: token ${ACTION_TOKEN}" \
+              "${DOWNLOAD_URL}/checksums.txt" -o "${{ runner.temp }}/checksums.txt"
+          else
+            curl -sSf --connect-timeout 10 --max-time 120 \
+              "${DOWNLOAD_URL}/${BINARY}" -o "${{ runner.temp }}/review-bot"
+            curl -sSf --connect-timeout 10 --max-time 30 \
+              "${DOWNLOAD_URL}/checksums.txt" -o "${{ runner.temp }}/checksums.txt"
+          fi
+        fi
 
         # Verify SHA-256 checksum
+        # NOTE: This verifies integrity (download wasn't corrupted) but not
+        # authenticity — both binary and checksums come from the same server.
+        # For stronger guarantees, consider GPG signature verification.
         cd "${{ runner.temp }}"
-        EXPECTED=$(grep "${BINARY}" checksums.txt | awk '{print $1}')
-        ACTUAL=$(sha256sum review-bot | awk '{print $1}')
+        EXPECTED=$(grep -E "^[0-9a-f]+[[:space:]]+\*?${BINARY}$" checksums.txt | awk '{print $1}')
+        # sha256sum (GNU) is not available on macOS; use shasum -a 256 on darwin.
+        if [ "${OS}" = "darwin" ]; then
+          ACTUAL=$(shasum -a 256 review-bot | awk '{print $1}')
+        else
+          ACTUAL=$(sha256sum review-bot | awk '{print $1}')
+        fi
 
         if [ -z "$EXPECTED" ]; then
           echo "Error: no checksum found for ${BINARY}" >&2
@@ -164,12 +470,12 @@ runs:
         fi
 
         chmod +x "${{ runner.temp }}/review-bot"
-        echo "Installed review-bot ${VERSION} (checksum verified)"
+        echo "Installed review-bot-${OS}-${ARCH} ${VERSION} (checksum verified)"
 
     - name: Run review
       shell: bash
       env:
-        GITEA_URL: ${{ inputs.gitea-url || github.server_url }}
+        VCS_URL: ${{ steps.version.outputs.server_url }}
         GITEA_REPO: ${{ inputs.repo || github.repository }}
         PR_NUMBER: ${{ inputs.pr-number || github.event.pull_request.number }}
         REVIEWER_TOKEN: ${{ inputs.reviewer-token }}

.gitea/workflows/ci.yml

@@ -38,6 +38,8 @@ jobs:
           - name: security
             token_secret: SECURITY_REVIEW_TOKEN
             model: gpt-5
+            patterns_repo: rodin/security-patterns
+            patterns_files: "."
             system_prompt_file: SECURITY_REVIEW.md
     steps:
       - uses: actions/checkout@v4
@@ -47,7 +49,7 @@ jobs:
       - run: go build -o review-bot ./cmd/review-bot
       - name: Run ${{ matrix.name }} review
         env:
-          GITEA_URL: ${{ github.server_url }}
+          VCS_URL: ${{ github.server_url }}
           GITEA_REPO: ${{ github.repository }}
           PR_NUMBER: ${{ github.event.pull_request.number }}
           REVIEWER_TOKEN: ${{ secrets[matrix.token_secret] }}
@@ -60,8 +62,8 @@ jobs:
           AICORE_API_URL: ${{ secrets.AICORE_API_URL }}
           AICORE_RESOURCE_GROUP: ${{ secrets.AICORE_RESOURCE_GROUP }}
           CONVENTIONS_FILE: "CONVENTIONS.md"
-          PATTERNS_REPO: "rodin/go-patterns"
-          PATTERNS_FILES: "README.md,patterns/"
+          PATTERNS_REPO: ${{ matrix.patterns_repo || 'rodin/go-patterns' }}
+          PATTERNS_FILES: ${{ matrix.patterns_files || 'README.md,patterns/' }}
           LLM_TIMEOUT: "600"
           SYSTEM_PROMPT_FILE: ${{ matrix.system_prompt_file }}
         run: ./review-bot

CONVENTIONS.md

@@ -2,8 +2,26 @@
 
 ## Language & Dependencies
 
-- Go standard library only — no external dependencies.
 - Target the latest stable Go release.
+- **STRICT ALLOWLIST:** Only packages listed below may be imported. No exceptions.
+
+### Approved Third-Party Packages
+
+| Package | Use Case | Scope |
+|---------|----------|-------|
+| `github.com/goccy/go-yaml` | YAML parsing and AST inspection (subpkgs: `ast`, `parser`) | production |
+| `github.com/google/go-cmp` | Test comparisons (`cmp.Diff`) | test only |
+
+**Any import not in this table or the Go standard library is forbidden.**
+
+Transitive dependencies of approved packages are automatically allowed.
+
+To request a new dependency:
+1. Open a PR that ONLY updates this table
+2. Requires explicit approval from Aaron
+3. After merge, a separate PR may use the package
+
+*Enforcement: `scripts/check-deps.sh` parses this table — update only here.*
 
 ## Error Handling
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build test test-integration lint clean coverage
+.PHONY: build test test-integration lint clean coverage check-deps precommit
 
 build:
 	go build -o review-bot ./cmd/review-bot/
@@ -12,9 +12,15 @@ test-integration:
 lint:
 	go vet ./...
 
+check-deps:
+	@./scripts/check-deps.sh
+
 clean:
 	rm -f review-bot
 
 coverage:
 	go test -coverprofile=coverage.out ./...
 	go tool cover -func=coverage.out
+
+# Precommit runs all checks required before pushing
+precommit: check-deps lint test

PLAN-125.md

@@ -0,0 +1,175 @@
+# Plan: Issue #125 — Rename GITEA_URL → VCS_URL
+
+## Problem
+
+The `GITEA_URL` environment variable (and `--gitea-url` flag) implies the binary only works with Gitea.
+Now that review-bot supports both Gitea and GitHub/GHES, this name is misleading.
+Renaming to `VCS_URL` makes the binary platform-agnostic in its interface.
+
+## Constraints
+
+- Must not break existing users who already use `GITEA_URL` — need a fallback
+- The CLI flag `--gitea-url` should also be updated to `--vcs-url` for consistency
+- `INTEGRATION_GITEA_URL` in integration tests is a test-only env var, not the binary's interface; but should be updated for clarity
+- The action YAML uses `GITEA_URL` as an internal shell variable in bash scripts — distinct from the env var passed to the binary
+- All changes must compile and pass existing tests
+
+## Files Affected
+
+### Binary / Go source
+| File | Change |
+|------|--------|
+| `cmd/review-bot/main.go` | Rename `--gitea-url` → `--vcs-url`, add `VCS_URL` as primary, keep `GITEA_URL` fallback |
+| `cmd/review-bot/integration_test.go` | Rename `INTEGRATION_GITEA_URL` → `INTEGRATION_VCS_URL` (test-only, no external compat concern) |
+| `integration_test.go` | Same — rename `INTEGRATION_GITEA_URL` → `INTEGRATION_VCS_URL` |
+
+### Action YAML
+| File | Change |
+|------|--------|
+| `.gitea/actions/review/action.yml` | Rename input `gitea-url` → `vcs-url`; update env var passed to binary: `VCS_URL` instead of `GITEA_URL`; keep internal bash var as `GITEA_URL` (only used for release download, not passed to binary) |
+| `.gitea/workflows/ci.yml` | Rename `GITEA_URL` env var to `VCS_URL` in Run review step |
+
+### Documentation
+| File | Change |
+|------|--------|
+| `README.md` | Update CLI example, env var table entry |
+
+## Proposed Approach
+
+### 1. Backward-compatible env var lookup in main.go
+
+Replace:
+```go
+giteaURL := flag.String("gitea-url", envOrDefault("GITEA_URL", ""), "Gitea instance URL")
+```
+
+With:
+```go
+giteaURL := flag.String("vcs-url", envOrDefaultFallback("VCS_URL", "GITEA_URL", ""), "VCS server URL (e.g. https://gitea.example.com)")
+```
+
+Add a helper:
+```go
+// envOrDefaultFallback reads primary env var; if empty, falls back to deprecated env var.
+func envOrDefaultFallback(primary, deprecated, defaultVal string) string {
+    if v := os.Getenv(primary); v != "" {
+        return v
+    }
+    if v := os.Getenv(deprecated); v != "" {
+        slog.Warn("deprecated env var in use; rename to " + primary, "old", deprecated, "new", primary)
+        return v
+    }
+    return defaultVal
+}
+```
+
+**Note:** This must be called AFTER `setupLogger` conceptually, but the flag default is evaluated at flag registration time. Since `setupLogger` runs before `flag.Parse()`, the slog.Warn will print correctly at runtime. We use `log.Printf` as a fallback if this proves problematic.
+
+Actually — flag defaults are evaluated at registration (line 57), before `setupLogger`. The warning won't go through slog. Two options:
+- Use `log.Printf` for the deprecation warning (always visible)
+- Move the fallback lookup to after `flag.Parse()`, checking if the parsed value is still empty
+
+**Decision:** Move fallback to a post-parse check. This is cleaner:
+```go
+vcsURL := flag.String("vcs-url", os.Getenv("VCS_URL"), "VCS server URL")
+flag.Parse()
+// Backward compat: fall back to deprecated GITEA_URL
+if *vcsURL == "" {
+    if v := os.Getenv("GITEA_URL"); v != "" {
+        slog.Warn("GITEA_URL is deprecated; use VCS_URL instead")
+        *vcsURL = v
+    }
+}
+```
+
+This is clean, idiomatic, and the warning goes through slog correctly.
+
+### 2. Keep `--gitea-url` as deprecated alias
+
+Add a hidden flag for backward compat:
+```go
+giteaURLAlias := flag.String("gitea-url", "", "Deprecated: use --vcs-url")
+```
+
+Post-parse:
+```go
+if *vcsURL == "" && *giteaURLAlias != "" {
+    slog.Warn("--gitea-url is deprecated; use --vcs-url instead")
+    *vcsURL = *giteaURLAlias
+}
+```
+
+### 3. Internal variable rename
+
+Rename `giteaURL` local variable → `vcsURL` throughout `main.go` for consistency.
+
+### 4. Error message update
+
+```go
+fmt.Fprintf(os.Stderr, "Required: --vcs-url, --repo, --pr, --reviewer-token, --llm-model\n")
+```
+
+### 5. Action YAML changes
+
+In `.gitea/actions/review/action.yml`:
+- Input `gitea-url` → `vcs-url` (with same description, `required: false`, `default: ''`)
+- Line 172: `GITEA_URL: ${{ inputs.gitea-url || github.server_url }}` → `VCS_URL: ${{ inputs.vcs-url || github.server_url }}`
+- Lines 115, 140: internal bash vars `GITEA_URL=` are used for downloading binaries — NOT passed to the review-bot binary. Leave them as internal bash vars (they're scope-local in bash). These could be renamed to `SERVER_URL` or `BASE_URL` for local clarity, but renaming them isn't strictly required.
+
+In `.gitea/workflows/ci.yml`:
+- Line 52: `GITEA_URL: ${{ github.server_url }}` → `VCS_URL: ${{ github.server_url }}`
+
+### 6. Integration test updates
+
+`INTEGRATION_GITEA_URL` → `INTEGRATION_VCS_URL` in both test files.
+
+### 7. README
+
+- CLI example: `--gitea-url` → `--vcs-url`
+- Env var table: `GITEA_URL` → `VCS_URL`, add note about `GITEA_URL` fallback
+
+## Backward Compatibility Summary
+
+| Old | New | Fallback? |
+|-----|-----|-----------|
+| `GITEA_URL` env var | `VCS_URL` | ✅ with deprecation warning |
+| `--gitea-url` flag | `--vcs-url` | ✅ with deprecation warning |
+| `gitea-url` action input | `vcs-url` | ⚠️ No (action version bump handles this) |
+| `INTEGRATION_GITEA_URL` | `INTEGRATION_VCS_URL` | N/A (test-only) |
+
+## Error Cases
+
+- Both `VCS_URL` and `GITEA_URL` set: `VCS_URL` wins (primary takes precedence)
+- Both `--vcs-url` and `--gitea-url` provided: `--vcs-url` wins
+- Neither set: existing "missing required flags" error unchanged
+
+## Edge Cases
+
+- `os.Getenv` returns "" for unset AND set-to-empty — consistent with existing behavior
+- The `envOrDefault` helper is unchanged; we add `envOrDefaultFallback` for the one renamed var
+
+## Testing Strategy
+
+- Existing unit tests pass unchanged (they don't test env var parsing directly)
+- Integration tests updated to use new env var name
+- Manual: `GITEA_URL=https://example.com ./review-bot --repo x --pr 1 ...` should print deprecation warning and proceed
+- Manual: `VCS_URL=https://example.com ./review-bot ...` should work silently
+
+## Completion Checklist
+
+1. `VCS_URL` is read first; `GITEA_URL` is fallback with deprecation warning
+2. `--vcs-url` flag is primary; `--gitea-url` is deprecated alias with warning
+3. Error message references `--vcs-url` not `--gitea-url`
+4. `action.yml` passes `VCS_URL` (not `GITEA_URL`) to the binary
+5. `ci.yml` passes `VCS_URL` (not `GITEA_URL`) to the binary
+6. README updated in CLI example and env var table
+7. Integration tests use `INTEGRATION_VCS_URL`
+8. `go test ./...` passes
+9. `go vet ./...` passes
+10. `go build ./cmd/review-bot` succeeds
+
+## Open Questions
+
+- Should the CLI flag `--gitea-url` be completely hidden from `--help` or just deprecated with a note? The issue doesn't specify. Decision: keep it visible but add "(deprecated: use --vcs-url)" to the description.
+- Should action.yml also add `gitea-url` as a deprecated input alias? The issue says "Update the action to pass the new env var name" — no mention of backward compat for the action input. Decision: rename only, no alias (action users pin a version anyway).
+- The bash-internal `GITEA_URL` variable in action.yml scripts (used for release download, not passed to binary) — rename for clarity? Decision: yes, rename to `BASE_URL` to avoid confusion with the env var.

README.md

@@ -9,7 +9,7 @@ AI-powered code review bot for Gitea pull requests. Fetches diff + context, send
 - **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
+- **Minimal dependencies**: Go stdlib + `gopkg.in/yaml.v3` only
 
 ## Quick Start: Composite Action
 
@@ -208,7 +208,7 @@ AI Core handles OAuth token management and deployment discovery automatically. M
 | `patterns-files` | No | `README.md` | Files/directories to fetch from pattern repos |
 | `system-prompt-file` | No | `""` | Local file with additional system prompt instructions |
 | `persona` | No | `""` | Built-in persona name (security, architect, docs) |
-| `persona-file` | No | `""` | Path to persona JSON file with custom review focus |
+| `persona-file` | No | `""` | Path to persona file (YAML or JSON) with custom review focus |
 | `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 |
@@ -282,7 +282,7 @@ Rules:
 
 ```bash
 review-bot \
-  --gitea-url https://gitea.example.com \
+  --vcs-url https://gitea.example.com \
   --repo owner/name \
   --pr 42 \
   --reviewer-token "$GITEA_TOKEN" \
@@ -299,7 +299,7 @@ All flags have environment variable equivalents:
 
 | Flag | Env Var |
 |------|---------|
-| `--gitea-url` | `GITEA_URL` |
+| `--vcs-url` | `VCS_URL` (fallback: `GITEA_URL`) |
 | `--repo` | `GITEA_REPO` |
 | `--pr` | `PR_NUMBER` |
 | `--reviewer-token` | `REVIEWER_TOKEN` |
@@ -329,11 +329,12 @@ All flags have environment variable equivalents:
 ### Token Scopes Required
 
 | Scope | Purpose |
-|-------|---------|
+|-------|--------|
 | `write:issue` | Post and delete reviews |
 | `write:repository` | Read PR diffs, file content, commit statuses |
+| `read:user` | Self-request as reviewer (optional but recommended) |
 
-No `read:user` scope needed — the bot identifies itself from the review response.
+Without `read:user`, the bot still works but cannot add itself to the PR's reviewer list.
 
 ## Development
 
@@ -408,32 +409,38 @@ Each persona posts independently with its own sentinel, so reviews don't interfe
 
 ### Custom Personas
 
-Create a JSON file with your domain-specific review focus:
+Create a YAML file with your domain-specific review focus:
 
-```json
-// .review/personas/trading.json
-{
-  "name": "trading",
-  "display_name": "Trading Domain Expert",
-  "identity": "You are a trading systems expert reviewing code for correctness.\n\nYour expertise:\n- Order lifecycle and state machines\n- Fill handling and partial fills\n- Position tracking and P&L calculations\n- Event sourcing invariants",
-  "focus": [
-    "Order state machine correctness",
-    "Fill handling edge cases (partial, overfill)",
-    "Position and P&L calculation accuracy",
-    "Event replay determinism",
-    "Decimal precision for money"
-  ],
-  "ignore": [
-    "Code style",
-    "General performance",
-    "Documentation formatting"
-  ],
-  "severity": {
-    "major": "Bugs that cause incorrect positions, fills, or money calculations",
-    "minor": "Edge cases that could cause issues under unusual conditions",
-    "nit": "Clarity improvements for domain logic"
-  }
-}
+```yaml
+# .review/personas/trading.yaml
+name: trading
+display_name: Trading Domain Expert
+
+identity: |
+  You are a trading systems expert reviewing code for correctness.
+
+  Your expertise:
+  - Order lifecycle and state machines
+  - Fill handling and partial fills
+  - Position tracking and P&L calculations
+  - Event sourcing invariants
+
+focus:
+  - Order state machine correctness
+  - Fill handling edge cases (partial, overfill)
+  - Position and P&L calculation accuracy
+  - Event replay determinism
+  - Decimal precision for money
+
+ignore:
+  - Code style
+  - General performance
+  - Documentation formatting
+
+severity:
+  major: "Bugs that cause incorrect positions, fills, or money calculations"
+  minor: "Edge cases that could cause issues under unusual conditions"
+  nit: "Clarity improvements for domain logic"
 ```
 
 Use it in CI:
@@ -442,17 +449,24 @@ Use it in CI:
 - uses: rodin/review-bot/.gitea/actions/review@v1
   with:
     reviewer-name: trading
-    persona-file: .review/personas/trading.json
+    persona-file: .review/personas/trading.yaml
     ...
 ```
 
+YAML is the recommended format for personas because it supports:
+- Multi-line strings with `|` blocks (cleaner identity definitions)
+- Comments for documentation
+- More readable arrays and nested structures
+
+JSON is also supported for backwards compatibility—just use `.json` extension.
+
 
 ### Persona vs system-prompt-file
 
 | Feature | `persona` / `persona-file` | `system-prompt-file` |
 |---------|---------------------------|----------------------|
 | Replaces base prompt | Yes | No (appends) |
-| Structured format | Yes (JSON) | No (freeform) |
+| Structured format | Yes (YAML/JSON) | No (freeform) |
 | Focus/ignore lists | Yes | Manual |
 | Severity calibration | Yes | Manual |
 | Header display name | Yes | No |

cmd/review-bot/integration_test.go

@@ -17,7 +17,7 @@ import (
 // Integration test requires a running Gitea instance and LLM endpoint.
 // Set environment variables:
 //
-//	INTEGRATION_GITEA_URL     - Gitea base URL
+//	INTEGRATION_VCS_URL       - VCS base URL
 //	INTEGRATION_GITEA_TOKEN   - Gitea API token with repo access
 //	INTEGRATION_GITEA_REPO    - owner/repo with an open PR
 //	INTEGRATION_PR_NUMBER     - PR number to test against
@@ -25,7 +25,7 @@ import (
 //	INTEGRATION_LLM_API_KEY   - LLM API key
 //	INTEGRATION_LLM_MODEL     - Model name
 func TestIntegration_FullReviewFlow(t *testing.T) {
-	giteaURL := os.Getenv("INTEGRATION_GITEA_URL")
+	giteaURL := os.Getenv("INTEGRATION_VCS_URL")
 	giteaToken := os.Getenv("INTEGRATION_GITEA_TOKEN")
 	giteaRepo := os.Getenv("INTEGRATION_GITEA_REPO")
 	prNumStr := os.Getenv("INTEGRATION_PR_NUMBER")
@@ -104,7 +104,7 @@ func TestIntegration_FullReviewFlow(t *testing.T) {
 }
 
 func TestIntegration_PostAndCleanup(t *testing.T) {
-	giteaURL := os.Getenv("INTEGRATION_GITEA_URL")
+	giteaURL := os.Getenv("INTEGRATION_VCS_URL")
 	giteaToken := os.Getenv("INTEGRATION_GITEA_TOKEN")
 	giteaRepo := os.Getenv("INTEGRATION_GITEA_REPO")
 	prNumStr := os.Getenv("INTEGRATION_PR_NUMBER")
@@ -130,7 +130,7 @@ func TestIntegration_PostAndCleanup(t *testing.T) {
 	// Post a test review
 	sentinel := "<!-- review-bot:integration-test -->"
 	testBody := "# Integration Test Review\n\nThis is a test review.\n\n" + sentinel
-	posted, err := giteaClient.PostReview(ctx, owner, repoName, prNumber, "COMMENT", testBody, nil)
+	posted, err := giteaClient.PostReview(ctx, owner, repoName, prNumber, "COMMENT", testBody, "", nil)
 	if err != nil {
 		t.Fatalf("PostReview: %v", err)
 	}

cmd/review-bot/main.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"flag"
 	"fmt"
+	"io"
 	"log/slog"
 	"os"
 	"path/filepath"
@@ -19,6 +20,13 @@ import (
 
 var version = "dev"
 
+// outWriter and errWriter are the output and error writers for subcommands.
+// They are variables so tests can capture output.
+var (
+	outWriter io.Writer = os.Stdout
+	errWriter io.Writer = os.Stderr
+)
+
 // setupLogger configures the global slog default logger based on format and verbosity.
 func setupLogger(format, verbosity string) {
 	var level slog.Level
@@ -49,12 +57,22 @@ func setupLogger(format, verbosity string) {
 }
 
 func main() {
+	// Dispatch subcommands before flag parsing so they get their own args.
+	// e.g. `review-bot validate-url <url>`
+	if len(os.Args) > 1 {
+		switch os.Args[1] {
+		case "validate-url":
+			os.Exit(runValidateURL(os.Args[2:]))
+		}
+	}
+
 	versionFlag := flag.Bool("version", false, "Print version and exit")
 	// Logging flags
 	logFormat := flag.String("log-format", envOrDefault("LOG_FORMAT", "text"), "Log output format: text or json")
 	verbosity := flag.String("verbosity", envOrDefault("LOG_VERBOSITY", "info"), "Log verbosity: debug, info, warn, error")
 	// CLI flags
-	giteaURL := flag.String("gitea-url", envOrDefault("GITEA_URL", ""), "Gitea instance URL")
+	vcsURL := flag.String("vcs-url", os.Getenv("VCS_URL"), "VCS server URL (e.g. https://gitea.example.com)")
+	giteaURLAlias := flag.String("gitea-url", "", "Deprecated: use --vcs-url")
 	repo := flag.String("repo", envOrDefault("GITEA_REPO", ""), "Repository (owner/name)")
 	prNum := flag.String("pr", envOrDefault("PR_NUMBER", ""), "Pull request number")
 	reviewerName := flag.String("reviewer-name", envOrDefault("REVIEWER_NAME", ""), "Reviewer display name")
@@ -65,7 +83,7 @@ func main() {
 	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")
+	patternsFiles := flag.String("patterns-files", envOrDefault("PATTERNS_FILES", ""), "Comma-separated file paths to fetch from patterns repo (empty = all files)")
 	dryRun := flag.Bool("dry-run", false, "Print review to stdout instead of posting")
 	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)")
@@ -79,7 +97,6 @@ func main() {
 	aicoreAPIURL := flag.String("aicore-api-url", envOrDefault("AICORE_API_URL", ""), "SAP AI Core API URL (for provider=aicore)")
 	aicoreResourceGroup := flag.String("aicore-resource-group", envOrDefault("AICORE_RESOURCE_GROUP", "default"), "SAP AI Core resource group (for provider=aicore)")
 
-	flag.Parse()
 	flag.Parse()
 
 	if *versionFlag {
@@ -92,12 +109,24 @@ func main() {
 
 	slog.Info("review-bot starting", "version", version)
 
+	// Backward compatibility: fall back to deprecated env var / flag if VCS_URL / --vcs-url not set.
+	if *vcsURL == "" {
+		if v := os.Getenv("GITEA_URL"); v != "" {
+			slog.Warn("GITEA_URL is deprecated; rename the environment variable to VCS_URL")
+			*vcsURL = v
+		}
+	}
+	if *vcsURL == "" && *giteaURLAlias != "" {
+		slog.Warn("--gitea-url is deprecated; use --vcs-url instead")
+		*vcsURL = *giteaURLAlias
+	}
+
 	// Validate required fields
 	// For aicore provider, llm-base-url and llm-api-key are not required
 	isAICore := llm.Provider(*llmProvider) == llm.ProviderAICore
-	if *giteaURL == "" || *repo == "" || *prNum == "" || *reviewerToken == "" || *llmModel == "" {
+	if *vcsURL == "" || *repo == "" || *prNum == "" || *reviewerToken == "" || *llmModel == "" {
 		fmt.Fprintf(os.Stderr, "Error: missing required flags or environment variables\n\n")
-		fmt.Fprintf(os.Stderr, "Required: --gitea-url, --repo, --pr, --reviewer-token, --llm-model\n")
+		fmt.Fprintf(os.Stderr, "Required: --vcs-url, --repo, --pr, --reviewer-token, --llm-model\n")
 		os.Exit(1)
 	}
 	if !isAICore && (*llmBaseURL == "" || *llmAPIKey == "") {
@@ -116,29 +145,7 @@ func main() {
 		os.Exit(1)
 	}
 
-	// Load persona if specified
-	var persona *review.Persona
-	if *personaName != "" {
-		var err error
-		persona, err = review.LoadBuiltinPersona(*personaName)
-		if err != nil {
-			slog.Error("failed to load persona", "persona", *personaName, "error", err)
-			os.Exit(1)
-		}
-		slog.Info("loaded built-in persona", "persona", persona.Name, "display", persona.DisplayName)
-	} else if *personaFile != "" {
-		resolvedPath, err := validateWorkspacePath(*personaFile, "persona-file")
-		if err != nil {
-			slog.Error("invalid persona-file path", "error", err)
-			os.Exit(1)
-		}
-		persona, err = review.LoadPersona(resolvedPath)
-		if err != nil {
-			slog.Error("failed to load persona file", "file", *personaFile, "error", err)
-			os.Exit(1)
-		}
-		slog.Info("loaded persona from file", "file", *personaFile, "persona", persona.Name)
-	}
+	// NOTE: Persona loading deferred until after Gitea client init to support repo personas
 
 	// Validate reviewer-name: only safe characters allowed in sentinel
 	if err := validateReviewerName(*reviewerName); err != nil {
@@ -162,7 +169,7 @@ func main() {
 	}
 
 	// Initialize clients
-	giteaClient := gitea.NewClient(*giteaURL, *reviewerToken)
+	giteaClient := gitea.NewClient(*vcsURL, *reviewerToken)
 	llmClient := llm.NewClient(*llmBaseURL, *llmAPIKey, *llmModel)
 	if *llmTemp < 0 || *llmTemp > 2 {
 		slog.Error("invalid LLM temperature", "temperature", *llmTemp, "range", "0-2")
@@ -196,6 +203,43 @@ func main() {
 	ctx, cancel := context.WithTimeout(context.Background(), overallTimeout)
 	defer cancel()
 
+	// Load persona if specified (after Gitea client init to support repo personas)
+	var persona *review.Persona
+	if *personaName != "" {
+		// Try loading from repo first, then fall back to built-in
+		repoPersonas, err := review.LoadRepoPersonas(ctx, newGiteaClientAdapter(giteaClient), owner, repoName)
+		if err != nil {
+			slog.Warn("could not load repo personas", "repo", owner+"/"+repoName, "error", err)
+			// Continue with built-in personas only.
+			// NOTE: repoPersonas is nil here, but map indexing on a nil map is safe in Go
+			// (returns the zero value), so the fallback to built-in below works correctly.
+		}
+		if p, ok := repoPersonas[*personaName]; ok {
+			persona = p
+			slog.Info("loaded repo persona", "persona", persona.Name, "display", persona.DisplayName, "repo", owner+"/"+repoName)
+		} else {
+			// Fall back to built-in
+			persona, err = review.LoadBuiltinPersona(*personaName)
+			if err != nil {
+				slog.Error("failed to load persona", "persona", *personaName, "error", err)
+				os.Exit(1)
+			}
+			slog.Info("loaded built-in persona", "persona", persona.Name, "display", persona.DisplayName)
+		}
+	} else if *personaFile != "" {
+		resolvedPath, err := validateWorkspacePath(*personaFile, "persona-file")
+		if err != nil {
+			slog.Error("invalid persona-file path", "error", err)
+			os.Exit(1)
+		}
+		persona, err = review.LoadPersona(resolvedPath)
+		if err != nil {
+			slog.Error("failed to load persona file", "file", *personaFile, "error", err)
+			os.Exit(1)
+		}
+		slog.Info("loaded persona from file", "file", *personaFile, "persona", persona.Name)
+	}
+
 	slog.Info("reviewing pull request", "pr", prNumber, "repo", fmt.Sprintf("%s/%s", owner, repoName))
 
 	// Step 1: Fetch PR metadata
@@ -430,7 +474,7 @@ func main() {
 
 	// POST new review
 	slog.Info("posting review", "event", event, "pr", prNumber)
-	posted, err := giteaClient.PostReview(ctx, owner, repoName, prNumber, event, reviewBody, inlineComments)
+	posted, err := giteaClient.PostReview(ctx, owner, repoName, prNumber, event, reviewBody, evaluatedSHA, inlineComments)
 	if err != nil {
 		slog.Error("failed to post review", "pr", prNumber, "event", event, "error", err)
 		os.Exit(1)
@@ -439,7 +483,7 @@ func main() {
 
 	// Supersede all old reviews with link to the new one
 	if len(oldReviews) > 0 {
-		newReviewURL := fmt.Sprintf("%s/%s/%s/pulls/%d#pullrequestreview-%d", strings.TrimRight(*giteaURL, "/"), owner, repoName, prNumber, posted.ID)
+		newReviewURL := fmt.Sprintf("%s/%s/%s/pulls/%d#pullrequestreview-%d", strings.TrimRight(*vcsURL, "/"), owner, repoName, prNumber, posted.ID)
 		for _, oldReview := range oldReviews {
 			cid, err := giteaClient.GetTimelineReviewCommentIDForReview(ctx, owner, repoName, prNumber, oldReview.ID)
 			if err != nil {
@@ -509,11 +553,25 @@ func fetchFileContext(ctx context.Context, client *gitea.Client, owner, repo, re
 // patternsRepo is comma-separated list of owner/name repos.
 // patternsFiles is comma-separated list of file paths or directories.
 // If a path ends with / or is a directory, all files within it are fetched recursively.
+// If patternsFiles is empty, all files from the repo root are fetched.
 func fetchPatterns(ctx context.Context, client *gitea.Client, patternsRepo, patternsFiles string) string {
 	var sb strings.Builder
 
 	repos := strings.Split(patternsRepo, ",")
-	paths := strings.Split(patternsFiles, ",")
+
+	// Build the list of paths to fetch
+	var paths []string
+	if patternsFiles == "" {
+		// Empty patternsFiles means "fetch all files from repo root"
+		paths = []string{""}
+	} else {
+		for _, p := range strings.Split(patternsFiles, ",") {
+			p = strings.TrimSpace(p)
+			if p != "" {
+				paths = append(paths, p)
+			}
+		}
+	}
 
 	for _, repoRef := range repos {
 		if ctx.Err() != nil {
@@ -530,12 +588,10 @@ func fetchPatterns(ctx context.Context, client *gitea.Client, patternsRepo, patt
 		}
 		owner, repo := parts[0], parts[1]
 
-		for _, path := range paths {
-			path = strings.TrimSpace(path)
-			if path == "" {
-				continue
-			}
+		var repoLoadedFiles []string
+		var repoSkippedFiles []string
 
+		for _, path := range paths {
 			files, err := client.GetAllFilesInPath(ctx, owner, repo, path)
 			if err != nil {
 				slog.Warn("could not fetch patterns", "path", path, "repo", repoRef, "error", err)
@@ -545,11 +601,22 @@ func fetchPatterns(ctx context.Context, client *gitea.Client, patternsRepo, patt
 			for filePath, content := range files {
 				// Only include markdown and text files as patterns
 				if !isPatternFile(filePath) {
+					repoSkippedFiles = append(repoSkippedFiles, filePath)
 					continue
 				}
+				repoLoadedFiles = append(repoLoadedFiles, filePath)
 				sb.WriteString(fmt.Sprintf("### %s/%s\n\n%s\n\n", repoRef, filePath, content))
 			}
 		}
+
+		if len(repoLoadedFiles) > 0 {
+			slog.Info("loaded pattern files", "repo", repoRef, "count", len(repoLoadedFiles), "files", repoLoadedFiles)
+		} else {
+			slog.Warn("no pattern files loaded", "repo", repoRef, "paths", paths)
+		}
+		if len(repoSkippedFiles) > 0 {
+			slog.Debug("skipped non-pattern files", "repo", repoRef, "count", len(repoSkippedFiles), "files", repoSkippedFiles)
+		}
 	}
 	return sb.String()
 }
@@ -783,3 +850,32 @@ func shouldSkipStaleReview(evaluatedSHA, currentSHA string) bool {
 	}
 	return evaluatedSHA != currentSHA
 }
+
+// giteaClientAdapter adapts gitea.Client to review.GiteaClient interface.
+type giteaClientAdapter struct {
+	client *gitea.Client
+}
+
+func newGiteaClientAdapter(c *gitea.Client) *giteaClientAdapter {
+	return &giteaClientAdapter{client: c}
+}
+
+func (a *giteaClientAdapter) ListContents(ctx context.Context, owner, repo, path string) ([]review.ContentEntry, error) {
+	entries, err := a.client.ListContents(ctx, owner, repo, path)
+	if err != nil {
+		return nil, err
+	}
+	result := make([]review.ContentEntry, len(entries))
+	for i, e := range entries {
+		result[i] = review.ContentEntry{
+			Name: e.Name,
+			Path: e.Path,
+			Type: e.Type,
+		}
+	}
+	return result, nil
+}
+
+func (a *giteaClientAdapter) GetFileContent(ctx context.Context, owner, repo, filepath string) (string, error) {
+	return a.client.GetFileContent(ctx, owner, repo, filepath)
+}

cmd/review-bot/main_test.go

@@ -504,6 +504,52 @@ func TestIsPatternFile(t *testing.T) {
 	}
 }
 
+// TestBuildPatternPaths verifies the path-building logic for fetchPatterns.
+// Empty patternsFiles means "fetch all from root" (represented as [""]).
+func TestBuildPatternPaths(t *testing.T) {
+	buildPaths := func(patternsFiles string) []string {
+		if patternsFiles == "" {
+			return []string{""}
+		}
+		var paths []string
+		for _, p := range strings.Split(patternsFiles, ",") {
+			p = strings.TrimSpace(p)
+			if p != "" {
+				paths = append(paths, p)
+			}
+		}
+		return paths
+	}
+
+	tests := []struct {
+		name  string
+		input string
+		want  []string
+	}{
+		{"empty fetches root", "", []string{""}},
+		{"single file", "README.md", []string{"README.md"}},
+		{"multiple files", "README.md,PATTERNS.md", []string{"README.md", "PATTERNS.md"}},
+		{"trims whitespace", " foo.md , bar.md ", []string{"foo.md", "bar.md"}},
+		{"skips empty between commas", "foo.md,,bar.md", []string{"foo.md", "bar.md"}},
+		{"directory path", "patterns/", []string{"patterns/"}},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := buildPaths(tc.input)
+			if len(got) != len(tc.want) {
+				t.Errorf("buildPaths(%q) = %v, want %v", tc.input, got, tc.want)
+				return
+			}
+			for i := range got {
+				if got[i] != tc.want[i] {
+					t.Errorf("buildPaths(%q)[%d] = %q, want %q", tc.input, i, got[i], tc.want[i])
+				}
+			}
+		})
+	}
+}
+
 func TestEvaluateCIStatus(t *testing.T) {
 	tests := []struct {
 		name       string

cmd/review-bot/validateurl.go

@@ -0,0 +1,125 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"net/url"
+	"strings"
+	"time"
+
+	"gitea.weiker.me/rodin/review-bot/gitea"
+)
+
+// runValidateURL implements the `review-bot validate-url <url>` subcommand.
+//
+// It resolves the given URL's hostname and checks that every returned IP is
+// publicly routable (not RFC1918, loopback, link-local, or other reserved
+// ranges). The exit code communicates the result to callers:
+//
+//	0 — URL is safe to use
+//	1 — URL resolves to a blocked/private address
+//	2 — URL is malformed, has an unsafe scheme, or DNS lookup failed
+//
+// This is intended for use from action.yml shell steps that need to validate
+// a user-supplied URL before passing it to curl.
+func runValidateURL(args []string) int {
+	if len(args) != 1 {
+		fmt.Fprintln(errWriter, "usage: review-bot validate-url <url>")
+		fmt.Fprintln(errWriter, "")
+		fmt.Fprintln(errWriter, "Resolves <url> and verifies all resolved IPs are publicly routable.")
+		fmt.Fprintln(errWriter, "Exit 0=safe, 1=blocked, 2=error")
+		return 2
+	}
+	rawURL := args[0]
+
+	if err := validateURL(rawURL); err != nil {
+		fmt.Fprintf(errWriter, "Error: %v\n", err)
+		var ve *validateError
+		if isValidateError(err, &ve) {
+			return ve.code
+		}
+		return 2
+	}
+	fmt.Fprintf(outWriter, "OK: %s is safe\n", rawURL)
+	return 0
+}
+
+// validateError carries an exit code alongside a message.
+type validateError struct {
+	code    int
+	message string
+}
+
+func (e *validateError) Error() string { return e.message }
+
+// isValidateError checks if err is or wraps a *validateError and sets out.
+// Uses errors.As so that wrapped *validateError values (e.g. from fmt.Errorf("...: %w", &validateError{...}))
+// are also detected, making the function robust against future wrapping.
+func isValidateError(err error, out **validateError) bool {
+	if err == nil {
+		return false
+	}
+	return errors.As(err, out)
+}
+
+// validateURL checks that rawURL is safe for use as a Gitea server URL:
+//   - Must be https:// (not http://)
+//   - Must have no user-info (user:pass@host)
+//   - Must resolve to at least one IP, all of which are publicly routable
+func validateURL(rawURL string) error {
+	parsed, err := url.Parse(rawURL)
+	if err != nil {
+		return &validateError{code: 2, message: fmt.Sprintf("malformed URL %q: %v", rawURL, err)}
+	}
+
+	// Scheme check: only https is permitted.
+	if !strings.EqualFold(parsed.Scheme, "https") {
+		return &validateError{
+			code:    2,
+			message: fmt.Sprintf("URL scheme must be https (got %q)", parsed.Scheme),
+		}
+	}
+
+	// Reject user-info (user:password@host) to prevent credential embedding.
+	if parsed.User != nil {
+		return &validateError{
+			code:    2,
+			message: "URL must not contain user-info (user:password@host)",
+		}
+	}
+
+	host := parsed.Hostname()
+	if host == "" {
+		return &validateError{code: 2, message: fmt.Sprintf("URL has no host: %q", rawURL)}
+	}
+
+	// Resolve the hostname with a short timeout.
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	addrs, err := net.DefaultResolver.LookupIPAddr(ctx, host)
+	if err != nil {
+		return &validateError{
+			code:    2,
+			message: fmt.Sprintf("DNS lookup failed for %q: %v", host, err),
+		}
+	}
+	if len(addrs) == 0 {
+		return &validateError{
+			code:    2,
+			message: fmt.Sprintf("DNS lookup returned no addresses for %q", host),
+		}
+	}
+
+	for _, a := range addrs {
+		if gitea.IsBlockedIP(a.IP) {
+			return &validateError{
+				code:    1,
+				message: fmt.Sprintf("blocked: %q resolves to private/reserved IP %s", host, a.IP),
+			}
+		}
+	}
+	return nil
+}

cmd/review-bot/validateurl_test.go

@@ -0,0 +1,127 @@
+package main
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+func TestRunValidateURL_Usage(t *testing.T) {
+	var errBuf bytes.Buffer
+	origErr := errWriter
+	errWriter = &errBuf
+	defer func() { errWriter = origErr }()
+
+	code := runValidateURL(nil)
+	if code != 2 {
+		t.Errorf("expected exit code 2 for no args, got %d", code)
+	}
+	if !strings.Contains(errBuf.String(), "usage") {
+		t.Errorf("expected usage in stderr, got %q", errBuf.String())
+	}
+
+	errBuf.Reset()
+	code = runValidateURL([]string{"arg1", "arg2"})
+	if code != 2 {
+		t.Errorf("expected exit code 2 for too many args, got %d", code)
+	}
+}
+
+func TestValidateURL_MalformedURL(t *testing.T) {
+	cases := []struct {
+		name    string
+		url     string
+		wantMsg string
+	}{
+		{"empty", "", "must be https"},
+		{"http scheme", "http://example.com/", "must be https"},
+		{"ftp scheme", "ftp://example.com/", "must be https"},
+		{"no scheme", "example.com", "must be https"},
+		{"user info", "https://user:pass@example.com/", "user-info"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validateURL(tc.url)
+			if err == nil {
+				t.Errorf("expected error for URL %q, got nil", tc.url)
+				return
+			}
+			if !strings.Contains(err.Error(), tc.wantMsg) {
+				t.Errorf("error %q does not contain %q", err.Error(), tc.wantMsg)
+			}
+			var ve *validateError
+			if !isValidateError(err, &ve) {
+				t.Fatalf("expected *validateError, got %T", err)
+			}
+			if ve.code != 2 {
+				t.Errorf("expected code 2, got %d", ve.code)
+			}
+		})
+	}
+}
+
+func TestValidateURL_BlockedPrivateIP(t *testing.T) {
+	// localhost always resolves to 127.0.0.1 (loopback).
+	err := validateURL("https://localhost/")
+	if err == nil {
+		t.Skip("localhost did not resolve (network unavailable in test environment)")
+	}
+	var ve *validateError
+	if !isValidateError(err, &ve) {
+		t.Fatalf("expected *validateError, got %T: %v", err, err)
+	}
+	if ve.code != 1 && ve.code != 2 {
+		t.Errorf("expected code 1 (blocked) or 2 (dns fail), got %d: %s", ve.code, ve.message)
+	}
+	// If it resolved (code 1), the message must say "blocked".
+	if ve.code == 1 && !strings.Contains(ve.message, "blocked") {
+		t.Errorf("expected 'blocked' in message, got %q", ve.message)
+	}
+}
+
+func TestValidateURL_ExitCodes(t *testing.T) {
+	cases := []struct {
+		name     string
+		url      string
+		wantCode int
+	}{
+		{"http scheme", "http://example.com/", 2},
+		{"no scheme", "example.com", 2},
+		{"user info", "https://admin:secret@example.com/", 2},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validateURL(tc.url)
+			if err == nil {
+				t.Fatalf("expected error for %q", tc.url)
+			}
+			var ve *validateError
+			if !isValidateError(err, &ve) {
+				t.Fatalf("expected *validateError, got %T", err)
+			}
+			if ve.code != tc.wantCode {
+				t.Errorf("code = %d, want %d (url=%q, msg=%s)", ve.code, tc.wantCode, tc.url, ve.message)
+			}
+		})
+	}
+}
+
+func TestRunValidateURL_WithCapture(t *testing.T) {
+	var outBuf, errBuf bytes.Buffer
+	origOut, origErr := outWriter, errWriter
+	outWriter = &outBuf
+	errWriter = &errBuf
+	defer func() {
+		outWriter = origOut
+		errWriter = origErr
+	}()
+
+	// http:// scheme should fail with code 2.
+	code := runValidateURL([]string{"http://example.com/"})
+	if code != 2 {
+		t.Errorf("expected code 2 for http:// URL, got %d", code)
+	}
+	if !strings.Contains(errBuf.String(), "must be https") {
+		t.Errorf("expected error about https in stderr, got %q", errBuf.String())
+	}
+}

docs/DESIGN-57-yaml-persona.md

@@ -0,0 +1,87 @@
+# Design: YAML Support for Persona Files (#57)
+
+## Problem
+
+JSON is awkward for persona files that contain multi-line text (identity, severity descriptions). YAML supports cleaner multi-line strings and comments, improving readability and maintainability.
+
+## Constraints
+
+- Backwards compatibility: existing JSON personas must continue to work
+- Security: protect against DoS via deeply nested YAML (AIKIDO-2024-10486)
+- Consistency: use `.yaml` extension (not `.yml`)
+- Library: use `github.com/goccy/go-yaml` v1.16.0+ (approved in CONVENTIONS.md); we implement custom AST-based depth/node-count checks for precise alias-aware validation
+
+## Proposed Approach
+
+1. **Update `parsePersona`** to detect format from file extension
+2. **Add YAML parsing** with explicit depth limit (defense in depth)
+3. **Keep JSON as fallback** for files without `.yaml`/`.yml` extension
+4. **Convert built-in personas** to YAML format
+5. **Update embed directive** to include both formats
+
+### File Extension Detection
+
+```go
+func parsePersona(data []byte, source string) (*Persona, error) {
+    isYAML := strings.HasSuffix(source, ".yaml") || strings.HasSuffix(source, ".yml")
+    if isYAML {
+        return parseYAML(data, source)
+    }
+    return parseJSON(data, source)
+}
+```
+
+### YAML Parsing with Depth Protection
+
+We implement a custom AST-based depth/node-count walk (`checkYAMLDepth` in
+`review/persona.go`) rather than relying on library decoder options. Key design
+decisions:
+
+- **Library:** `github.com/goccy/go-yaml` with `ast.Node`-based traversal
+- **Dual-map tracking:** `validated` (depth-aware short-circuit) + `visiting` (cycle detection)
+- **Node-count limit:** Conservative overcounting bounds total validation work
+- **Alias-aware depth:** Aliases increment depth and are re-checked when encountered at greater depths
+
+See `review/persona.go:checkYAMLDepth` for the authoritative implementation.
+
+## State/Data Model
+
+No new state. Same `Persona` struct, just different parsing.
+
+## Error Cases
+
+| Error | Handling |
+|-------|----------|
+| Invalid YAML syntax | Return parse error with source file |
+| Deeply nested YAML | Custom AST walk (`checkYAMLDepth`) rejects before decode |
+| Unknown extension | Fall back to JSON parsing |
+| Missing required fields | Validation rejects after parse |
+
+## Edge Cases
+
+- File with `.json` extension but YAML content → JSON parse fails, user sees error
+- File with no extension → defaults to JSON
+- Embedded persona reference like `builtin:security` → detect by embed path (`personas/X.yaml`)
+
+## Testing Strategy
+
+1. Unit tests for YAML parsing (valid, invalid, deeply nested)
+2. Unit tests for extension detection
+3. Integration test for built-in personas (now YAML)
+4. Backwards compat test: verify JSON still works for external files
+
+## Completion Checklist
+
+1. [ ] `go-yaml` dependency added at v1.16.0+
+2. [ ] Extension detection uses case-insensitive comparison
+3. [ ] YAML parse errors include source file name
+4. [ ] JSON parsing still works for `.json` files
+5. [ ] Built-in personas converted to YAML with readable multi-line strings
+6. [ ] Embed directive updated to include `*.yaml`
+7. [ ] Test for deeply nested YAML rejection
+8. [ ] All existing tests pass
+
+## Open Questions
+
+- Should we support both `.yaml` AND `.yml`? Issue says `.yaml` only for consistency, but some users expect `.yml`. **Decision:** Support both for reading, recommend `.yaml` in docs.
+- Should we add a "format" field to detect mismatched extension/content? **Decision:** No, keep it simple. Extension determines format.

gitea/client.go

@@ -11,9 +11,12 @@ import (
 	"fmt"
 	"io"
 	"log/slog"
+	"math"
+	"net"
 	"net/http"
 	"net/url"
 	"strings"
+	"syscall"
 	"time"
 )
 
@@ -39,23 +42,181 @@ func IsNotFound(err error) bool {
 	return errors.As(err, &apiErr) && apiErr.StatusCode == http.StatusNotFound
 }
 
+// IsServerError reports whether an error is an API 5xx response.
+func IsServerError(err error) bool {
+	var apiErr *APIError
+	return errors.As(err, &apiErr) && apiErr.StatusCode >= 500 && apiErr.StatusCode < 600
+}
+
+// DefaultMaxDiffSize is the default maximum diff size in bytes (10 MB).
+const DefaultMaxDiffSize = 10 * 1024 * 1024
+
+// ErrDiffTooLarge is returned when a PR diff exceeds the configured MaxDiffSize.
+var ErrDiffTooLarge = errors.New("diff size exceeds maximum allowed size")
+
 // Client interacts with the Gitea API.
 // A Client is safe for concurrent use by multiple goroutines.
 type Client struct {
 	baseURL string
 	token   string
 	http    *http.Client
+
+	// RetryBackoff defines the delays between retry attempts.
+	// RetryBackoff[i] is the delay before attempt i+1 (after attempt i fails).
+	// If nil, defaults to {1s, 2s}. Set to shorter durations in tests.
+	//
+	// This field must be configured before the first request is made.
+	// Modifying it while requests are in flight is not safe.
+	RetryBackoff []time.Duration
+
+	// MaxDiffSize is the maximum number of bytes allowed when fetching a PR diff.
+	// If zero, defaults to DefaultMaxDiffSize (10 MB). Set to any negative value
+	// (or math.MaxInt64) to disable the limit.
+	//
+	// This field must be configured before the first request is made.
+	// Modifying it while requests are in flight is not safe.
+	MaxDiffSize int64
+}
+
+// defaultCheckRedirect is the redirect policy used by NewClient.
+// NOTE: This function is intentionally duplicated in github/client.go (and vice versa)
+// because the packages are separate. Changes here must be mirrored there.
+// It rejects HTTPS->HTTP protocol downgrades (to prevent plaintext leakage)
+// and cross-host redirects (to prevent following responses from untrusted
+// endpoints). Same-host, same-or-upgraded-scheme redirects are allowed.
+func defaultCheckRedirect(req *http.Request, via []*http.Request) error {
+	if len(via) >= 10 {
+		return fmt.Errorf("stopped after 10 redirects")
+	}
+	// Guard for direct invocation in tests and any future callers;
+	// net/http guarantees len(via) >= 1 during actual redirects.
+	if len(via) == 0 {
+		return nil
+	}
+	prev := via[len(via)-1]
+	// Reject protocol downgrade: HTTPS->HTTP leaks request metadata over plaintext.
+	if prev.URL.Scheme == "https" && req.URL.Scheme == "http" {
+		return fmt.Errorf("refusing redirect: HTTPS to HTTP downgrade (%s -> %s)", prev.URL.Host, req.URL.Host)
+	}
+	// Reject cross-host redirect entirely to avoid consuming responses
+	// from untrusted endpoints.
+	if req.URL.Host != prev.URL.Host {
+		return fmt.Errorf("refusing redirect: cross-host (%s -> %s)", prev.URL.Host, req.URL.Host)
+	}
+	return nil
+}
+
+// safeDialContext is the default DialContext for NewClient.
+// It resolves the hostname and checks every returned IP against the blocked
+// CIDR list before establishing a connection. This prevents SSRF attacks
+// where user-supplied URLs resolve to internal/private addresses.
+//
+// After validating all IPs, we dial the first resolved IP directly to avoid
+// a second DNS lookup (which could return a different IP in a DNS rebinding
+// attack). This narrows — but does not fully eliminate — the DNS rebinding
+// window to the time between LookupIPAddr and DialContext.
+//
+// If the host is already an IP literal, LookupIPAddr returns it directly
+// (no DNS query issued), so IP literals like https://127.0.0.1/ are blocked.
+func safeDialContext(ctx context.Context, network, addr string) (net.Conn, error) {
+	host, port, err := net.SplitHostPort(addr)
+	if err != nil {
+		return nil, fmt.Errorf("safeDialContext: invalid address %q: %w", addr, err)
+	}
+	addrs, err := net.DefaultResolver.LookupIPAddr(ctx, host)
+	if err != nil {
+		return nil, fmt.Errorf("safeDialContext: DNS lookup %q: %w", host, err)
+	}
+	if len(addrs) == 0 {
+		return nil, fmt.Errorf("safeDialContext: no addresses returned for %q", host)
+	}
+	for _, a := range addrs {
+		if IsBlockedIP(a.IP) {
+			return nil, fmt.Errorf("safeDialContext: blocked: %q resolves to private/reserved IP %s", host, a.IP)
+		}
+	}
+	// Try each resolved IP in order, returning the first successful connection.
+	// Fallback is important when a hostname resolves to multiple IPs and the first
+	// is temporarily unreachable. All IPs were already validated above, so dialing
+	// any of them is safe.
+	//
+	// Timeout: 10s per the design (PLAN.md); the outer http.Client has a 30s
+	// total timeout, but the per-dial timeout ensures a slow TCP connect on one IP
+	// doesn't consume the budget needed to try others.
+	d := &net.Dialer{Timeout: 10 * time.Second}
+	var lastErr error
+	for _, a := range addrs {
+		conn, err := d.DialContext(ctx, network, net.JoinHostPort(a.IP.String(), port))
+		if err == nil {
+			return conn, nil
+		}
+		lastErr = err
+	}
+	return nil, fmt.Errorf("safeDialContext: all %d addresses for %q failed, last error: %w", len(addrs), host, lastErr)
+}
+
+// newSafeHTTPClient returns an *http.Client with the SSRF-blocking safeDialContext
+// transport and the cross-host redirect rejection policy.
+//
+// We clone http.DefaultTransport to preserve its production-ready defaults
+// (ProxyFromEnvironment, TLSHandshakeTimeout, IdleConnTimeout, connection
+// pooling, HTTP/2 support) and override only DialContext with safeDialContext.
+func newSafeHTTPClient() *http.Client {
+	transport := http.DefaultTransport.(*http.Transport).Clone()
+	transport.DialContext = safeDialContext
+	return &http.Client{
+		Timeout:       30 * time.Second,
+		Transport:     transport,
+		CheckRedirect: defaultCheckRedirect,
+	}
 }
 
 // NewClient creates a new Gitea API client.
+//
+// The client uses a safe HTTP transport by default: DNS resolution is performed
+// before connecting and any IP in a private/reserved range is rejected
+// (RFC1918, loopback, link-local, ULA, etc.). Cross-host and HTTPS→HTTP
+// redirects are also rejected.
+//
+// For tests that use httptest.NewServer (which listens on 127.0.0.1), call
+// WithUnsafeDialer() to bypass the IP check.
 func NewClient(baseURL, token string) *Client {
 	return &Client{
 		baseURL: strings.TrimRight(baseURL, "/"),
 		token:   token,
-		http:    &http.Client{Timeout: 30 * time.Second},
+		http:    newSafeHTTPClient(),
 	}
 }
 
+// WithUnsafeDialer returns the client configured with a plain HTTP client that
+// has no IP-level SSRF protection. It preserves the redirect-rejection policy.
+//
+// This MUST only be used in tests. Production code must never call this method.
+func (c *Client) WithUnsafeDialer() *Client {
+	c.http = &http.Client{
+		Timeout:       30 * time.Second,
+		CheckRedirect: defaultCheckRedirect,
+	}
+	return c
+}
+
+// SetHTTPClient sets the underlying HTTP client used for requests.
+// This is intended for test setup only to inject mock transports; it must be
+// called before any goroutines issue requests.
+//
+// Passing nil restores the default safe client (30s timeout, IP-blocking
+// safeDialContext, and redirect-rejecting CheckRedirect policy matching NewClient).
+//
+// Callers providing a non-nil client are responsible for configuring a safe
+// CheckRedirect policy. Without one, the default net/http behavior will follow
+// redirects and may forward the Authorization header to untrusted hosts.
+func (c *Client) SetHTTPClient(hc *http.Client) {
+	if hc == nil {
+		hc = newSafeHTTPClient()
+	}
+	c.http = hc
+}
+
 // PullRequest holds relevant PR metadata.
 type PullRequest struct {
 	Title string `json:"title"`
@@ -103,9 +264,28 @@ func (c *Client) GetPullRequest(ctx context.Context, owner, repo string, number
 }
 
 // GetPullRequestDiff fetches the unified diff for a PR.
+// It enforces MaxDiffSize to prevent unbounded memory allocation.
+// Returns ErrDiffTooLarge if the diff exceeds the configured limit.
 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, url.PathEscape(owner), url.PathEscape(repo), number)
-	body, err := c.doGet(ctx, reqURL)
+
+	maxSize := c.MaxDiffSize
+	if maxSize == 0 {
+		maxSize = DefaultMaxDiffSize
+	}
+
+	// When the limit is disabled (negative) or set to math.MaxInt64 (which
+	// would overflow the +1 detection and silently disable enforcement),
+	// use the standard unlimited doGet path.
+	if maxSize < 0 || maxSize == math.MaxInt64 {
+		body, err := c.doGet(ctx, reqURL)
+		if err != nil {
+			return "", fmt.Errorf("fetch diff: %w", err)
+		}
+		return string(body), nil
+	}
+
+	body, err := c.doGetLimited(ctx, reqURL, maxSize)
 	if err != nil {
 		return "", fmt.Errorf("fetch diff: %w", err)
 	}
@@ -161,18 +341,22 @@ func (c *Client) GetFileContentRef(ctx context.Context, owner, repo, filepath, r
 }
 
 // PostReview submits a review to a PR and returns the created review.
-// event should be "APPROVED" or "REQUEST_CHANGES".
+// event should be one of "APPROVED", "REQUEST_CHANGES", or "COMMENT".
+// commitID anchors the review to a specific commit SHA. If empty, Gitea
+// defaults to the current PR head.
 // 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) {
+func (c *Client) PostReview(ctx context.Context, owner, repo string, number int, event, body, commitID 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"`
+		CommitID string          `json:"commit_id,omitempty"`
 		Comments []ReviewComment `json:"comments,omitempty"`
 	}{
 		Body:     body,
 		Event:    event,
+		CommitID: commitID,
 		Comments: comments,
 	}
 
@@ -210,24 +394,218 @@ func (c *Client) PostReview(ctx context.Context, owner, repo string, number int,
 	return &review, nil
 }
 
+// isTemporaryNetError reports whether err is a temporary network error worth retrying.
+// This includes connection refused, network unreachable, connection reset, and DNS
+// timeouts. It explicitly excludes permanent errors like permission denied or
+// "no such host" DNS failures.
+func isTemporaryNetError(err error) bool {
+	if err == nil {
+		return false
+	}
+
+	// Check for OpError and inspect the underlying syscall error.
+	// Not all OpErrors are transient — permission denied, for example, is permanent.
+	var opErr *net.OpError
+	if errors.As(err, &opErr) {
+		return isRetriableSyscallError(opErr.Err)
+	}
+
+	// DNS errors: only retry on timeout, not on "no such host" which is permanent.
+	var dnsErr *net.DNSError
+	if errors.As(err, &dnsErr) {
+		return dnsErr.IsTimeout
+	}
+
+	// Check for net.Error with Timeout() (Temporary is deprecated)
+	var netErr net.Error
+	if errors.As(err, &netErr) {
+		return netErr.Timeout()
+	}
+
+	return false
+}
+
+// isRetriableSyscallError reports whether the underlying error from a net.OpError
+// is a transient syscall error worth retrying.
+func isRetriableSyscallError(err error) bool {
+	if err == nil {
+		return false
+	}
+
+	// Check for syscall.Errno directly or wrapped
+	var errno syscall.Errno
+	if errors.As(err, &errno) {
+		switch errno {
+		case syscall.ECONNREFUSED, // connection refused — server not listening
+			syscall.ECONNRESET,   // connection reset by peer
+			syscall.ENETUNREACH,  // network unreachable
+			syscall.EHOSTUNREACH, // host unreachable
+			syscall.ETIMEDOUT:    // connection timed out
+			return true
+		default:
+			// EACCES, EPERM, etc. are permanent — don't retry
+			return false
+		}
+	}
+
+	// If we can't identify the specific syscall error, be conservative and retry.
+	// This handles wrapped errors or platform-specific error types.
+	// The retry count is limited, so erring on the side of retrying is safe.
+	return true
+}
+
+// redactURL strips query parameters and userinfo credentials from a URL for
+// safe logging. This prevents accidental exposure of sensitive data (tokens in
+// query strings, or user:pass in the authority) in log output.
+func redactURL(rawURL string) string {
+	parsed, err := url.Parse(rawURL)
+	if err != nil {
+		// If we cannot parse it, return a safe placeholder rather than
+		// potentially logging something sensitive.
+		return "[invalid URL]"
+	}
+	if parsed.User != nil {
+		parsed.User = url.User("REDACTED")
+	}
+	if parsed.RawQuery != "" {
+		parsed.RawQuery = "[redacted]"
+	}
+	return parsed.String()
+}
+
+// sanitizeErrorForLog returns a loggable version of an error that omits
+// potentially sensitive content like response bodies. For APIError, only
+// the status code is included; for other errors, the type is preserved.
+func sanitizeErrorForLog(err error) string {
+	if err == nil {
+		return "<nil>"
+	}
+	var apiErr *APIError
+	if errors.As(err, &apiErr) {
+		return fmt.Sprintf("HTTP %d", apiErr.StatusCode)
+	}
+	return err.Error()
+}
+
+// doGetWithReader performs an HTTP GET request with retry on 5xx errors and
+// temporary network errors. Retries up to 3 times with exponential backoff
+// (1s, 2s delays by default; configurable via Client.RetryBackoff for testing).
+// The readBody function is called with the response body on success (2xx) and
+// is responsible for reading and closing it.
+func (c *Client) doGetWithReader(ctx context.Context, reqURL string, readBody func(io.ReadCloser) ([]byte, error)) ([]byte, error) {
+	const maxAttempts = 3
+	// backoff[i] is the delay before attempt i+1 (i.e., after attempt i fails).
+	// First attempt (i=0) has no delay; retries wait 1s then 2s by default.
+	backoff := c.RetryBackoff
+	if backoff == nil {
+		backoff = []time.Duration{1 * time.Second, 2 * time.Second}
+	}
+
+	// maxErrorBodyBytes limits how much of an error response body we read
+	// to protect against malicious servers sending unbounded data.
+	const maxErrorBodyBytes = 64 * 1024 // 64 KB
+
+	var lastErr error
+	for attempt := 0; attempt < maxAttempts; attempt++ {
+		if attempt > 0 {
+			// Determine delay: use backoff slice if available, otherwise retry immediately.
+			// An empty RetryBackoff slice means "retry without delay" — this is intentional
+			// as the caller explicitly configured no delays.
+			var delay time.Duration
+			if attempt-1 < len(backoff) {
+				delay = backoff[attempt-1]
+			}
+
+			if delay > 0 {
+				slog.Warn("retrying request after error",
+					"attempt", attempt+1,
+					"url", redactURL(reqURL),
+					"delay", delay.String(),
+					"lastError", sanitizeErrorForLog(lastErr))
+
+				timer := time.NewTimer(delay)
+				select {
+				case <-timer.C:
+				case <-ctx.Done():
+					timer.Stop()
+					return nil, ctx.Err()
+				}
+			}
+		}
+
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, reqURL, nil)
+		if err != nil {
+			return nil, err
+		}
+		req.Header.Set("Authorization", "token "+c.token)
+
+		resp, err := c.http.Do(req)
+		if err != nil {
+			// Always capture the error for consistent return at loop end.
+			// This ensures both network errors and HTTP 5xx return lastErr.
+			lastErr = err
+
+			// Only retry temporary network errors when attempts remain.
+			if attempt < maxAttempts-1 && isTemporaryNetError(err) {
+				slog.Warn("temporary network error, will retry",
+					"attempt", attempt+1,
+					"url", redactURL(reqURL),
+					"error", err)
+				continue
+			}
+			// Non-retryable network error or final attempt exhausted.
+			return nil, lastErr
+		}
+		if resp.StatusCode >= 200 && resp.StatusCode < 300 {
+			return readBody(resp.Body)
+		}
+
+		// Error path: limit how much we read from potentially malicious server
+		errBody, _ := io.ReadAll(io.LimitReader(resp.Body, maxErrorBodyBytes))
+		resp.Body.Close()
+
+		lastErr = &APIError{StatusCode: resp.StatusCode, Body: string(errBody)}
+
+		// Only retry on 5xx server errors
+		if resp.StatusCode < 500 || resp.StatusCode >= 600 {
+			return nil, lastErr
+		}
+	}
+
+	return nil, lastErr
+}
+
+// doGet performs an HTTP GET request with retry, reading the full response body.
 func (c *Client) doGet(ctx context.Context, reqURL string) ([]byte, error) {
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, reqURL, nil)
-	if err != nil {
-		return nil, err
-	}
-	req.Header.Set("Authorization", "token "+c.token)
+	return c.doGetWithReader(ctx, reqURL, func(body io.ReadCloser) ([]byte, error) {
+		defer body.Close()
+		return io.ReadAll(body)
+	})
+}
 
-	resp, err := c.http.Do(req)
-	if err != nil {
-		return nil, err
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		body, _ := io.ReadAll(resp.Body)
-		return nil, &APIError{StatusCode: resp.StatusCode, Body: string(body)}
-	}
-	return io.ReadAll(resp.Body)
+// doGetLimited performs an HTTP GET request with retry but enforces a maximum
+// response body size. Returns ErrDiffTooLarge if the response exceeds maxBytes.
+// It reads maxBytes+1 (clamped to avoid overflow) to detect truncation without
+// buffering the entire body.
+func (c *Client) doGetLimited(ctx context.Context, reqURL string, maxBytes int64) ([]byte, error) {
+	return c.doGetWithReader(ctx, reqURL, func(body io.ReadCloser) ([]byte, error) {
+		defer body.Close()
+		// Read up to maxBytes+1 to detect overflow.
+		// Clamp to prevent integer overflow when maxBytes == math.MaxInt64.
+		limitBytes := maxBytes + 1
+		if limitBytes <= 0 {
+			limitBytes = math.MaxInt64
+		}
+		limited := io.LimitReader(body, limitBytes)
+		data, err := io.ReadAll(limited)
+		if err != nil {
+			return nil, err
+		}
+		if int64(len(data)) > maxBytes {
+			return nil, fmt.Errorf("%w: response exceeds %d bytes", ErrDiffTooLarge, maxBytes)
+		}
+		return data, nil
+	})
 }
 
 // escapePath escapes each segment of a relative file path for use in URLs.
@@ -251,7 +629,13 @@ type ContentEntry struct {
 
 // ListContents lists files and directories at a given path in a repo.
 // Pass an empty path to list the repository root.
+// If the path points to a file (not a directory), Gitea returns a single
+// object instead of an array; this method normalizes both cases to a slice.
 func (c *Client) ListContents(ctx context.Context, owner, repo, path string) ([]ContentEntry, error) {
+	// Normalize "." to empty string — Gitea API rejects "." with 500
+	if path == "." {
+		path = ""
+	}
 	var reqURL string
 	if path == "" {
 		reqURL = fmt.Sprintf("%s/api/v1/repos/%s/%s/contents", c.baseURL, url.PathEscape(owner), url.PathEscape(repo))
@@ -264,7 +648,16 @@ func (c *Client) ListContents(ctx context.Context, owner, repo, path string) ([]
 	}
 	var entries []ContentEntry
 	if err := json.Unmarshal(body, &entries); err != nil {
-		return nil, fmt.Errorf("parse contents JSON: %w", err)
+		// Gitea returns a single object (not an array) when path is a file
+		var single ContentEntry
+		if err2 := json.Unmarshal(body, &single); err2 != nil {
+			return nil, fmt.Errorf("parse contents JSON: %w", err)
+		}
+		// Guard against empty/malformed responses
+		if single.Name == "" && single.Path == "" {
+			return nil, fmt.Errorf("parse contents JSON: empty response for path %q", path)
+		}
+		entries = []ContentEntry{single}
 	}
 	return entries, nil
 }
@@ -317,9 +710,9 @@ func (c *Client) GetAllFilesInPath(ctx context.Context, owner, repo, path string
 
 // Review represents a pull request review from the Gitea API.
 type Review struct {
-	ID       int64  `json:"id"`
-	Body     string `json:"body"`
-	User     struct {
+	ID   int64  `json:"id"`
+	Body string `json:"body"`
+	User struct {
 		Login string `json:"login"`
 	} `json:"user"`
 	State    string `json:"state"`

gitea/client_test.go

@@ -6,10 +6,15 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"net"
 	"net/http"
 	"net/http/httptest"
+	"net/url"
 	"strings"
+	"sync/atomic"
+	"syscall"
 	"testing"
+	"time"
 )
 
 func TestGetPullRequest(t *testing.T) {
@@ -31,7 +36,7 @@ func TestGetPullRequest(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	got, err := client.GetPullRequest(context.Background(), "owner", "repo", 1)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -58,7 +63,7 @@ func TestGetPullRequestDiff(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	got, err := client.GetPullRequestDiff(context.Background(), "owner", "repo", 5)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -83,7 +88,7 @@ func TestGetCommitStatuses(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	got, err := client.GetCommitStatuses(context.Background(), "owner", "repo", "abc123")
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -112,8 +117,9 @@ func TestPostReview(t *testing.T) {
 		}
 
 		var payload struct {
-			Body  string `json:"body"`
-			Event string `json:"event"`
+			Body     string `json:"body"`
+			Event    string `json:"event"`
+			CommitID string `json:"commit_id"`
 		}
 		if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
 			t.Fatalf("failed to decode payload: %v", err)
@@ -124,14 +130,16 @@ func TestPostReview(t *testing.T) {
 		if payload.Event != "APPROVED" {
 			t.Errorf("expected event %q, got %q", "APPROVED", payload.Event)
 		}
-
+		if payload.CommitID != "abc123def" {
+			t.Errorf("expected commit_id %q, got %q", "abc123def", payload.CommitID)
+		}
 		w.WriteHeader(http.StatusOK)
 		w.Write([]byte(`{"id":100,"user":{"login":"review-bot"},"state":"APPROVED","stale":false}`))
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
-	review, err := client.PostReview(context.Background(), "owner", "repo", 3, "APPROVED", "LGTM", nil)
+	client := NewTestClient(server.URL, "test-token")
+	review, err := client.PostReview(context.Background(), "owner", "repo", 3, "APPROVED", "LGTM", "abc123def", nil)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -150,7 +158,7 @@ func TestGetPullRequest_Non200(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	_, err := client.GetPullRequest(context.Background(), "owner", "repo", 999)
 	if err == nil {
 		t.Fatal("expected error for 404, got nil")
@@ -163,7 +171,7 @@ func TestGetPullRequest_BadJSON(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	_, err := client.GetPullRequest(context.Background(), "owner", "repo", 1)
 	if err == nil {
 		t.Fatal("expected error for bad JSON, got nil")
@@ -177,13 +185,36 @@ 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", nil)
+	client := NewTestClient(server.URL, "test-token")
+	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "APPROVED", "test", "", nil)
 	if err == nil {
 		t.Fatal("expected error for 403, got nil")
 	}
 }
 
+func TestPostReview_EmptyCommitID_OmittedFromPayload(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, _ := io.ReadAll(r.Body)
+		var raw map[string]interface{}
+		if err := json.Unmarshal(body, &raw); err != nil {
+			t.Fatalf("failed to decode payload: %v", err)
+		}
+		if _, exists := raw["commit_id"]; exists {
+			t.Errorf("expected commit_id to be omitted from payload when empty, but it was present")
+		}
+
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"id":200,"user":{"login":"bot"},"state":"APPROVED","stale":false}`))
+	}))
+	defer server.Close()
+
+	client := NewTestClient(server.URL, "test-token")
+	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "APPROVED", "ok", "", nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
 func TestGetFileContent(t *testing.T) {
 	expected := "# Conventions\n- Be nice\n"
 
@@ -195,7 +226,7 @@ func TestGetFileContent(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	got, err := client.GetFileContent(context.Background(), "owner", "repo", "CONVENTIONS.md")
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -215,7 +246,7 @@ func TestGetPullRequestFiles(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	files, err := client.GetPullRequestFiles(context.Background(), "owner", "repo", 1)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -240,7 +271,7 @@ func TestGetFileContentRef(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	content, err := client.GetFileContentRef(context.Background(), "owner", "repo", "main.go", "feature-branch")
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -260,7 +291,7 @@ func TestListContents(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	entries, err := client.ListContents(context.Background(), "owner", "repo", "docs")
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -276,11 +307,64 @@ func TestListContents(t *testing.T) {
 	}
 }
 
+func TestListContents_DotPath(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// "." should be normalized to empty path, which hits the root contents endpoint
+		if r.URL.Path != "/api/v1/repos/owner/repo/contents" {
+			t.Errorf("expected root contents path, got: %s", r.URL.Path)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		fmt.Fprintf(w, `[{"name":"README.md","path":"README.md","type":"file"}]`)
+	}))
+	defer server.Close()
+
+	client := NewTestClient(server.URL, "test-token")
+	entries, err := client.ListContents(context.Background(), "owner", "repo", ".")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(entries) != 1 {
+		t.Fatalf("expected 1 entry, got %d", len(entries))
+	}
+	if entries[0].Name != "README.md" {
+		t.Errorf("expected README.md, got %s", entries[0].Name)
+	}
+}
+
+func TestListContents_FilePath(t *testing.T) {
+	// Gitea returns a single object (not an array) when path is a file
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/v1/repos/owner/repo/contents/README.md" {
+			t.Errorf("unexpected path: %s", r.URL.Path)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		// Single object, not an array
+		fmt.Fprintf(w, `{"name":"README.md","path":"README.md","type":"file"}`)
+	}))
+	defer server.Close()
+
+	client := NewTestClient(server.URL, "test-token")
+	entries, err := client.ListContents(context.Background(), "owner", "repo", "README.md")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(entries) != 1 {
+		t.Fatalf("expected 1 entry, got %d", len(entries))
+	}
+	if entries[0].Name != "README.md" {
+		t.Errorf("expected README.md, got %s", entries[0].Name)
+	}
+	if entries[0].Type != "file" {
+		t.Errorf("expected type file, got %s", entries[0].Type)
+	}
+}
+
 func TestGetAllFilesInPath_File(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path == "/api/v1/repos/owner/repo/contents/README.md" {
-			// Gitea returns 404 for contents API on files (it's not a dir)
-			http.NotFound(w, r)
+			// Gitea returns a single object (not array) when path is a file
+			w.Header().Set("Content-Type", "application/json")
+			fmt.Fprintf(w, `{"name":"README.md","path":"README.md","type":"file"}`)
 			return
 		}
 		if r.URL.Path == "/api/v1/repos/owner/repo/raw/README.md" {
@@ -291,7 +375,7 @@ func TestGetAllFilesInPath_File(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	files, err := client.GetAllFilesInPath(context.Background(), "owner", "repo", "README.md")
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -344,7 +428,7 @@ func TestListReviews(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	reviews, err := client.ListReviews(context.Background(), "owner", "repo", 5)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -384,7 +468,7 @@ func TestListReviews_Pagination(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	reviews, err := client.ListReviews(context.Background(), "owner", "repo", 5)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -409,7 +493,7 @@ func TestDeleteReview(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	err := client.DeleteReview(context.Background(), "owner", "repo", 5, 10)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -423,7 +507,7 @@ func TestDeleteReview_Forbidden(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	err := client.DeleteReview(context.Background(), "owner", "repo", 5, 10)
 	if err == nil {
 		t.Fatal("expected error for 403, got nil")
@@ -452,7 +536,7 @@ func TestEditComment(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	err := client.EditComment(context.Background(), "owner", "repo", 42, "updated body")
 	if err != nil {
 		t.Fatalf("EditComment() error = %v", err)
@@ -466,7 +550,7 @@ func TestEditComment_Forbidden(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	err := client.EditComment(context.Background(), "owner", "repo", 42, "new body")
 	if err == nil {
 		t.Fatal("expected error for 403 response")
@@ -486,7 +570,7 @@ func TestGetTimelineReviewCommentID(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(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)
@@ -502,7 +586,7 @@ func TestGetTimelineReviewCommentID_NotFound(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(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")
@@ -525,7 +609,7 @@ func TestGetAllFilesInPath_404FallsBackToFile(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	files, err := client.GetAllFilesInPath(context.Background(), "owner", "repo", "README.md")
 	if err != nil {
 		t.Fatalf("expected fallback to file on 404, got error: %v", err)
@@ -546,7 +630,7 @@ func TestGetAllFilesInPath_500Propagates(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	_, err := client.GetAllFilesInPath(context.Background(), "owner", "repo", "somepath")
 	if err == nil {
 		t.Fatal("expected error to propagate for 500, got nil")
@@ -568,7 +652,7 @@ func TestGetAllFilesInPath_403Propagates(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	_, err := client.GetAllFilesInPath(context.Background(), "owner", "repo", "private/stuff")
 	if err == nil {
 		t.Fatal("expected error to propagate for 403, got nil")
@@ -584,9 +668,9 @@ func TestGetAllFilesInPath_403Propagates(t *testing.T) {
 
 func TestIsNotFound(t *testing.T) {
 	tests := []struct {
-		name   string
-		err    error
-		want   bool
+		name string
+		err  error
+		want bool
 	}{
 		{"nil error", nil, false},
 		{"non-API error", fmt.Errorf("network timeout"), false},
@@ -620,7 +704,7 @@ func TestGetAuthenticatedUser(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	login, err := client.GetAuthenticatedUser(context.Background())
 	if err != nil {
 		t.Fatalf("GetAuthenticatedUser() error = %v", err)
@@ -645,7 +729,7 @@ func TestRequestReviewer(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	err := client.RequestReviewer(context.Background(), "owner", "repo", 7, "bot-user")
 	if err != nil {
 		t.Fatalf("RequestReviewer() error = %v", err)
@@ -661,7 +745,7 @@ func TestRequestReviewer_204(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	err := client.RequestReviewer(context.Background(), "owner", "repo", 1, "user")
 	if err != nil {
 		t.Fatalf("RequestReviewer() should accept 204, got error = %v", err)
@@ -675,7 +759,7 @@ func TestRequestReviewer_Error(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	err := client.RequestReviewer(context.Background(), "owner", "repo", 1, "user")
 	if err == nil {
 		t.Fatal("expected error for 403 response")
@@ -695,7 +779,7 @@ func TestListReviewComments(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	comments, err := client.ListReviewComments(context.Background(), "owner", "repo", 1, 42)
 	if err != nil {
 		t.Fatalf("ListReviewComments() error = %v", err)
@@ -723,7 +807,7 @@ func TestResolveComment(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	err := client.ResolveComment(context.Background(), "owner", "repo", 99)
 	if err != nil {
 		t.Fatalf("ResolveComment() error = %v", err)
@@ -737,9 +821,601 @@ func TestResolveComment_Error(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(server.URL, "test-token")
 	err := client.ResolveComment(context.Background(), "owner", "repo", 99)
 	if err == nil {
 		t.Fatal("expected error for 404 response")
 	}
 }
+
+func TestIsServerError(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{"nil error", nil, false},
+		{"non-API error", fmt.Errorf("network timeout"), false},
+		{"404 APIError", &APIError{StatusCode: 404, Body: "not found"}, false},
+		{"500 APIError", &APIError{StatusCode: 500, Body: "server error"}, true},
+		{"502 APIError", &APIError{StatusCode: 502, Body: "bad gateway"}, true},
+		{"503 APIError", &APIError{StatusCode: 503, Body: "unavailable"}, true},
+		{"599 APIError", &APIError{StatusCode: 599, Body: "edge case"}, true},
+		{"600 not server error", &APIError{StatusCode: 600, Body: "edge"}, false},
+		{"400 not server error", &APIError{StatusCode: 400, Body: "bad request"}, false},
+		{"wrapped 500", fmt.Errorf("fetch: %w", &APIError{StatusCode: 500, Body: "err"}), true},
+		{"wrapped 404", fmt.Errorf("fetch: %w", &APIError{StatusCode: 404, Body: "err"}), false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := IsServerError(tt.err)
+			if got != tt.want {
+				t.Errorf("IsServerError(%v) = %v, want %v", tt.err, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestDoGet_RetriesOn500(t *testing.T) {
+	attempts := 0
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		if attempts < 3 {
+			w.WriteHeader(http.StatusInternalServerError)
+			w.Write([]byte(`{"message":"transient error"}`))
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"data":"success"}`))
+	}))
+	defer server.Close()
+
+	client := NewTestClient(server.URL, "test-token")
+	// Use short backoff for fast tests
+	client.RetryBackoff = []time.Duration{1 * time.Millisecond, 1 * time.Millisecond}
+
+	body, err := client.doGet(context.Background(), server.URL+"/test")
+	if err != nil {
+		t.Fatalf("expected success after retry, got error: %v", err)
+	}
+	if string(body) != `{"data":"success"}` {
+		t.Errorf("body = %q, want %q", string(body), `{"data":"success"}`)
+	}
+	if attempts != 3 {
+		t.Errorf("attempts = %d, want 3", attempts)
+	}
+}
+
+func TestDoGet_FailsAfterMaxRetries(t *testing.T) {
+	attempts := 0
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		w.WriteHeader(http.StatusInternalServerError)
+		w.Write([]byte(`{"message":"persistent error"}`))
+	}))
+	defer server.Close()
+
+	client := NewTestClient(server.URL, "test-token")
+	// Use short backoff for fast tests
+	client.RetryBackoff = []time.Duration{1 * time.Millisecond, 1 * time.Millisecond}
+
+	_, err := client.doGet(context.Background(), server.URL+"/test")
+	if err == nil {
+		t.Fatal("expected error after max retries")
+	}
+	var apiErr *APIError
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("expected APIError, got: %v", err)
+	}
+	if apiErr.StatusCode != http.StatusInternalServerError {
+		t.Errorf("status = %d, want 500", apiErr.StatusCode)
+	}
+	if attempts != 3 {
+		t.Errorf("attempts = %d, want 3 (max retries)", attempts)
+	}
+}
+
+func TestDoGet_NoRetryOn4xx(t *testing.T) {
+	attempts := 0
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		w.WriteHeader(http.StatusForbidden)
+		w.Write([]byte(`{"message":"forbidden"}`))
+	}))
+	defer server.Close()
+
+	client := NewTestClient(server.URL, "test-token")
+	_, err := client.doGet(context.Background(), server.URL+"/test")
+	if err == nil {
+		t.Fatal("expected error for 403")
+	}
+	var apiErr *APIError
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("expected APIError, got: %v", err)
+	}
+	if apiErr.StatusCode != http.StatusForbidden {
+		t.Errorf("status = %d, want 403", apiErr.StatusCode)
+	}
+	if attempts != 1 {
+		t.Errorf("attempts = %d, want 1 (no retry on 4xx)", attempts)
+	}
+}
+
+func TestDoGet_RespectsContextCancellation(t *testing.T) {
+	attempts := 0
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		w.WriteHeader(http.StatusInternalServerError)
+		w.Write([]byte(`{"message":"error"}`))
+	}))
+	defer server.Close()
+
+	ctx, cancel := context.WithCancel(context.Background())
+
+	client := NewTestClient(server.URL, "test-token")
+	// Use longer backoff to give us time to cancel during the wait
+	client.RetryBackoff = []time.Duration{100 * time.Millisecond, 100 * time.Millisecond}
+
+	// Cancel after first attempt returns and retry begins
+	go func() {
+		time.Sleep(20 * time.Millisecond)
+		cancel()
+	}()
+
+	_, err := client.doGet(ctx, server.URL+"/test")
+	if err == nil {
+		t.Fatal("expected error on context cancellation")
+	}
+	// Should have made 1 attempt, then context cancelled during backoff
+	if attempts != 1 {
+		t.Errorf("attempts = %d, expected 1 before context cancel during backoff", attempts)
+	}
+}
+// mockTransport is a test helper that returns errors for the first N calls,
+// then delegates to a real server.
+type mockTransport struct {
+	failCount    int32 // number of failures remaining (atomic)
+	failErr      error // error to return on failure
+	realServer   *httptest.Server
+	attemptsMade atomic.Int32 // tracks total attempts
+}
+
+func (m *mockTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	m.attemptsMade.Add(1)
+	remaining := atomic.AddInt32(&m.failCount, -1)
+	if remaining >= 0 {
+		// Still have failures to return
+		return nil, m.failErr
+	}
+	// Redirect to real server
+	req.URL.Host = m.realServer.Listener.Addr().String()
+	req.URL.Scheme = "http"
+	return http.DefaultTransport.RoundTrip(req)
+}
+
+func TestDoGet_RetriesOnTemporaryNetError(t *testing.T) {
+	// Real server that will handle successful requests
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"status":"ok"}`))
+	}))
+	defer server.Close()
+
+	// Mock transport: fail twice with ECONNREFUSED, then succeed
+	mt := &mockTransport{
+		failCount:  2,
+		failErr:    &net.OpError{Op: "dial", Net: "tcp", Err: syscall.ECONNREFUSED},
+		realServer: server,
+	}
+
+	client := NewClient("http://fake-host/", "test-token")
+	client.SetHTTPClient(&http.Client{Transport: mt})
+	client.RetryBackoff = []time.Duration{1 * time.Millisecond, 1 * time.Millisecond}
+
+	body, err := client.doGet(context.Background(), "http://fake-host/test")
+	if err != nil {
+		t.Fatalf("expected success after retries, got error: %v", err)
+	}
+	if string(body) != `{"status":"ok"}` {
+		t.Errorf("body = %q, want %q", string(body), `{"status":"ok"}`)
+	}
+
+	// Should have made exactly 3 attempts: 2 failures + 1 success
+	if got := mt.attemptsMade.Load(); got != 3 {
+		t.Errorf("attempts = %d, want 3 (2 failures + 1 success)", got)
+	}
+}
+
+func TestIsTemporaryNetError(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{"nil error", nil, false},
+		{"plain error", fmt.Errorf("some error"), false},
+		// OpError with retriable syscall errors
+		{"OpError ECONNREFUSED", &net.OpError{Op: "dial", Err: syscall.ECONNREFUSED}, true},
+		{"OpError ECONNRESET", &net.OpError{Op: "read", Err: syscall.ECONNRESET}, true},
+		{"OpError ENETUNREACH", &net.OpError{Op: "dial", Err: syscall.ENETUNREACH}, true},
+		{"OpError EHOSTUNREACH", &net.OpError{Op: "dial", Err: syscall.EHOSTUNREACH}, true},
+		{"OpError ETIMEDOUT", &net.OpError{Op: "dial", Err: syscall.ETIMEDOUT}, true},
+		// OpError with permanent syscall errors — should NOT retry
+		{"OpError EACCES", &net.OpError{Op: "dial", Err: syscall.EACCES}, false},
+		{"OpError EPERM", &net.OpError{Op: "dial", Err: syscall.EPERM}, false},
+		// OpError with unknown inner error — conservative retry
+		{"OpError unknown inner", &net.OpError{Op: "dial", Err: fmt.Errorf("unknown")}, true},
+		// DNS errors
+		{"DNS timeout", &net.DNSError{IsTimeout: true}, true},
+		{"DNS no such host", &net.DNSError{IsTimeout: false, Name: "bad.host"}, false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := isTemporaryNetError(tt.err)
+			if got != tt.want {
+				t.Errorf("isTemporaryNetError(%v) = %v, want %v", tt.err, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIsRetriableSyscallError(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{"nil", nil, false},
+		{"ECONNREFUSED", syscall.ECONNREFUSED, true},
+		{"ECONNRESET", syscall.ECONNRESET, true},
+		{"ENETUNREACH", syscall.ENETUNREACH, true},
+		{"EHOSTUNREACH", syscall.EHOSTUNREACH, true},
+		{"ETIMEDOUT", syscall.ETIMEDOUT, true},
+		{"EACCES (permanent)", syscall.EACCES, false},
+		{"EPERM (permanent)", syscall.EPERM, false},
+		{"ENOENT (permanent)", syscall.ENOENT, false},
+		{"unknown error", fmt.Errorf("something"), true}, // conservative retry
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := isRetriableSyscallError(tt.err)
+			if got != tt.want {
+				t.Errorf("isRetriableSyscallError(%v) = %v, want %v", tt.err, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestRedactURL(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{
+			name:  "no query params",
+			input: "https://gitea.example.com/api/v1/repos/owner/repo/pulls/1",
+			want:  "https://gitea.example.com/api/v1/repos/owner/repo/pulls/1",
+		},
+		{
+			name:  "with query params - redacts",
+			input: "https://gitea.example.com/api/v1/repos/owner/repo/raw/file?ref=main",
+			want:  "https://gitea.example.com/api/v1/repos/owner/repo/raw/file?[redacted]",
+		},
+		{
+			name:  "multiple query params",
+			input: "https://example.com/path?token=secret&page=1",
+			want:  "https://example.com/path?[redacted]",
+		},
+		{
+			name:  "invalid URL",
+			input: "://invalid",
+			want:  "[invalid URL]",
+		},
+		{
+			name:  "empty string",
+			input: "",
+			want:  "",
+		},
+		{
+			name:  "with userinfo - redacts credentials",
+			input: "https://admin:secret@gitea.example.com/api/v1/repos",
+			want:  "https://REDACTED@gitea.example.com/api/v1/repos",
+		},
+		{
+			name:  "with userinfo and query params",
+			input: "https://user:pass@example.com/path?token=abc",
+			want:  "https://REDACTED@example.com/path?[redacted]",
+		},
+		{
+			name:  "username only - no password",
+			input: "https://user@example.com/path",
+			want:  "https://REDACTED@example.com/path",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := redactURL(tt.input)
+			if got != tt.want {
+				t.Errorf("redactURL(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestSanitizeErrorForLog(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+		want string
+	}{
+		{
+			name: "nil error",
+			err:  nil,
+			want: "<nil>",
+		},
+		{
+			name: "APIError omits body",
+			err:  &APIError{StatusCode: 500, Body: "internal error: database connection failed"},
+			want: "HTTP 500",
+		},
+		{
+			name: "APIError with large body still only shows status",
+			err:  &APIError{StatusCode: 502, Body: strings.Repeat("x", 1000)},
+			want: "HTTP 502",
+		},
+		{
+			name: "non-API error preserved",
+			err:  fmt.Errorf("connection refused"),
+			want: "connection refused",
+		},
+		{
+			name: "wrapped APIError",
+			err:  fmt.Errorf("request failed: %w", &APIError{StatusCode: 503, Body: "service unavailable"}),
+			want: "HTTP 503",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := sanitizeErrorForLog(tt.err)
+			if got != tt.want {
+				t.Errorf("sanitizeErrorForLog() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestNewClient_HasCheckRedirect(t *testing.T) {
+	c := NewClient("https://gitea.example.com", "token")
+	if c.http.CheckRedirect == nil {
+		t.Fatal("expected CheckRedirect to be set")
+	}
+}
+
+func TestDefaultCheckRedirect_RejectsHTTPSToHTTP(t *testing.T) {
+	prev := &http.Request{URL: &url.URL{Scheme: "https", Host: "gitea.example.com", Path: "/foo"}}
+	req := &http.Request{
+		URL:    &url.URL{Scheme: "http", Host: "gitea.example.com", Path: "/foo"},
+		Header: http.Header{"Authorization": []string{"token abc"}},
+	}
+	err := defaultCheckRedirect(req, []*http.Request{prev})
+	if err == nil {
+		t.Fatal("expected error on HTTPS->HTTP redirect")
+	}
+	if !strings.Contains(err.Error(), "HTTPS to HTTP downgrade") {
+		t.Errorf("unexpected error message: %v", err)
+	}
+}
+
+func TestDefaultCheckRedirect_RejectsCrossHost(t *testing.T) {
+	prev := &http.Request{URL: &url.URL{Scheme: "https", Host: "gitea.example.com", Path: "/foo"}}
+	req := &http.Request{
+		URL:    &url.URL{Scheme: "https", Host: "cdn.example.com", Path: "/bar"},
+		Header: http.Header{"Authorization": []string{"token abc"}},
+	}
+	err := defaultCheckRedirect(req, []*http.Request{prev})
+	if err == nil {
+		t.Fatal("expected error on cross-host redirect")
+	}
+	if !strings.Contains(err.Error(), "cross-host") {
+		t.Errorf("unexpected error message: %v", err)
+	}
+}
+
+func TestDefaultCheckRedirect_AllowsSameHost(t *testing.T) {
+	prev := &http.Request{URL: &url.URL{Scheme: "https", Host: "gitea.example.com", Path: "/foo"}}
+	req := &http.Request{
+		URL:    &url.URL{Scheme: "https", Host: "gitea.example.com", Path: "/bar"},
+		Header: http.Header{"Authorization": []string{"token abc"}},
+	}
+	err := defaultCheckRedirect(req, []*http.Request{prev})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if auth := req.Header.Get("Authorization"); auth != "token abc" {
+		t.Errorf("expected Authorization to be preserved, got %q", auth)
+	}
+}
+
+func TestDefaultCheckRedirect_AllowsSameHostHTTPToHTTP(t *testing.T) {
+	prev := &http.Request{URL: &url.URL{Scheme: "http", Host: "localhost:3000", Path: "/foo"}}
+	req := &http.Request{
+		URL:    &url.URL{Scheme: "http", Host: "localhost:3000", Path: "/bar"},
+		Header: http.Header{},
+	}
+	err := defaultCheckRedirect(req, []*http.Request{prev})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestDefaultCheckRedirect_RejectsTooManyRedirects(t *testing.T) {
+	via := make([]*http.Request, 10)
+	for i := range via {
+		via[i] = &http.Request{URL: &url.URL{Scheme: "https", Host: "gitea.example.com", Path: "/"}}
+	}
+	req := &http.Request{URL: &url.URL{Scheme: "https", Host: "gitea.example.com", Path: "/final"}}
+	err := defaultCheckRedirect(req, via)
+	if err == nil {
+		t.Fatal("expected error after 10 redirects")
+	}
+	if !strings.Contains(err.Error(), "10 redirects") {
+		t.Errorf("unexpected error message: %v", err)
+	}
+}
+
+func TestDefaultCheckRedirect_EmptyViaAllowed(t *testing.T) {
+	req := &http.Request{URL: &url.URL{Scheme: "https", Host: "gitea.example.com", Path: "/foo"}}
+	err := defaultCheckRedirect(req, nil)
+	if err != nil {
+		t.Fatalf("unexpected error with empty via: %v", err)
+	}
+}
+
+func TestSetHTTPClient_NilRestoresDefault(t *testing.T) {
+	c := NewClient("https://gitea.example.com", "token")
+	c.SetHTTPClient(nil)
+	if c.http == nil {
+		t.Fatal("expected non-nil http client after SetHTTPClient(nil)")
+	}
+	if c.http.Timeout != 30*time.Second {
+		t.Errorf("expected 30s timeout, got %v", c.http.Timeout)
+	}
+	if c.http.CheckRedirect == nil {
+		t.Fatal("expected CheckRedirect policy after SetHTTPClient(nil)")
+	}
+}
+
+// TestSafeDialContextBlocksPrivateIPs verifies that NewClient (which uses
+// safeDialContext by default) refuses to connect to private/reserved IPs.
+func TestSafeDialContextBlocksPrivateIPs(t *testing.T) {
+	// These servers listen on 127.0.0.1, so the safe dialer will block them.
+	// We use NewClient (NOT NewTestClient) to exercise the real safe dialer.
+	privateURLs := []struct {
+		name string
+		url  string
+	}{
+		{"loopback localhost", "http://localhost/"},
+		{"loopback 127.0.0.1", "http://127.0.0.1/"},
+	}
+
+	for _, tc := range privateURLs {
+		t.Run(tc.name, func(t *testing.T) {
+			c := NewClient(tc.url, "token")
+			_, err := c.GetPullRequest(context.Background(), "owner", "repo", 1)
+			if err == nil {
+				t.Errorf("expected error connecting to %s, got nil", tc.url)
+			}
+			// Error must mention SSRF/blocked, not a random network error.
+			if !strings.Contains(err.Error(), "blocked") &&
+				!strings.Contains(err.Error(), "private") &&
+				!strings.Contains(err.Error(), "loopback") &&
+				!strings.Contains(err.Error(), "reserved") {
+				t.Logf("error: %v", err)
+				// Allow other errors (connection refused, DNS) since the point
+				// is that we don't silently succeed — but prefer the explicit block message.
+			}
+		})
+	}
+}
+
+// TestWithUnsafeDialerAllowsLocalhost verifies that WithUnsafeDialer bypasses
+// the IP check, allowing tests to connect to httptest.Server (127.0.0.1).
+func TestWithUnsafeDialerAllowsLocalhost(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte(`{"title":"test","body":"","head":{"sha":"abc","ref":"main"}}`))
+	}))
+	defer server.Close()
+
+	// WithUnsafeDialer should allow connecting to 127.0.0.1.
+	c := NewClient(server.URL, "token").WithUnsafeDialer()
+	pr, err := c.GetPullRequest(context.Background(), "owner", "repo", 1)
+	if err != nil {
+		t.Fatalf("unexpected error with unsafe dialer: %v", err)
+	}
+	if pr.Title != "test" {
+		t.Errorf("expected title 'test', got %q", pr.Title)
+	}
+}
+
+// TestNewClient_HasSafeTransport verifies that NewClient installs the
+// SSRF-blocking transport (i.e. Transport is not nil and DialContext is set).
+func TestNewClient_HasSafeTransport(t *testing.T) {
+	c := NewClient("https://gitea.example.com", "token")
+	if c.http.Transport == nil {
+		t.Fatal("expected Transport to be set on NewClient (safe dialer)")
+	}
+	transport, ok := c.http.Transport.(*http.Transport)
+	if !ok {
+		t.Fatalf("expected *http.Transport, got %T", c.http.Transport)
+	}
+	if transport.DialContext == nil {
+		t.Fatal("expected DialContext to be set on transport (safe dialer)")
+	}
+}
+
+// TestSetHTTPClient_NilRestoresSafeTransport verifies that SetHTTPClient(nil)
+// restores the safe transport (not just any client).
+func TestSetHTTPClient_NilRestoresSafeTransport(t *testing.T) {
+	c := NewClient("https://gitea.example.com", "token")
+	c.SetHTTPClient(&http.Client{}) // replace with plain client
+	c.SetHTTPClient(nil)            // restore
+	transport, ok := c.http.Transport.(*http.Transport)
+	if !ok {
+		t.Fatalf("expected *http.Transport after SetHTTPClient(nil), got %T", c.http.Transport)
+	}
+	if transport.DialContext == nil {
+		t.Fatal("expected DialContext to be restored after SetHTTPClient(nil)")
+	}
+}
+
+// TestNewSafeHTTPClient_PreservesDefaultTransportSettings verifies that
+// newSafeHTTPClient clones http.DefaultTransport to retain proxy support,
+// TLS handshake timeout, idle connection limits, and HTTP/2.
+func TestNewSafeHTTPClient_PreservesDefaultTransportSettings(t *testing.T) {
+	c := NewClient("https://gitea.example.com", "token")
+	transport, ok := c.http.Transport.(*http.Transport)
+	if !ok {
+		t.Fatalf("expected *http.Transport, got %T", c.http.Transport)
+	}
+
+	defaults := http.DefaultTransport.(*http.Transport)
+
+	// TLSHandshakeTimeout must be inherited (non-zero), not the zero value
+	// that a bare &http.Transport{} would have.
+	if transport.TLSHandshakeTimeout == 0 {
+		t.Error("TLSHandshakeTimeout is 0; expected inherited value from DefaultTransport")
+	}
+	if transport.TLSHandshakeTimeout != defaults.TLSHandshakeTimeout {
+		t.Errorf("TLSHandshakeTimeout = %v, want %v", transport.TLSHandshakeTimeout, defaults.TLSHandshakeTimeout)
+	}
+
+	// IdleConnTimeout must be inherited.
+	if transport.IdleConnTimeout == 0 {
+		t.Error("IdleConnTimeout is 0; expected inherited value from DefaultTransport")
+	}
+	if transport.IdleConnTimeout != defaults.IdleConnTimeout {
+		t.Errorf("IdleConnTimeout = %v, want %v", transport.IdleConnTimeout, defaults.IdleConnTimeout)
+	}
+
+	// MaxIdleConns must be inherited.
+	if transport.MaxIdleConns == 0 {
+		t.Error("MaxIdleConns is 0; expected inherited value from DefaultTransport")
+	}
+
+	// ForceAttemptHTTP2 must be inherited.
+	if !transport.ForceAttemptHTTP2 {
+		t.Error("ForceAttemptHTTP2 is false; expected true from DefaultTransport")
+	}
+
+	// Proxy must be set (ProxyFromEnvironment).
+	if transport.Proxy == nil {
+		t.Error("Proxy is nil; expected ProxyFromEnvironment from DefaultTransport")
+	}
+
+	// DialContext must be our safe dialer, not the default.
+	if transport.DialContext == nil {
+		t.Error("DialContext is nil; expected safeDialContext")
+	}
+}

gitea/diff_size_test.go

@@ -0,0 +1,97 @@
+package gitea
+
+import (
+	"context"
+	"errors"
+	"math"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestGetPullRequestDiff_SizeLimits(t *testing.T) {
+	tests := []struct {
+		name        string
+		diff        string
+		maxDiffSize int64
+		wantErr     error
+		wantDiff    string
+	}{
+		{
+			name:        "exceeds max size",
+			diff:        strings.Repeat("+ added line\n", 1000), // ~13 KB
+			maxDiffSize: 100,
+			wantErr:     ErrDiffTooLarge,
+		},
+		{
+			name:        "within max size",
+			diff:        "diff --git a/f.go b/f.go\n--- a/f.go\n+++ b/f.go\n@@ -1 +1 @@\n-old\n+new\n",
+			maxDiffSize: 1024,
+			wantDiff:    "diff --git a/f.go b/f.go\n--- a/f.go\n+++ b/f.go\n@@ -1 +1 @@\n-old\n+new\n",
+		},
+		{
+			name:        "exactly at limit",
+			diff:        strings.Repeat("x", 50),
+			maxDiffSize: 50,
+			wantDiff:    strings.Repeat("x", 50),
+		},
+		{
+			name:        "one byte over limit",
+			diff:        strings.Repeat("x", 51),
+			maxDiffSize: 50,
+			wantErr:     ErrDiffTooLarge,
+		},
+		{
+			name:        "disabled limit",
+			diff:        strings.Repeat("x", 10000),
+			maxDiffSize: -1,
+			wantDiff:    strings.Repeat("x", 10000),
+		},
+		{
+			name:        "math.MaxInt64 treated as disabled",
+			diff:        strings.Repeat("x", 10000),
+			maxDiffSize: math.MaxInt64,
+			wantDiff:    strings.Repeat("x", 10000),
+		},
+		{
+			name:        "default limit",
+			diff:        "diff content",
+			maxDiffSize: 0, // zero means use DefaultMaxDiffSize
+			wantDiff:    "diff content",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.Write([]byte(tt.diff)) //nolint:errcheck // test handler
+			}))
+			defer server.Close()
+
+			client := NewTestClient(server.URL, "test-token")
+			client.MaxDiffSize = tt.maxDiffSize
+			client.RetryBackoff = []time.Duration{}
+
+			got, err := client.GetPullRequestDiff(context.Background(), "owner", "repo", 1)
+
+			if tt.wantErr != nil {
+				if err == nil {
+					t.Fatal("expected error, got nil")
+				}
+				if !errors.Is(err, tt.wantErr) {
+					t.Errorf("expected %v, got: %v", tt.wantErr, err)
+				}
+				return
+			}
+
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if got != tt.wantDiff {
+				t.Errorf("diff mismatch: got length %d, want length %d", len(got), len(tt.wantDiff))
+			}
+		})
+	}
+}

gitea/export_test.go

@@ -0,0 +1,18 @@
+// Package gitea — export_test.go exposes test helpers to test files in this
+// package. It uses `package gitea` (not `package gitea_test`) so it can access
+// unexported identifiers; Go only compiles it into the test binary, never into
+// the production binary. This is the idiomatic pattern for white-box testing
+// in Go (see net/http/export_test.go in the stdlib for the same approach).
+package gitea
+
+// NewTestClient creates a Gitea client configured for use in unit tests.
+// It bypasses the IP-level SSRF protection so that tests can connect to
+// httptest.Server instances (which listen on 127.0.0.1).
+//
+// Using the internal package gitea declaration (not gitea_test) means this
+// symbol is available to all _test.go files in this package. It is ONLY
+// compiled into the test binary; production binaries never include it.
+// Production code must use NewClient, which enables the safe dialer.
+func NewTestClient(baseURL, token string) *Client {
+	return NewClient(baseURL, token).WithUnsafeDialer()
+}

gitea/ipcheck.go

@@ -0,0 +1,91 @@
+// Package gitea provides a client for the Gitea API.
+// ipcheck.go implements IP-level SSRF protection by checking resolved addresses
+// against known blocked CIDR ranges (RFC1918, loopback, link-local, etc.).
+package gitea
+
+import (
+	"fmt"
+	"net"
+)
+
+// blockedCIDRStrings is the canonical list of CIDR strings that should never
+// be contacted by review-bot. See IsBlockedIP for the full list of covered
+// address families.
+//
+// These are hard-coded literals: any parse failure is a programming error.
+// Validity is verified by TestBlockedCIDRsValid in ipcheck_test.go.
+var blockedCIDRStrings = []string{
+	// IPv4 loopback
+	"127.0.0.0/8",
+	// IPv4 unspecified / "this network"
+	"0.0.0.0/8",
+	// RFC1918 private ranges
+	"10.0.0.0/8",
+	"172.16.0.0/12",
+	"192.168.0.0/16",
+	// IPv4 link-local (APIPA, also used by AWS instance metadata 169.254.169.254)
+	"169.254.0.0/16",
+	// IPv4 shared address space (RFC6598, carrier-grade NAT)
+	"100.64.0.0/10",
+	// IPv4 multicast
+	"224.0.0.0/4",
+	// IPv4 reserved / broadcast
+	"240.0.0.0/4",
+	// IPv6 loopback
+	"::1/128",
+	// IPv6 unspecified
+	"::/128",
+	// IPv6 link-local
+	"fe80::/10",
+	// IPv6 unique local (ULA) — RFC4193
+	"fc00::/7",
+	// IPv6 multicast
+	"ff00::/8",
+}
+
+// blockedCIDRs is the parsed form of blockedCIDRStrings.
+// Any entry that fails to parse is recorded in blockedCIDRParseErrors instead
+// of panicking; tests verify this slice is always empty via TestBlockedCIDRsValid.
+var (
+	blockedCIDRs           []*net.IPNet
+	blockedCIDRParseErrors []string
+)
+
+func init() {
+	blockedCIDRs = make([]*net.IPNet, 0, len(blockedCIDRStrings))
+	for _, r := range blockedCIDRStrings {
+		_, cidr, err := net.ParseCIDR(r)
+		if err != nil {
+			// Record the error rather than panicking; TestBlockedCIDRsValid
+			// will catch this during tests, and the CI build will fail.
+			blockedCIDRParseErrors = append(blockedCIDRParseErrors,
+				fmt.Sprintf("ipcheck: invalid built-in CIDR %q: %v", r, err))
+			continue
+		}
+		blockedCIDRs = append(blockedCIDRs, cidr)
+	}
+}
+
+// IsBlockedIP reports whether ip is in a blocked address range.
+// It is exported for use by the validate-url subcommand and tests outside
+// this package.
+//
+// IPv6-mapped IPv4 addresses (e.g. ::ffff:192.168.1.1) are normalized to their
+// IPv4 form before checking so that IPv4 CIDRs catch them.
+//
+// Based on:
+//   - RFC1918 private ranges
+//   - RFC5735 / RFC4193 special-use IPv4/IPv6 ranges
+//   - RFC4291 IPv6 link-local / loopback
+func IsBlockedIP(ip net.IP) bool {
+	// Normalize IPv6-mapped IPv4 addresses (::ffff:x.x.x.x) to plain IPv4.
+	if v4 := ip.To4(); v4 != nil {
+		ip = v4
+	}
+	for _, cidr := range blockedCIDRs {
+		if cidr.Contains(ip) {
+			return true
+		}
+	}
+	return false
+}

gitea/ipcheck_test.go

@@ -0,0 +1,144 @@
+package gitea
+
+import (
+	"net"
+	"testing"
+)
+
+func TestIsBlockedIP(t *testing.T) {
+	blocked := []struct {
+		name string
+		ip   string
+	}{
+		// IPv4 loopback
+		{"loopback 127.0.0.1", "127.0.0.1"},
+		{"loopback 127.0.0.2", "127.0.0.2"},
+		{"loopback 127.255.255.255", "127.255.255.255"},
+		// IPv4 unspecified
+		{"unspecified 0.0.0.0", "0.0.0.0"},
+		{"unspecified 0.1.2.3", "0.1.2.3"},
+		// RFC1918
+		{"RFC1918 10.0.0.1", "10.0.0.1"},
+		{"RFC1918 10.255.255.255", "10.255.255.255"},
+		{"RFC1918 172.16.0.1", "172.16.0.1"},
+		{"RFC1918 172.31.255.255", "172.31.255.255"},
+		{"RFC1918 192.168.0.1", "192.168.0.1"},
+		{"RFC1918 192.168.255.255", "192.168.255.255"},
+		// Link-local (APIPA / AWS metadata)
+		{"link-local 169.254.0.1", "169.254.0.1"},
+		{"link-local 169.254.169.254", "169.254.169.254"},
+		// Shared address space (carrier-grade NAT)
+		{"CGN 100.64.0.1", "100.64.0.1"},
+		{"CGN 100.127.255.255", "100.127.255.255"},
+		// Multicast
+		{"multicast 224.0.0.1", "224.0.0.1"},
+		{"multicast 239.255.255.255", "239.255.255.255"},
+		// Reserved
+		{"reserved 240.0.0.1", "240.0.0.1"},
+		{"broadcast 255.255.255.255", "255.255.255.255"},
+		// IPv6 loopback
+		{"IPv6 loopback ::1", "::1"},
+		// IPv6 unspecified
+		{"IPv6 unspecified ::", "::"},
+		// IPv6 link-local
+		{"IPv6 link-local fe80::1", "fe80::1"},
+		{"IPv6 link-local fe80::dead:beef", "fe80::dead:beef"},
+		// IPv6 ULA
+		{"IPv6 ULA fc00::1", "fc00::1"},
+		{"IPv6 ULA fd00::1", "fd00::1"},
+		// IPv6 multicast
+		{"IPv6 multicast ff02::1", "ff02::1"},
+	}
+
+	for _, tc := range blocked {
+		t.Run(tc.name, func(t *testing.T) {
+			ip := net.ParseIP(tc.ip)
+			if ip == nil {
+				t.Fatalf("failed to parse IP %q", tc.ip)
+			}
+			if !IsBlockedIP(ip) {
+				t.Errorf("IsBlockedIP(%q) = false, want true", tc.ip)
+			}
+		})
+	}
+
+	allowed := []struct {
+		name string
+		ip   string
+	}{
+		{"public 8.8.8.8", "8.8.8.8"},
+		{"public 1.1.1.1", "1.1.1.1"},
+		{"public 198.51.100.1", "198.51.100.1"}, // RFC5737 TEST-NET-2 — a documentation-only range;
+					// not assigned to any real host, but intentionally left unblocked here because
+					// it has no special routing treatment (unlike RFC1918/loopback/link-local) and
+					// blocking it would require tracking every RFC5737 range without meaningful
+					// security benefit (no server should ever listen on a TEST-NET address).
+		{"public 151.101.1.1", "151.101.1.1"},        // Fastly
+		{"public IPv6 2001:4860:4860::8888", "2001:4860:4860::8888"}, // Google DNS
+		{"public IPv6 2606:4700:4700::1111", "2606:4700:4700::1111"}, // Cloudflare DNS
+	}
+
+	for _, tc := range allowed {
+		t.Run(tc.name, func(t *testing.T) {
+			ip := net.ParseIP(tc.ip)
+			if ip == nil {
+				t.Fatalf("failed to parse IP %q", tc.ip)
+			}
+			if IsBlockedIP(ip) {
+				t.Errorf("IsBlockedIP(%q) = true, want false", tc.ip)
+			}
+		})
+	}
+}
+
+func TestIsBlockedIPv6MappedIPv4(t *testing.T) {
+	// ::ffff:192.168.1.1 is an IPv6-mapped IPv4 address — should be blocked as RFC1918.
+	// Construct it manually as a 16-byte IP.
+	mapped := net.IP{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0xff, 0xff, 192, 168, 1, 1}
+	if !IsBlockedIP(mapped) {
+		t.Errorf("IsBlockedIP(::ffff:192.168.1.1) = false, want true (IPv6-mapped IPv4 must be normalized)")
+	}
+
+	// ::ffff:8.8.8.8 — IPv6-mapped public IP — should be allowed.
+	mappedPublic := net.IP{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0xff, 0xff, 8, 8, 8, 8}
+	if IsBlockedIP(mappedPublic) {
+		t.Errorf("IsBlockedIP(::ffff:8.8.8.8) = true, want false")
+	}
+}
+
+func TestIsBlockedIPEdgeCases(t *testing.T) {
+	// The boundary between RFC1918 and public ranges.
+	// 172.15.255.255 is NOT private (just below 172.16.0.0/12).
+	notPrivate := net.ParseIP("172.15.255.255")
+	if IsBlockedIP(notPrivate) {
+		t.Errorf("IsBlockedIP(172.15.255.255) = true, want false (outside 172.16.0.0/12)")
+	}
+	// 172.32.0.0 is NOT private (just above 172.31.255.255).
+	notPrivate2 := net.ParseIP("172.32.0.0")
+	if IsBlockedIP(notPrivate2) {
+		t.Errorf("IsBlockedIP(172.32.0.0) = true, want false (outside 172.16.0.0/12)")
+	}
+	// CGN: 100.63.255.255 is NOT in 100.64.0.0/10.
+	notCGN := net.ParseIP("100.63.255.255")
+	if IsBlockedIP(notCGN) {
+		t.Errorf("IsBlockedIP(100.63.255.255) = true, want false (outside 100.64.0.0/10)")
+	}
+	// CGN: 100.128.0.0 is NOT in 100.64.0.0/10.
+	notCGN2 := net.ParseIP("100.128.0.0")
+	if IsBlockedIP(notCGN2) {
+		t.Errorf("IsBlockedIP(100.128.0.0) = true, want false (outside 100.64.0.0/10)")
+	}
+}
+
+// TestBlockedCIDRsValid verifies that all entries in blockedCIDRStrings parse
+// successfully. This catches programming errors in the CIDR list without
+// requiring a startup panic. The init() function records parse failures in
+// blockedCIDRParseErrors rather than panicking; this test makes those failures
+// visible as test failures during CI.
+func TestBlockedCIDRsValid(t *testing.T) {
+	if len(blockedCIDRParseErrors) > 0 {
+		for _, msg := range blockedCIDRParseErrors {
+			t.Errorf("CIDR parse error: %s", msg)
+		}
+	}
+}

gitea/post_review_comments_test.go

@@ -31,13 +31,13 @@ func TestPostReview_WithComments(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
+	client := NewTestClient(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)
+	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "REQUEST_CHANGES", "summary", "", comments)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -71,8 +71,8 @@ func TestPostReview_NilComments(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := NewClient(server.URL, "test-token")
-	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "APPROVED", "all good", nil)
+	client := NewTestClient(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)
 	}

github/client.go

@@ -0,0 +1,378 @@
+// Package github provides a client for the GitHub API.
+// It supports pull request operations, file content retrieval,
+// and review submission for both github.com and GitHub Enterprise.
+package github
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+)
+
+const (
+	defaultBaseURL = "https://api.github.com"
+
+	// maxRetryAttempts is the number of times doRequest will attempt a request.
+	maxRetryAttempts = 3
+
+	// maxRetryAfter caps the maximum delay from a Retry-After header to prevent
+	// a server from stalling the client indefinitely.
+	maxRetryAfter = 60 * time.Second
+
+	// maxErrorBodyBytes limits how much of an error response body we read
+	// to protect against malicious servers sending unbounded data.
+	maxErrorBodyBytes = 64 * 1024 // 64 KB
+
+	// maxResponseBodyBytes limits how much of a successful response body we read
+	// for defense-in-depth against servers returning excessively large payloads.
+	maxResponseBodyBytes = 10 * 1024 * 1024 // 10 MB
+)
+
+// APIError represents an HTTP error response from the GitHub API.
+// It carries the status code so callers can distinguish between
+// different failure modes (e.g. 404 vs 500).
+//
+// The Body field stores up to 64 KiB of the raw response for programmatic
+// inspection. Error() truncates to 200 bytes for safe logging, but callers
+// should avoid logging or propagating Body directly in production since it may
+// contain sensitive details from the upstream server.
+type APIError struct {
+	StatusCode int
+	Body       string
+}
+
+func (e *APIError) Error() string {
+	body := e.Body
+	if len(body) > 200 {
+		body = body[:200] + "...(truncated)"
+	}
+	// Sanitize newlines to prevent log injection from upstream response bodies.
+	body = strings.ReplaceAll(body, "\n", " ")
+	body = strings.ReplaceAll(body, "\r", " ")
+	return fmt.Sprintf("HTTP %d: %s", e.StatusCode, body)
+}
+
+// IsNotFound reports whether an error is an API 404 response.
+func IsNotFound(err error) bool {
+	if apiErr, ok := asAPIError(err); ok {
+		return apiErr.StatusCode == http.StatusNotFound
+	}
+	return false
+}
+
+// IsUnauthorized reports whether an error is an API 401 response.
+func IsUnauthorized(err error) bool {
+	if apiErr, ok := asAPIError(err); ok {
+		return apiErr.StatusCode == http.StatusUnauthorized
+	}
+	return false
+}
+
+func asAPIError(err error) (*APIError, bool) {
+	if err == nil {
+		return nil, false
+	}
+	var target *APIError
+	if errors.As(err, &target) {
+		return target, true
+	}
+	return nil, false
+}
+
+// Client interacts with the GitHub API.
+// A Client is safe for concurrent use by multiple goroutines.
+// SetHTTPClient and SetRetryBackoff are intended for test setup only and must
+// be called before any goroutines issue requests; they have no synchronization.
+type Client struct {
+	// TODO: baseURL is populated by NewClient but not yet consumed by doRequest/doGet.
+	// Higher-level exported methods (GetPullRequest, etc.) will use it to
+	// construct request URLs; remove this field if those methods end up
+	// accepting full URLs instead.
+	baseURL    string
+	token      string
+	httpClient *http.Client
+
+	// allowInsecureHTTP permits requests to HTTP (non-TLS) endpoints.
+	// When false, doRequest rejects URLs with an http:// scheme.
+	allowInsecureHTTP bool
+
+	// retryBackoff defines the delays between retry attempts for 429 responses.
+	// retryBackoff[i] is the delay before attempt i+1 (after attempt i fails).
+	// If nil, defaults to {1s, 2s}.
+	retryBackoff []time.Duration
+
+	// now returns the current time. Defaults to time.Now.
+	// Override in tests to control HTTP-date Retry-After calculations.
+	now func() time.Time
+}
+
+// defaultCheckRedirect is the redirect policy used by NewClient.
+// NOTE: This function is intentionally duplicated in gitea/client.go (and vice versa)
+// because the packages are separate. Changes here must be mirrored there.
+// It rejects HTTPS->HTTP protocol downgrades (to prevent plaintext leakage)
+// and cross-host redirects (to prevent following responses from untrusted
+// endpoints). Same-host, same-or-upgraded-scheme redirects are allowed.
+func defaultCheckRedirect(req *http.Request, via []*http.Request) error {
+	if len(via) >= 10 {
+		return fmt.Errorf("stopped after 10 redirects")
+	}
+	// Guard for direct invocation in tests and any future callers;
+	// net/http guarantees len(via) >= 1 during actual redirects.
+	if len(via) == 0 {
+		return nil
+	}
+	prev := via[len(via)-1]
+	// Reject protocol downgrade: HTTPS->HTTP leaks request metadata over plaintext.
+	if prev.URL.Scheme == "https" && req.URL.Scheme == "http" {
+		return fmt.Errorf("refusing redirect: HTTPS to HTTP downgrade (%s -> %s)", prev.URL.Host, req.URL.Host)
+	}
+	// Reject cross-host redirect entirely to avoid consuming responses
+	// from untrusted endpoints.
+	if req.URL.Host != prev.URL.Host {
+		return fmt.Errorf("refusing redirect: cross-host (%s -> %s)", prev.URL.Host, req.URL.Host)
+	}
+	return nil
+}
+
+// ClientOption configures optional behavior of a Client.
+type ClientOption func(*clientConfig)
+
+type clientConfig struct {
+	allowInsecureHTTP    bool
+	insecureIsTestBypass bool
+}
+
+// AllowInsecureHTTP permits sending credentials over plaintext HTTP connections.
+// In production, this option is gated by the REVIEW_BOT_ALLOW_INSECURE=1
+// environment variable. Without the env var set, the option is ignored
+// and a warning is logged.
+//
+// For tests, use AllowInsecureHTTPForTest (defined in a _test.go file in the same package) which bypasses the env gate.
+func AllowInsecureHTTP() ClientOption {
+	return func(cfg *clientConfig) {
+		cfg.allowInsecureHTTP = true
+	}
+}
+
+// NewClient creates a new GitHub API client.
+// If baseURL is empty, it defaults to https://api.github.com.
+// For GitHub Enterprise, pass the API base URL (e.g. https://github.concur.com/api/v3).
+func NewClient(token, baseURL string, opts ...ClientOption) *Client {
+	if baseURL == "" {
+		baseURL = defaultBaseURL
+	}
+
+	var cfg clientConfig
+	for _, opt := range opts {
+		opt(&cfg)
+	}
+
+	if cfg.allowInsecureHTTP && !cfg.insecureIsTestBypass {
+		if os.Getenv("REVIEW_BOT_ALLOW_INSECURE") != "1" {
+			slog.Warn("AllowInsecureHTTP ignored: set REVIEW_BOT_ALLOW_INSECURE=1 to enable")
+			cfg.allowInsecureHTTP = false
+		} else {
+			slog.Warn("AllowInsecureHTTP enabled — credentials may be sent over plaintext",
+				"env", "REVIEW_BOT_ALLOW_INSECURE=1")
+		}
+	}
+
+	return &Client{
+		baseURL:           strings.TrimRight(baseURL, "/"),
+		token:             token,
+		allowInsecureHTTP: cfg.allowInsecureHTTP,
+		httpClient: &http.Client{
+			Timeout:       30 * time.Second,
+			CheckRedirect: defaultCheckRedirect,
+		},
+		now: time.Now,
+	}
+}
+
+// SetHTTPClient sets the underlying HTTP client used for requests.
+// This is intended for test setup only to inject mock transports; it must be
+// called before any goroutines issue requests.
+//
+// Passing nil restores the default client (30s timeout + redirect-rejecting
+// CheckRedirect policy matching NewClient).
+//
+// Callers providing a non-nil client are responsible for configuring a safe
+// CheckRedirect policy. Without one, the default net/http behavior will follow
+// redirects and may forward the Authorization header to untrusted hosts.
+func (c *Client) SetHTTPClient(hc *http.Client) {
+	if hc == nil {
+		hc = &http.Client{
+			Timeout:       30 * time.Second,
+			CheckRedirect: defaultCheckRedirect,
+		}
+	}
+	c.httpClient = hc
+}
+
+// SetRetryBackoff sets the delays between retry attempts.
+// This is intended for testing to speed up retry tests.
+//
+// Note: if an empty non-nil slice is provided, Retry-After delays parsed from
+// server responses will be computed and capped but not applied (because
+// attempt < len(backoff) is always false). This is acceptable for the
+// test-only use case but callers should be aware of this edge case.
+func (c *Client) SetRetryBackoff(backoff []time.Duration) {
+	c.retryBackoff = backoff
+}
+
+// parseRetryAfter parses a Retry-After header value, supporting both integer
+// seconds (e.g. "120") and HTTP-date format (e.g. "Thu, 01 Dec 2025 16:00:00 GMT")
+// as specified in RFC 7231 §7.1.3.
+//
+// For integer values, it returns the duration directly.
+// For HTTP-date values, it computes the delay as the difference between the
+// parsed time and now. If the date is in the past, it returns 0.
+//
+// Returns (0, false) if the value cannot be parsed as either format.
+func (c *Client) parseRetryAfter(value string) (time.Duration, bool) {
+	value = strings.TrimSpace(value)
+
+	// Try integer seconds first (most common from GitHub).
+	// RFC 7231 allows delta-seconds of 0 to indicate immediate retry.
+	if seconds, err := strconv.Atoi(value); err == nil && seconds >= 0 {
+		return time.Duration(seconds) * time.Second, true
+	}
+
+	// Try HTTP-date format (RFC 7231 §7.1.3).
+	// http.ParseTime handles RFC 1123, RFC 850, and ASCTIME formats.
+	if retryAt, err := http.ParseTime(value); err == nil {
+		delay := retryAt.Sub(c.now())
+		if delay < 0 {
+			delay = 0
+		}
+		return delay, true
+	}
+
+	return 0, false
+}
+
+// redactURL redacts sensitive components from a URL for safe inclusion in error
+// messages and log output. It removes userinfo (e.g., user:pass@) and replaces
+// query parameters with a placeholder.
+func redactURL(rawURL string) string {
+	u, err := url.Parse(rawURL)
+	if err != nil {
+		return "<unparseable URL>"
+	}
+	u.User = nil
+
+	if u.RawQuery != "" {
+		u.RawQuery = "<redacted>"
+	}
+	return u.String()
+}
+
+// doRequest performs an HTTP request with retry on 429 rate limit responses.
+// It respects the Retry-After header when present, supporting both integer
+// seconds and HTTP-date formats (capped at maxRetryAfter).
+func (c *Client) doRequest(ctx context.Context, method, reqURL string, accept string) ([]byte, error) {
+	// NOTE: This parses reqURL a second time (http.NewRequestWithContext parses it
+	// again internally). Acceptable cost: URL parsing is cheap and threading the
+	// parsed *url.URL through would complicate the interface for negligible gain.
+	if !c.allowInsecureHTTP {
+		parsed, err := url.Parse(reqURL)
+		if err != nil {
+			return nil, fmt.Errorf("parse request URL: %w", err)
+		}
+		if strings.EqualFold(parsed.Scheme, "http") {
+			return nil, fmt.Errorf("refusing HTTP request to %s: use HTTPS or set AllowInsecureHTTP option", redactURL(reqURL))
+		}
+	}
+
+	var backoff []time.Duration
+	if c.retryBackoff != nil {
+		backoff = append([]time.Duration(nil), c.retryBackoff...)
+	} else {
+		backoff = []time.Duration{1 * time.Second, 2 * time.Second}
+	}
+
+	var lastErr error
+	for attempt := 0; attempt < maxRetryAttempts; attempt++ {
+		if attempt > 0 {
+			var delay time.Duration
+			if attempt-1 < len(backoff) {
+				delay = backoff[attempt-1]
+			}
+			if delay > 0 {
+				timer := time.NewTimer(delay)
+				select {
+				case <-timer.C:
+					timer.Stop() // no-op after fire; kept for symmetry with the ctx.Done case
+				case <-ctx.Done():
+					timer.Stop()
+					return nil, ctx.Err()
+				}
+			}
+		}
+
+		req, err := http.NewRequestWithContext(ctx, method, reqURL, nil)
+		if err != nil {
+			return nil, fmt.Errorf("create request: %w", err)
+		}
+		req.Header.Set("Authorization", "Bearer "+c.token)
+		if accept != "" {
+			req.Header.Set("Accept", accept)
+		} else {
+			req.Header.Set("Accept", "application/vnd.github+json")
+		}
+
+		resp, err := c.httpClient.Do(req)
+		if err != nil {
+			return nil, fmt.Errorf("do request: %w", err)
+		}
+
+		if resp.StatusCode >= 200 && resp.StatusCode < 300 {
+			body, err := io.ReadAll(io.LimitReader(resp.Body, maxResponseBodyBytes))
+			resp.Body.Close()
+			if err != nil {
+				return nil, fmt.Errorf("read response body: %w", err)
+			}
+			return body, nil
+		}
+
+		errBody, _ := io.ReadAll(io.LimitReader(resp.Body, maxErrorBodyBytes))
+		resp.Body.Close()
+
+		lastErr = &APIError{StatusCode: resp.StatusCode, Body: string(errBody)}
+
+		// Retry on 429 rate limit
+		if resp.StatusCode == http.StatusTooManyRequests && attempt < maxRetryAttempts-1 {
+			// Check for Retry-After header and override backoff if present.
+			// Supports both integer seconds (common) and HTTP-date format (RFC 7231).
+			if ra := resp.Header.Get("Retry-After"); ra != "" {
+				if delay, ok := c.parseRetryAfter(ra); ok {
+					if delay > maxRetryAfter {
+						delay = maxRetryAfter
+					}
+					if attempt < len(backoff) {
+						backoff[attempt] = delay
+					}
+				}
+			}
+			continue
+		}
+
+		// Don't retry other errors
+		return nil, lastErr
+	}
+
+	return nil, lastErr
+}
+
+// doGet is a convenience wrapper for GET requests with the default Accept header.
+func (c *Client) doGet(ctx context.Context, url string) ([]byte, error) {
+	return c.doRequest(ctx, http.MethodGet, url, "")
+}

github/client_test.go

@@ -0,0 +1,658 @@
+package github
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestNewClient_DefaultBaseURL(t *testing.T) {
+	c := NewClient("tok", "")
+	if c.baseURL != defaultBaseURL {
+		t.Errorf("baseURL = %q, want %q", c.baseURL, defaultBaseURL)
+	}
+}
+
+func TestNewClient_CustomBaseURL(t *testing.T) {
+	c := NewClient("tok", "https://github.concur.com/api/v3/")
+	if c.baseURL != "https://github.concur.com/api/v3" {
+		t.Errorf("baseURL = %q, want trailing slash stripped", c.baseURL)
+	}
+}
+
+func TestDoRequest_Success(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := r.Header.Get("Authorization"); got != "Bearer test-token" {
+			t.Errorf("Authorization = %q, want Bearer test-token", got)
+		}
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"ok":true}`))
+	}))
+	defer srv.Close()
+
+	c := NewClient("test-token", srv.URL, AllowInsecureHTTPForTest())
+	body, err := c.doGet(context.Background(), srv.URL+"/test")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if string(body) != `{"ok":true}` {
+		t.Errorf("body = %q, want %q", body, `{"ok":true}`)
+	}
+}
+
+func TestDoRequest_429_RetryAfter_IntegerSeconds(t *testing.T) {
+	attempts := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		if attempts == 1 {
+			w.Header().Set("Retry-After", "0")
+			w.WriteHeader(http.StatusTooManyRequests)
+			w.Write([]byte("rate limited"))
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("success"))
+	}))
+	defer srv.Close()
+
+	c := NewClient("tok", srv.URL, AllowInsecureHTTPForTest())
+	c.SetRetryBackoff([]time.Duration{0, 0})
+
+	body, err := c.doGet(context.Background(), srv.URL+"/test")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if string(body) != "success" {
+		t.Errorf("body = %q, want %q", body, "success")
+	}
+	if attempts != 2 {
+		t.Errorf("attempts = %d, want 2", attempts)
+	}
+}
+
+func TestDoRequest_429_RetryAfter_HTTPDate(t *testing.T) {
+	// Fix "now" to a known time for deterministic testing.
+	fixedNow := time.Date(2025, 12, 1, 15, 59, 59, 0, time.UTC)
+	retryAt := "Mon, 01 Dec 2025 16:00:00 GMT" // 1 second in the future
+
+	attempts := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		if attempts == 1 {
+			w.Header().Set("Retry-After", retryAt)
+			w.WriteHeader(http.StatusTooManyRequests)
+			w.Write([]byte("rate limited"))
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("success"))
+	}))
+	defer srv.Close()
+
+	c := NewClient("tok", srv.URL, AllowInsecureHTTPForTest())
+	c.now = func() time.Time { return fixedNow }
+	// Initial backoff is 0; the HTTP-date parser will compute 1s and override.
+	c.SetRetryBackoff([]time.Duration{0, 0})
+
+	body, err := c.doGet(context.Background(), srv.URL+"/test")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if string(body) != "success" {
+		t.Errorf("body = %q, want %q", body, "success")
+	}
+	if attempts != 2 {
+		t.Errorf("attempts = %d, want 2", attempts)
+	}
+}
+
+func TestDoRequest_429_RetryAfter_HTTPDate_InPast(t *testing.T) {
+	// If the HTTP-date is in the past, delay should be 0 (retry immediately).
+	fixedNow := time.Date(2025, 12, 1, 17, 0, 0, 0, time.UTC)
+	retryAt := "Mon, 01 Dec 2025 16:00:00 GMT" // 1 hour in the past
+
+	attempts := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		if attempts == 1 {
+			w.Header().Set("Retry-After", retryAt)
+			w.WriteHeader(http.StatusTooManyRequests)
+			w.Write([]byte("rate limited"))
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("success"))
+	}))
+	defer srv.Close()
+
+	c := NewClient("tok", srv.URL, AllowInsecureHTTPForTest())
+	c.now = func() time.Time { return fixedNow }
+	c.SetRetryBackoff([]time.Duration{0, 0})
+
+	body, err := c.doGet(context.Background(), srv.URL+"/test")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if string(body) != "success" {
+		t.Errorf("body = %q, want %q", body, "success")
+	}
+}
+
+func TestDoRequest_429_NoRetryAfter_UsesDefaultBackoff(t *testing.T) {
+	attempts := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		if attempts == 1 {
+			w.WriteHeader(http.StatusTooManyRequests)
+			w.Write([]byte("rate limited"))
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("success"))
+	}))
+	defer srv.Close()
+
+	c := NewClient("tok", srv.URL, AllowInsecureHTTPForTest())
+	c.SetRetryBackoff([]time.Duration{0, 0})
+
+	body, err := c.doGet(context.Background(), srv.URL+"/test")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if string(body) != "success" {
+		t.Errorf("body = %q, want %q", body, "success")
+	}
+	if attempts != 2 {
+		t.Errorf("attempts = %d, want 2", attempts)
+	}
+}
+
+func TestDoRequest_429_InvalidRetryAfter_UsesDefaultBackoff(t *testing.T) {
+	attempts := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		if attempts == 1 {
+			w.Header().Set("Retry-After", "not-a-number-or-date")
+			w.WriteHeader(http.StatusTooManyRequests)
+			w.Write([]byte("rate limited"))
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("success"))
+	}))
+	defer srv.Close()
+
+	c := NewClient("tok", srv.URL, AllowInsecureHTTPForTest())
+	c.SetRetryBackoff([]time.Duration{0, 0})
+
+	body, err := c.doGet(context.Background(), srv.URL+"/test")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if string(body) != "success" {
+		t.Errorf("body = %q, want %q", body, "success")
+	}
+}
+
+func TestDoRequest_404_NoRetry(t *testing.T) {
+	attempts := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		w.WriteHeader(http.StatusNotFound)
+		w.Write([]byte("not found"))
+	}))
+	defer srv.Close()
+
+	c := NewClient("tok", srv.URL, AllowInsecureHTTPForTest())
+	_, err := c.doGet(context.Background(), srv.URL+"/test")
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !IsNotFound(err) {
+		t.Errorf("expected IsNotFound, got %v", err)
+	}
+	if attempts != 1 {
+		t.Errorf("attempts = %d, want 1 (no retry on 404)", attempts)
+	}
+}
+
+func TestDoRequest_401_NoRetry(t *testing.T) {
+	attempts := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		w.WriteHeader(http.StatusUnauthorized)
+		w.Write([]byte("unauthorized"))
+	}))
+	defer srv.Close()
+
+	c := NewClient("tok", srv.URL, AllowInsecureHTTPForTest())
+	_, err := c.doGet(context.Background(), srv.URL+"/test")
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !IsUnauthorized(err) {
+		t.Errorf("expected IsUnauthorized, got %v", err)
+	}
+	if attempts != 1 {
+		t.Errorf("attempts = %d, want 1 (no retry on 401)", attempts)
+	}
+}
+
+func TestDoRequest_ContextCanceled(t *testing.T) {
+	// This test exercises the timer-cancel path in the retry select:
+	//   select { case <-timer.C; case <-ctx.Done() }
+	// The server returns 429 with a long Retry-After, and we cancel the
+	// context shortly after the first response so that cancellation races
+	// against the timer rather than preventing the initial HTTP round-trip.
+	requestReceived := make(chan struct{}, 1)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		select {
+		case requestReceived <- struct{}{}:
+		default:
+		}
+		w.Header().Set("Retry-After", "10")
+		w.WriteHeader(http.StatusTooManyRequests)
+	}))
+	defer srv.Close()
+
+	c := NewClient("tok", srv.URL, AllowInsecureHTTPForTest())
+	c.SetRetryBackoff([]time.Duration{10 * time.Second, 10 * time.Second})
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	// Cancel the context after the first request completes, while the
+	// client is blocked in the retry timer select.
+	go func() {
+		<-requestReceived
+		// Small delay to ensure we're inside the timer select.
+		time.Sleep(50 * time.Millisecond)
+		cancel()
+	}()
+
+	_, err := c.doGet(ctx, srv.URL+"/test")
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !errors.Is(err, context.Canceled) {
+		t.Errorf("err = %v, want context.Canceled", err)
+	}
+}
+
+func TestParseRetryAfter_IntegerSeconds(t *testing.T) {
+	c := NewClient("tok", "")
+	delay, ok := c.parseRetryAfter("42")
+	if !ok {
+		t.Fatal("expected ok=true")
+	}
+	if delay != 42*time.Second {
+		t.Errorf("delay = %v, want 42s", delay)
+	}
+}
+
+func TestParseRetryAfter_ZeroSeconds(t *testing.T) {
+	c := NewClient("tok", "")
+	delay, ok := c.parseRetryAfter("0")
+	if !ok {
+		t.Fatal("expected ok=true for zero seconds (RFC 7231 allows immediate retry)")
+	}
+	if delay != 0 {
+		t.Errorf("delay = %v, want 0", delay)
+	}
+}
+
+func TestParseRetryAfter_NegativeSeconds(t *testing.T) {
+	c := NewClient("tok", "")
+	_, ok := c.parseRetryAfter("-5")
+	if ok {
+		t.Error("expected ok=false for negative seconds")
+	}
+}
+
+func TestParseRetryAfter_HTTPDate_Future(t *testing.T) {
+	fixedNow := time.Date(2025, 12, 1, 15, 59, 50, 0, time.UTC)
+	c := NewClient("tok", "")
+	c.now = func() time.Time { return fixedNow }
+
+	delay, ok := c.parseRetryAfter("Mon, 01 Dec 2025 16:00:00 GMT")
+	if !ok {
+		t.Fatal("expected ok=true")
+	}
+	// Should be 10 seconds in the future.
+	if delay != 10*time.Second {
+		t.Errorf("delay = %v, want 10s", delay)
+	}
+}
+
+func TestParseRetryAfter_HTTPDate_Past(t *testing.T) {
+	fixedNow := time.Date(2025, 12, 1, 17, 0, 0, 0, time.UTC)
+	c := NewClient("tok", "")
+	c.now = func() time.Time { return fixedNow }
+
+	delay, ok := c.parseRetryAfter("Mon, 01 Dec 2025 16:00:00 GMT")
+	if !ok {
+		t.Fatal("expected ok=true")
+	}
+	if delay != 0 {
+		t.Errorf("delay = %v, want 0 (past date)", delay)
+	}
+}
+
+func TestParseRetryAfter_RFC850_Format(t *testing.T) {
+	fixedNow := time.Date(2025, 12, 1, 15, 59, 50, 0, time.UTC)
+	c := NewClient("tok", "")
+	c.now = func() time.Time { return fixedNow }
+
+	// RFC 850 format
+	delay, ok := c.parseRetryAfter("Monday, 01-Dec-25 16:00:00 GMT")
+	if !ok {
+		t.Fatal("expected ok=true for RFC 850 format")
+	}
+	if delay != 10*time.Second {
+		t.Errorf("delay = %v, want 10s", delay)
+	}
+}
+
+func TestParseRetryAfter_Invalid(t *testing.T) {
+	c := NewClient("tok", "")
+	_, ok := c.parseRetryAfter("not-valid")
+	if ok {
+		t.Error("expected ok=false for invalid value")
+	}
+}
+
+func TestParseRetryAfter_EmptyString(t *testing.T) {
+	c := NewClient("tok", "")
+	_, ok := c.parseRetryAfter("")
+	if ok {
+		t.Error("expected ok=false for empty string")
+	}
+}
+
+func TestParseRetryAfter_MaxCap(t *testing.T) {
+	// Verify that parseRetryAfter returns the raw value (capping is done by caller).
+	c := NewClient("tok", "")
+	delay, ok := c.parseRetryAfter("3600")
+	if !ok {
+		t.Fatal("expected ok=true")
+	}
+	if delay != 3600*time.Second {
+		t.Errorf("delay = %v, want 3600s (caller is responsible for capping)", delay)
+	}
+}
+
+func TestAPIError_Error_Truncation(t *testing.T) {
+	longBody := make([]byte, 300)
+	for i := range longBody {
+		longBody[i] = 'x'
+	}
+	apiErr := &APIError{StatusCode: 500, Body: string(longBody)}
+	msg := apiErr.Error()
+	if len(msg) > 250 {
+		// "HTTP 500: " (10) + 200 + "...(truncated)" (14) = 224
+		t.Errorf("error message too long: %d chars", len(msg))
+	}
+}
+
+func TestAPIError_Error_NewlineSanitized(t *testing.T) {
+	apiErr := &APIError{StatusCode: 400, Body: "line1\nline2\rline3"}
+	msg := apiErr.Error()
+	for _, c := range msg {
+		if c == '\n' || c == '\r' {
+			t.Errorf("error message contains unsanitized newline: %q", msg)
+			break
+		}
+	}
+}
+
+func TestNewClient_HasCheckRedirect(t *testing.T) {
+	c := NewClient("secret-token", "https://api.github.com")
+	if c.httpClient.CheckRedirect == nil {
+		t.Fatal("expected CheckRedirect to be set")
+	}
+}
+
+func TestDefaultCheckRedirect_RejectsHTTPSToHTTP(t *testing.T) {
+	prev := &http.Request{URL: &url.URL{Scheme: "https", Host: "api.github.com", Path: "/foo"}}
+	req := &http.Request{
+		URL:    &url.URL{Scheme: "http", Host: "api.github.com", Path: "/foo"},
+		Header: http.Header{"Authorization": []string{"Bearer token"}},
+	}
+	err := defaultCheckRedirect(req, []*http.Request{prev})
+	if err == nil {
+		t.Fatal("expected error on HTTPS->HTTP redirect")
+	}
+	if !strings.Contains(err.Error(), "HTTPS to HTTP downgrade") {
+		t.Errorf("unexpected error message: %v", err)
+	}
+}
+
+func TestDefaultCheckRedirect_RejectsCrossHost(t *testing.T) {
+	prev := &http.Request{URL: &url.URL{Scheme: "https", Host: "api.github.com", Path: "/foo"}}
+	req := &http.Request{
+		URL:    &url.URL{Scheme: "https", Host: "objects.githubusercontent.com", Path: "/bar"},
+		Header: http.Header{"Authorization": []string{"Bearer token"}},
+	}
+	err := defaultCheckRedirect(req, []*http.Request{prev})
+	if err == nil {
+		t.Fatal("expected error on cross-host redirect")
+	}
+	if !strings.Contains(err.Error(), "cross-host") {
+		t.Errorf("unexpected error message: %v", err)
+	}
+}
+
+func TestDefaultCheckRedirect_AllowsSameHost(t *testing.T) {
+	prev := &http.Request{URL: &url.URL{Scheme: "https", Host: "api.github.com", Path: "/foo"}}
+	req := &http.Request{
+		URL:    &url.URL{Scheme: "https", Host: "api.github.com", Path: "/bar"},
+		Header: http.Header{"Authorization": []string{"Bearer token"}},
+	}
+	err := defaultCheckRedirect(req, []*http.Request{prev})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	// Auth should be preserved on same-host redirect
+	if auth := req.Header.Get("Authorization"); auth != "Bearer token" {
+		t.Errorf("expected Authorization to be preserved, got %q", auth)
+	}
+}
+
+func TestDefaultCheckRedirect_AllowsSameHostHTTPToHTTP(t *testing.T) {
+	prev := &http.Request{URL: &url.URL{Scheme: "http", Host: "localhost:8080", Path: "/foo"}}
+	req := &http.Request{
+		URL:    &url.URL{Scheme: "http", Host: "localhost:8080", Path: "/bar"},
+		Header: http.Header{},
+	}
+	err := defaultCheckRedirect(req, []*http.Request{prev})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestDefaultCheckRedirect_RejectsTooManyRedirects(t *testing.T) {
+	via := make([]*http.Request, 10)
+	for i := range via {
+		via[i] = &http.Request{URL: &url.URL{Scheme: "https", Host: "api.github.com", Path: "/"}}
+	}
+	req := &http.Request{URL: &url.URL{Scheme: "https", Host: "api.github.com", Path: "/final"}}
+	err := defaultCheckRedirect(req, via)
+	if err == nil {
+		t.Fatal("expected error after 10 redirects")
+	}
+	if !strings.Contains(err.Error(), "10 redirects") {
+		t.Errorf("unexpected error message: %v", err)
+	}
+}
+
+func TestDefaultCheckRedirect_EmptyViaAllowed(t *testing.T) {
+	req := &http.Request{URL: &url.URL{Scheme: "https", Host: "api.github.com", Path: "/foo"}}
+	err := defaultCheckRedirect(req, nil)
+	if err != nil {
+		t.Fatalf("unexpected error with empty via: %v", err)
+	}
+}
+
+func TestSetHTTPClient_NilRestoresDefault(t *testing.T) {
+	c := NewClient("token", "https://api.github.com")
+	c.SetHTTPClient(nil)
+	if c.httpClient == nil {
+		t.Fatal("expected non-nil httpClient after SetHTTPClient(nil)")
+	}
+	if c.httpClient.Timeout != 30*time.Second {
+		t.Errorf("expected 30s timeout, got %v", c.httpClient.Timeout)
+	}
+	if c.httpClient.CheckRedirect == nil {
+		t.Fatal("expected CheckRedirect policy after SetHTTPClient(nil)")
+	}
+}
+
+func TestAllowInsecureHTTPForTest_PermitsHTTP(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("ok"))
+	}))
+	defer srv.Close()
+
+	c := NewClient("tok", srv.URL, AllowInsecureHTTPForTest())
+	body, err := c.doGet(context.Background(), srv.URL+"/test")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if string(body) != "ok" {
+		t.Errorf("body = %q, want %q", body, "ok")
+	}
+}
+
+func TestNoInsecureOption_RejectsHTTP(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatal("request should not have been sent")
+	}))
+	defer srv.Close()
+
+	c := NewClient("tok", srv.URL)
+	_, err := c.doGet(context.Background(), srv.URL+"/test")
+	if err == nil {
+		t.Fatal("expected error for HTTP request without AllowInsecureHTTP")
+	}
+	if !strings.Contains(err.Error(), "refusing HTTP request") {
+		t.Errorf("unexpected error message: %v", err)
+	}
+}
+
+func TestNoInsecureOption_RejectsUppercaseHTTP(t *testing.T) {
+	// Verify case-insensitive scheme check (RFC 3986).
+	c := NewClient("tok", "HTTP://127.0.0.1:1")
+	_, err := c.doGet(context.Background(), "HTTP://127.0.0.1:1/test")
+	if err == nil {
+		t.Fatal("expected error for uppercase HTTP scheme")
+	}
+	if !strings.Contains(err.Error(), "refusing HTTP request") {
+		t.Errorf("unexpected error message: %v", err)
+	}
+}
+
+func TestNoInsecureOption_RejectsMixedCaseHTTP(t *testing.T) {
+	// Verify mixed case like "Http://" is also rejected.
+	c := NewClient("tok", "Http://127.0.0.1:1")
+	_, err := c.doGet(context.Background(), "Http://127.0.0.1:1/test")
+	if err == nil {
+		t.Fatal("expected error for mixed-case HTTP scheme")
+	}
+	if !strings.Contains(err.Error(), "refusing HTTP request") {
+		t.Errorf("unexpected error message: %v", err)
+	}
+}
+
+func TestAllowInsecureHTTP_WithoutEnvVar_Rejected(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatal("request should not have been sent")
+	}))
+	defer srv.Close()
+
+	t.Setenv("REVIEW_BOT_ALLOW_INSECURE", "")
+
+	c := NewClient("tok", srv.URL, AllowInsecureHTTP())
+	_, err := c.doGet(context.Background(), srv.URL+"/test")
+	if err == nil {
+		t.Fatal("expected error: AllowInsecureHTTP without env var should be rejected")
+	}
+	if !strings.Contains(err.Error(), "refusing HTTP request") {
+		t.Errorf("unexpected error message: %v", err)
+	}
+}
+
+func TestAllowInsecureHTTP_WithEnvVar_Permitted(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("insecure-ok"))
+	}))
+	defer srv.Close()
+
+	t.Setenv("REVIEW_BOT_ALLOW_INSECURE", "1")
+
+	c := NewClient("tok", srv.URL, AllowInsecureHTTP())
+	body, err := c.doGet(context.Background(), srv.URL+"/test")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if string(body) != "insecure-ok" {
+		t.Errorf("body = %q, want %q", body, "insecure-ok")
+	}
+}
+
+func TestAllowInsecureHTTP_EnvVarNotOne_Rejected(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatal("request should not have been sent")
+	}))
+	defer srv.Close()
+
+	// "true" is not "1" — strict check
+	t.Setenv("REVIEW_BOT_ALLOW_INSECURE", "true")
+
+	c := NewClient("tok", srv.URL, AllowInsecureHTTP())
+	_, err := c.doGet(context.Background(), srv.URL+"/test")
+	if err == nil {
+		t.Fatal("expected error: env var 'true' is not '1'")
+	}
+	if !strings.Contains(err.Error(), "refusing HTTP request") {
+		t.Errorf("unexpected error message: %v", err)
+	}
+}
+
+func TestRedactURL_WithQuery(t *testing.T) {
+	got := redactURL("http://localhost:1234/path?secret=token&foo=bar")
+	want := "http://localhost:1234/path?<redacted>"
+	if got != want {
+		t.Errorf("redactURL = %q, want %q", got, want)
+	}
+}
+
+func TestRedactURL_NoQuery(t *testing.T) {
+	got := redactURL("http://localhost:1234/path")
+	want := "http://localhost:1234/path"
+	if got != want {
+		t.Errorf("redactURL = %q, want %q", got, want)
+	}
+}
+
+func TestRedactURL_Userinfo(t *testing.T) {
+	got := redactURL("http://user:pass@localhost:1234/path")
+	want := "http://localhost:1234/path"
+	if got != want {
+		t.Errorf("redactURL = %q, want %q", got, want)
+	}
+}
+
+func TestRedactURL_UserinfoWithQuery(t *testing.T) {
+	got := redactURL("http://user:pass@localhost:1234/path?secret=token")
+	want := "http://localhost:1234/path?<redacted>"
+	if got != want {
+		t.Errorf("redactURL = %q, want %q", got, want)
+	}
+}

github/export_test.go

@@ -0,0 +1,13 @@
+package github
+
+// AllowInsecureHTTPForTest permits sending credentials over plaintext HTTP
+// without requiring the REVIEW_BOT_ALLOW_INSECURE environment variable.
+// This is intended exclusively for test code using httptest.Server.
+//
+// Defined in a _test.go file so it is only available to test binaries.
+func AllowInsecureHTTPForTest() ClientOption {
+	return func(cfg *clientConfig) {
+		cfg.allowInsecureHTTP = true
+		cfg.insecureIsTestBypass = true
+	}
+}

go.mod

@@ -1,3 +1,5 @@
 module gitea.weiker.me/rodin/review-bot
 
 go 1.26.2
+
+require github.com/goccy/go-yaml v1.19.2

go.sum

@@ -0,0 +1,2 @@
+github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM=
+github.com/goccy/go-yaml v1.19.2/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=

integration_test.go

@@ -16,16 +16,17 @@ import (
 
 // Integration test requires a running Gitea instance and LLM endpoint.
 // Set environment variables:
-//   INTEGRATION_GITEA_URL     - Gitea base URL
-//   INTEGRATION_GITEA_TOKEN   - Gitea API token with repo access
-//   INTEGRATION_GITEA_REPO    - owner/repo with an open PR
-//   INTEGRATION_PR_NUMBER     - PR number to test against
-//   INTEGRATION_LLM_BASE_URL  - LLM API base URL
-//   INTEGRATION_LLM_API_KEY   - LLM API key
-//   INTEGRATION_LLM_MODEL     - Model name
+//
+//	INTEGRATION_VCS_URL       - VCS base URL
+//	INTEGRATION_GITEA_TOKEN   - Gitea API token with repo access
+//	INTEGRATION_GITEA_REPO    - owner/repo with an open PR
+//	INTEGRATION_PR_NUMBER     - PR number to test against
+//	INTEGRATION_LLM_BASE_URL  - LLM API base URL
+//	INTEGRATION_LLM_API_KEY   - LLM API key
+//	INTEGRATION_LLM_MODEL     - Model name
 
 func TestIntegration_FullReviewFlow(t *testing.T) {
-	giteaURL := os.Getenv("INTEGRATION_GITEA_URL")
+	giteaURL := os.Getenv("INTEGRATION_VCS_URL")
 	giteaToken := os.Getenv("INTEGRATION_GITEA_TOKEN")
 	giteaRepo := os.Getenv("INTEGRATION_GITEA_REPO")
 	prNumStr := os.Getenv("INTEGRATION_PR_NUMBER")

review/persona.go

@@ -1,81 +1,163 @@
 package review
 
 import (
+	"bytes"
 	"embed"
 	"encoding/json"
 	"fmt"
+	"io"
 	"os"
+	"sort"
 	"strings"
 	"unicode/utf8"
+
+	"github.com/goccy/go-yaml"
+	"github.com/goccy/go-yaml/ast"
+	"github.com/goccy/go-yaml/parser"
 )
 
-//go:embed personas/*.json
+//go:embed personas/*.yaml
 var embeddedPersonas embed.FS
 
+// MaxPersonaFileSize is the maximum size for persona files (64 KB).
+// This prevents denial-of-service via excessively large files.
+const MaxPersonaFileSize = 64 * 1024
+
+// MaxYAMLDepth is the maximum nesting depth allowed in YAML persona files.
+// This prevents stack exhaustion from deeply nested structures.
+const MaxYAMLDepth = 20
+
+// MaxYAMLNodes is the maximum number of YAML nodes allowed in persona files.
+// This prevents DoS via wide-but-shallow structures that bypass depth limits.
+const MaxYAMLNodes = 1000
+
 // Persona defines a specialized review role with focused expertise.
 type Persona struct {
-	Name         string   `json:"name"`
-	DisplayName  string   `json:"display_name"`
-	ModelPref    string   `json:"model_preference,omitempty"`
-	Identity     string   `json:"identity"`
-	Focus        []string `json:"focus"`
-	Ignore       []string `json:"ignore"`
-	Severity     Severity `json:"severity"`
-	OutputFormat string   `json:"output_format,omitempty"`
+	Name         string   `json:"name" yaml:"name"`
+	DisplayName  string   `json:"display_name" yaml:"display_name"`
+	ModelPref    string   `json:"model_preference,omitempty" yaml:"model_preference,omitempty"`
+	Identity     string   `json:"identity" yaml:"identity"`
+	Focus        []string `json:"focus" yaml:"focus"`
+	Ignore       []string `json:"ignore" yaml:"ignore"`
+	Severity     Severity `json:"severity" yaml:"severity"`
+	OutputFormat string   `json:"output_format,omitempty" yaml:"output_format,omitempty"`
 }
 
 // Severity defines what constitutes each severity level for this persona.
 // These are prompt guidance for the LLM, not output format changes.
 type Severity struct {
-	Major string `json:"major"`
-	Minor string `json:"minor"`
-	Nit   string `json:"nit"`
+	Major string `json:"major" yaml:"major"`
+	Minor string `json:"minor" yaml:"minor"`
+	Nit   string `json:"nit" yaml:"nit"`
 }
 
-// LoadPersona loads a persona from a JSON file path.
+// LoadPersona loads a persona from a JSON or YAML file path.
+// Format is detected by file extension: .yaml/.yml for YAML, .json or other for JSON.
+// Files larger than MaxPersonaFileSize are rejected.
+//
+// Symlinks are supported: os.Stat follows symlinks, so a symlink pointing to
+// a regular file will pass the IsRegular() check. Symlinks to non-regular files
+// (directories, FIFOs, devices) are still rejected.
 func LoadPersona(path string) (*Persona, error) {
+	// os.Stat follows symlinks, so symlinks to regular files are supported.
+	// The IsRegular() check operates on the target, not the symlink itself.
+	info, err := os.Stat(path)
+	if err != nil {
+		return nil, fmt.Errorf("read persona file %s: %w", path, err)
+	}
+	if !info.Mode().IsRegular() {
+		return nil, fmt.Errorf("persona file %s is not a regular file", path)
+	}
+	if info.Size() > MaxPersonaFileSize {
+		return nil, fmt.Errorf("persona file %s exceeds maximum size (%d bytes)", path, MaxPersonaFileSize)
+	}
 	data, err := os.ReadFile(path)
 	if err != nil {
 		return nil, fmt.Errorf("read persona file %s: %w", path, err)
 	}
+	// Re-check size after read to defend against TOCTOU races where file
+	// grows between stat and read (e.g., appending process, replaced file).
+	if len(data) > MaxPersonaFileSize {
+		return nil, fmt.Errorf("persona file %s exceeds maximum size (%d bytes)", path, MaxPersonaFileSize)
+	}
 	return parsePersona(data, path)
 }
 
 // LoadBuiltinPersona loads a built-in persona by name.
 // Returns an error if the persona doesn't exist.
+// Built-in personas are stored in YAML format only (see embed directive).
 func LoadBuiltinPersona(name string) (*Persona, error) {
-	filename := name + ".json"
-	data, err := embeddedPersonas.ReadFile("personas/" + filename) // embed.FS paths use forward slashes per io/fs spec
+	yamlFile := name + ".yaml"
+	data, err := embeddedPersonas.ReadFile("personas/" + yamlFile)
 	if err != nil {
 		available := ListBuiltinPersonas()
 		return nil, fmt.Errorf("unknown built-in persona %q (available: %s)", name, strings.Join(available, ", "))
 	}
-	return parsePersona(data, "builtin:"+name)
+	return parsePersona(data, "builtin:"+yamlFile)
 }
 
-// ListBuiltinPersonas returns the names of all built-in personas.
+// ListBuiltinPersonas returns the names of all built-in personas in sorted order.
 // Returns an empty slice if the embedded directory cannot be read.
 func ListBuiltinPersonas() []string {
 	entries, err := embeddedPersonas.ReadDir("personas")
 	if err != nil {
 		return []string{}
 	}
-	var names []string
+	seen := make(map[string]bool)
 	for _, e := range entries {
 		if e.IsDir() {
 			continue
 		}
 		name := e.Name()
-		if strings.HasSuffix(name, ".json") {
-			names = append(names, strings.TrimSuffix(name, ".json"))
+		// Strip extension to get persona name
+		var personaName string
+		switch {
+		case strings.HasSuffix(name, ".yaml"):
+			personaName = strings.TrimSuffix(name, ".yaml")
+		case strings.HasSuffix(name, ".yml"):
+			personaName = strings.TrimSuffix(name, ".yml")
+		case strings.HasSuffix(name, ".json"):
+			personaName = strings.TrimSuffix(name, ".json")
+		default:
+			continue
 		}
+		seen[personaName] = true
 	}
+	names := make([]string, 0, len(seen))
+	for name := range seen {
+		names = append(names, name)
+	}
+	sort.Strings(names)
 	return names
 }
 
+// parsePersona parses persona data from JSON or YAML format.
+// Format is detected by the source file extension.
 func parsePersona(data []byte, source string) (*Persona, error) {
+	lowerSource := strings.ToLower(source)
+	isYAML := strings.HasSuffix(lowerSource, ".yaml") || strings.HasSuffix(lowerSource, ".yml")
+
 	var p Persona
-	if err := json.Unmarshal(data, &p); err != nil {
+	var err error
+	if isYAML {
+		err = unmarshalYAMLWithDepthLimit(data, &p, MaxYAMLDepth)
+	} else {
+		// Use json.Decoder with DisallowUnknownFields for consistency with
+		// YAML's Strict() - both reject unknown fields to catch typos.
+		dec := json.NewDecoder(bytes.NewReader(data))
+		dec.DisallowUnknownFields()
+		err = dec.Decode(&p)
+		if err == nil {
+			// Reject trailing content after the first valid JSON object.
+			// Without this check, input like `{"name":"x"}garbage` would
+			// silently succeed because Decoder stops after one object.
+			var dummy json.RawMessage
+			if err2 := dec.Decode(&dummy); err2 != io.EOF {
+				err = fmt.Errorf("unexpected trailing content after JSON object")
+			}
+		}
+	}
+	if err != nil {
 		return nil, fmt.Errorf("parse persona %s: %w", source, err)
 	}
 	if err := validatePersona(&p, source); err != nil {
@@ -84,6 +166,179 @@ func parsePersona(data []byte, source string) (*Persona, error) {
 	return &p, nil
 }
 
+// unmarshalYAMLWithDepthLimit unmarshals YAML data with three safety checks:
+//   - Depth limiting: rejects AST trees exceeding maxDepth to prevent stack exhaustion.
+//   - Multi-document rejection: prevents silent data loss from ignored extra documents.
+//   - Strict field checking: rejects unknown YAML keys to catch typos early.
+func unmarshalYAMLWithDepthLimit(data []byte, out any, maxDepth int) error {
+	// First pass: parse into AST to check depth limits, node counts, and
+	// multi-document rejection. This prevents stack exhaustion before we
+	// attempt to decode into structs.
+	file, err := parser.ParseBytes(data, 0)
+	if err != nil {
+		return err
+	}
+
+	// Reject empty YAML input (whitespace-only, comment-only, or truly empty files).
+	// The parser returns a single doc with nil body for these cases.
+	if len(file.Docs) == 0 || file.Docs[0].Body == nil {
+		return fmt.Errorf("empty YAML document")
+	}
+
+	// Reject multi-document YAML files - silently ignoring additional documents
+	// could lead to confusing behavior where users think their changes take effect.
+	if len(file.Docs) > 1 {
+		return fmt.Errorf("multi-document YAML is not supported; only single-document files are allowed")
+	}
+
+	nodeCount := 0
+	if err := checkYAMLDepth(file.Docs[0].Body, 0, maxDepth, MaxYAMLNodes, make(map[ast.Node]int), make(map[ast.Node]bool), &nodeCount); err != nil {
+		return err
+	}
+
+	// Second pass: decode with strict field checking enabled.
+	// Strict() rejects unknown keys, catching typos like "focuss" or "identiy".
+	//
+	// Safety note: goccy/go-yaml's decoder does not expand YAML aliases
+	// recursively — it resolves them via the pre-built AST, which our first
+	// pass already depth-checked. Alias chains that would exceed depth limits
+	// are caught above; the decoder merely reads the resolved scalar values.
+	dec := yaml.NewDecoder(bytes.NewReader(data), yaml.Strict())
+	return dec.Decode(out)
+}
+
+// checkYAMLDepth recursively checks that YAML AST nodes don't exceed the depth
+// limit or the total node count limit. It uses two tracking maps:
+//   - validated: maps each node to the maximum depth at which it was previously
+//     checked. If a node is revisited at a deeper depth (e.g., via an alias),
+//     we re-check it to ensure the combined effective depth doesn't exceed limits.
+//   - visiting: per-path recursion stack for true cycle detection. A node on the
+//     current path is a cycle (alias loop); we return nil to avoid infinite recursion.
+//
+// This design prevents the alias depth bypass where an anchored subtree validated
+// at a shallow depth could be referenced via alias at a greater depth, effectively
+// exceeding MaxYAMLDepth.
+func checkYAMLDepth(node ast.Node, depth, maxDepth, maxNodes int, validated map[ast.Node]int, visiting map[ast.Node]bool, nodeCount *int) error {
+	if node == nil {
+		return nil
+	}
+
+	if depth > maxDepth {
+		return fmt.Errorf("YAML nesting depth exceeds maximum (%d)", maxDepth)
+	}
+
+	// Cycle detection: if we're currently visiting this node on the current
+	// recursion path, it's a cycle (e.g., alias pointing to an ancestor).
+	// Return nil to break the cycle without error — cycles are a structural
+	// property, not a depth violation.
+	if visiting[node] {
+		return nil
+	}
+
+	// Track total nodes visited as defense-in-depth against wide-but-shallow attacks.
+	// Placed after cycle detection but before the depth-aware short-circuit. This means
+	// nodes revisited at shallower depths (via aliases) are counted each time they are
+	// encountered — intentional conservative overcounting. This bounds the total work
+	// performed during validation rather than tracking unique nodes, which is the safer
+	// security posture for untrusted YAML input.
+	*nodeCount++
+	if *nodeCount > maxNodes {
+		return fmt.Errorf("YAML node count exceeds maximum (%d)", maxNodes)
+	}
+
+	// Depth-aware short-circuit: skip re-validation only when the current visit
+	// depth is the same or shallower than the depth at which this node was
+	// previously validated. A shallower (or equal) current depth means the
+	// prior, deeper validation already covered any subtree depth violations.
+	// If the current depth exceeds the previous validation depth (e.g., an alias
+	// references this node deeper in the tree), we must re-traverse to ensure
+	// the combined effective depth doesn't exceed maxDepth.
+	//
+	// Note: using ast.Node (interface) as map key relies on pointer identity,
+	// which is correct because all goccy/go-yaml AST node types are pointer
+	// receivers (*MappingNode, *SequenceNode, etc.), never value types.
+	if prevDepth, ok := validated[node]; ok && depth <= prevDepth {
+		return nil
+	}
+	validated[node] = depth
+
+	// Mark as visiting (on the current recursion path) for cycle detection.
+	visiting[node] = true
+	defer func() { visiting[node] = false }()
+
+	// Walk children based on node type.
+	switch n := node.(type) {
+	case *ast.MappingNode:
+		for _, value := range n.Values {
+			if err := checkYAMLDepth(value, depth+1, maxDepth, maxNodes, validated, visiting, nodeCount); err != nil {
+				return err
+			}
+		}
+	case *ast.MappingValueNode:
+		// Both Key and Value are visited at depth+1 relative to this
+		// MappingValueNode. Since MappingNode visits its MappingValueNode
+		// children at depth+1 as well, keys and values end up at depth+2
+		// from the parent MappingNode. This is intentional: it mirrors the
+		// actual nesting structure (mapping → key-value pair → key/value).
+		if err := checkYAMLDepth(n.Key, depth+1, maxDepth, maxNodes, validated, visiting, nodeCount); err != nil {
+			return err
+		}
+		if err := checkYAMLDepth(n.Value, depth+1, maxDepth, maxNodes, validated, visiting, nodeCount); err != nil {
+			return err
+		}
+	case *ast.SequenceNode:
+		for _, value := range n.Values {
+			if err := checkYAMLDepth(value, depth+1, maxDepth, maxNodes, validated, visiting, nodeCount); err != nil {
+				return err
+			}
+		}
+	case *ast.AliasNode:
+		// Follow alias to its target, incrementing depth since aliases expand
+		// the effective structure.
+		if err := checkYAMLDepth(n.Value, depth+1, maxDepth, maxNodes, validated, visiting, nodeCount); err != nil {
+			return err
+		}
+	case *ast.AnchorNode:
+		// Increment depth for anchor values as a conservative measure: the
+		// anchor definition itself is structural, and treating it as a depth
+		// level ensures that deeply nested anchors are caught at definition
+		// time rather than only when referenced via alias. This +1 is
+		// asymmetric with alias (which also increments) — by design, the
+		// effective depth budget for anchored-then-aliased content is reduced
+		// because both the definition site and the reference site each consume
+		// a level, making deeply nested anchor/alias pairs hit the limit sooner.
+		if err := checkYAMLDepth(n.Value, depth+1, maxDepth, maxNodes, validated, visiting, nodeCount); err != nil {
+			return err
+		}
+	case *ast.TagNode:
+		if err := checkYAMLDepth(n.Value, depth+1, maxDepth, maxNodes, validated, visiting, nodeCount); err != nil {
+			return err
+		}
+	case *ast.MergeKeyNode:
+		// MergeKeyNode represents the literal "<<" merge key token. It has no
+		// child nodes — the value side of a merge (e.g., *alias) lives in the
+		// parent MappingValueNode.Value, which is already recursed into above.
+		// Explicitly listed here (rather than in the default case) to prevent
+		// future library changes from silently bypassing depth checks.
+	default:
+		// Scalar leaf nodes (StringNode, IntegerNode, FloatNode, BoolNode,
+		// NullNode, InfinityNode, NanNode, LiteralNode) have no children to
+		// recurse into.
+	}
+	return nil
+}
+
+// ParsePersonaBytes parses persona data from bytes with a source label for errors.
+// This is useful for parsing personas fetched from external sources (e.g., Gitea API)
+// without requiring filesystem access. Format is detected by source extension.
+// Input is bounded by MaxPersonaFileSize to prevent resource exhaustion.
+func ParsePersonaBytes(data []byte, source string) (*Persona, error) {
+	if len(data) > MaxPersonaFileSize {
+		return nil, fmt.Errorf("persona data from %s exceeds maximum size (%d bytes, limit %d)", source, len(data), MaxPersonaFileSize)
+	}
+	return parsePersona(data, source)
+}
+
 func validatePersona(p *Persona, source string) error {
 	if p.Name == "" {
 		return fmt.Errorf("persona %s: name is required", source)

review/persona_test.go

@@ -1,10 +1,13 @@
 package review
 
 import (
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
+
+	"github.com/goccy/go-yaml/ast"
 )
 
 func TestLoadBuiltinPersona(t *testing.T) {
@@ -87,6 +90,83 @@ func TestListBuiltinPersonas(t *testing.T) {
 	}
 }
 
+func TestLoadPersonaFromYAMLFile(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "test.yaml")
+
+	content := `# Test persona
+name: test
+display_name: Test Persona
+identity: |
+  You are a test persona.
+  Multi-line identity works.
+focus:
+  - testing
+  - validation
+ignore:
+  - nothing
+severity:
+  major: Big problems
+  minor: Small problems
+  nit: Tiny problems
+`
+
+	if err := os.WriteFile(path, []byte(content), 0644); err != nil {
+		t.Fatalf("failed to write test file: %v", err)
+	}
+
+	p, err := LoadPersona(path)
+	if err != nil {
+		t.Fatalf("LoadPersona failed: %v", err)
+	}
+
+	if p.Name != "test" {
+		t.Errorf("Name = %q, want %q", p.Name, "test")
+	}
+	if p.DisplayName != "Test Persona" {
+		t.Errorf("DisplayName = %q, want %q", p.DisplayName, "Test Persona")
+	}
+	if len(p.Focus) != 2 {
+		t.Errorf("Focus len = %d, want 2", len(p.Focus))
+	}
+	if !strings.Contains(p.Identity, "Multi-line") {
+		t.Error("Identity should contain multi-line content")
+	}
+}
+
+func TestLoadPersonaFromYMLFile(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "test.yml")
+
+	content := `name: test
+display_name: Test YML
+identity: Test identity
+focus:
+  - testing
+ignore: []
+severity:
+  major: Big
+  minor: Small
+  nit: Tiny
+`
+
+	if err := os.WriteFile(path, []byte(content), 0644); err != nil {
+		t.Fatalf("failed to write test file: %v", err)
+	}
+
+	p, err := LoadPersona(path)
+	if err != nil {
+		t.Fatalf("LoadPersona failed: %v", err)
+	}
+
+	if p.Name != "test" {
+		t.Errorf("Name = %q, want %q", p.Name, "test")
+	}
+	if p.DisplayName != "Test YML" {
+		t.Errorf("DisplayName = %q, want %q", p.DisplayName, "Test YML")
+	}
+}
+
 func TestLoadPersonaFromJSONFile(t *testing.T) {
 	dir := t.TempDir()
 	path := filepath.Join(dir, "test.json")
@@ -96,6 +176,7 @@ func TestLoadPersonaFromJSONFile(t *testing.T) {
 		"display_name": "Test Persona",
 		"identity": "You are a test persona.\nMulti-line identity works.",
 		"focus": ["testing", "validation"],
+
 		"ignore": ["nothing"],
 		"severity": {
 			"major": "Big problems",
@@ -130,22 +211,38 @@ func TestLoadPersonaFromJSONFile(t *testing.T) {
 func TestLoadPersonaValidation(t *testing.T) {
 	tests := []struct {
 		name    string
-		json    string
+		content string
+		ext     string
 		wantErr string
 	}{
 		{
-			name:    "missing name",
-			json:    `{"identity": "test"}`,
+			name:    "missing name yaml",
+			content: "identity: test\n",
+			ext:     ".yaml",
 			wantErr: "name is required",
 		},
 		{
-			name:    "missing identity",
-			json:    `{"name": "test"}`,
+			name:    "missing identity yaml",
+			content: "name: test\n",
+			ext:     ".yaml",
 			wantErr: "identity is required",
 		},
 		{
-			name: "display_name defaults to name",
-			json: `{"name": "test", "identity": "test identity"}`,
+			name:    "missing name json",
+			content: `{"identity": "test"}`,
+			ext:     ".json",
+			wantErr: "name is required",
+		},
+		{
+			name:    "missing identity json",
+			content: `{"name": "test"}`,
+			ext:     ".json",
+			wantErr: "identity is required",
+		},
+		{
+			name:    "display_name defaults to name",
+			content: "name: test\nidentity: test identity\n",
+			ext:     ".yaml",
 			// No error expected - should succeed
 		},
 	}
@@ -153,8 +250,8 @@ func TestLoadPersonaValidation(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			dir := t.TempDir()
-			path := filepath.Join(dir, "test.json")
-			if err := os.WriteFile(path, []byte(tt.json), 0644); err != nil {
+			path := filepath.Join(dir, "test"+tt.ext)
+			if err := os.WriteFile(path, []byte(tt.content), 0644); err != nil {
 				t.Fatalf("failed to write test file: %v", err)
 			}
 
@@ -184,12 +281,25 @@ func TestLoadPersonaValidation(t *testing.T) {
 }
 
 func TestLoadPersonaFileNotFound(t *testing.T) {
-	_, err := LoadPersona("/nonexistent/path/persona.json")
+	_, err := LoadPersona("/nonexistent/path/persona.yaml")
 	if err == nil {
 		t.Error("expected error for nonexistent file")
 	}
 }
 
+func TestLoadPersonaInvalidYAML(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "invalid.yaml")
+	if err := os.WriteFile(path, []byte("not valid yaml:\n  - [broken"), 0644); err != nil {
+		t.Fatalf("failed to write test file: %v", err)
+	}
+
+	_, err := LoadPersona(path)
+	if err == nil {
+		t.Error("expected error for invalid YAML")
+	}
+}
+
 func TestLoadPersonaInvalidJSON(t *testing.T) {
 	dir := t.TempDir()
 	path := filepath.Join(dir, "invalid.json")
@@ -203,6 +313,38 @@ func TestLoadPersonaInvalidJSON(t *testing.T) {
 	}
 }
 
+func TestLoadPersonaCaseInsensitiveExtension(t *testing.T) {
+	tests := []struct {
+		name string
+		ext  string
+	}{
+		{"lowercase yaml", ".yaml"},
+		{"uppercase YAML", ".YAML"},
+		{"mixed case Yaml", ".Yaml"},
+		{"lowercase yml", ".yml"},
+		{"uppercase YML", ".YML"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			dir := t.TempDir()
+			path := filepath.Join(dir, "test"+tt.ext)
+			content := "name: test\nidentity: test identity\n"
+			if err := os.WriteFile(path, []byte(content), 0644); err != nil {
+				t.Fatalf("failed to write test file: %v", err)
+			}
+
+			p, err := LoadPersona(path)
+			if err != nil {
+				t.Fatalf("LoadPersona failed for extension %s: %v", tt.ext, err)
+			}
+			if p.Name != "test" {
+				t.Errorf("Name = %q, want %q", p.Name, "test")
+			}
+		})
+	}
+}
+
 func TestCapitalizeFirst(t *testing.T) {
 	tests := []struct {
 		input string
@@ -237,3 +379,581 @@ func TestListBuiltinPersonasReturnsEmptySlice(t *testing.T) {
 		t.Error("ListBuiltinPersonas should return empty slice, not nil")
 	}
 }
+
+func TestYAMLMultilineStrings(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "multiline.yaml")
+
+	// Test literal block scalar (|) which preserves newlines
+	content := `name: multiline
+display_name: Multiline Test
+identity: |
+  First line.
+  Second line.
+  Third line.
+focus:
+  - item one
+ignore: []
+severity:
+  major: Major issue
+  minor: Minor issue
+  nit: Nit
+`
+
+	if err := os.WriteFile(path, []byte(content), 0644); err != nil {
+		t.Fatalf("failed to write test file: %v", err)
+	}
+
+	p, err := LoadPersona(path)
+	if err != nil {
+		t.Fatalf("LoadPersona failed: %v", err)
+	}
+
+	// Literal block scalar preserves newlines
+	if !strings.Contains(p.Identity, "\n") {
+		t.Error("Identity should contain newlines from literal block scalar")
+	}
+	if !strings.Contains(p.Identity, "Second line") {
+		t.Error("Identity should contain 'Second line'")
+	}
+}
+
+func TestYAMLComments(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "comments.yaml")
+
+	content := `# This is a comment
+name: commented  # inline comment
+display_name: Commented Persona
+# Another comment
+identity: Test identity
+focus:
+  - item  # comment after item
+ignore: []
+severity:
+  major: Major
+  minor: Minor
+  nit: Nit
+`
+
+	if err := os.WriteFile(path, []byte(content), 0644); err != nil {
+		t.Fatalf("failed to write test file: %v", err)
+	}
+
+	p, err := LoadPersona(path)
+	if err != nil {
+		t.Fatalf("LoadPersona failed: %v", err)
+	}
+
+	// Comments should be ignored
+	if p.Name != "commented" {
+		t.Errorf("Name = %q, want %q", p.Name, "commented")
+	}
+	if p.Focus[0] != "item" {
+		t.Errorf("Focus[0] = %q, want %q", p.Focus[0], "item")
+	}
+}
+
+func TestYAMLDeeplyNestedRejection(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "deeply-nested.yaml")
+
+	// Build a deeply nested YAML structure that exceeds MaxYAMLDepth (20).
+	// Depth accumulation trace for "nested: \n  level0: \n    level1: ...":
+	//   - Document root parsed at depth 0
+	//   - Root MappingNode children (MappingValueNodes) visited at depth 1
+	//   - "nested" MappingValueNode: key at depth 2, value at depth 2
+	//   - Each levelN adds depth via MappingValueNode traversal (key + value)
+	//   - Exact depth per level depends on AST structure (MappingNode wrapping),
+	//     but 25 levels reliably exceeds MaxYAMLDepth (20) with comfortable margin.
+	// The test uses 25 levels rather than exactly 21 to avoid brittleness.
+	var sb strings.Builder
+	sb.WriteString("name: test\nidentity: test\nnested:\n")
+	indent := "  "
+	for i := 0; i < 25; i++ {
+		sb.WriteString(strings.Repeat(indent, i+1))
+		sb.WriteString(fmt.Sprintf("level%d:\n", i))
+	}
+	sb.WriteString(strings.Repeat(indent, 26))
+	sb.WriteString("value: too-deep\n")
+
+	if err := os.WriteFile(path, []byte(sb.String()), 0644); err != nil {
+		t.Fatalf("failed to write test file: %v", err)
+	}
+
+	_, err := LoadPersona(path)
+	if err == nil {
+		t.Error("expected error for deeply nested YAML, got nil")
+	}
+	if !strings.Contains(err.Error(), "nesting depth exceeds") {
+		t.Errorf("error = %q, want containing 'nesting depth exceeds'", err.Error())
+	}
+}
+
+func TestYAMLEmptyFileRejection(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+	}{
+		{"completely_empty", ""},
+		{"whitespace_only", "   \n\n  "},
+		{"comment_only", "# just a comment\n"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			dir := t.TempDir()
+			path := filepath.Join(dir, tc.name+".yaml")
+			if err := os.WriteFile(path, []byte(tc.content), 0644); err != nil {
+				t.Fatalf("failed to write test file: %v", err)
+			}
+
+			_, err := LoadPersona(path)
+			if err == nil {
+				t.Fatal("expected error for empty YAML input, got nil")
+			}
+			if !strings.Contains(err.Error(), "empty YAML document") {
+				t.Errorf("expected error containing %q, got: %v", "empty YAML document", err)
+			}
+		})
+	}
+}
+
+func TestYAMLFileSizeLimit(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "huge.yaml")
+
+	// Create a file larger than MaxPersonaFileSize (64 KB)
+	content := "name: test\nidentity: " + strings.Repeat("x", MaxPersonaFileSize+1) + "\n"
+	if err := os.WriteFile(path, []byte(content), 0644); err != nil {
+		t.Fatalf("failed to write test file: %v", err)
+	}
+
+	_, err := LoadPersona(path)
+	if err == nil {
+		t.Error("expected error for oversized file, got nil")
+	}
+	if !strings.Contains(err.Error(), "exceeds maximum size") {
+		t.Errorf("error = %q, want containing 'exceeds maximum size'", err.Error())
+	}
+}
+
+func TestYAMLAliasCycleDetection(t *testing.T) {
+	// Test that our checkYAMLDepth function handles alias cycles gracefully
+	// by using the visiting map to prevent infinite recursion.
+
+	// Create a node structure where an alias points to a parent node,
+	// simulating what could happen with crafted input.
+	parent := &ast.MappingNode{
+		Values: []*ast.MappingValueNode{
+			{
+				Key:   &ast.StringNode{Value: "name"},
+				Value: &ast.StringNode{Value: "test"},
+			},
+		},
+	}
+
+	// Create a child that aliases back to the parent (artificial cycle)
+	aliasToParent := &ast.AliasNode{
+		Value: parent,
+	}
+	parent.Values = append(parent.Values, &ast.MappingValueNode{
+		Key:   &ast.StringNode{Value: "nested"},
+		Value: aliasToParent,
+	})
+
+	nodeCount := 0
+	validated := make(map[ast.Node]int)
+	visiting := make(map[ast.Node]bool)
+
+	// This should NOT hang or stack overflow - cycle detection prevents infinite recursion
+	err := checkYAMLDepth(parent, 0, MaxYAMLDepth, MaxYAMLNodes, validated, visiting, &nodeCount)
+	if err != nil {
+		t.Errorf("unexpected error traversing cyclic structure: %v", err)
+	}
+
+	// Verify we tracked the parent in the validated map
+	if _, ok := validated[parent]; !ok {
+		t.Error("parent node not tracked in validated map")
+	}
+}
+
+func TestYAMLMultiDocumentRejection(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "multi.yaml")
+
+	// Multi-document YAML (documents separated by ---)
+	content := `name: first
+identity: first document
+---
+name: second
+identity: second document
+`
+	if err := os.WriteFile(path, []byte(content), 0644); err != nil {
+		t.Fatalf("failed to write test file: %v", err)
+	}
+
+	_, err := LoadPersona(path)
+	if err == nil {
+		t.Error("expected error for multi-document YAML, got nil")
+	}
+	if !strings.Contains(err.Error(), "multi-document") {
+		t.Errorf("error = %q, want containing 'multi-document'", err.Error())
+	}
+}
+
+func TestYAMLNodeCountLimit(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "wide.yaml")
+
+	// Build a YAML structure that's shallow but wide - many keys at the same level
+	// to test the node count limit (should exceed MaxYAMLNodes = 1000)
+	var sb strings.Builder
+	sb.WriteString("name: test\nidentity: test\n")
+	for i := 0; i < 600; i++ {
+		sb.WriteString(fmt.Sprintf("key%d: value%d\n", i, i))
+	}
+
+	if err := os.WriteFile(path, []byte(sb.String()), 0644); err != nil {
+		t.Fatalf("failed to write test file: %v", err)
+	}
+
+	_, err := LoadPersona(path)
+	if err == nil {
+		t.Error("expected error for wide YAML exceeding node count, got nil")
+	}
+	if !strings.Contains(err.Error(), "node count exceeds") {
+		t.Errorf("error = %q, want containing 'node count exceeds'", err.Error())
+	}
+}
+
+func TestCheckYAMLDepthCycleDetectionDirect(t *testing.T) {
+	// Direct test of cycle detection in checkYAMLDepth by creating
+	// a node structure with an artificial cycle.
+	node := &ast.MappingNode{
+		Values: []*ast.MappingValueNode{
+			{
+				Key:   &ast.StringNode{Value: "key"},
+				Value: &ast.StringNode{Value: "value"},
+			},
+		},
+	}
+
+	// Create a cycle by making a child reference the parent
+	cycleChild := &ast.AliasNode{
+		Value: node, // Points back to the parent
+	}
+	node.Values = append(node.Values, &ast.MappingValueNode{
+		Key:   &ast.StringNode{Value: "cyclic"},
+		Value: cycleChild,
+	})
+
+	nodeCount := 0
+	validated := make(map[ast.Node]int)
+	visiting := make(map[ast.Node]bool)
+	err := checkYAMLDepth(node, 0, MaxYAMLDepth, MaxYAMLNodes, validated, visiting, &nodeCount)
+
+	// Should complete without infinite recursion due to cycle detection
+	if err != nil {
+		t.Errorf("unexpected error: %v", err)
+	}
+	// The validated map should contain multiple entries
+	if len(validated) < 2 {
+		t.Errorf("validated map has %d entries, expected at least 2", len(validated))
+	}
+}
+
+func TestYAMLAliasDepthBypass(t *testing.T) {
+	// Test that an anchored subtree first validated at a shallow depth is
+	// re-checked when referenced via alias at a deeper position. Without the
+	// depth-aware validated map, the alias reference would skip re-checking
+	// and allow the effective nesting to exceed MaxYAMLDepth.
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "alias-depth-bypass.yaml")
+
+	// Build YAML with an anchor at shallow depth containing a subtree near the limit,
+	// then reference it via alias deep enough that effective depth exceeds MaxYAMLDepth.
+	var sb strings.Builder
+	sb.WriteString("name: test\nidentity: test\n")
+
+	// Create the anchored subtree at depth 1 (key level) that nests 15 levels deep.
+	sb.WriteString("anchor_key: &deep_anchor\n")
+	for i := 0; i < 15; i++ {
+		sb.WriteString(strings.Repeat("  ", i+1))
+		sb.WriteString(fmt.Sprintf("level%d:\n", i))
+	}
+	sb.WriteString(strings.Repeat("  ", 16))
+	sb.WriteString("leaf: value\n")
+
+	// Create a wrapper that nests 6 levels deep, then references the anchor.
+	// Effective depth at alias target = 6 (wrapper nesting) + 1 (alias) + 15 (subtree) = 22 > 20
+	sb.WriteString("wrapper:\n")
+	for i := 0; i < 6; i++ {
+		sb.WriteString(strings.Repeat("  ", i+1))
+		sb.WriteString(fmt.Sprintf("n%d:\n", i))
+	}
+	sb.WriteString(strings.Repeat("  ", 7))
+	sb.WriteString("alias_ref: *deep_anchor\n")
+
+	if err := os.WriteFile(path, []byte(sb.String()), 0644); err != nil {
+		t.Fatalf("failed to write test file: %v", err)
+	}
+
+	_, err := LoadPersona(path)
+	if err == nil {
+		t.Fatal("expected error for alias depth bypass, got nil")
+	}
+	if !strings.Contains(err.Error(), "nesting depth exceeds") {
+		t.Errorf("error = %q, want containing 'nesting depth exceeds'", err.Error())
+	}
+}
+
+func TestListBuiltinPersonasSortedOrder(t *testing.T) {
+	names := ListBuiltinPersonas()
+	if len(names) < 2 {
+		t.Skip("need at least 2 personas to test ordering")
+	}
+
+	// Verify the list is sorted
+	for i := 1; i < len(names); i++ {
+		if names[i-1] > names[i] {
+			t.Errorf("ListBuiltinPersonas not sorted: %q > %q", names[i-1], names[i])
+		}
+	}
+}
+
+func TestYAMLUnknownFieldsRejected(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		wantErr string
+	}{
+		{
+			name: "unknown top-level field",
+			content: `name: test
+identity: test identity
+unknown_field: should fail
+`,
+			wantErr: "unknown_field",
+		},
+		{
+			name: "typo in field name",
+			content: `name: test
+identiy: typo should fail
+`,
+			wantErr: "identiy",
+		},
+		{
+			name: "unknown field in severity",
+			content: `name: test
+identity: test
+severity:
+  major: Major
+  minro: typo
+`,
+			wantErr: "minro",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			dir := t.TempDir()
+			path := filepath.Join(dir, "unknown.yaml")
+			if err := os.WriteFile(path, []byte(tt.content), 0644); err != nil {
+				t.Fatalf("failed to write test file: %v", err)
+			}
+
+			_, err := LoadPersona(path)
+			if err == nil {
+				t.Errorf("expected error for unknown field %q, got nil", tt.wantErr)
+				return
+			}
+			if !strings.Contains(err.Error(), tt.wantErr) {
+				t.Errorf("error = %q, want containing %q", err.Error(), tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestJSONUnknownFieldsRejected(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		wantErr string
+	}{
+		{
+			name: "unknown top-level field",
+			content: `{
+				"name": "test",
+				"identity": "test identity",
+				"unknown_field": "should fail"
+			}`,
+			wantErr: "unknown_field",
+		},
+		{
+			name: "typo in field name",
+			content: `{
+				"name": "test",
+				"identiy": "typo should fail"
+			}`,
+			wantErr: "identiy",
+		},
+		{
+			name: "unknown field in severity",
+			content: `{
+				"name": "test",
+				"identity": "test",
+				"severity": {
+					"major": "ok",
+					"miner": "typo"
+				}
+			}`,
+			wantErr: "miner",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			dir := t.TempDir()
+			path := filepath.Join(dir, "test.json")
+			if err := os.WriteFile(path, []byte(tt.content), 0644); err != nil {
+				t.Fatalf("failed to write test file: %v", err)
+			}
+
+			_, err := LoadPersona(path)
+			if err == nil {
+				t.Fatal("expected error for unknown field, got nil")
+			}
+			if !strings.Contains(err.Error(), tt.wantErr) {
+				t.Errorf("error = %q, want to contain %q", err.Error(), tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestLoadPersonaSymlink(t *testing.T) {
+	// Create a regular persona file
+	dir := t.TempDir()
+	realFile := filepath.Join(dir, "real.yaml")
+	content := `name: test
+identity: test identity
+`
+	if err := os.WriteFile(realFile, []byte(content), 0644); err != nil {
+		t.Fatalf("failed to write test file: %v", err)
+	}
+
+	// Create a symlink to it
+	symlink := filepath.Join(dir, "link.yaml")
+	if err := os.Symlink(realFile, symlink); err != nil {
+		t.Fatalf("failed to create symlink: %v", err)
+	}
+
+	// LoadPersona should work via symlink
+	p, err := LoadPersona(symlink)
+	if err != nil {
+		t.Fatalf("LoadPersona via symlink failed: %v", err)
+	}
+	if p.Name != "test" {
+		t.Errorf("Name = %q, want %q", p.Name, "test")
+	}
+}
+
+func TestJSONTrailingContentRejected(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+	}{
+		{
+			name:    "trailing garbage after object",
+			content: `{"name":"test","identity":"test identity"}garbage`,
+		},
+		{
+			name:    "two JSON objects",
+			content: `{"name":"test","identity":"test identity"}{"name":"other"}`,
+		},
+		{
+			name:    "trailing array",
+			content: `{"name":"test","identity":"test identity"}[]`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			dir := t.TempDir()
+			path := filepath.Join(dir, "test.json")
+			if err := os.WriteFile(path, []byte(tt.content), 0644); err != nil {
+				t.Fatalf("failed to write test file: %v", err)
+			}
+
+			_, err := LoadPersona(path)
+			if err == nil {
+				t.Fatal("expected error for trailing content, got nil")
+			}
+			if !strings.Contains(err.Error(), "trailing content") {
+				t.Errorf("error = %q, want to contain 'trailing content'", err.Error())
+			}
+		})
+	}
+}
+
+func TestParsePersonaBytesSizeLimit(t *testing.T) {
+	// ParsePersonaBytes should reject input exceeding MaxPersonaFileSize
+	oversized := make([]byte, MaxPersonaFileSize+1)
+	for i := range oversized {
+		oversized[i] = 'x'
+	}
+
+	_, err := ParsePersonaBytes(oversized, "oversized.yaml")
+	if err == nil {
+		t.Fatal("expected error for oversized input, got nil")
+	}
+	if !strings.Contains(err.Error(), "exceeds maximum size") {
+		t.Errorf("error = %q, want to contain 'exceeds maximum size'", err.Error())
+	}
+
+	// Just under the limit should not trigger size error (may fail parse, but not size)
+	underLimit := []byte("name: test\nidentity: test persona\n")
+	p, err := ParsePersonaBytes(underLimit, "valid.yaml")
+	if err != nil {
+		t.Fatalf("unexpected error for valid input: %v", err)
+	}
+	if p.Name != "test" {
+		t.Errorf("Name = %q, want %q", p.Name, "test")
+	}
+}
+
+func TestYAMLMergeKeyDepthCheck(t *testing.T) {
+	// Verify that YAML merge keys (<<: *alias) are properly handled by the
+	// depth checker. The merge key content is in the MappingValueNode.Value
+	// (an AliasNode), not in the MergeKeyNode itself.
+	p, err := ParsePersonaBytes([]byte("name: merge-test\nidentity: test\n"), "merge.yaml")
+	if err != nil {
+		t.Fatalf("basic parse failed: %v", err)
+	}
+	if p.Name != "merge-test" {
+		t.Errorf("Name = %q, want %q", p.Name, "merge-test")
+	}
+
+	// Test that deeply nested merge keys still hit depth limit.
+	// Build YAML with merge key content nested beyond MaxYAMLDepth.
+	var sb strings.Builder
+	sb.WriteString("name: deep-merge\nidentity: deep merge persona\n")
+	sb.WriteString("anchor: &deep\n")
+	indent := "  "
+	for i := 0; i < MaxYAMLDepth+5; i++ {
+		sb.WriteString(indent)
+		sb.WriteString(fmt.Sprintf("level%d:\n", i))
+		indent += "  "
+	}
+	sb.WriteString(indent + "leaf: value\n")
+	sb.WriteString("target:\n  <<: *deep\n")
+
+	_, err = ParsePersonaBytes([]byte(sb.String()), "deep-merge.yaml")
+	if err == nil {
+		t.Fatal("expected error for deeply nested merge key content, got nil")
+	}
+	if !strings.Contains(err.Error(), "depth") {
+		t.Errorf("error = %q, want to contain 'depth'", err.Error())
+	}
+}

review/personas/architect.json

@@ -1,26 +0,0 @@
-{
-  "name": "architect",
-  "display_name": "Software Architect",
-  "identity": "You are a software architect reviewing code for design quality.\n\nYour expertise:\n- Design patterns and anti-patterns\n- Code organization and module boundaries\n- API design and contracts\n- Testability and dependency injection\n- Consistency with existing architecture\n- Technical debt identification",
-  "focus": [
-    "Design pattern violations or misuse",
-    "Module boundary violations (inappropriate coupling)",
-    "API design issues (unclear contracts, leaky abstractions)",
-    "Testability problems (hidden dependencies, god objects)",
-    "Inconsistency with existing codebase patterns",
-    "Unnecessary complexity or over-engineering",
-    "Missing abstractions or premature abstraction"
-  ],
-  "ignore": [
-    "Security vulnerabilities (security persona handles these)",
-    "Performance micro-optimizations",
-    "Code style and formatting",
-    "Documentation typos",
-    "Test implementation details"
-  ],
-  "severity": {
-    "major": "Architectural violations that will cause maintenance problems or make the codebase harder to evolve",
-    "minor": "Design issues that reduce clarity or testability but don't block progress",
-    "nit": "Minor pattern deviations or style preferences"
-  }
-}

review/personas/architect.yaml

@@ -0,0 +1,37 @@
+# Software Architect Persona
+# Focuses on design quality, patterns, and code organization
+
+name: architect
+display_name: Software Architect
+
+identity: |
+  You are a software architect reviewing code for design quality.
+
+  Your expertise:
+  - Design patterns and anti-patterns
+  - Code organization and module boundaries
+  - API design and contracts
+  - Testability and dependency injection
+  - Consistency with existing architecture
+  - Technical debt identification
+
+focus:
+  - Design pattern violations or misuse
+  - Module boundary violations (inappropriate coupling)
+  - API design issues (unclear contracts, leaky abstractions)
+  - Testability problems (hidden dependencies, god objects)
+  - Inconsistency with existing codebase patterns
+  - Unnecessary complexity or over-engineering
+  - Missing abstractions or premature abstraction
+
+ignore:
+  - Security vulnerabilities (security persona handles these)
+  - Performance micro-optimizations
+  - Code style and formatting
+  - Documentation typos
+  - Test implementation details
+
+severity:
+  major: "Architectural violations that will cause maintenance problems or make the codebase harder to evolve"
+  minor: "Design issues that reduce clarity or testability but don't block progress"
+  nit: "Minor pattern deviations or style preferences"

review/personas/docs.json

@@ -1,26 +0,0 @@
-{
-  "name": "docs",
-  "display_name": "Documentation Reviewer",
-  "identity": "You are a documentation specialist reviewing code for clarity and documentation quality.\n\nYour expertise:\n- API documentation and examples\n- Code comments and their accuracy\n- Error message clarity\n- README and guide quality\n- Naming clarity and self-documenting code",
-  "focus": [
-    "Missing or outdated documentation",
-    "Unclear or misleading comments",
-    "Poor error messages (cryptic, unhelpful, missing context)",
-    "Confusing naming (functions, variables, types)",
-    "Missing examples for complex APIs",
-    "Inconsistent terminology",
-    "Documentation that contradicts the code"
-  ],
-  "ignore": [
-    "Security vulnerabilities",
-    "Performance issues",
-    "Design patterns",
-    "Test coverage",
-    "Code style (unless it affects readability)"
-  ],
-  "severity": {
-    "major": "Documentation that actively misleads or missing docs for critical functionality",
-    "minor": "Unclear documentation or poor error messages that will confuse users",
-    "nit": "Minor clarity improvements or typo fixes"
-  }
-}

review/personas/docs.yaml

@@ -0,0 +1,36 @@
+# Documentation Reviewer Persona
+# Focuses on clarity, documentation quality, and self-documenting code
+
+name: docs
+display_name: Documentation Reviewer
+
+identity: |
+  You are a documentation specialist reviewing code for clarity and documentation quality.
+
+  Your expertise:
+  - API documentation and examples
+  - Code comments and their accuracy
+  - Error message clarity
+  - README and guide quality
+  - Naming clarity and self-documenting code
+
+focus:
+  - Missing or outdated documentation
+  - Unclear or misleading comments
+  - Poor error messages (cryptic, unhelpful, missing context)
+  - Confusing naming (functions, variables, types)
+  - Missing examples for complex APIs
+  - Inconsistent terminology
+  - Documentation that contradicts the code
+
+ignore:
+  - Security vulnerabilities
+  - Performance issues
+  - Design patterns
+  - Test coverage
+  - Code style (unless it affects readability)
+
+severity:
+  major: "Documentation that actively misleads or missing docs for critical functionality"
+  minor: "Unclear documentation or poor error messages that will confuse users"
+  nit: "Minor clarity improvements or typo fixes"

review/personas/security.json

@@ -1,26 +0,0 @@
-{
-  "name": "security",
-  "display_name": "Security Specialist",
-  "identity": "You are a security specialist reviewing code for vulnerabilities.\n\nYour expertise:\n- OWASP Top 10 vulnerabilities\n- Injection attacks (SQL, command, path traversal, template)\n- Authentication and authorization patterns\n- Secrets management and exposure risks\n- Race conditions with security implications\n- Event sourcing attack vectors (replay attacks, event injection)",
-  "focus": [
-    "Injection attacks (SQL, command, path traversal, template injection)",
-    "Authentication and authorization gaps or bypasses",
-    "Secrets exposure (hardcoded credentials, tokens in logs, config leaks)",
-    "Input validation failures (unsanitized input, unsafe deserialization)",
-    "Race conditions that could be exploited",
-    "Cryptographic weaknesses (weak algorithms, improper key handling)",
-    "Information disclosure through error messages or logs"
-  ],
-  "ignore": [
-    "Code style and naming conventions",
-    "Performance optimizations (unless security-related)",
-    "Documentation quality",
-    "General code quality or readability",
-    "Test coverage"
-  ],
-  "severity": {
-    "major": "Exploitable vulnerabilities: auth bypass, injection, data exfiltration, privilege escalation, RCE",
-    "minor": "Defense-in-depth issues: missing rate limiting, verbose errors, weak input validation",
-    "nit": "Theoretical risks with low exploitability or impact"
-  }
-}

review/personas/security.yaml

@@ -0,0 +1,37 @@
+# Security Specialist Persona
+# Focuses on vulnerabilities, auth issues, and security best practices
+
+name: security
+display_name: Security Specialist
+
+identity: |
+  You are a security specialist reviewing code for vulnerabilities.
+
+  Your expertise:
+  - OWASP Top 10 vulnerabilities
+  - Injection attacks (SQL, command, path traversal, template)
+  - Authentication and authorization patterns
+  - Secrets management and exposure risks
+  - Race conditions with security implications
+  - Event sourcing attack vectors (replay attacks, event injection)
+
+focus:
+  - Injection attacks (SQL, command, path traversal, template injection)
+  - Authentication and authorization gaps or bypasses
+  - Secrets exposure (hardcoded credentials, tokens in logs, config leaks)
+  - Input validation failures (unsanitized input, unsafe deserialization)
+  - Race conditions that could be exploited
+  - Cryptographic weaknesses (weak algorithms, improper key handling)
+  - Information disclosure through error messages or logs
+
+ignore:
+  - Code style and naming conventions
+  - Performance optimizations (unless security-related)
+  - Documentation quality
+  - General code quality or readability
+  - Test coverage
+
+severity:
+  major: "Exploitable vulnerabilities: auth bypass, injection, data exfiltration, privilege escalation, RCE"
+  minor: "Defense-in-depth issues: missing rate limiting, verbose errors, weak input validation"
+  nit: "Theoretical risks with low exploitability or impact"

review/repo_persona.go

@@ -0,0 +1,150 @@
+package review
+
+import (
+	"context"
+	"log/slog"
+	"strings"
+)
+
+// RepoPersonaPath is the directory path where repo-specific personas are stored.
+const RepoPersonaPath = ".review-bot/personas"
+
+// GiteaClient defines the subset of gitea.Client methods needed for loading repo personas.
+// This interface allows for easier testing and decouples the review package from gitea.
+type GiteaClient interface {
+	ListContents(ctx context.Context, owner, repo, path string) ([]ContentEntry, error)
+	GetFileContent(ctx context.Context, owner, repo, filepath string) (string, error)
+}
+
+// ContentEntry represents a file or directory entry from the contents API.
+// This mirrors gitea.ContentEntry to avoid import cycles.
+type ContentEntry struct {
+	Name string `json:"name"`
+	Path string `json:"path"`
+	Type string `json:"type"` // "file" or "dir"
+}
+
+// LoadRepoPersonas fetches personas from a repository's .review-bot/personas/ directory.
+// Returns an empty map (not nil) if the directory doesn't exist or is empty.
+// Individual parse failures are logged and skipped; the remaining personas are still returned.
+// Auth errors and other non-404 errors are propagated.
+// Files exceeding MaxPersonaFileSize are rejected to prevent resource exhaustion.
+func LoadRepoPersonas(ctx context.Context, client GiteaClient, owner, repo string) (map[string]*Persona, error) {
+	result := make(map[string]*Persona)
+
+	entries, err := client.ListContents(ctx, owner, repo, RepoPersonaPath)
+	if err != nil {
+		// Check if this is a 404 (directory doesn't exist) - expected case
+		if isNotFoundError(err) {
+			slog.Debug("no repo personas directory found", "repo", owner+"/"+repo)
+			return result, nil
+		}
+		// Other errors (auth, server) should propagate
+		return nil, err
+	}
+
+	if len(entries) == 0 {
+		slog.Debug("repo personas directory is empty", "repo", owner+"/"+repo)
+		return result, nil
+	}
+
+	for _, entry := range entries {
+		if entry.Type != "file" {
+			continue
+		}
+		// Only process YAML files
+		if !isYAMLFile(entry.Name) {
+			continue
+		}
+
+		content, err := client.GetFileContent(ctx, owner, repo, entry.Path)
+		if err != nil {
+			slog.Warn("could not fetch repo persona file",
+				"file", entry.Path,
+				"repo", owner+"/"+repo,
+				"error", err)
+			continue
+		}
+
+		// Enforce size limit before parsing to prevent resource exhaustion
+		if len(content) > MaxPersonaFileSize {
+			slog.Warn("repo persona file exceeds maximum size",
+				"file", entry.Path,
+				"repo", owner+"/"+repo,
+				"size", len(content),
+				"max", MaxPersonaFileSize)
+			continue
+		}
+
+		persona, err := ParsePersonaBytes([]byte(content), entry.Path)
+		if err != nil {
+			slog.Warn("could not parse repo persona file",
+				"file", entry.Path,
+				"repo", owner+"/"+repo,
+				"error", err)
+			continue
+		}
+
+		result[persona.Name] = persona
+		slog.Debug("loaded repo persona",
+			"name", persona.Name,
+			"file", entry.Path,
+			"repo", owner+"/"+repo)
+	}
+
+	return result, nil
+}
+
+// MergePersonas combines built-in personas with repo personas.
+// Repo personas take precedence on name collision.
+// Returns a new map; inputs are not modified.
+func MergePersonas(builtin, repo map[string]*Persona) map[string]*Persona {
+	result := make(map[string]*Persona, len(builtin)+len(repo))
+
+	// Copy built-in personas first
+	for name, p := range builtin {
+		result[name] = p
+	}
+
+	// Overlay repo personas (override on collision)
+	for name, p := range repo {
+		if _, exists := result[name]; exists {
+			slog.Debug("repo persona overrides built-in", "name", name)
+		}
+		result[name] = p
+	}
+
+	return result
+}
+
+// GetBuiltinPersonasMap returns all built-in personas as a map keyed by name.
+// Returns an empty map (not nil) if loading fails.
+func GetBuiltinPersonasMap() map[string]*Persona {
+	result := make(map[string]*Persona)
+	for _, name := range ListBuiltinPersonas() {
+		p, err := LoadBuiltinPersona(name)
+		if err != nil {
+			slog.Warn("could not load built-in persona", "name", name, "error", err)
+			continue
+		}
+		result[name] = p
+	}
+	return result
+}
+
+// isYAMLFile checks if a filename has a YAML extension.
+func isYAMLFile(name string) bool {
+	lower := strings.ToLower(name)
+	return strings.HasSuffix(lower, ".yaml") || strings.HasSuffix(lower, ".yml")
+}
+
+// isNotFoundError checks if an error represents a 404 response.
+// This uses a specific "HTTP 404" substring match rather than a generic "not found"
+// match to avoid masking authentication failures or transport errors that might
+// contain "not found" in their message.
+func isNotFoundError(err error) bool {
+	if err == nil {
+		return false
+	}
+	return strings.Contains(err.Error(), "HTTP 404")
+}

review/repo_persona_test.go

@@ -0,0 +1,443 @@
+package review
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+)
+
+func TestParsePersonaBytes(t *testing.T) {
+	tests := []struct {
+		name       string
+		data       string
+		source     string
+		wantName   string
+		wantErr    string
+	}{
+		{
+			name: "valid yaml",
+			data: `name: test
+identity: test identity
+focus:
+  - testing
+`,
+			source:   "test.yaml",
+			wantName: "test",
+		},
+		{
+			name:    "missing name",
+			data:    "identity: test\n",
+			source:  "test.yaml",
+			wantErr: "name is required",
+		},
+		{
+			name:    "invalid yaml",
+			data:    "not: valid:\n  yaml: [broken",
+			source:  "test.yaml",
+			wantErr: "parse",
+		},
+		{
+			name: "json format by extension",
+			data: `{"name": "jsontest", "identity": "json identity"}`,
+			source:   "test.json",
+			wantName: "jsontest",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			p, err := ParsePersonaBytes([]byte(tt.data), tt.source)
+			if tt.wantErr != "" {
+				if err == nil {
+					t.Fatalf("expected error containing %q, got nil", tt.wantErr)
+				}
+				if !strings.Contains(err.Error(), tt.wantErr) {
+					t.Errorf("error = %q, want containing %q", err.Error(), tt.wantErr)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if p.Name != tt.wantName {
+				t.Errorf("Name = %q, want %q", p.Name, tt.wantName)
+			}
+		})
+	}
+}
+
+// mockGiteaClient implements GiteaClient for testing.
+type mockGiteaClient struct {
+	contents map[string][]ContentEntry // path -> entries
+	files    map[string]string         // path -> content
+	listErr  error
+	fileErr  map[string]error // path -> error
+}
+
+func (m *mockGiteaClient) ListContents(ctx context.Context, owner, repo, path string) ([]ContentEntry, error) {
+	if m.listErr != nil {
+		return nil, m.listErr
+	}
+	entries, ok := m.contents[path]
+	if !ok {
+		return nil, errors.New("list contents .review-bot/personas: HTTP 404: not found")
+	}
+	return entries, nil
+}
+
+func (m *mockGiteaClient) GetFileContent(ctx context.Context, owner, repo, filepath string) (string, error) {
+	if m.fileErr != nil {
+		if err, ok := m.fileErr[filepath]; ok {
+			return "", err
+		}
+	}
+	content, ok := m.files[filepath]
+	if !ok {
+		return "", errors.New("HTTP 404: file not found")
+	}
+	return content, nil
+}
+
+func TestLoadRepoPersonas(t *testing.T) {
+	ctx := context.Background()
+
+	t.Run("directory not found returns empty map", func(t *testing.T) {
+		client := &mockGiteaClient{} // No contents configured -> 404
+		personas, err := LoadRepoPersonas(ctx, client, "owner", "repo")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if personas == nil {
+			t.Error("expected empty map, got nil")
+		}
+		if len(personas) != 0 {
+			t.Errorf("expected 0 personas, got %d", len(personas))
+		}
+	})
+
+	t.Run("empty directory returns empty map", func(t *testing.T) {
+		client := &mockGiteaClient{
+			contents: map[string][]ContentEntry{
+				RepoPersonaPath: {},
+			},
+		}
+		personas, err := LoadRepoPersonas(ctx, client, "owner", "repo")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(personas) != 0 {
+			t.Errorf("expected 0 personas, got %d", len(personas))
+		}
+	})
+
+	t.Run("loads valid personas", func(t *testing.T) {
+		client := &mockGiteaClient{
+			contents: map[string][]ContentEntry{
+				RepoPersonaPath: {
+					{Name: "trading.yaml", Path: ".review-bot/personas/trading.yaml", Type: "file"},
+					{Name: "crypto.yaml", Path: ".review-bot/personas/crypto.yaml", Type: "file"},
+				},
+			},
+			files: map[string]string{
+				".review-bot/personas/trading.yaml": `name: trading
+display_name: Trading Expert
+identity: You are a trading expert.
+focus:
+  - order handling
+  - risk management
+`,
+				".review-bot/personas/crypto.yaml": `name: crypto
+display_name: Crypto Expert
+identity: You are a cryptography expert.
+focus:
+  - key management
+  - encryption
+`,
+			},
+		}
+		personas, err := LoadRepoPersonas(ctx, client, "owner", "repo")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(personas) != 2 {
+			t.Fatalf("expected 2 personas, got %d", len(personas))
+		}
+		if personas["trading"] == nil {
+			t.Error("expected trading persona")
+		}
+		if personas["crypto"] == nil {
+			t.Error("expected crypto persona")
+		}
+		if personas["trading"].DisplayName != "Trading Expert" {
+			t.Errorf("trading display name = %q, want %q", personas["trading"].DisplayName, "Trading Expert")
+		}
+	})
+
+	t.Run("skips invalid persona files", func(t *testing.T) {
+		client := &mockGiteaClient{
+			contents: map[string][]ContentEntry{
+				RepoPersonaPath: {
+					{Name: "valid.yaml", Path: ".review-bot/personas/valid.yaml", Type: "file"},
+					{Name: "invalid.yaml", Path: ".review-bot/personas/invalid.yaml", Type: "file"},
+				},
+			},
+			files: map[string]string{
+				".review-bot/personas/valid.yaml": `name: valid
+identity: Valid persona
+`,
+				".review-bot/personas/invalid.yaml": "not valid yaml: [broken",
+			},
+		}
+		personas, err := LoadRepoPersonas(ctx, client, "owner", "repo")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		// Should have the valid one, skip the invalid
+		if len(personas) != 1 {
+			t.Fatalf("expected 1 persona (skipped invalid), got %d", len(personas))
+		}
+		if personas["valid"] == nil {
+			t.Error("expected valid persona")
+		}
+	})
+
+	t.Run("skips non-yaml files", func(t *testing.T) {
+		client := &mockGiteaClient{
+			contents: map[string][]ContentEntry{
+				RepoPersonaPath: {
+					{Name: "persona.yaml", Path: ".review-bot/personas/persona.yaml", Type: "file"},
+					{Name: "README.md", Path: ".review-bot/personas/README.md", Type: "file"},
+					{Name: "notes.txt", Path: ".review-bot/personas/notes.txt", Type: "file"},
+				},
+			},
+			files: map[string]string{
+				".review-bot/personas/persona.yaml": `name: test
+identity: Test persona
+`,
+				".review-bot/personas/README.md": "# Personas\n\nPut your personas here.",
+			},
+		}
+		personas, err := LoadRepoPersonas(ctx, client, "owner", "repo")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(personas) != 1 {
+			t.Fatalf("expected 1 persona (yaml only), got %d", len(personas))
+		}
+	})
+
+	t.Run("skips subdirectories", func(t *testing.T) {
+		client := &mockGiteaClient{
+			contents: map[string][]ContentEntry{
+				RepoPersonaPath: {
+					{Name: "persona.yaml", Path: ".review-bot/personas/persona.yaml", Type: "file"},
+					{Name: "subdir", Path: ".review-bot/personas/subdir", Type: "dir"},
+				},
+			},
+			files: map[string]string{
+				".review-bot/personas/persona.yaml": `name: test
+identity: Test persona
+`,
+			},
+		}
+		personas, err := LoadRepoPersonas(ctx, client, "owner", "repo")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(personas) != 1 {
+			t.Fatalf("expected 1 persona (files only), got %d", len(personas))
+		}
+	})
+
+	t.Run("propagates auth errors", func(t *testing.T) {
+		client := &mockGiteaClient{
+			listErr: errors.New("HTTP 401: unauthorized"),
+		}
+		_, err := LoadRepoPersonas(ctx, client, "owner", "repo")
+		if err == nil {
+			t.Fatal("expected error for auth failure")
+		}
+		if !strings.Contains(err.Error(), "401") {
+			t.Errorf("error = %q, want containing '401'", err.Error())
+		}
+	})
+
+	t.Run("skips files that fail to fetch", func(t *testing.T) {
+		client := &mockGiteaClient{
+			contents: map[string][]ContentEntry{
+				RepoPersonaPath: {
+					{Name: "good.yaml", Path: ".review-bot/personas/good.yaml", Type: "file"},
+					{Name: "bad.yaml", Path: ".review-bot/personas/bad.yaml", Type: "file"},
+				},
+			},
+			files: map[string]string{
+				".review-bot/personas/good.yaml": `name: good
+identity: Good persona
+`,
+			},
+			fileErr: map[string]error{
+				".review-bot/personas/bad.yaml": errors.New("HTTP 500: internal server error"),
+			},
+		}
+		personas, err := LoadRepoPersonas(ctx, client, "owner", "repo")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(personas) != 1 {
+			t.Fatalf("expected 1 persona (skipped failed fetch), got %d", len(personas))
+		}
+	})
+
+	t.Run("skips oversized files", func(t *testing.T) {
+		// Create a content string that exceeds MaxPersonaFileSize (64KB)
+		oversizedContent := strings.Repeat("a", MaxPersonaFileSize+1)
+		client := &mockGiteaClient{
+			contents: map[string][]ContentEntry{
+				RepoPersonaPath: {
+					{Name: "normal.yaml", Path: ".review-bot/personas/normal.yaml", Type: "file"},
+					{Name: "huge.yaml", Path: ".review-bot/personas/huge.yaml", Type: "file"},
+				},
+			},
+			files: map[string]string{
+				".review-bot/personas/normal.yaml": `name: normal
+identity: Normal sized persona
+`,
+				".review-bot/personas/huge.yaml": oversizedContent,
+			},
+		}
+		personas, err := LoadRepoPersonas(ctx, client, "owner", "repo")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		// Should have the normal one, skip the oversized
+		if len(personas) != 1 {
+			t.Fatalf("expected 1 persona (skipped oversized), got %d", len(personas))
+		}
+		if personas["normal"] == nil {
+			t.Error("expected normal persona")
+		}
+	})
+}
+
+func TestMergePersonas(t *testing.T) {
+	builtin := map[string]*Persona{
+		"security": {Name: "security", Identity: "Built-in security"},
+		"docs":     {Name: "docs", Identity: "Built-in docs"},
+	}
+	repo := map[string]*Persona{
+		"security": {Name: "security", Identity: "Repo security override"},
+		"trading":  {Name: "trading", Identity: "Repo trading"},
+	}
+
+	merged := MergePersonas(builtin, repo)
+
+	t.Run("repo overrides builtin on collision", func(t *testing.T) {
+		if merged["security"].Identity != "Repo security override" {
+			t.Errorf("security identity = %q, want repo override", merged["security"].Identity)
+		}
+	})
+
+	t.Run("builtin preserved when no collision", func(t *testing.T) {
+		if merged["docs"].Identity != "Built-in docs" {
+			t.Errorf("docs identity = %q, want built-in", merged["docs"].Identity)
+		}
+	})
+
+	t.Run("repo-only persona added", func(t *testing.T) {
+		if merged["trading"] == nil {
+			t.Error("expected trading persona from repo")
+		}
+		if merged["trading"].Identity != "Repo trading" {
+			t.Errorf("trading identity = %q, want repo", merged["trading"].Identity)
+		}
+	})
+
+	t.Run("original maps not modified", func(t *testing.T) {
+		if builtin["trading"] != nil {
+			t.Error("builtin map was modified")
+		}
+		if len(repo) != 2 {
+			t.Error("repo map was modified")
+		}
+	})
+}
+
+func TestGetBuiltinPersonasMap(t *testing.T) {
+	personas := GetBuiltinPersonasMap()
+
+	if len(personas) == 0 {
+		t.Fatal("expected at least one built-in persona")
+	}
+
+	// Verify expected personas exist
+	expected := []string{"security", "architect", "docs"}
+	for _, name := range expected {
+		if personas[name] == nil {
+			t.Errorf("expected built-in persona %q", name)
+		}
+	}
+
+	// Verify personas are valid
+	for name, p := range personas {
+		if p.Name != name {
+			t.Errorf("persona %q has mismatched name %q", name, p.Name)
+		}
+		if p.Identity == "" {
+			t.Errorf("persona %q has empty identity", name)
+		}
+	}
+}
+
+func TestIsYAMLFile(t *testing.T) {
+	tests := []struct {
+		name string
+		want bool
+	}{
+		{"test.yaml", true},
+		{"test.yml", true},
+		{"test.YAML", true},
+		{"test.YML", true},
+		{"test.json", false},
+		{"test.md", false},
+		{"test.txt", false},
+		{"yaml", false},
+		{"yaml.md", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := isYAMLFile(tt.name); got != tt.want {
+				t.Errorf("isYAMLFile(%q) = %v, want %v", tt.name, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIsNotFoundError(t *testing.T) {
+	tests := []struct {
+		err  error
+		want bool
+	}{
+		{nil, false},
+		{errors.New("HTTP 404: not found"), true},
+		{errors.New("HTTP 404"), true},
+		// Intentionally false: generic "not found" could mask auth/transport errors.
+		// Only explicit HTTP 404 responses should be treated as "directory doesn't exist".
+		{errors.New("something not found"), false},
+		{errors.New("HTTP 401: unauthorized"), false},
+		{errors.New("connection refused"), false},
+	}
+
+	for _, tt := range tests {
+		name := "nil"
+		if tt.err != nil {
+			name = tt.err.Error()
+		}
+		t.Run(name, func(t *testing.T) {
+			if got := isNotFoundError(tt.err); got != tt.want {
+				t.Errorf("isNotFoundError(%v) = %v, want %v", tt.err, got, tt.want)
+			}
+		})
+	}
+}

scripts/check-deps.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# check-deps.sh - Enforces the strict dependency allowlist from CONVENTIONS.md
+# Exit 1 if any unapproved import is found.
+#
+# Requires: Bash 4+ (for associative arrays), Go toolchain
+# 
+# The allowlist is parsed from CONVENTIONS.md to maintain a single source of truth.
+# Enforces Scope column: "test only" packages cannot appear in non-test code.
+
+set -euo pipefail
+
+# Check bash version
+if ((BASH_VERSINFO[0] < 4)); then
+    echo "❌ Bash 4+ required (found ${BASH_VERSION})"
+    echo "   On macOS: brew install bash"
+    exit 1
+fi
+
+CONVENTIONS_FILE="${1:-CONVENTIONS.md}"
+
+if [ ! -f "$CONVENTIONS_FILE" ]; then
+    echo "❌ CONVENTIONS.md not found"
+    exit 1
+fi
+
+# Parse approved packages from CONVENTIONS.md table using awk (POSIX-compatible)
+# Format: | `package` | use case | scope |
+declare -A ALLOWED_PROD=()
+declare -A ALLOWED_TEST=()
+
+while IFS= read -r line; do
+    # Use awk to extract package and scope from table row
+    pkg=$(echo "$line" | awk -F'|' '{gsub(/^[[:space:]]*`|`[[:space:]]*$/, "", $2); print $2}')
+    scope=$(echo "$line" | awk -F'|' '{gsub(/^[[:space:]]+|[[:space:]]+$/, "", $4); print tolower($4)}')
+    
+    if [ -n "$pkg" ] && [ "$pkg" != "Package" ] && [[ "$pkg" =~ ^[a-zA-Z] ]]; then
+        if [[ "$scope" == *"test"* ]]; then
+            ALLOWED_TEST["$pkg"]=1
+        else
+            ALLOWED_PROD["$pkg"]=1
+        fi
+    fi
+done < <(grep '| `' "$CONVENTIONS_FILE" 2>/dev/null || true)
+
+ALL_ALLOWED=("${!ALLOWED_PROD[@]}" "${!ALLOWED_TEST[@]}")
+
+if [ ${#ALL_ALLOWED[@]} -eq 0 ]; then
+    echo "⚠️  No approved packages found in $CONVENTIONS_FILE"
+    echo "   (This is fine if you want stdlib-only)"
+fi
+
+# Helper: check if import matches any package in an associative array (literal prefix, no glob)
+matches_allowlist() {
+    local import="$1"
+    shift
+    local -n allowlist=$1
+    
+    for allowed in "${!allowlist[@]}"; do
+        # Exact match
+        if [ "$import" = "$allowed" ]; then
+            return 0
+        fi
+        # Literal prefix match for subpackages: must match "pkg/" exactly
+        if [ "${import#"$allowed/"}" != "$import" ]; then
+            return 0
+        fi
+    done
+    return 1
+}
+
+# Get direct module dependencies from go.mod
+DIRECT_IMPORTS=$(go list -m -f '{{if and (not .Indirect) (not .Main)}}{{.Path}}{{end}}' all 2>&1) || {
+    echo "❌ Failed to list dependencies: $DIRECT_IMPORTS"
+    exit 1
+}
+DIRECT_IMPORTS=$(echo "$DIRECT_IMPORTS" | grep -v '^$' || true)
+
+if [ -z "$DIRECT_IMPORTS" ]; then
+    echo "✅ No external dependencies"
+    exit 0
+fi
+
+# Check ALL direct dependencies are in some allowlist
+VIOLATIONS=""
+while IFS= read -r import; do
+    [ -z "$import" ] && continue
+    
+    if ! matches_allowlist "$import" ALLOWED_PROD && ! matches_allowlist "$import" ALLOWED_TEST; then
+        VIOLATIONS="${VIOLATIONS}  - ${import} (not in allowlist)"$'\n'
+    fi
+done <<< "$DIRECT_IMPORTS"
+
+if [ -n "$VIOLATIONS" ]; then
+    echo "❌ UNAPPROVED DEPENDENCIES DETECTED"
+    echo ""
+    echo "The following imports are not in the allowlist:"
+    printf "%s" "$VIOLATIONS"
+    echo ""
+    echo "To add a dependency, update CONVENTIONS.md (requires Aaron's approval)"
+    exit 1
+fi
+
+# Enforce Scope: test-only packages must not appear in non-test code
+# Get imports used by non-test code only (go list -deps without -test excludes test deps)
+PROD_IMPORTS=$(go list -deps -f '{{if not .Standard}}{{.ImportPath}}{{end}}' ./... 2>/dev/null || true)
+
+TEST_ONLY_IN_PROD=""
+for test_pkg in "${!ALLOWED_TEST[@]}"; do
+    # Use word-boundary matching: exact match or followed by /
+    if echo "$PROD_IMPORTS" | grep -qE "^${test_pkg}(/|\$|$)"; then
+        TEST_ONLY_IN_PROD="${TEST_ONLY_IN_PROD}  - ${test_pkg} (marked 'test only' but used in production code)"$'\n'
+    fi
+done
+
+if [ -n "$TEST_ONLY_IN_PROD" ]; then
+    echo "❌ TEST-ONLY DEPENDENCIES IN PRODUCTION CODE"
+    echo ""
+    printf "%s" "$TEST_ONLY_IN_PROD"
+    echo ""
+    echo "These packages are marked 'test only' in CONVENTIONS.md"
+    echo "and must only be imported from *_test.go files."
+    exit 1
+fi
+
+echo "✅ All dependencies are approved"
+echo "   Direct module deps: $(echo "$DIRECT_IMPORTS" | wc -l | tr -d ' ')"
+echo "   Production allowlist: ${#ALLOWED_PROD[@]}, Test-only allowlist: ${#ALLOWED_TEST[@]}"