fix(review): correct external-fork PR checkout, swap pre-fetch for compact diffs, add SKIPPED FILES contract

CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable user-visible changes to CASCADE are documented here. The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project does not use strict semver for releases.
+
+## Unreleased
+
+### Changed
+
+- **Review-agent context shape: compact diffs instead of full files.** The review agent's pre-fetched PR context now consists of compact per-file diffs (using GitHub's `file.patch`) rather than full file contents. Files that can't fit the budget — deleted, binary, oversized patch, or cumulative budget exhausted — are surfaced in a structured `SKIPPED FILES` injection that names each file with a reason and tells the agent how to fetch it on demand (`gh pr diff`, `Read`, `Grep`). This scales with PR size rather than repo size, mitigates LLM context rot, and ensures the agent is aware of (rather than blind to) the omissions. The context budget is `REVIEW_DIFF_CONTEXT_TOKEN_LIMIT` (200k tokens), replacing the prior 25k full-file cap. The `SKIPPED FILES` injection is also delivered to the four other agents that share the PR context pipeline (`respond-to-ci`, `respond-to-pr-comment`, `respond-to-review`, `resolve-conflicts`); explicit prompt guidance is added in `review.yaml` only. (Spec [001](docs/specs/001-pr-review-correctness.md), plan [2/2](docs/plans/001-pr-review-correctness/2-context-rework.md.done).)
+
+### Fixed
+
+- **Review agent on external-fork and large PRs.** PR checkouts now use the canonical `refs/pull/N/head` ref, which works for same-repo branches and external-fork branches alike. Previously, a silent `git checkout <branch>` failure on fork PRs caused the worker to review the base branch (`dev`) while believing it was on the PR branch, producing confidently wrong reviews. Any git or HEAD-SHA mismatch now fails the run loudly rather than silently continuing. Additionally, every paginated GitHub REST endpoint used in the review setup pipeline now paginates to completion, so PRs with more than 100 changed files are no longer truncated at the first page. (Spec [001](docs/specs/001-pr-review-correctness.md), plan [1/2](docs/plans/001-pr-review-correctness/1-checkout-and-pagination.md.done).)

CLAUDE.md

@@ -41,6 +41,18 @@ Projects are configured in the PostgreSQL database (`projects` table). Each proj
 
 ## Development
 
+### PR Checkout (worker)
+
+The worker checks out PRs via the canonical `refs/pull/N/head` ref — works for both same-repo branches and external-fork branches. When `prNumber` is set on `AgentInput`, `setupRepository`:
+
+1. Fetches `+refs/pull/<N>/head:refs/remotes/pr/<N>` from `origin`.
+2. Detached-checks out `pr/<N>`.
+3. If `headSha` is also set on `AgentInput`, verifies `git rev-parse HEAD` matches.
+
+Any non-zero git exit code throws — there is no warn-and-continue in setup. Failed runs are marked failed in the dashboard rather than proceeding on a stale or wrong working tree.
+
+The legacy `prBranch` field is retained for human-readable logging but is **not** used to drive checkout (fork branches don't exist on `origin` and the by-name path silently 404s).
+
 ### Testing
 
 > **For a full catalog of test helpers, factory functions, and mock objects**, see [`tests/README.md`](tests/README.md).
@@ -759,6 +771,14 @@ CASCADE integrates llmist's resilience features to ensure reliable operation dur
 
 ## Debugging Production Sessions
 
+### Review Agent — Context Shape
+
+The review agent receives a **compact per-file diff context** rather than full file contents. Each changed file appears as a `### <filename> (<status>, +N -M)` section followed by a unified diff hunk. The budget is `REVIEW_DIFF_CONTEXT_TOKEN_LIMIT` (200,000 tokens), with a per-file cap of 10% of that.
+
+Files that can't fit (deleted, binary, oversized patch, or budget exhausted) are surfaced via a separate `SKIPPED FILES` injection. The injection is self-documenting: it lists each filename + reason and instructs the agent to fetch on demand using `gh pr diff <PR_NUMBER> -- <path>`, `Read <path>`, or `Grep <pattern> <path>`.
+
+When debugging review-agent output that misses something, check the `PR context prepared` log entry for `included`/`skipped`/`skipReasons` to confirm whether the file was even visible to the agent.
+
 ### Manual Session Download
 
 Download session logs and card data from a Trello card for debugging:

docs/architecture/03-trigger-system.md

@@ -145,7 +145,7 @@ Each trigger in a YAML agent definition can declare a `contextPipeline` — an o
 | `contextFiles` | Read key project files (README, etc.) |
 | `workItem` | Fetch work item details from PM tool |
 | `prepopulateTodos` | Pre-populate todo list from work item checklists |
-| `prContext` | Fetch PR details, diff, reviews |
+| `prContext` | Fetch PR details, compact per-file diffs, CI checks; emit a `SKIPPED FILES` injection when files are omitted (over budget, deleted, binary) |
 | `prConversation` | Fetch PR comments and review threads |
 | `pipelineSnapshot` | Fetch CI pipeline status |
 | `alertingIssue` | Fetch Sentry issue and event details |