fix(a6df-0162): constrain reviewer file field to diff files and add overlap recovery

reviewer-base.md had no constraint that findings' "file" field must
reference files from the diff being reviewed. Light-tier reviewers could
cite test files from verification findings, causing record-review.sh to
reject with "files do not overlap with any changed files in the diff."
Added explicit diff-subset constraint to the findings schema and inline
annotation. Also added file-overlap rejection recovery guidance to
REVIEW-WORKFLOW.md: re-dispatch with a higher-tier reviewer before
escalating to the user. Regenerated all 6 reviewer agent files.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: JoeOakhartNava

.test-index

@@ -38,7 +38,8 @@ plugins/dso/docs/decisions/adr-config-system.md:tests/scripts/test-adr-config-sy
 plugins/dso/docs/workflow-config-schema.json:tests/scripts/test-workflow-config-schema.sh
 plugins/dso/docs/workflows/COMMIT-WORKFLOW.md:tests/scripts/test-commit-workflow-step-1-5.sh
 plugins/dso/docs/workflows/REVIEW-PROTOCOL-WORKFLOW.md:tests/hooks/test-review-protocol-workflow.sh
-plugins/dso/docs/workflows/REVIEW-WORKFLOW.md:tests/workflows/test-review-workflow-no-snapshot.sh,tests/workflows/test-review-workflow-size-thresholds.sh,tests/workflows/test-review-workflow-classifier-override-prevention.sh,tests/skills/test_review_workflow_model_escalation.py
+plugins/dso/docs/workflows/prompts/reviewer-base.md:tests/docs/test-reviewer-base-file-constraint.sh
+plugins/dso/docs/workflows/REVIEW-WORKFLOW.md:tests/workflows/test-review-workflow-no-snapshot.sh,tests/workflows/test-review-workflow-size-thresholds.sh,tests/workflows/test-review-workflow-classifier-override-prevention.sh,tests/skills/test_review_workflow_model_escalation.py,tests/docs/test-reviewer-base-file-constraint.sh
 plugins/dso/hooks/dispatchers/pre-bash.sh:tests/hooks/test-pre-bash-dispatcher.sh
 plugins/dso/hooks/dispatchers/pre-edit.sh:tests/hooks/test-pre-edit-write-dispatcher.sh
 plugins/dso/hooks/dispatchers/pre-write.sh:tests/hooks/test-pre-edit-write-dispatcher.sh

plugins/dso/agents/code-reviewer-deep-arch.md

@@ -3,7 +3,7 @@ name: code-reviewer-deep-arch
 model: opus
 description: Deep-tier architectural reviewer (Opus): synthesizes specialist findings, assesses systemic risk, produces unified verdict across all dimensions.
 ---
-<!-- content-hash: 5726710d4d9c90e5b79810a1b16bbdb047fc53bc2aaa65780598cffff23ed9a6 -->
+<!-- content-hash: e356045cd2825e9e3f698ffe1411de98b6406107455e9425857841636ab7fe01 -->
 <!-- generated by build-review-agents.sh — do not edit manually -->
 
 # Code Reviewer — Universal Base Guidance
@@ -92,7 +92,7 @@ Produce a JSON object with this EXACT schema (for writing to disk in Step 3).
 
 VIOLATIONS CAUSE RE-DISPATCH.
 
-REQUIRED: EXACTLY three top-level keys: "scores", "findings", "summary".
+REQUIRED: EXACTLY three top-level keys: "scores", "findings" (file field must reference diff files only), "summary".
 Do NOT add "schema_version", "review_result", "id", "review_date", or any other key —
 the validator will reject any extra keys and force a re-dispatch.
 The "scores" object MUST contain ALL five dimensions listed below with integer 1–5 or "N/A".
@@ -115,13 +115,15 @@ will be rejected by the validator and force a re-dispatch.
       "severity": "critical|important|minor",
       "category": "<one of the 5 score dimensions>",
       "description": "...",
-      "file": "path/to/file"
+      "file": "path/to/file (MUST be from the diff being reviewed)"
     }
   ],
   "summary": "2-3 sentence assessment"
 }
 ```
 
+**`file` field constraint**: The `file` field in each finding MUST reference a file present in the diff being reviewed (DIFF_FILE). Do not use files from your recommendations (e.g., test files that should be created) — only files that appear in the actual diff. `record-review.sh` validates that finding files overlap with changed files and rejects the review if they do not.
+
 ---
 
 ## Scoring Rules

plugins/dso/agents/code-reviewer-deep-correctness.md

@@ -3,7 +3,7 @@ name: code-reviewer-deep-correctness
 model: sonnet
 description: Deep-tier correctness specialist (Sonnet A): focused exclusively on correctness — edge cases, error handling, security, efficiency.
 ---
-<!-- content-hash: d42a3d7b417a4e0699de9eda503d6b9ec64de71a5b320dedff5901ae671580e1 -->
+<!-- content-hash: b19cd9c73923f3f67f1b9642dda3d007261f6c349f63edbf7d246e0d69fb678d -->
 <!-- generated by build-review-agents.sh — do not edit manually -->
 
 # Code Reviewer — Universal Base Guidance
@@ -92,7 +92,7 @@ Produce a JSON object with this EXACT schema (for writing to disk in Step 3).
 
 VIOLATIONS CAUSE RE-DISPATCH.
 
-REQUIRED: EXACTLY three top-level keys: "scores", "findings", "summary".
+REQUIRED: EXACTLY three top-level keys: "scores", "findings" (file field must reference diff files only), "summary".
 Do NOT add "schema_version", "review_result", "id", "review_date", or any other key —
 the validator will reject any extra keys and force a re-dispatch.
 The "scores" object MUST contain ALL five dimensions listed below with integer 1–5 or "N/A".
@@ -115,13 +115,15 @@ will be rejected by the validator and force a re-dispatch.
       "severity": "critical|important|minor",
       "category": "<one of the 5 score dimensions>",
       "description": "...",
-      "file": "path/to/file"
+      "file": "path/to/file (MUST be from the diff being reviewed)"
     }
   ],
   "summary": "2-3 sentence assessment"
 }
 ```
 
+**`file` field constraint**: The `file` field in each finding MUST reference a file present in the diff being reviewed (DIFF_FILE). Do not use files from your recommendations (e.g., test files that should be created) — only files that appear in the actual diff. `record-review.sh` validates that finding files overlap with changed files and rejects the review if they do not.
+
 ---
 
 ## Scoring Rules

plugins/dso/agents/code-reviewer-deep-hygiene.md

@@ -3,7 +3,7 @@ name: code-reviewer-deep-hygiene
 model: sonnet
 description: Deep-tier hygiene/design specialist (Sonnet C): focused on hygiene, design, and maintainability.
 ---
-<!-- content-hash: ff89bbdf4a3ffd69f24e1e87a394c3a5bea7444d9fb17202094107ff6cfdfe8c -->
+<!-- content-hash: 4e79d423e1ec1c1b351a07a0d816c67e4955f9039cf6dc28ba256fe30760a08b -->
 <!-- generated by build-review-agents.sh — do not edit manually -->
 
 # Code Reviewer — Universal Base Guidance
@@ -92,7 +92,7 @@ Produce a JSON object with this EXACT schema (for writing to disk in Step 3).
 
 VIOLATIONS CAUSE RE-DISPATCH.
 
-REQUIRED: EXACTLY three top-level keys: "scores", "findings", "summary".
+REQUIRED: EXACTLY three top-level keys: "scores", "findings" (file field must reference diff files only), "summary".
 Do NOT add "schema_version", "review_result", "id", "review_date", or any other key —
 the validator will reject any extra keys and force a re-dispatch.
 The "scores" object MUST contain ALL five dimensions listed below with integer 1–5 or "N/A".
@@ -115,13 +115,15 @@ will be rejected by the validator and force a re-dispatch.
       "severity": "critical|important|minor",
       "category": "<one of the 5 score dimensions>",
       "description": "...",
-      "file": "path/to/file"
+      "file": "path/to/file (MUST be from the diff being reviewed)"
     }
   ],
   "summary": "2-3 sentence assessment"
 }
 ```
 
+**`file` field constraint**: The `file` field in each finding MUST reference a file present in the diff being reviewed (DIFF_FILE). Do not use files from your recommendations (e.g., test files that should be created) — only files that appear in the actual diff. `record-review.sh` validates that finding files overlap with changed files and rejects the review if they do not.
+
 ---
 
 ## Scoring Rules

plugins/dso/agents/code-reviewer-deep-verification.md

@@ -3,7 +3,7 @@ name: code-reviewer-deep-verification
 model: sonnet
 description: Deep-tier verification specialist (Sonnet B): focused exclusively on verification — test presence, quality, edge case coverage, mock correctness.
 ---
-<!-- content-hash: d814c1f3e94c5d3b14ebdcb18b0f4251fc0da7811ac48f42d26a09ea7e8a3e46 -->
+<!-- content-hash: 602c046ebbc4c7b30de2b9977ef704f29432a3d17e0eec13781409a3a48e7c4a -->
 <!-- generated by build-review-agents.sh — do not edit manually -->
 
 # Code Reviewer — Universal Base Guidance
@@ -92,7 +92,7 @@ Produce a JSON object with this EXACT schema (for writing to disk in Step 3).
 
 VIOLATIONS CAUSE RE-DISPATCH.
 
-REQUIRED: EXACTLY three top-level keys: "scores", "findings", "summary".
+REQUIRED: EXACTLY three top-level keys: "scores", "findings" (file field must reference diff files only), "summary".
 Do NOT add "schema_version", "review_result", "id", "review_date", or any other key —
 the validator will reject any extra keys and force a re-dispatch.
 The "scores" object MUST contain ALL five dimensions listed below with integer 1–5 or "N/A".
@@ -115,13 +115,15 @@ will be rejected by the validator and force a re-dispatch.
       "severity": "critical|important|minor",
       "category": "<one of the 5 score dimensions>",
       "description": "...",
-      "file": "path/to/file"
+      "file": "path/to/file (MUST be from the diff being reviewed)"
     }
   ],
   "summary": "2-3 sentence assessment"
 }
 ```
 
+**`file` field constraint**: The `file` field in each finding MUST reference a file present in the diff being reviewed (DIFF_FILE). Do not use files from your recommendations (e.g., test files that should be created) — only files that appear in the actual diff. `record-review.sh` validates that finding files overlap with changed files and rejects the review if they do not.
+
 ---
 
 ## Scoring Rules

plugins/dso/agents/code-reviewer-light.md

@@ -3,7 +3,7 @@ name: code-reviewer-light
 model: haiku
 description: Light-tier code reviewer: single-pass, highest-signal checklist for fast feedback on low-to-medium-risk changes.
 ---
-<!-- content-hash: 5673f0c1e9c4b3a2b26ead04e6d15316679f75c7e03de602dc4eabcc01a40463 -->
+<!-- content-hash: fe59b4bf97783cc606b8b560efe24fd7d26c0bbeaa5bbc8936cb71c31797959e -->
 <!-- generated by build-review-agents.sh — do not edit manually -->
 
 # Code Reviewer — Universal Base Guidance
@@ -92,7 +92,7 @@ Produce a JSON object with this EXACT schema (for writing to disk in Step 3).
 
 VIOLATIONS CAUSE RE-DISPATCH.
 
-REQUIRED: EXACTLY three top-level keys: "scores", "findings", "summary".
+REQUIRED: EXACTLY three top-level keys: "scores", "findings" (file field must reference diff files only), "summary".
 Do NOT add "schema_version", "review_result", "id", "review_date", or any other key —
 the validator will reject any extra keys and force a re-dispatch.
 The "scores" object MUST contain ALL five dimensions listed below with integer 1–5 or "N/A".
@@ -115,13 +115,15 @@ will be rejected by the validator and force a re-dispatch.
       "severity": "critical|important|minor",
       "category": "<one of the 5 score dimensions>",
       "description": "...",
-      "file": "path/to/file"
+      "file": "path/to/file (MUST be from the diff being reviewed)"
     }
   ],
   "summary": "2-3 sentence assessment"
 }
 ```
 
+**`file` field constraint**: The `file` field in each finding MUST reference a file present in the diff being reviewed (DIFF_FILE). Do not use files from your recommendations (e.g., test files that should be created) — only files that appear in the actual diff. `record-review.sh` validates that finding files overlap with changed files and rejects the review if they do not.
+
 ---
 
 ## Scoring Rules

plugins/dso/agents/code-reviewer-standard.md

@@ -3,7 +3,7 @@ name: code-reviewer-standard
 model: sonnet
 description: Standard-tier code reviewer: comprehensive review across all five scoring dimensions for moderate-to-high-risk changes.
 ---
-<!-- content-hash: 00da22af428ebe07e30ae88b6f3af311c37719a343780d3ab8a5fe4c15b07972 -->
+<!-- content-hash: 6b7521de5275fb0e3e381a422bb5ecef99bba2096586edc65d21a9642540b740 -->
 <!-- generated by build-review-agents.sh — do not edit manually -->
 
 # Code Reviewer — Universal Base Guidance
@@ -92,7 +92,7 @@ Produce a JSON object with this EXACT schema (for writing to disk in Step 3).
 
 VIOLATIONS CAUSE RE-DISPATCH.
 
-REQUIRED: EXACTLY three top-level keys: "scores", "findings", "summary".
+REQUIRED: EXACTLY three top-level keys: "scores", "findings" (file field must reference diff files only), "summary".
 Do NOT add "schema_version", "review_result", "id", "review_date", or any other key —
 the validator will reject any extra keys and force a re-dispatch.
 The "scores" object MUST contain ALL five dimensions listed below with integer 1–5 or "N/A".
@@ -115,13 +115,15 @@ will be rejected by the validator and force a re-dispatch.
       "severity": "critical|important|minor",
       "category": "<one of the 5 score dimensions>",
       "description": "...",
-      "file": "path/to/file"
+      "file": "path/to/file (MUST be from the diff being reviewed)"
     }
   ],
   "summary": "2-3 sentence assessment"
 }
 ```
 
+**`file` field constraint**: The `file` field in each finding MUST reference a file present in the diff being reviewed (DIFF_FILE). Do not use files from your recommendations (e.g., test files that should be created) — only files that appear in the actual diff. `record-review.sh` validates that finding files overlap with changed files and rejects the review if they do not.
+
 ---
 
 ## Scoring Rules

plugins/dso/docs/workflows/REVIEW-WORKFLOW.md

@@ -393,6 +393,8 @@ REPO_ROOT=$(git rev-parse --show-toplevel)
 
 `record-review.sh` reads scores, summary, and findings from `reviewer-findings.json`, verifies `--reviewer-hash` integrity, validates findings against scores, checks file overlap with the actual diff, verifies `--expected-hash` against the current diff hash, and writes the review state file that the commit gate checks. If it rejects, fix and retry.
 
+**File-overlap rejection recovery**: If `record-review.sh` exits with `ERROR: reviewer findings files do not overlap with any changed files in the diff`, the reviewer's `file` fields in its findings reference files not in the diff (e.g., test files from verification recommendations instead of the source files being reviewed). Do NOT escalate to the user immediately. Instead: (1) re-dispatch the review with a higher-tier reviewer (e.g., light → standard) which is more reliable at correctly reporting diff files in the `file` field; (2) if the re-dispatched reviewer also produces non-overlapping files, THEN escalate to the user.
+
 **IMPORTANT — always use `compute-diff-hash.sh`**: Never compute the diff hash via raw `git diff | shasum` — the canonical script applies pathspec exclusions (`.tickets-tracker/`, snapshots, images) and checkpoint-aware diff base detection. Untracked files are excluded (new files must be staged before review). A raw pipeline produces a completely different hash and will cause `--expected-hash` mismatch errors.
 
 ## After Review

plugins/dso/docs/workflows/prompts/reviewer-base.md

@@ -84,7 +84,7 @@ Produce a JSON object with this EXACT schema (for writing to disk in Step 3).
 
 VIOLATIONS CAUSE RE-DISPATCH.
 
-REQUIRED: EXACTLY three top-level keys: "scores", "findings", "summary".
+REQUIRED: EXACTLY three top-level keys: "scores", "findings" (file field must reference diff files only), "summary".
 Do NOT add "schema_version", "review_result", "id", "review_date", or any other key —
 the validator will reject any extra keys and force a re-dispatch.
 The "scores" object MUST contain ALL five dimensions listed below with integer 1–5 or "N/A".
@@ -107,13 +107,15 @@ will be rejected by the validator and force a re-dispatch.
       "severity": "critical|important|minor",
       "category": "<one of the 5 score dimensions>",
       "description": "...",
-      "file": "path/to/file"
+      "file": "path/to/file (MUST be from the diff being reviewed)"
     }
   ],
   "summary": "2-3 sentence assessment"
 }
 ```
 
+**`file` field constraint**: The `file` field in each finding MUST reference a file present in the diff being reviewed (DIFF_FILE). Do not use files from your recommendations (e.g., test files that should be created) — only files that appear in the actual diff. `record-review.sh` validates that finding files overlap with changed files and rejects the review if they do not.
+
 ---
 
 ## Scoring Rules