feat: add --paths to scope reviews to named files, dirs, or globs

[ywy50]

Adds a --paths LIST flag (repeatable, comma-separated) that scopes a review run to specific files, whole directories, or globs, relative to the reviewed directory, while the agent keeps the full repository as working directory and context.

Behavior

• When set, every composed review prompt gets an operator scope block telling the agent to read the whole repo for context but report findings on and modify only the listed paths. The scope is prompt-enforced, not mechanical.
• The block sits outside the BEGIN/END REVIEW markers, with the other operator rules (Ground rules, Containment, tool note), so the untrusted review body cannot have planted or widened it.
• When unset, composed prompts are byte-identical to before this change (pinned by a test).
• Review prompts only: suggest, commit, and conflict prompts are unchanged.
• An explicitly empty --paths is refused: it would silently mean the whole tree, the opposite of the narrowing it asked for.
• Subcommands do not read it, so gauntlet runs --paths x is refused by the stray-flag check (allowlists unchanged).

Wiring

• listFlag-backed flag in cmd/gauntlet/flags.go, validated in finishFlags.
• runner.Config.Paths threads it to the prompt.Compose call in the runner; --show-prompt passes it directly. Compose gains a paths []string parameter; those are the only two call sites.
• Help table (Reviews group, metavar LIST), docs/CLI.md next to --reviews, CHANGELOG Unreleased entry, and the flag-name contract snapshot updated.

Tests

• Flag parsing: repeatable/comma lists with a file, a directory, and a glob; omitted default; explicit-empty and whitespace-only rejection; subcommand rejection.
• Compose: scope block present with all three entry kinds, positioned after the review markers, byte-identical output when unset (nil and empty slice).
• go test ./... green, gofmt clean; verified live via --show-prompt with and without --paths.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 66a7c37d-8563-45b5-a0d7-68140ae67dbd

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}