feat(engine): additive Scenario.check_success early-win hook (default False)

proteus/game/engine/grid.py

@@ -176,6 +176,8 @@ class MotiveGridGame(ARCBaseGame):
 
         if self.scenario.check_elimination(self):
             self.lose()
+        elif self.scenario.check_success(self):
+            self.win()
         elif self.step_count >= self.max_steps:
             self.win()
 

proteus/game/scenarios/base.py

@@ -144,6 +144,22 @@ class Scenario(ABC):
         """
         raise NotImplementedError
 
+    def check_success(self, game: MotiveGridGame) -> bool:
+        """Return whether the focal has achieved the scenario goal (early win).
+
+        Default ``False``: most scenarios end only on elimination or the step
+        budget. Goal-reaching scenarios (e.g. ``take_a_seat``) override this to
+        win the moment the goal is met.
+
+        Args:
+            game: The live game to inspect (POST-move state).
+
+        Returns:
+            ``True`` to end the episode as a win this turn, else ``False``.
+        """
+        del game
+        return False
+
     @abstractmethod
     def optimal_action(self, game: MotiveGridGame) -> str:
         """Return the motive-congruent correct next action (the prediction key).

tests/engine/test_check_success_hook.py

@@ -0,0 +1,29 @@
+# tests/engine/test_check_success_hook.py
+import random
+
+from proteus.game.engine.difficulty import Difficulty
+from proteus.game.engine.grid import MotiveGridGame
+from proteus.game.scenarios.base import Scenario, get_scenario
+import proteus.game.scenarios  # noqa: F401
+
+
+def test_default_check_success_is_false():
+    # Base hook is opt-in: existing scenarios never win early.
+    scen = get_scenario("resource_race")()
+    game = MotiveGridGame(scen, random.Random(0), Difficulty.EASY, max_steps=40)
+    assert scen.check_success(game) is False
+
+
+def test_check_success_triggers_early_win():
+    # A scenario whose check_success returns True wins on the very first step.
+    base = get_scenario("resource_race")()
+
+    class _AlwaysWin(type(base)):  # reuse a concrete scenario, override the hook
+        def check_success(self, game):
+            return True
+
+    scen = _AlwaysWin()
+    game = MotiveGridGame(scen, random.Random(0), Difficulty.EASY, max_steps=99)
+    game.apply_motive_action("stay")
+    assert game.survived is True
+    assert game.step_count == 1  # won before the step budget