diff --git a/docs/mcp-namespace-health.md b/docs/mcp-namespace-health.md index f73ece1..206446a 100644 --- a/docs/mcp-namespace-health.md +++ b/docs/mcp-namespace-health.md @@ -52,3 +52,25 @@ The read-only `gitea_assess_mcp_namespace_health` tool can classify probe evidence supplied by a client. It intentionally distinguishes `required_tool_registered=true` from `required_tool_callable=false`; the latter must block reviewer and merger workflows until the live namespace is repaired. + +## Enforcement in the review/merge state machine + +The block is not advisory. Feed the `blocks_merge_workflow` verdict from +`gitea_assess_mcp_namespace_health` into +`gitea_assess_review_merge_state_machine` as `live_namespace_broken`: + +```text +health = gitea_assess_mcp_namespace_health(namespace="gitea-merger", ...) +state = gitea_assess_review_merge_state_machine( + state_completion=..., + pre_merge_gates=..., + live_namespace_broken=health["blocks_merge_workflow"], + ) +# state["merge"]["allowed"] is False whenever the live namespace is broken, +# even when every review state and pre-merge gate is otherwise satisfied. +``` + +When `live_namespace_broken=True`, `assess_workflow_blockers`, +`can_approve`, `can_merge`, and `workflow_status` all fail closed. This is the +guard that stops a merge from proceeding on a false-ready namespace, as in the +PR #418 halt that motivated this work (#543). diff --git a/gitea_mcp_server.py b/gitea_mcp_server.py index 28f83d6..308c367 100644 --- a/gitea_mcp_server.py +++ b/gitea_mcp_server.py @@ -8625,40 +8625,45 @@ def gitea_assess_review_merge_state_machine( pre_merge_gates: dict[str, bool] | None = None, infra_stop: bool = False, capability_blocked: bool = False, + live_namespace_broken: bool = False, recovery_handoff_text: str | None = None, final_report_text: str | None = None, ) -> dict: - """Read-only: assess enforced PR review/merge workflow state (#290).""" + """Read-only: assess enforced PR review/merge workflow state (#290). + + ``live_namespace_broken`` fails review/merge closed when the live MCP + namespace call path is unusable even though the tool is registered in + FastMCP (#543 AC5). Supply the ``blocks_merge_workflow`` verdict from + ``gitea_assess_mcp_namespace_health``. + """ completion = state_completion or {} - blockers = review_merge_state_machine.assess_workflow_blockers( - infra_stop=infra_stop, - capability_blocked=capability_blocked, - ) + blocker_kwargs = { + "infra_stop": infra_stop, + "capability_blocked": capability_blocked, + "live_namespace_broken": live_namespace_broken, + } + blockers = review_merge_state_machine.assess_workflow_blockers(**blocker_kwargs) result = { "workflow": review_merge_state_machine.workflow_status( completion, - infra_stop=infra_stop, - capability_blocked=capability_blocked, + **blocker_kwargs, ), "blockers": blockers, "approve": review_merge_state_machine.can_approve( completion, - infra_stop=infra_stop, - capability_blocked=capability_blocked, + **blocker_kwargs, ), "merge": review_merge_state_machine.can_merge( completion, pre_merge_gates=pre_merge_gates, - infra_stop=infra_stop, - capability_blocked=capability_blocked, + **blocker_kwargs, ), } if target_state: result["advancement"] = review_merge_state_machine.assess_state_advancement( completion, target_state=target_state, - infra_stop=infra_stop, - capability_blocked=capability_blocked, + **blocker_kwargs, ) if recovery_handoff_text is not None: result["recovery_handoff"] = ( diff --git a/review_merge_state_machine.py b/review_merge_state_machine.py index 33c9705..8262a00 100644 --- a/review_merge_state_machine.py +++ b/review_merge_state_machine.py @@ -93,8 +93,16 @@ def assess_workflow_blockers( capability_blocked: bool = False, mcp_reconnect_failed: bool = False, stale_capability_state: bool = False, + live_namespace_broken: bool = False, ) -> dict[str, Any]: - """Return hard blockers that forbid all PR queue work (#290 AC3).""" + """Return hard blockers that forbid all PR queue work (#290 AC3). + + ``live_namespace_broken`` fails the merge/review path closed when the live + MCP namespace call path is unusable (e.g. ``client is closing: EOF``) even + though the tool is registered in FastMCP (#543 AC5). Feed it the + ``blocks_merge_workflow`` verdict from + ``mcp_namespace_health.classify_namespace_probe``. + """ reasons: list[str] = [] if infra_stop: reasons.append("infra_stop is active; PR selection/review/merge is forbidden") @@ -104,6 +112,12 @@ def assess_workflow_blockers( reasons.append("MCP reconnect failed; stale session state cannot be reused") if stale_capability_state: reasons.append("stale MCP capability state detected after reconnect failure") + if live_namespace_broken: + reasons.append( + "live MCP namespace call path is broken (registered in FastMCP but " + "not callable through the namespace); repair the namespace before " + "review/merge" + ) return { "block": bool(reasons), "reasons": reasons, @@ -118,16 +132,19 @@ def assess_state_advancement( state_completion: dict[str, bool] | None, *, target_state: str, - infra_stop: bool = False, - capability_blocked: bool = False, + **blocker_kwargs, ) -> dict[str, Any]: - """Fail closed when *target_state* is requested before upstream gates pass.""" + """Fail closed when *target_state* is requested before upstream gates pass. + + Forwards every blocker flag (``infra_stop``, ``capability_blocked``, + ``mcp_reconnect_failed``, ``stale_capability_state``, + ``live_namespace_broken``) to :func:`assess_workflow_blockers` so + ``can_approve``/``can_merge`` honor the full blocker set, not just + infra_stop/capability_blocked (#543 AC5). + """ completion = dict(state_completion or {}) target = _clean(target_state).upper() - blockers = assess_workflow_blockers( - infra_stop=infra_stop, - capability_blocked=capability_blocked, - ) + blockers = assess_workflow_blockers(**blocker_kwargs) reasons = list(blockers["reasons"]) try: diff --git a/tests/test_mcp_namespace_health.py b/tests/test_mcp_namespace_health.py index 8f06ee4..44f81f1 100644 --- a/tests/test_mcp_namespace_health.py +++ b/tests/test_mcp_namespace_health.py @@ -2,6 +2,7 @@ import unittest import gitea_mcp_server import mcp_namespace_health +import review_merge_state_machine as rmsm class TestMcpNamespaceHealth(unittest.TestCase): @@ -81,5 +82,74 @@ class TestMcpNamespaceHealth(unittest.TestCase): self.assertEqual(result["diagnostics"]["process_pid"], 9876) +class TestLiveNamespaceBlocksMerge(unittest.TestCase): + """AC5: a broken live namespace must hard-block the review/merge state machine.""" + + def _merge_ready_completion(self): + # Completion through PRE_MERGE_RECHECK is the state where a clean merge + # is otherwise allowed (see test_merge_allowed_with_pre_merge_gates). + idx = rmsm.REVIEW_MERGE_STATES.index("PRE_MERGE_RECHECK") + return {state: True for state in rmsm.REVIEW_MERGE_STATES[: idx + 1]} + + def _all_gates(self): + return {gate: True for gate in rmsm._PRE_MERGE_REQUIRED_GATES} + + def test_assess_workflow_blockers_flags_live_namespace_broken(self): + clean = rmsm.assess_workflow_blockers() + self.assertFalse(clean["block"]) + + broken = rmsm.assess_workflow_blockers(live_namespace_broken=True) + self.assertTrue(broken["block"]) + self.assertTrue(any("namespace" in r.lower() for r in broken["reasons"])) + + def test_can_merge_blocks_even_when_all_gates_pass(self): + # Without the namespace blocker a fully-complete workflow can merge... + allowed = rmsm.can_merge( + self._merge_ready_completion(), pre_merge_gates=self._all_gates() + ) + self.assertTrue(allowed["allowed"]) + + # ...but a broken live namespace overrides every satisfied gate. + blocked = rmsm.can_merge( + self._merge_ready_completion(), + pre_merge_gates=self._all_gates(), + live_namespace_broken=True, + ) + self.assertTrue(blocked["block"]) + self.assertFalse(blocked["allowed"]) + + def test_workflow_status_forwards_namespace_blocker(self): + status = rmsm.workflow_status( + self._merge_ready_completion(), live_namespace_broken=True + ) + self.assertFalse(status["merge_allowed"]) + self.assertFalse(status["approve_allowed"]) + + def test_server_tool_blocks_merge_on_live_namespace_broken(self): + result = gitea_mcp_server.gitea_assess_review_merge_state_machine( + state_completion=self._merge_ready_completion(), + pre_merge_gates=self._all_gates(), + live_namespace_broken=True, + ) + self.assertTrue(result["blockers"]["block"]) + self.assertFalse(result["merge"]["allowed"]) + + def test_classify_verdict_bridges_into_merge_block(self): + # The classify verdict is the intended feed for live_namespace_broken. + verdict = mcp_namespace_health.classify_namespace_probe( + "gitea-merger", + registered_tools=["gitea_whoami", "gitea_adopt_merger_pr_lease"], + probe_result={"success": False, "error": "client is closing: EOF"}, + process={"pid": 555, "profile": "prgs-merger"}, + ) + self.assertTrue(verdict["blocks_merge_workflow"]) + blocked = rmsm.can_merge( + self._merge_ready_completion(), + pre_merge_gates=self._all_gates(), + live_namespace_broken=verdict["blocks_merge_workflow"], + ) + self.assertFalse(blocked["allowed"]) + + if __name__ == "__main__": unittest.main()