Add review-planning.sh for independent planning review

[taspinar]

What changed

• New ./scripts/review-planning.sh [--agent] [--model]: runs in a planning worktree with role planning-reviewer and the read-only profile. It refuses another branch, missing planning documents, and unapproved requirements before starting an agent.
• The reviewer receives the planning documents (description when present, requirements, architecture, roadmap, ADRs) and their diff against origin/main, including deleted documents.
• New contract .agents/prompts/planning-reviewer.md: consistency with the approved requirements and between documents, requirement coverage, justified choices, testable roadmap features with valid dependencies, and necessary ADRs. Findings about the requirements themselves are allowed and labelled.
• Each round is stored as .agents/reviews/planning-<name>-review-NN.json with a generated report, in the shared review format with kind: "planning" and no Issue.
• The review records the planning scope (reviewed_paths, including the optional description and the decisions directory) and its fingerprint, so adding, changing, or deleting a planning document makes it stale; other changes do not.
• triage-review.sh refuses planning reviews.
• Running a reviewer with retry and storing its result moved to scripts/lib/review-run.sh, shared by review-feature.sh and review-planning.sh.
• docs/development.md describes the planning review.

Issue / acceptance criteria

Closes #45

Risk

• Low
• Medium
• High

Verification evidence

• ./scripts/verify.sh passed (12 checks)
• Tests added/updated where appropriate (tests/review-planning-test.sh, also passing under macOS system bash 3.2)
• Independent review completed when required
• Architecture/docs/ADR updated when required

Real run: review-planning.sh with Codex (gpt-6-astra) on a deliberately thin throwaway planning (a household recipe app) returned CHANGES REQUIRED with five relevant Major findings (unresolved product decisions, unplanned access control, missing data flows, unjustified technology choices, untestable roadmap features).

Independent review of this change: Codex (gpt-6-astra), read-only. CHANGES REQUIRED:

• M1 (a new planning document did not make the review stale): fixed by recording the planning scope rather than the existing files, with tests for a new ADR and a removed description.
• M2 (deleted planning documents were missing from the reviewer's diff): fixed, with a test.
• MIN1 (next steps referred to scripts that do not exist yet): fixed; the messages describe the manual revision loop until Add revise-planning.sh with a recorded decision per finding #46 and Add finish-planning.sh with an approval tied to the planning documents #47.

Not re-reviewed after the fixes.

Agent involvement

Planner: —
Implementer: Claude (Opus 5.5)
Reviewer: Codex (gpt-6-astra)

Production impact

None.

🤖 Generated with Claude Code