Summary

• In git-worktree setups, reviewer subagents were reading files from the main checkout instead of the worktree where the commits actually live, producing spurious findings against stale content (e.g., a flood of file-purpose-comment MUST FAIL hits on files that already had purpose comments in the worktree).
• Root cause: the @filepath entries in each instruction file's "Files to Review" section are not auto-expanded — the reviewer must Read each file itself — so they resolve against whatever cwd the subagent inherits. When that cwd is the main checkout, Read returns un-refactored content, which then disagrees with the "Relevant File Contents" block that was correctly inlined from the worktree.
• Fix: emit an explicit ## Project Root directive at the top of each instruction file stating the absolute project root and telling the reviewer to prepend it when calling Read. Reviewer behavior is now cwd-independent.

Changes

• src/deepwork/review/instructions.py — build_instruction_file takes an optional project_root: Path; emits the new section when provided. write_instruction_files threads it through.
• specs/deepwork/review/REVIEW-REQ-005-instruction-generation.md — adds REVIEW-REQ-005.1.9 with the worktree rationale.
• tests/unit/review/test_instructions.py — new tests covering presence, ordering before "Review Instructions", backward-compat when project_root is omitted, and the write_instruction_files plumbing.

Test plan

• uv run pytest tests/unit/review/test_instructions.py (60 passed)
• uv run pytest tests/unit/review/ (260 passed)
• Verify the generated instruction file contains a visible ## Project Root section in an actual worktree run

🤖 Generated with Claude Code