feat: add review --feature-list flag

[camwest]

Why

I want to use this in a daily clawpatch automation that precomputes an authored slice, ranks candidate features, and then asks clawpatch to review only that explicit set.

Today review --since still selects from the full diff after map, so the automation cannot guarantee authored-only review.

Approach

This adds clawpatch review --feature-list <path>.

The file takes one feature id per line. Clawpatch keeps the file order, de-dupes repeated ids by first occurrence, fails on unknown or empty lists, and rejects combinations with --feature, --project, --since, and --include-dirty.

I kept this scoped to review instead of ci. The automation can run map, recompute selection from the mapped state, then call review --feature-list with the exact ranked ids it wants.

Proof

• focused workflow tests for parse, validation, ordering, unknown ids, and explicit review of a skipped feature
• typecheck
• autoreview clean

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 9, 2026, 1:39 PM ET / 17:39 UTC.

Summary
Adds a clawpatch review --feature-list <path> CLI flag that reads ordered feature ids from a file, selects those features for review, validates incompatible filters, and documents/tests the workflow.

Reproducibility: not applicable. this is a new CLI feature, not a reported current-main bug. Source inspection confirms current main lacks --feature-list, while the PR diff shows the proposed behavior and tests.

Review metrics: 2 noteworthy metrics.

• Changed surface: 6 files, +235/-3. The PR touches CLI parsing, review selection, docs, and workflow tests, which is the full user-facing flag path.
• Workflow tests added: 6 focused tests added. The new tests cover parsing, flag conflicts, missing files, ordering, unknown ids, and skipped-feature review behavior.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof from a real setup is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P1] Add redacted terminal output or a terminal screenshot showing clawpatch review --feature-list selecting an ordered feature list in a real project.
• Update the code-review behavior summary so it mentions --feature-list alongside --feature.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR body lists tests/typecheck/autoreview only; add redacted terminal output, logs, or a terminal screenshot showing review --feature-list in a real project, then updating the PR body should trigger a fresh ClawSweeper review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

• [P1] The PR body provides only tests/typecheck/autoreview proof; contributor-supplied real CLI output is still needed before merge.
• [P1] This adds a new explicit review-selection CLI surface that can review listed non-pending features, so maintainers should accept that behavior intentionally.

Maintainer options:

1. Decide the mitigation before merge
   Land the focused review --feature-list support after maintainers accept the CLI surface, the docs summary is made consistent, and the contributor adds redacted real CLI proof.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P1] This needs contributor proof and maintainer acceptance of a new CLI selection flag, not an automated repair lane.

Security
Cleared: The diff adds local reading of an explicitly supplied CLI file path and no new dependencies, workflow permissions, credential handling, or supply-chain changes.

Review findings

• [P3] Update the behavior summary for feature lists — docs/code-review.md:42-44

Review details

Best possible solution:

Land the focused review --feature-list support after maintainers accept the CLI surface, the docs summary is made consistent, and the contributor adds redacted real CLI proof.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a new CLI feature, not a reported current-main bug. Source inspection confirms current main lacks --feature-list, while the PR diff shows the proposed behavior and tests.

Is this the best way to solve the issue?

Mostly yes: adding a dedicated review selection flag is a narrow implementation path for explicit authored slices. Before merge, the docs should consistently describe the new selection mode and the contributor should add real CLI behavior proof.

Full review comments:

• [P3] Update the behavior summary for feature lists — docs/code-review.md:42-44
  The new section documents --feature-list as explicit selection, but the page still says review only selects pending features unless --feature is set. After this flag lands, listed skipped/fixed features can be reviewed explicitly, so the current behavior summary should mention --feature-list too.
  Confidence: 0.87

Overall correctness: patch is correct
Overall confidence: 0.82

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 98f51b3daf23.

Label changes

Label changes:

• add P3: This is a low-risk CLI automation feature with focused scope rather than an urgent bug or regression.
• add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body lists tests/typecheck/autoreview only; add redacted terminal output, logs, or a terminal screenshot showing review --feature-list in a real project, then updating the PR body should trigger a fresh ClawSweeper review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Label justifications:

• P3: This is a low-risk CLI automation feature with focused scope rather than an urgent bug or regression.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body lists tests/typecheck/autoreview only; add redacted terminal output, logs, or a terminal screenshot showing review --feature-list in a real project, then updating the PR body should trigger a fresh ClawSweeper review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

What I checked:

• Repository policy read: Read the full target AGENTS.md; it identifies clawpatch as a TypeScript CLI, asks for focused tests/docs for behavior changes, and says generated dist output should not be edited. (AGENTS.md:1, 98f51b3daf23)
• Current main lacks the requested flag: Searching current main finds existing review selection, --since, --include-dirty, and --prompt-file, but no feature-list or featureList support. (src/cli.ts:153, 98f51b3daf23)
• PR adds CLI parsing and validation: The PR commit adds featureList to review flags, feature-list as a value flag, conflict checks for --feature, --project, --since, and --include-dirty, plus help text. (src/cli.ts:157, 5d1002292bfa)
• PR adds explicit feature-list selection: The PR commit reads the feature-list file, trims blank lines, reports unknown or empty lists, preserves first-occurrence order through selectFeaturesByIdList, and lets explicit lists review non-pending features. (src/app.ts:1995, 5d1002292bfa)
• PR adds focused workflow coverage: The PR commit adds workflow tests for parsing, incompatible flags, missing files, order/de-dupe, unknown ids, and explicit review of a skipped feature. (src/workflow.test.ts:3190, 5d1002292bfa)
• Real behavior proof gap: The PR body lists focused tests, typecheck, and autoreview clean, and the provided GitHub context includes no comments, screenshots, terminal output, logs, recordings, or linked artifacts showing the feature in a real setup. (5d1002292bfa)

Likely related people:

• Peter Steinberger: Current-main blame for src/app.ts, src/cli.ts, and src/selection.ts points to the v0.5.0 release commit, and later review filter work added --include-dirty. (role: recent area contributor; confidence: high; commits: d407835d91c7, 580a0b0c10c2; files: src/app.ts, src/cli.ts, src/selection.ts)
• Vincent Koc: git log -S ties review candidate selection and non-pending review validation history to a large review workflow hardening commit. (role: review workflow contributor; confidence: medium; commits: 5aea8abb0490; files: src/app.ts, src/selection.ts, src/workflow.test.ts)
• Matt Van Horn: Added review --since diff filtering across the same review selection, CLI, docs, and workflow-test surface that this PR extends. (role: adjacent feature contributor; confidence: medium; commits: b399e8946cb1; files: src/app.ts, src/cli.ts, src/workflow.test.ts)
• Daniel Pittman: Added the nearby --prompt-file review flag and file-reading/test pattern that this PR follows for --feature-list. (role: adjacent CLI file-flag contributor; confidence: medium; commits: ea5d3b7a774a; files: src/app.ts, src/cli.ts, src/workflow.test.ts)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.