Implementation Plan: T5-P4-A2-WP2 Make build_inspector_cmd a Proper Capability-Gated Method (#4093)

## Summary

Replace the unchecked `RuntimeError` stubs in both
`ClaudeCodeBackend.build_inspector_cmd` and
`CodexBackend.build_inspector_cmd` with a proper
`CapabilityNotSupportedError` that is raised only when
`inspector_capable=False`. This involves:

1. Defining `CapabilityNotSupportedError(Exception)` in
`core/types/_type_exceptions.py` with structured `capability` and
`backend_name` fields
2. Replacing `RuntimeError` raises in both backends with
`CapabilityNotSupportedError`
3. Removing `inspector_capable` from `_FORWARD_DECLARED` (it now has a
production consumer)
4. Updating conformance tests to assert the new exception type
5. Adding a parametrized arch test in
`test_backend_behavioral_contract.py`

## Implementation Plan

Plan file:
`/home/talon/projects/autoskillit-runs/impl-20260612-102320-415368/.autoskillit/temp/make-plan/t5-p4-a2-wp2-capability-gated-build-inspector-cmd_plan_2026-06-12_103500.md`

Closes #4017

🤖 Generated with [Claude Code](https://claude.com/claude-code) via
AutoSkillit
<!-- autoskillit:pipeline-signature
steps=prepare_pr,run_arch_lenses,compose_pr,annotate_pr_diff,review_pr
-->

## Token Usage Summary

| Step | Model | count | uncached | output | cache_read | peak_ctx |
turns | cache_write | time |

|------|-------|-------|----------|--------|------------|----------|-------|-------------|------|
| plan* | opus[1m] | 1 | 3.5k | 11.9k | 1.1M | 94.3k | 40 | 73.3k | 10m
33s |
| verify* | sonnet | 1 | 172 | 13.7k | 1.1M | 65.3k | 72 | 44.4k | 4m
17s |
| implement* | MiniMax-M3 | 1 | 2.0M | 8.4k | 0 | 0 | 74 | 0 | 4m 16s |
| fix* | sonnet | 1 | 126 | 5.2k | 692.4k | 59.5k | 42 | 38.6k | 5m 34s
|
| audit_impl* | sonnet | 1 | 46 | 16.1k | 168.1k | 43.3k | 17 | 38.9k |
5m 34s |
| prepare_pr* | MiniMax-M3 | 1 | 196.1k | 2.3k | 0 | 0 | 13 | 0 | 55s |
| compose_pr* | MiniMax-M3 | 1 | 176.6k | 1.2k | 0 | 0 | 11 | 0 | 46s |
| **Total** | | | 2.4M | 58.9k | 3.1M | 94.3k | | 195.2k | 31m 56s |

\* *Step used a non-Anthropic provider; caching behavior may differ.*

## Token Efficiency

| Step | LoC Changed | cache_read/LoC | cache_write/LoC | output/LoC |
|------|-------------|----------------|-----------------|------------|
| plan | 0 | — | — | — |
| verify | 0 | — | — | — |
| implement | 50 | 0.0 | 0.0 | 167.2 |
| fix | 7 | 98910.0 | 5514.4 | 745.6 |
| audit_impl | 0 | — | — | — |
| prepare_pr | 0 | — | — | — |
| compose_pr | 0 | — | — | — |
| **Total** | **57** | 53800.9 | 3425.0 | 1033.6 |

## Model Usage Breakdown

| Model | steps | uncached | output | cache_read | cache_write | time |
|-------|-------|----------|--------|------------|-------------|------|
| opus[1m] | 1 | 3.5k | 11.9k | 1.1M | 73.3k | 10m 33s |
| sonnet | 3 | 344 | 35.1k | 1.9M | 121.9k | 15m 26s |
| MiniMax-M3 | 3 | 2.4M | 11.9k | 0 | 0 | 5m 56s |

Author: Trecek

src/autoskillit/core/__init__.pyi

@@ -223,6 +223,7 @@ from .types import BackgroundSupervisor as BackgroundSupervisor
 from .types import BareResume as BareResume
 from .types import CampaignProtector as CampaignProtector
 from .types import CanonicalTokenUsage as CanonicalTokenUsage
+from .types import CapabilityNotSupportedError as CapabilityNotSupportedError
 from .types import CaptureEntrySpec as CaptureEntrySpec
 from .types import CaptureValueType as CaptureValueType
 from .types import CaptureValueTypeError as CaptureValueTypeError

src/autoskillit/core/types/_type_exceptions.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 __all__ = [
+    "CapabilityNotSupportedError",
     "RecipeLoadError",
     "ProcessStaleError",
     "RecipeNotFoundError",
@@ -19,3 +20,12 @@ class ProcessStaleError(RecipeLoadError):
 
 class RecipeNotFoundError(RecipeLoadError):
     """Named recipe could not be found in any scan directory."""
+
+
+class CapabilityNotSupportedError(Exception):
+    """Backend does not support the requested capability."""
+
+    def __init__(self, capability: str, backend_name: str) -> None:
+        self.capability = capability
+        self.backend_name = backend_name
+        super().__init__(f"{backend_name!r} does not support capability {capability!r}")

src/autoskillit/execution/backends/claude.py

@@ -27,6 +27,7 @@
     BackendConventions,
     BackendEventKind,
     BareResume,
+    CapabilityNotSupportedError,
     ClaudeDirectoryConventions,
     ClaudeEventData,
     ClaudeFlags,
@@ -865,4 +866,7 @@ def ensure_pre_launch(self) -> list[str]:
         return []
 
     def build_inspector_cmd(self, prompt: str, *, model: str = "") -> CmdSpec:
-        raise RuntimeError("build_inspector_cmd not yet implemented — lands in #3534")
+        if not self.capabilities.inspector_capable:
+            raise CapabilityNotSupportedError("inspector_capable", self.name)
+        msg = "inspector_capable is True but build_inspector_cmd has no implementation"
+        raise AssertionError(msg)

src/autoskillit/execution/backends/codex.py

@@ -35,6 +35,7 @@
     BackendCapabilities,
     BackendConventions,
     BareResume,
+    CapabilityNotSupportedError,
     ClaudeDirectoryConventions,
     CmdSpec,
     CodexEventType,
@@ -1054,4 +1055,7 @@ def ensure_pre_launch(self) -> list[str]:
         return errors
 
     def build_inspector_cmd(self, prompt: str, *, model: str = "") -> CmdSpec:
-        raise RuntimeError("build_inspector_cmd not yet implemented — lands in #3534")
+        if not self.capabilities.inspector_capable:
+            raise CapabilityNotSupportedError("inspector_capable", self.name)
+        msg = "inspector_capable is True but build_inspector_cmd has no implementation"
+        raise AssertionError(msg)

tests/_test_filter.py

@@ -248,7 +248,7 @@ class ImportContext(enum.StrEnum):
     "_type_constants_registries": frozenset(
         {"cli", "config", "core", "pipeline", "recipe", "server", "workspace"}
     ),
-    "_type_exceptions": frozenset({"core", "fleet", "recipe", "server"}),
+    "_type_exceptions": frozenset({"core", "execution", "fleet", "recipe", "server"}),
     "_type_phoropter": frozenset({"core"}),
     "_type_tradition_manifest": frozenset({"core"}),
     "_step_context": frozenset({"core", "execution", "pipeline", "server"}),

tests/arch/test_capability_consumption.py

@@ -44,11 +44,6 @@ class ForwardDeclaredField:
         rationale="MCP env forwarding — enforcement arch test exists, awaiting src/ consumer",
         added_date=date(2026, 5, 31),
     ),
-    "inspector_capable": ForwardDeclaredField(
-        issue=3533,
-        rationale="Health Inspector capability gating — production consumer in #3574",
-        added_date=date(2026, 6, 1),
-    ),
     "required_session_files": ForwardDeclaredField(
         issue=3134,
         rationale=(

tests/arch/test_subpackage_isolation.py

@@ -982,7 +982,7 @@ def test_data_directories_are_not_python_packages() -> None:
         "dispatch gate add defense-in-depth checks",
     ),
     "execution/backends/codex.py": (
-        1060,
+        1062,
         "REQ-CNST-010-E9: Codex backend — skill_sigil capability threading adds multi-line "
         "keyword args to _ensure_skill_prefix call sites and _has_prefix guard; "
         "write_guard_tool_names env injection adds 7 lines to _codex_exec_extras; "
@@ -994,7 +994,8 @@ def test_data_directories_are_not_python_packages() -> None:
         "; project_log_dir method added to CodexSessionLocator (+3 net lines)"
         "; session_log_path method added to CodexSessionLocator (+5 net lines)"
         "; process_idle_timeout_ms field wired through build_skill_session_cmd and "
-        "build_food_truck_cmd CmdSpec constructors (+8 net lines)",
+        "build_food_truck_cmd CmdSpec constructors (+8 net lines)"
+        "; CapabilityNotSupportedError capability-gate in build_inspector_cmd (+1 net line)",
     ),
 }
 

tests/execution/backends/test_backend_behavioral_contract.py

@@ -6,7 +6,7 @@
 
 import pytest
 
-from autoskillit.core import DirectInstall
+from autoskillit.core import CapabilityNotSupportedError, DirectInstall
 from autoskillit.execution.backends import BACKEND_REGISTRY
 from autoskillit.execution.backends.codex import CodexBackend
 
@@ -22,6 +22,10 @@
             "completion_marker": "%%X%%",
         },
     ),
+    "inspector_capable": (
+        "build_inspector_cmd",
+        {"prompt": "test prompt"},
+    ),
     "session_resume_capable": (
         "build_resume_cmd",
         {"resume_session_id": "x", "prompt": "x"},
@@ -44,9 +48,14 @@ def test_true_bool_capabilities_have_non_raising_implementations(
             except (RuntimeError, NotImplementedError) as exc:
                 pytest.fail(f"{backend_name}.{method_name}() raised {type(exc).__name__}: {exc}")
 
-    def test_inspector_capable_is_false(self, backend_name: str) -> None:
+    def test_incapable_backends_raise_capability_not_supported(self, backend_name: str) -> None:
         backend = BACKEND_REGISTRY[backend_name]()
-        assert backend.capabilities.inspector_capable is False
+        if backend.capabilities.inspector_capable:
+            pytest.skip("backend is inspector_capable")
+        with pytest.raises(CapabilityNotSupportedError) as exc_info:
+            backend.build_inspector_cmd("test prompt")
+        assert exc_info.value.capability == "inspector_capable"
+        assert exc_info.value.backend_name == backend_name
 
 
 class TestWriteDetectionStrategyRouting:

tests/execution/backends/test_coding_agent_backend_conformance.py

@@ -11,6 +11,7 @@
 from autoskillit.core import (
     BackendCapabilities,
     BackendConventions,
+    CapabilityNotSupportedError,
     CmdSpec,
     CodingAgentBackend,
     DirectInstall,
@@ -28,7 +29,6 @@
 
 NOT_YET_LIVE: frozenset[str] = frozenset(
     {
-        "inspector_capable",
         "min_version",
         "patch_format",
         "required_session_files",
@@ -276,9 +276,10 @@ def test_build_inspector_cmd_raises_when_not_capable(self) -> None:
         """BackendCapabilities.inspector_capable — raises when not capable."""
         if self.backend.capabilities.inspector_capable:
             pytest.skip("backend is inspector_capable — not testing the not-capable path")
-        with pytest.raises(RuntimeError) as exc_info:
+        with pytest.raises(CapabilityNotSupportedError) as exc_info:
             self.backend.build_inspector_cmd("test prompt")
-        assert "not yet implemented" in str(exc_info.value)
+        assert exc_info.value.capability == "inspector_capable"
+        assert exc_info.value.backend_name == self.backend.name
 
     # --- Group 6: Behavioral Contracts ---
 

tests/test_test_filter_core_cascade.py

@@ -211,7 +211,7 @@ def test_type_constants_registries_cascade(self) -> None:
 
     def test_type_exceptions_cascade(self) -> None:
         assert MODULE_CASCADE_CORE["_type_exceptions"] == frozenset(
-            {"core", "fleet", "recipe", "server"}
+            {"core", "execution", "fleet", "recipe", "server"}
         )
 
     def test_step_context_cascade(self) -> None:
@@ -670,7 +670,7 @@ def test_type_constants_registries_narrow_cascade(self, tmp_path: Path) -> None:
             )
 
     def test_type_exceptions_narrow_cascade(self, tmp_path: Path) -> None:
-        """_type_exceptions → narrow cascade of 4 dirs."""
+        """_type_exceptions → narrow cascade of 5 dirs."""
         tests_root = self._make_tests_root(tmp_path, self.ALL_DIRS)
         result = build_test_scope(
             changed_files={"src/autoskillit/core/types/_type_exceptions.py"},
@@ -679,12 +679,11 @@ def test_type_exceptions_narrow_cascade(self, tmp_path: Path) -> None:
         )
         assert result is not None
         dir_names = {p.name for p in result}
-        for pkg in ["core", "fleet", "recipe", "server"]:
+        for pkg in ["core", "execution", "fleet", "recipe", "server"]:
             assert pkg in dir_names, f"_type_exceptions cascade should include {pkg}"
         for excluded in [
             "cli",
             "config",
-            "execution",
             "pipeline",
             "migration",
             "workspace",