Add review path filtering for markdown-heavy mixed diffs

Problem

Teach scripts/review and the /pr workflow how to scope review input for unusually large mixed code+markdown diffs, especially when task/docs markdown dominates the patch. The goal is not to hide markdown by default, but to preserve review quality when a branch has so many markdown edits that the behavior-changing files get drowned out.

Context

The current scripts/review interface only supports whole-branch review, staged review, or PR-number review. It does not support path filtering, include lists, or exclude globs. On mixed branches that contain behavior changes plus many task/docs markdown updates, the review diff becomes noisy and can exceed the comfortable size for a useful code review.

This came up directly during /pr flow on a branch with code changes under scripts/, tasks/tools/, and tests, plus many task markdown files. scripts/review warned that the diff was over 3000 lines and the practical workaround was to unstage everything, stage only non-markdown files, run scripts/review --staged, then restage everything for the actual PR. That works, but it is clumsy and easy to forget.

At the same time, markdown often matters in review when only a handful of files changed. The filtering path should therefore be treated as an exceptional tool for markdown-heavy mixed diffs, not a new default that quietly drops .md context from normal reviews.

Relevant files and surfaces:

• scripts/review - builds the diff input and launches the local review agent
• scripts/review_prompt.py - review prompt generation
• /pr flow docs in agent command surfaces - currently have to suggest manual staging workarounds

Constraints:

• preserve current default behavior for existing callers
• make the filtered review path explicit and easy to use
• avoid teaching agents to overuse markdown filtering on ordinary reviews
• support markdown-heavy mixed diffs without forcing users to rewrite their staging area

Possible Solutions

1. Recommended: add explicit path filtering flags to scripts/review, but use them sparingly.

Add support for include/exclude pathspecs or exclude globs so review can run on the current branch diff while omitting high-volume markdown, likely under paths like tasks/ or docs/, or via *.md filtering when appropriate. Keep this explicit and reserve any automatic use for clearly markdown-heavy mixed diffs, not routine reviews with only a few markdown files.

2. Document the staged-only workaround and leave the script unchanged.

This is low effort, but still awkward and error-prone because users have to rewrite the index just to scope the review.

3. Teach /pr itself to auto-split review input from PR contents.

This could work, but the real missing capability is in scripts/review. Fixing it there makes the improvement reusable outside /pr.

Plan

Implement option 1 with strong guardrails against overuse.

1. Extend scripts/review with an explicit way to filter diff input, for example directory filters for tasks/ and docs/, --exclude-glob '*.md', and/or pathspec passthrough after --.
2. Ensure the default branch/staged/PR modes still behave exactly as they do today when no filter is provided.
3. If /pr grows an automatic recommendation or auto-filter path, gate it behind a clearly large markdown-heavy mixed diff threshold rather than small markdown changes. The intended use case is branches with dozens of markdown files, not reviews with only a few relevant .md edits.
4. Update the review prompt metadata and any artifact labeling so scoped reviews clearly state that the diff was filtered.
5. Update /pr guidance to recommend the built-in filter only for markdown-heavy mixed branches instead of the staging workaround.
6. Add tests for filtered branch review and filtered staged review behavior, including guardrail coverage that ordinary small markdown diffs are not auto-filtered.

Implementation Progress

QA Exploration

• [ ] QA exploration completed (or N/A for non-UI tasks)

Review Feedback

• [ ] Review cleared