fix(profiles): canonical reconciler ops and guard raw branch delete (#687)

Address REQUEST_CHANGES on PR #688: - migrate_profiles: emit fully canonical reconciler/author/reviewer defaults; canonicalize explicit ops; fail if reconciler loses required pr.close/read - gitea_delete_branch: deny reconciler (and non-author roles); refuse preservation/protected branches before any API call - gitea_cleanup_merged_pr_branch: require reconciler role only; block preservation/evidence branches via branch_cleanup_guard - docs: end-to-end operator runbook for profile migrate/apply/reconnect/cleanup - tests: migration canonicalization, idempotency, raw-delete denial, guarded cleanup success and unmerged/preserve rejections Closes #687.
2026-07-12 22:35:14 -04:00
parent c7a444eb4b
commit 4a63578003
8 changed files with 702 additions and 55 deletions
@@ -27,7 +27,13 @@ from task_capability_map import required_permission, required_role

 DELETE_PROFILE = {
    "profile_name": "prgs-author-delete",
-    "allowed_operations": ["gitea.read", "gitea.branch.delete"],
+    "role": "author",
+    "allowed_operations": [
+        "gitea.read",
+        "gitea.pr.create",
+        "gitea.branch.push",
+        "gitea.branch.delete",
+    ],
    "forbidden_operations": [],
    "audit_label": "prgs-author-delete",
 }
@@ -8,10 +8,33 @@ import branch_cleanup_guard as guard  # noqa: E402
 import mcp_server  # noqa: E402
 import task_capability_map  # noqa: E402
 from final_report_validator import assess_final_report_validator  # noqa: E402
-from mcp_server import gitea_cleanup_merged_pr_branch  # noqa: E402
+from mcp_server import gitea_cleanup_merged_pr_branch, gitea_delete_branch  # noqa: E402

 FAKE_AUTH = "token fake"

+# Reconciler-shaped profile that holds branch.delete (recommended) plus
+# required pr.close/read so _role_kind classifies as reconciler.
+RECONCILER_WITH_DELETE = {
+    "profile_name": "prgs-reconciler",
+    "role": "reconciler",
+    "allowed_operations": [
+        "gitea.read",
+        "gitea.pr.close",
+        "gitea.pr.comment",
+        "gitea.issue.comment",
+        "gitea.issue.close",
+        "gitea.branch.delete",
+    ],
+    "forbidden_operations": [
+        "gitea.pr.approve",
+        "gitea.pr.merge",
+        "gitea.pr.review",
+        "gitea.pr.create",
+        "gitea.branch.push",
+        "gitea.repo.commit",
+    ],
+}
+

 class TestRawBranchDeleteGuard(unittest.TestCase):
    def test_detects_local_and_remote_raw_git_delete_commands(self):
@@ -134,11 +157,7 @@ class TestMergedPrBranchCleanupTool(unittest.TestCase):
    def test_root_checkout_cleanup_fails_closed(self):
        patch(
            "mcp_server.get_profile",
-            return_value={
-                "profile_name": "branch-cleanup",
-                "allowed_operations": ["gitea.read", "gitea.branch.delete"],
-                "forbidden_operations": [],
-            },
+            return_value=dict(RECONCILER_WITH_DELETE),
        ).start()
        res = gitea_cleanup_merged_pr_branch(
            pr_number=487,
@@ -155,11 +174,7 @@ class TestMergedPrBranchCleanupTool(unittest.TestCase):
        branch = "feat/issue-485-lease-comments-non-list-guard"
        patch(
            "mcp_server.get_profile",
-            return_value={
-                "profile_name": "branch-cleanup",
-                "allowed_operations": ["gitea.read", "gitea.branch.delete"],
-                "forbidden_operations": [],
-            },
+            return_value=dict(RECONCILER_WITH_DELETE),
        ).start()
        self.mock_api.side_effect = [
            {
@@ -190,11 +205,7 @@ class TestMergedPrBranchCleanupTool(unittest.TestCase):
        branch = "feat/issue-485-lease-comments-non-list-guard"
        patch(
            "mcp_server.get_profile",
-            return_value={
-                "profile_name": "branch-cleanup",
-                "allowed_operations": ["gitea.read", "gitea.branch.delete"],
-                "forbidden_operations": [],
-            },
+            return_value=dict(RECONCILER_WITH_DELETE),
        ).start()
        self.mock_api.side_effect = [
            {
@@ -220,6 +231,168 @@ class TestMergedPrBranchCleanupTool(unittest.TestCase):
        ]
        self.assertFalse(delete_calls)

+    def test_reconciler_with_branch_delete_cannot_raw_delete(self):
+        """#687: reconciler + gitea.branch.delete still cannot call raw delete."""
+        patch(
+            "mcp_server.get_profile",
+            return_value=dict(RECONCILER_WITH_DELETE),
+        ).start()
+        res = gitea_delete_branch(
+            branch="fix/issue-683-workflow-guard-hardening",
+            remote="prgs",
+        )
+        self.assertFalse(res.get("success", True))
+        self.assertFalse(res.get("performed", True))
+        reasons = " ".join(res.get("reasons") or [])
+        self.assertIn("raw gitea_delete_branch", reasons)
+        self.assertIn("cleanup_merged_pr_branch", reasons)
+        self.mock_api.assert_not_called()
+
+    def test_reconciler_raw_delete_denies_preservation_branch(self):
+        patch(
+            "mcp_server.get_profile",
+            return_value=dict(RECONCILER_WITH_DELETE),
+        ).start()
+        res = gitea_delete_branch(
+            branch="chore/issue-681-preserve-review-session-wip",
+            remote="prgs",
+        )
+        self.assertFalse(res.get("performed", True))
+        self.mock_api.assert_not_called()
+
+    def test_author_with_branch_delete_role_ok_but_preserve_blocked(self):
+        """Author role may use raw delete path when permitted; preserve fails closed."""
+        patch(
+            "mcp_server.get_profile",
+            return_value={
+                "profile_name": "prgs-author",
+                "role": "author",
+                "allowed_operations": [
+                    "gitea.read",
+                    "gitea.pr.create",
+                    "gitea.branch.push",
+                    "gitea.branch.delete",
+                ],
+                "forbidden_operations": ["gitea.pr.approve", "gitea.pr.merge"],
+            },
+        ).start()
+        res = gitea_delete_branch(
+            branch="chore/issue-681-preserve-review-session-wip",
+            remote="prgs",
+        )
+        self.assertFalse(res.get("performed", True))
+        self.assertIn("preservation", " ".join(res.get("reasons") or []))
+        self.mock_api.assert_not_called()
+
+    def test_unmerged_branch_cleanup_rejected(self):
+        branch = "feat/unmerged-work"
+        patch(
+            "mcp_server.get_profile",
+            return_value=dict(RECONCILER_WITH_DELETE),
+        ).start()
+        self.mock_api.side_effect = [
+            {
+                "number": 999,
+                "merged": False,
+                "merged_at": None,
+                "head": {"ref": branch, "sha": "b" * 40},
+                "base": {"ref": "master"},
+            },
+            {},
+        ]
+        res = gitea_cleanup_merged_pr_branch(
+            pr_number=999,
+            confirmation=f"CLEANUP MERGED PR 999 BRANCH {branch}",
+            branch=branch,
+            remote="prgs",
+            worktree_path="/tmp/repo/branches/cleanup",
+        )
+        self.assertFalse(res["performed"])
+        self.assertTrue(
+            any("not merged" in r for r in (res.get("reasons") or []))
+        )
+        delete_calls = [
+            call for call in self.mock_api.call_args_list if call.args[0] == "DELETE"
+        ]
+        self.assertFalse(delete_calls)
+
+    def test_preservation_branch_cleanup_rejected(self):
+        branch = "chore/issue-681-preserve-review-session-wip"
+        patch(
+            "mcp_server.get_profile",
+            return_value=dict(RECONCILER_WITH_DELETE),
+        ).start()
+        self.mock_api.side_effect = [
+            {
+                "number": 681,
+                "merged": True,
+                "merged_at": "2026-07-08T01:00:00Z",
+                "head": {"ref": branch, "sha": "c" * 40},
+                "base": {"ref": "master"},
+            },
+            {},
+        ]
+        res = gitea_cleanup_merged_pr_branch(
+            pr_number=681,
+            confirmation=f"CLEANUP MERGED PR 681 BRANCH {branch}",
+            branch=branch,
+            remote="prgs",
+            worktree_path="/tmp/repo/branches/cleanup",
+        )
+        self.assertFalse(res["performed"])
+        self.assertTrue(
+            any("preservation" in r for r in (res.get("reasons") or []))
+        )
+        delete_calls = [
+            call for call in self.mock_api.call_args_list if call.args[0] == "DELETE"
+        ]
+        self.assertFalse(delete_calls)
+
+    def test_non_reconciler_with_delete_denied_cleanup(self):
+        patch(
+            "mcp_server.get_profile",
+            return_value={
+                "profile_name": "prgs-author",
+                "role": "author",
+                "allowed_operations": [
+                    "gitea.read",
+                    "gitea.pr.create",
+                    "gitea.branch.push",
+                    "gitea.branch.delete",
+                ],
+                "forbidden_operations": [],
+            },
+        ).start()
+        res = gitea_cleanup_merged_pr_branch(
+            pr_number=487,
+            confirmation="CLEANUP MERGED PR 487 BRANCH feat/branch",
+            branch="feat/branch",
+            remote="prgs",
+            worktree_path="/tmp/repo/branches/cleanup",
+        )
+        self.assertFalse(res["performed"])
+        self.assertEqual(res.get("required_role_kind"), "reconciler")
+        self.mock_api.assert_not_called()
+
+    def test_assess_guard_rejects_preservation_branch(self):
+        assessment = guard.assess_merged_pr_branch_cleanup(
+            pr_number=681,
+            head_branch="chore/issue-681-preserve-review-session-wip",
+            merged=True,
+            remote_branch_exists=True,
+            open_pr_heads=set(),
+            head_on_target=True,
+            delete_capability_allowed=True,
+            confirmation=(
+                "CLEANUP MERGED PR 681 BRANCH "
+                "chore/issue-681-preserve-review-session-wip"
+            ),
+        )
+        self.assertFalse(assessment["safe_to_delete"])
+        self.assertTrue(
+            any("preservation" in r for r in assessment["block_reasons"])
+        )
+

 if __name__ == "__main__":
    unittest.main()
@@ -1425,10 +1425,16 @@ class TestReviewPR(unittest.TestCase):
 class TestDeleteBranch(unittest.TestCase):

    DELETE_PROFILE = {
-        "profile_name": "test-deleter",
-        "allowed_operations": ["gitea.read", "gitea.branch.delete"],
+        "profile_name": "test-author-deleter",
+        "role": "author",
+        "allowed_operations": [
+            "gitea.read",
+            "gitea.pr.create",
+            "gitea.branch.push",
+            "gitea.branch.delete",
+        ],
        "forbidden_operations": [],
-        "audit_label": "test-deleter",
+        "audit_label": "test-author-deleter",
    }

    @patch("mcp_server.get_profile", return_value=DELETE_PROFILE)
@@ -92,14 +92,19 @@ class TestMigrateProfiles(unittest.TestCase):
        author = prgs_gitea["identities"]["author"]
        self.assertEqual(author["username"], "jcwalker3")
        self.assertEqual(author["auth"]["id"], "redacted-author-ref")
-        self.assertEqual(author["allowed_operations"], ["read", "comment"])
-        self.assertEqual(author["forbidden_operations"], ["approve", "merge"])
+        self.assertEqual(
+            author["allowed_operations"], ["gitea.read", "gitea.pr.comment"]
+        )
+        self.assertEqual(
+            author["forbidden_operations"],
+            ["gitea.pr.approve", "gitea.pr.merge"],
+        )

        reviewer = prgs_gitea["identities"]["reviewer"]
        self.assertEqual(reviewer["role"], "reviewer")
        self.assertEqual(reviewer["username"], "sysadmin")
        self.assertEqual(reviewer["auth"]["id"], "redacted-reviewer-ref")
-        self.assertIn("merge", reviewer["allowed_operations"])
+        self.assertIn("gitea.pr.merge", reviewer["allowed_operations"])

    def test_alias_generation(self):
        """Test that aliases are correctly generated to support old profile names."""
@@ -188,7 +193,7 @@ class TestMigrateProfiles(unittest.TestCase):
        self.assertNotIn("token", stdout_output.lower())

    def test_explicit_operations_are_preserved(self):
-        """Explicit v1 permissions must not be replaced by role defaults."""
+        """Explicit v1 permissions are canonicalized, not replaced by role defaults."""
        v1_data = json.loads(json.dumps(self.v1_content))
        v1_data["profiles"]["prgs-reviewer"]["allowed_operations"] = ["read"]
        v1_data["profiles"]["prgs-reviewer"]["forbidden_operations"] = ["merge"]
@@ -198,8 +203,8 @@ class TestMigrateProfiles(unittest.TestCase):
            v2_data["environments"]["prgs"]["services"]["gitea"]
            ["identities"]["reviewer"]
        )
-        self.assertEqual(reviewer["allowed_operations"], ["read"])
-        self.assertEqual(reviewer["forbidden_operations"], ["merge"])
+        self.assertEqual(reviewer["allowed_operations"], ["gitea.read"])
+        self.assertEqual(reviewer["forbidden_operations"], ["gitea.pr.merge"])

    def test_inferred_role_defaults_only_when_unambiguous(self):
        """Role defaults are allowed only for clear author/reviewer profiles."""
@@ -307,7 +312,10 @@ class TestMigrateProfiles(unittest.TestCase):
            self.assertEqual(cm.exception.code, 1)

    def test_reconciler_profile_migration(self):
-        """Verify that reconciler profiles with explicit operations migrate correctly."""
+        """Legacy reconciler shorthands migrate to valid canonical operations."""
+        import gitea_config
+        import reconciler_profile
+
        v1_data = {
            "version": 1,
            "profiles": {
@@ -316,8 +324,22 @@ class TestMigrateProfiles(unittest.TestCase):
                    "username": "reconciler-agent",
                    "auth": {"type": "keychain", "id": "reconciler-ref"},
                    "execution_profile": "prgs-reconciler",
-                    "allowed_operations": ["read", "pr.close", "gitea.branch.delete"],
-                    "forbidden_operations": ["merge", "approve"]
+                    "allowed_operations": [
+                        "read",
+                        "pr.close",
+                        "pr.comment",
+                        "issue.comment",
+                        "issue.close",
+                        "gitea.branch.delete",
+                    ],
+                    "forbidden_operations": [
+                        "merge",
+                        "approve",
+                        "review",
+                        "pr.create",
+                        "branch.push",
+                        "commit",
+                    ],
                }
            }
        }
@@ -327,12 +349,35 @@ class TestMigrateProfiles(unittest.TestCase):
            ["identities"]["reconciler"]
        )
        self.assertEqual(reconciler["role"], "reconciler")
-        self.assertEqual(reconciler["allowed_operations"], ["read", "pr.close", "gitea.branch.delete"])
-        self.assertEqual(reconciler["forbidden_operations"], ["merge", "approve"])
+        allowed = reconciler["allowed_operations"]
+        forbidden = reconciler["forbidden_operations"]
+        # No invalid shorthand remains
+        for bad in ("pr.close", "pr.comment", "issue.close", "read", "merge"):
+            self.assertNotIn(bad, allowed)
+            self.assertNotIn(bad, forbidden)
+        for required in (
+            "gitea.read",
+            "gitea.pr.close",
+            "gitea.pr.comment",
+            "gitea.issue.comment",
+            "gitea.issue.close",
+            "gitea.branch.delete",
+        ):
+            self.assertIn(required, allowed)
+            # Production loader accepts every allowed op
+            self.assertEqual(
+                gitea_config.normalize_operation(required), required
+            )
        self.assertEqual(v2_data["aliases"]["prgs-reconciler"], "prgs.gitea.reconciler")
+        assessment = reconciler_profile.assess_reconciler_profile(allowed, forbidden)
+        self.assertTrue(assessment["valid"])
+        self.assertTrue(migrate_profiles.validate_v2_data(v2_data))

    def test_reconciler_profile_defaults(self):
-        """Verify that reconciler profiles without explicit operations get defaults."""
+        """Reconciler defaults are fully canonical and loader-valid."""
+        import gitea_config
+        import reconciler_profile
+
        v1_data = {
            "version": 1,
            "profiles": {
@@ -358,6 +403,77 @@ class TestMigrateProfiles(unittest.TestCase):
            reconciler["forbidden_operations"],
            migrate_profiles.RECONCILER_DEFAULT_FORBIDDEN,
        )
+        for op in reconciler["allowed_operations"]:
+            self.assertEqual(gitea_config.normalize_operation(op), op)
+            self.assertTrue(op.startswith("gitea."))
+        assessment = reconciler_profile.assess_reconciler_profile(
+            reconciler["allowed_operations"],
+            reconciler["forbidden_operations"],
+        )
+        self.assertTrue(assessment["valid"])
+        self.assertNotIn(
+            "gitea.branch.delete", assessment["missing_recommended_operations"]
+        )
+
+    def test_reconciler_migration_idempotent_canonicalize(self):
+        """Second canonicalize of already-canonical ops is a no-op."""
+        first = migrate_profiles.canonicalize_operations(
+            list(migrate_profiles.RECONCILER_DEFAULT_ALLOWED)
+        )
+        second = migrate_profiles.canonicalize_operations(first)
+        self.assertEqual(first, second)
+        self.assertEqual(first, list(migrate_profiles.RECONCILER_DEFAULT_ALLOWED))
+
+    def test_reconciler_missing_required_fails_visibly(self):
+        """Missing gitea.pr.close after migration fails closed (not silent drop)."""
+        v1_data = {
+            "version": 1,
+            "profiles": {
+                "prgs-reconciler": {
+                    "base_url": "redacted-prgs-service",
+                    "username": "reconciler-agent",
+                    "auth": {"type": "keychain", "id": "reconciler-ref"},
+                    "execution_profile": "prgs-reconciler",
+                    "allowed_operations": ["read", "gitea.branch.delete"],
+                    "forbidden_operations": ["merge"],
+                }
+            },
+        }
+        with self.assertRaisesRegex(ValueError, "missing required"):
+            migrate_profiles.migrate_v1_to_v2(v1_data)
+
+    def test_unknown_operation_fails_visibly(self):
+        v1_data = {
+            "version": 1,
+            "profiles": {
+                "prgs-author": {
+                    "base_url": "redacted-prgs-service",
+                    "username": "jcwalker3",
+                    "auth": {"type": "keychain", "id": "hidden-author-ref"},
+                    "execution_profile": "prgs-author",
+                    "allowed_operations": ["read", "not.a.real.op"],
+                    "forbidden_operations": ["merge"],
+                }
+            },
+        }
+        with self.assertRaisesRegex(ValueError, "cannot be canonicalized"):
+            migrate_profiles.migrate_v1_to_v2(v1_data)
+
+    def test_role_inference_author_reviewer_merger_reconciler(self):
+        self.assertEqual(
+            migrate_profiles.infer_role("prgs-author", "prgs-author"), "author"
+        )
+        self.assertEqual(
+            migrate_profiles.infer_role("prgs-reviewer", "prgs-reviewer"),
+            "reviewer",
+        )
+        self.assertEqual(
+            migrate_profiles.infer_role("prgs-reconciler", "prgs-reconciler"),
+            "reconciler",
+        )
+        self.assertIsNone(
+            migrate_profiles.infer_role("prgs-merger", "prgs-merger")
+        )


 if __name__ == "__main__":