fix: scope MCP cleanup proof to mutation ledgers (#517)

Raw branch/comment delete detection now scans only Cleanup mutations,
Git ref mutations, and Worktree mutations ledger fields so narrative
§28B citations and validation notes no longer false-positive.

Authorized cleanup tool proof also applies when cleanup is claimed under
Git ref or Worktree mutation ledgers while Cleanup mutations is none.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

tests/test_mcp_native_cleanup_proof.py

@@ -38,11 +38,22 @@ class TestRawBranchDeleteBlocked(unittest.TestCase):
         self.assertTrue(result["block"])
         self.assertIn("git branch -d", result["commands"][0])
 
-    def test_git_push_delete_blocked(self):
-        report = "Ran git push origin --delete feat/x for cleanup"
+    def test_git_push_delete_in_ledger_blocked(self):
+        report = "- Git ref mutations: git push origin --delete feat/x"
         result = assess_raw_branch_delete_report(report)
         self.assertTrue(result["block"])
 
+    def test_narrative_git_push_delete_not_blocked(self):
+        report = "\n".join([
+            "## Validation",
+            "Workflow §28B forbids raw git push --delete for cleanup.",
+            "- Cleanup mutations: none",
+            "- Git ref mutations: none",
+            "- Worktree mutations: none",
+        ])
+        result = assess_raw_branch_delete_report(report)
+        self.assertFalse(result["block"])
+
     def test_authorized_mcp_path_passes(self):
         report = _authorized_cleanup_report()
         result = assess_raw_branch_delete_report(report)
@@ -50,16 +61,27 @@ class TestRawBranchDeleteBlocked(unittest.TestCase):
 
 
 class TestRawCommentDeleteBlocked(unittest.TestCase):
-    def test_curl_delete_comment_blocked(self):
+    def test_curl_delete_comment_in_ledger_blocked(self):
         report = (
-            "Cleanup: curl -X DELETE https://gitea.example/api/v1/repos/o/r/"
+            "- Cleanup mutations: curl -X DELETE https://gitea.example/api/v1/repos/o/r/"
             "issues/9/comments/42"
         )
         result = assess_raw_comment_delete_report(report)
         self.assertTrue(result["block"])
 
-    def test_delete_issue_comment_helper_blocked(self):
-        report = "Used delete_issue_comment script to purge lease comments"
+    def test_narrative_comment_delete_not_blocked(self):
+        report = "\n".join([
+            "Files reviewed: post_merge_cleanup_proof.py (raw comment delete patterns)",
+            "Validation note: never use delete_issue_comment for lease cleanup.",
+            "- Cleanup mutations: none",
+            "- Git ref mutations: none",
+            "- Worktree mutations: none",
+        ])
+        result = assess_raw_comment_delete_report(report)
+        self.assertFalse(result["block"])
+
+    def test_delete_issue_comment_helper_in_ledger_blocked(self):
+        report = "- Cleanup mutations: delete_issue_comment purged lease comments"
         result = assess_raw_comment_delete_report(report)
         self.assertTrue(result["block"])
 
@@ -84,6 +106,41 @@ class TestAuthorizedReconcilerPath(unittest.TestCase):
         result = assess_authorized_reconciler_cleanup_path(_authorized_cleanup_report())
         self.assertFalse(result["block"])
 
+    def test_git_ref_cleanup_without_mcp_tool_blocked(self):
+        report = "\n".join([
+            "## Controller Handoff",
+            "- Cleanup mutations: none",
+            "- Git ref mutations: git branch -D feat/issue-517-test",
+            "- Reconciler capability: prgs-reconciler",
+        ])
+        result = assess_authorized_reconciler_cleanup_path(report)
+        self.assertTrue(result["block"])
+        self.assertTrue(
+            any("Git ref mutations cleanup must name" in r for r in result["reasons"])
+        )
+
+    def test_worktree_cleanup_without_mcp_tool_blocked(self):
+        report = "\n".join([
+            "## Controller Handoff",
+            "- Cleanup mutations: none",
+            "- Worktree mutations: git worktree remove branches/review-pr542",
+            "- Reconciler capability: prgs-reconciler",
+        ])
+        result = assess_authorized_reconciler_cleanup_path(report)
+        self.assertTrue(result["block"])
+        self.assertTrue(
+            any("Worktree mutations cleanup must name" in r for r in result["reasons"])
+        )
+
+    def test_git_fetch_in_git_ref_mutations_not_cleanup_claim(self):
+        report = "\n".join([
+            "## Controller Handoff",
+            "- Cleanup mutations: none",
+            "- Git ref mutations: git fetch prgs master",
+        ])
+        result = assess_authorized_reconciler_cleanup_path(report)
+        self.assertFalse(result["block"])
+
 
 class TestMergerHandoffGuidance(unittest.TestCase):
     def test_merger_cleanup_without_handoff_blocked(self):
@@ -114,6 +171,33 @@ class TestCompositeVerifier(unittest.TestCase):
         self.assertTrue(result["block"])
         self.assertGreaterEqual(len(result["reasons"]), 2)
 
+    def test_narrative_cleanup_mentions_pass_when_ledgers_none(self):
+        report = "\n".join([
+            "## Review summary",
+            "Validated workflow §28B MCP-native cleanup guidance.",
+            "Files reviewed describe raw git branch -d and delete_issue_comment blocks.",
+            "",
+            "## Controller Handoff",
+            "- Cleanup mutations: none",
+            "- Git ref mutations: none",
+            "- Worktree mutations: none",
+        ])
+        result = assess_mcp_native_cleanup_proof(report)
+        self.assertFalse(result["block"], result["reasons"])
+
+    def test_git_ref_cleanup_bypass_blocked_in_composite(self):
+        report = "\n".join([
+            "## Controller Handoff",
+            "- Cleanup mutations: none",
+            "- Git ref mutations: git branch -D feat/issue-517-test",
+            "- Reconciler capability: prgs-reconciler",
+        ])
+        result = assess_mcp_native_cleanup_proof(report)
+        self.assertTrue(result["block"])
+        self.assertTrue(
+            any("Git ref mutations cleanup must name" in r for r in result["reasons"])
+        )
+
 
 class TestFinalReportValidatorIntegration(unittest.TestCase):
     def test_validator_blocks_raw_branch_delete_in_review_report(self):
@@ -133,6 +217,35 @@ class TestFinalReportValidatorIntegration(unittest.TestCase):
         ]
         self.assertEqual(mcp_blocks, [])
 
+    def test_validator_passes_narrative_cleanup_mentions_with_none_ledgers(self):
+        report = "\n".join([
+            "## Review summary",
+            "Workflow §28B documents raw git push --delete and delete_issue_comment blocks.",
+            "",
+            "## Controller Handoff",
+            "- Cleanup mutations: none",
+            "- Git ref mutations: none",
+            "- Worktree mutations: none",
+        ])
+        result = assess_final_report_validator(report, "review_pr")
+        mcp_blocks = [
+            f for f in result["findings"]
+            if f.get("rule_id") == "shared.mcp_native_cleanup_proof"
+            and f.get("severity") == "block"
+        ]
+        self.assertEqual(mcp_blocks, [])
+
+    def test_validator_blocks_git_ref_cleanup_bypass(self):
+        report = "\n".join([
+            "## Controller Handoff",
+            "- Cleanup mutations: none",
+            "- Git ref mutations: git branch -D feat/issue-517-test",
+            "- Reconciler capability: prgs-reconciler",
+        ])
+        result = assess_final_report_validator(report, "reconcile_already_landed")
+        rules = {f["rule_id"] for f in result["findings"] if f.get("severity") == "block"}
+        self.assertIn("shared.mcp_native_cleanup_proof", rules)
+
 
 if __name__ == "__main__":
     unittest.main()