@@ -29,0 +135,4 @@
+
+    def _tdd_aware_run(self: Any, runner: Any) -> bool:
+        failed: bool = _original_run(self, runner)
+        if not should_invert_result(set(self.effective_tags)):

@@ -29,0 +137,4 @@
+        failed: bool = _original_run(self, runner)
+        if not should_invert_result(set(self.effective_tags)):
+            return failed
+

@@ -29,0 +141,4 @@
+        if failed:
+            # Expected failure — the bug still exists.  Reset the failed
+            # steps so the scenario is reported as passed.
+            for step in self.all_steps:

@@ -29,0 +144,4 @@
+            for step in self.all_steps:
+                if step.status == Status.failed:
+                    step.status = Status.untested
+                    step.exception = None

@@ -0,0 +101,4 @@
+def step_tdd_demo_deliberate_fail(context: Context) -> None:
+    """This step deliberately fails to simulate a bug still being present.
+
+    The ``@tdd_expected_fail`` tag on the scenario causes the after_scenario

@@ -0,0 +1,12 @@
+@mock_only
+Feature: TDD expected-fail result inversion demo
+  Demonstrates the @tdd_expected_fail tag inverting a deliberately failing
+  scenario so it is reported as passed.  This exercises the after_scenario

@@ -29,0 +138,4 @@
+        if not should_invert_result(set(self.effective_tags)):
+            return failed
+
+        if failed:

@@ -29,0 +144,4 @@
+            for step in self.all_steps:
+                if step.status == Status.failed:
+                    step.status = Status.untested
+                    step.exception = None

@@ -29,0 +149,4 @@
+            self.clear_status()
+            self.set_status(Status.passed)
+            return False  # Not a failure for the runner
+        # Unexpected pass — the bug appears to be fixed but the

@@ -0,0 +101,4 @@
+def step_tdd_demo_deliberate_fail(context: Context) -> None:
+    """This step deliberately fails to simulate a bug still being present.
+
+    The ``@tdd_expected_fail`` tag on the scenario causes the after_scenario

@@ -29,0 +135,4 @@
+
+    def _tdd_aware_run(self: Any, runner: Any) -> bool:
+        failed: bool = _original_run(self, runner)
+        if not should_invert_result(set(self.effective_tags)):

@@ -29,0 +138,4 @@
+        if not should_invert_result(set(self.effective_tags)):
+            return failed
+
+        if failed:

@@ -29,0 +144,4 @@
+            for step in self.all_steps:
+                if step.status == Status.failed:
+                    step.status = Status.untested
+                    step.exception = None

@@ -29,0 +158,4 @@
+            "bug fix workflow. See CONTRIBUTING.md > Bug Fix Workflow.",
+            self.name,
+        )
+        self.set_status(Status.failed)

@@ -29,0 +134,4 @@
+    _original_run = Scenario.run
+
+    def _tdd_aware_run(self: Any, runner: Any) -> bool:
+        failed: bool = _original_run(self, runner)

@@ -29,0 +137,4 @@
+        failed: bool = _original_run(self, runner)
+        if not should_invert_result(set(self.effective_tags)):
+            return failed
+

@@ -29,0 +141,4 @@
+        if failed:
+            # Expected failure — the bug still exists.  Reset the failed
+            # steps so the scenario is reported as passed.
+            for step in self.all_steps:

@@ -29,0 +144,4 @@
+            for step in self.all_steps:
+                if step.status == Status.failed:
+                    step.status = Status.untested
+                    step.exception = None

@@ -29,0 +45,4 @@
+#                          fixed without removing the tag (reported as failed).
+#
+# The ``validate_tdd_tags`` and ``should_invert_result`` helpers below are
+# called from the ``before_scenario`` and ``after_scenario`` hooks

@@ -29,0 +135,4 @@
+
+    def _tdd_aware_run(self: Any, runner: Any) -> bool:
+        failed: bool = _original_run(self, runner)
+        if not should_invert_result(set(self.effective_tags)):

@@ -29,0 +137,4 @@
+        failed: bool = _original_run(self, runner)
+        if not should_invert_result(set(self.effective_tags)):
+            return failed
+

@@ -29,0 +144,4 @@
+            for step in self.all_steps:
+                if step.status == Status.failed:
+                    step.status = Status.untested
+                    step.exception = None

@@ -36,0 +218,4 @@
+    return True  # Force failure for the runner
+
+
+def handle_tdd_expected_fail(scenario: Any) -> None:

@@ -36,0 +292,4 @@
+
+    The patch is installed once in ``before_all`` and is idempotent.
+    """
+    from behave.model import Scenario

@@ -228,0 +507,4 @@
+    # Validate the three-tag system BEFORE any other setup so that
+    # misconfigured TDD tests are caught immediately.
+    # See CONTRIBUTING.md > TDD Bug Test Tags for the full specification.
+    validate_tdd_tags(set(scenario.effective_tags))

@@ -0,0 +117,4 @@
+
+
+@then("tdd demo this step is never reached")
+def step_tdd_demo_never_reached(context: Context) -> None:

@@ -36,0 +237,4 @@
+
+    Args:
+        scenario: A Behave ``Scenario`` (or compatible mock) with at least
+            ``effective_tags`` (or ``tags``), ``all_steps``, ``status``,

@@ -228,0 +508,4 @@
+    try:
+        validate_tdd_tags(set(scenario.effective_tags))
+    except ValueError as exc:
+        scenario.set_status(Status.failed)