Merge pull request 'feat: reject legacy Workspace mutations field in reviewer handoffs (Closes #320)' (#357) from feat/issue-320-remove-workspace-mutations into master

review_proofs.py

@@ -1791,6 +1791,20 @@ HANDOFF_BASE_FIELDS = (
     ("Safety", ("safety",)),
 )
 
+# Issue #320: reviewer handoffs replace the legacy ambiguous
+# "Workspace mutations" field with these precise mutation categories.
+HANDOFF_REVIEW_MUTATION_FIELDS = (
+    ("File edits by reviewer", ("file edits by reviewer",)),
+    ("Worktree/index mutations", ("worktree/index mutations",)),
+    ("Git ref mutations", ("git ref mutations",)),
+    ("MCP/Gitea mutations", ("mcp/gitea mutations",)),
+    ("Review mutations", ("review mutations",)),
+    ("Merge mutations", ("merge mutations",)),
+    ("Cleanup mutations", ("cleanup mutations",)),
+    ("External-state mutations", ("external-state mutations",)),
+    ("Read-only diagnostics", ("read-only diagnostics",)),
+)
+
 HANDOFF_ROLE_FIELDS = {
     "review": (
         ("Selected PR", ("selected pr",)),
@@ -1806,7 +1820,7 @@ HANDOFF_ROLE_FIELDS = {
         ("Merge result", ("merge result",)),
         ("Linked issue status", ("linked issue status", "linked issue")),
         ("Cleanup status", ("cleanup status", "cleanup")),
-    ),
+    ) + HANDOFF_REVIEW_MUTATION_FIELDS,
     "author": (
         ("Selected issue", ("selected issue",)),
         ("Issue lock proof", ("issue lock proof", "lock before diff")),
@@ -1957,6 +1971,25 @@ def assess_controller_handoff(report_text, role=None, local_edits=False):
             field for field in required
             if field[0] not in ("Workspace mutations", "Mutations")
         ]
+    if role == "review":
+        # Issue #320: reviewer handoffs use the precise mutation categories
+        # in HANDOFF_REVIEW_MUTATION_FIELDS instead of the legacy ambiguous
+        # "Workspace mutations" field, which is rejected below.
+        required = [
+            field for field in required
+            if field[0] != "Workspace mutations"
+        ]
+        if any(label.startswith("workspace mutations") for label in labels):
+            return {
+                "verdict": "incomplete",
+                "downgraded": True,
+                "missing_fields": [],
+                "reasons": [
+                    "review handoff must not include legacy "
+                    "'Workspace mutations' field; report the precise "
+                    "mutation categories instead (issue #320)"
+                ],
+            }
     required.extend(HANDOFF_ROLE_FIELDS.get(role or "", ()))
 
     missing = []