engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/providers.py

@@ -0,0 +1,471 @@
+"""Qualified provider contracts and current local implementations.
+
+Provider selection is configuration-owned.  These protocols deliberately expose
+diagnostics only; they do not grant execution, repository or network authority.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from ipaddress import IPv4Address, IPv4Network
+import os
+import pwd
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+from typing import Mapping, Protocol, Sequence
+
+
+@dataclass(frozen=True)
+class ProviderStatus:
+    name: str
+    version: str
+    qualified: bool
+    detail: str
+
+
+@dataclass(frozen=True)
+class LaunchdRuntimeDetails:
+    """Host observation for one owned LaunchAgent, without control authority."""
+
+    label: str
+    loaded: bool
+    active: bool
+    pid: int | None
+    last_exit_code: str | None
+    memory_kib: int | None = None
+    uptime_seconds: int | None = None
+
+
+def _elapsed_seconds(value: str) -> int | None:
+    """Parse macOS ``ps etime`` without treating malformed host output as fact."""
+    match = re.fullmatch(r"(?:(\d+)-)?(?:(\d{1,2}):)?(\d{1,2}):(\d{2})", value)
+    if not match:
+        return None
+    days, hours, minutes, seconds = (int(part or 0) for part in match.groups())
+    if minutes >= 60 or seconds >= 60:
+        return None
+    return days * 86_400 + hours * 3_600 + minutes * 60 + seconds
+
+
+class RuntimeProvider(Protocol):
+    def status(self) -> ProviderStatus: ...
+
+
+class ProcessProvider(Protocol):
+    """The sole boundary for local child-process execution."""
+
+    def execute(
+        self, root: Path, arguments: Sequence[str], *, environment: Mapping[str, str] | None = None,
+    ) -> subprocess.CompletedProcess[str]: ...
+
+    def spawn(self, root: Path, arguments: Sequence[str]) -> subprocess.Popen[str]: ...
+
+    def spawn_detached(self, root: Path, arguments: Sequence[str], environment: Mapping[str, str]) -> subprocess.Popen[bytes]: ...
+
+
+class LocalProcessProvider:
+    """Default local process adapter; orchestration code never imports subprocess for work."""
+
+    def execute(
+        self, root: Path, arguments: Sequence[str], *, environment: Mapping[str, str] | None = None,
+    ) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            arguments, cwd=root, env=dict(environment) if environment is not None else None,
+            text=True, capture_output=True, check=False,
+        )
+
+    def spawn(self, root: Path, arguments: Sequence[str]) -> subprocess.Popen[str]:
+        return subprocess.Popen(
+            tuple(arguments), cwd=root, text=True, stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT, start_new_session=True,
+        )
+
+    def spawn_detached(self, root: Path, arguments: Sequence[str], environment: Mapping[str, str]) -> subprocess.Popen[bytes]:
+        return subprocess.Popen(
+            tuple(arguments), cwd=root, env=dict(environment), start_new_session=True,
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+        )
+
+
+def installed_python_environment() -> dict[str, str]:
+    """Return the Server-owned interpreter environment for child validation.
+
+    An installed Engineering Platform Server is executed by its installation
+    virtual environment.  Child validation must retain that interpreter when a
+    repository asks for the conventional ``python -m ...`` command; otherwise
+    it can accidentally resolve a different system Python.
+    """
+    # Keep the venv launcher path intact.  Resolving it selects the framework
+    # base interpreter and lets a child validation command escape the EP venv.
+    executable = Path(sys.executable).expanduser().absolute()
+    environment = dict(os.environ)
+    environment["PATH"] = str(executable.parent) + os.pathsep + environment.get("PATH", "")
+    virtual_environment = executable.parent.parent
+    if (virtual_environment / "pyvenv.cfg").is_file():
+        environment["VIRTUAL_ENV"] = str(virtual_environment)
+    return environment
+
+
+class DeterministicValidationExecutor:
+    """Run one resolved validation control outside provider-agent dispatch."""
+
+    def __init__(self, process: ProcessProvider | None = None) -> None:
+        self.process = process or LocalProcessProvider()
+
+    def run(self, root: Path, command: tuple[str, ...]) -> "DeterministicValidationResult":
+        try:
+            completed = self.process.execute(root, command, environment=installed_python_environment())
+            stdout = completed.stdout
+            stderr = completed.stderr
+            return DeterministicValidationResult(
+                exit_code=completed.returncode,
+                stdout=stdout if isinstance(stdout, str) else None,
+                stderr=stderr if isinstance(stderr, str) else None,
+                diagnostic_capture_available=isinstance(stdout, str) and isinstance(stderr, str),
+            )
+        except OSError:
+            return DeterministicValidationResult(
+                exit_code=None, stdout=None, stderr=None,
+                diagnostic_capture_available=False,
+            )
+
+
+@dataclass(frozen=True)
+class DeterministicValidationResult:
+    """One deterministic command outcome, including non-authoritative output."""
+
+    exit_code: int | None
+    stdout: str | None
+    stderr: str | None
+    diagnostic_capture_available: bool
+
+
+class RepositoryProvider(Protocol):
+    def status(self, root: Path) -> ProviderStatus: ...
+    def command(self, root: Path, *args: str) -> str: ...
+
+
+class ServiceManagerProvider(Protocol):
+    def status(self) -> ProviderStatus: ...
+    def install(self, label: str, plist: Path) -> None: ...
+    def uninstall(self, plist: Path) -> None: ...
+
+
+class RemoteSubmissionProvider(Protocol):
+    def status(self) -> ProviderStatus: ...
+
+
+class PrivateRemoteAccessProvider(Protocol):
+    def status(self) -> ProviderStatus: ...
+
+
+MANAGED_CODEX_CLI_PREFIX_ENVIRONMENT = "EP_MANAGED_CODEX_CLI_PREFIX"
+
+
+def default_engineering_platform_codex_cli_prefix() -> Path:
+    """Return the stable account-owned default, independent of ``$HOME``.
+
+    A runner may deliberately receive an isolated HOME for tool state.  That
+    must never manufacture a second EP-managed CLI installation location.
+    """
+    try:
+        account_home = Path(pwd.getpwuid(os.getuid()).pw_dir)
+    except (KeyError, OSError):
+        account_home = Path.home()
+    return account_home / ".local" / "share" / "engineering-platform" / "codex-cli"
+
+
+def engineering_platform_codex_cli_prefix() -> Path:
+    """Return the installation-pinned CLI prefix, never a process HOME path."""
+    configured = os.environ.get(MANAGED_CODEX_CLI_PREFIX_ENVIRONMENT)
+    if configured:
+        candidate = Path(configured).expanduser()
+        if candidate.is_absolute():
+            return candidate.resolve(strict=False)
+    return default_engineering_platform_codex_cli_prefix()
+
+
+def codex_cli_executable() -> str | None:
+    """Return only Engineering Platform's managed Codex CLI executable."""
+    managed = engineering_platform_codex_cli_prefix() / "bin" / "codex"
+    if managed.is_file() and os.access(managed, os.X_OK):
+        return str(managed)
+    return None
+
+
+class CodexCliProvider(LocalProcessProvider):
+    """Codex process adapter pinned exclusively to EP's managed launcher."""
+
+    def __init__(self, executable: str | None = None) -> None:
+        del executable  # Runtime injection must not bypass EP's managed CLI.
+        self._executable = codex_cli_executable() or ""
+
+    def managed_installation_path(self) -> str | None:
+        """Return provenance only when this invocation is pinned to EP's CLI."""
+        managed = engineering_platform_codex_cli_prefix() / "bin" / "codex"
+        return str(engineering_platform_codex_cli_prefix()) if self._executable == str(managed) else None
+
+    def _arguments(self, arguments: Sequence[str]) -> tuple[str, ...]:
+        if arguments and arguments[0] == "codex":
+            return (self._executable, *arguments[1:])
+        return tuple(arguments)
+
+    def status(self) -> ProviderStatus:
+        available = bool(self._executable) and Path(self._executable).is_file() and os.access(self._executable, os.X_OK)
+        return ProviderStatus("codex_cli", "configured", available, "available" if available else "codex unavailable")
+
+    def command(self, *args: str) -> subprocess.CompletedProcess[str]:
+        if not self._executable:
+            raise FileNotFoundError("Engineering Platform managed Codex CLI is unavailable")
+        return subprocess.run((self._executable, *args), text=True, capture_output=True, check=False)
+
+    def app_server(self) -> subprocess.Popen[str]:
+        """Open the provider-owned interactive Codex app-server channel."""
+        if not self._executable:
+            raise FileNotFoundError("Engineering Platform managed Codex CLI is unavailable")
+        return subprocess.Popen(
+            (self._executable, "app-server"), stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL, text=True, bufsize=1,
+        )
+
+    def close_app_server(self, process: subprocess.Popen[str]) -> None:
+        process.terminate()
+        try:
+            process.wait(timeout=1)
+        except subprocess.TimeoutExpired:
+            process.kill()
+            process.wait(timeout=1)
+        for stream in (process.stdin, process.stdout):
+            if stream is not None:
+                stream.close()
+
+    def invoke(
+        self,
+        root: Path,
+        arguments: tuple[str, ...],
+        *,
+        timeout: float | None = None,
+        environment: Mapping[str, str] | None = None,
+        input_text: str | None = None,
+    ) -> subprocess.CompletedProcess[str]:
+        """Execute a complete Codex command; callers never spawn its CLI directly."""
+        command = self._arguments(arguments)
+        # Reviewer invocations are bounded advisory work.  Primary execution
+        # streams through ``spawn`` and does not supply a timeout here.
+        if environment is None and input_text is None:
+            return self.execute(root, command)
+        # The executable is this provider's configured Codex launcher, never a
+        # caller-selected command. Remaining values are Codex CLI arguments.
+        return subprocess.run(
+            (self._executable, *command[1:]), cwd=root,
+            env=dict(environment) if environment is not None else None, timeout=timeout,
+            text=True, input=input_text, capture_output=True, check=False,
+        )
+
+    def spawn_invocation(
+        self, root: Path, arguments: tuple[str, ...], *, environment: Mapping[str, str] | None = None
+    ) -> subprocess.Popen[str]:
+        command = self._arguments(arguments)
+        if environment is None:
+            return self.spawn(root, command)
+        return subprocess.Popen(
+            (self._executable, *command[1:]), cwd=root, env=dict(environment),
+            text=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, start_new_session=True,
+        )
+
+
+class GitProvider(LocalProcessProvider):
+    """Local Git provider, deliberately separate from the GitHub API provider."""
+
+    def execute(self, root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+        return super().execute(root, args)
+
+    def command(self, root: Path, *args: str) -> str:
+        """Run Git and expose its bounded text result to repository orchestration."""
+        completed = self.execute(root, *args)
+        if completed.returncode:
+            raise RuntimeError(completed.stderr.strip() or completed.stdout.strip() or "git command failed")
+        return completed.stdout.strip()
+
+
+class GitHubProvider:
+    def status(self, root: Path) -> ProviderStatus:
+        remote = GitProvider().execute(root, "git", "remote", "get-url", "origin")
+        qualified = remote.returncode == 0 and "github" in remote.stdout.lower()
+        return ProviderStatus("github", "configured", qualified, remote.stdout.strip() if qualified else "GitHub origin unavailable")
+
+    def github(self, *args: str) -> str:
+        completed = subprocess.run(("gh", *args), text=True, capture_output=True, check=False)
+        if completed.returncode:
+            raise RuntimeError(completed.stderr.strip() or "GitHub provider command failed")
+        return completed.stdout.strip()
+
+
+class LaunchdProvider:
+    def status(self) -> ProviderStatus:
+        available = shutil.which("launchctl") is not None
+        return ProviderStatus("launchd", "configured", available, "available" if available else "launchctl unavailable")
+
+    def install(self, label: str, plist: Path) -> None:
+        subprocess.run(("launchctl", "bootout", f"gui/{__import__('os').getuid()}", str(plist)), check=False, capture_output=True)
+        subprocess.run(("launchctl", "bootstrap", f"gui/{__import__('os').getuid()}", str(plist)), check=False)
+
+    def uninstall(self, plist: Path) -> None:
+        subprocess.run(("launchctl", "bootout", f"gui/{__import__('os').getuid()}", str(plist)), check=False)
+
+    def inspect(self, label: str) -> bool:
+        executable = shutil.which("launchctl")
+        if not executable:
+            return False
+        return subprocess.run((executable, "print", f"gui/{__import__('os').getuid()}/{label}"), text=True, capture_output=True, check=False).returncode == 0
+
+    def runtime_status(self, label: str) -> ProviderStatus:
+        """Return whether one owned LaunchAgent has a live service process.
+
+        ``launchctl print`` succeeding only proves that a job remains loaded.
+        A KeepAlive job can be loaded while repeatedly exiting, so reporting it
+        as healthy would project a stale "active" status to the dashboard.
+        """
+        details = self.runtime_details(label)
+        if not details.loaded:
+            if shutil.which("launchctl") is None:
+                return ProviderStatus("launchd", "configured", False, "launchctl unavailable")
+            return ProviderStatus("launchd", "configured", False, "LaunchAgent is not loaded")
+        if details.active:
+            return ProviderStatus("launchd", "configured", True, "LaunchAgent process is active")
+        return ProviderStatus(
+            "launchd",
+            "configured",
+            False,
+            "LaunchAgent is loaded but has no active process",
+        )
+
+    def runtime_details(self, label: str) -> LaunchdRuntimeDetails:
+        """Read the actual LaunchAgent host state used by component detail views."""
+        executable = shutil.which("launchctl")
+        if not executable:
+            return LaunchdRuntimeDetails(label, False, False, None, None)
+        completed = subprocess.run(
+            (executable, "print", f"gui/{os.getuid()}/{label}"),
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+        if completed.returncode:
+            return LaunchdRuntimeDetails(label, False, False, None, None)
+        output = completed.stdout
+        active_count = re.search(r"(?m)^\s*active count\s*=\s*(\d+)", output)
+        pid_match = re.search(r"(?m)^\s*pid\s*=\s*([1-9]\d*)", output)
+        last_exit = re.search(r"(?m)^\s*last exit code\s*=\s*(.+)$", output)
+        pid = int(pid_match.group(1)) if pid_match else None
+        active = (active_count is not None and int(active_count.group(1)) > 0) or pid is not None
+        memory_kib, uptime_seconds = self._process_metrics(pid) if active and pid else (None, None)
+        return LaunchdRuntimeDetails(
+            label, True, active, pid,
+            last_exit.group(1).strip() if last_exit else None,
+            memory_kib, uptime_seconds,
+        )
+
+    @staticmethod
+    def _process_metrics(pid: int) -> tuple[int | None, int | None]:
+        """Read memory and elapsed time for a launchd-proven process only."""
+        executable = shutil.which("ps")
+        if not executable:
+            return None, None
+        completed = subprocess.run(
+            (executable, "-o", "rss=", "-o", "etime=", "-p", str(pid)),
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+        if completed.returncode:
+            return None, None
+        columns = completed.stdout.strip().split()
+        if len(columns) != 2 or not columns[0].isdigit():
+            return None, None
+        return int(columns[0]), _elapsed_seconds(columns[1])
+
+    def restart(self, label: str) -> None:
+        executable = shutil.which("launchctl")
+        if not executable:
+            raise OSError("launchctl unavailable")
+        completed = subprocess.run((executable, "kickstart", "-k", f"gui/{__import__('os').getuid()}/{label}"), text=True, capture_output=True, check=False)
+        if completed.returncode:
+            raise OSError(completed.stderr.strip() or "launchd restart failed")
+
+    def quiesce(self, label: str, plist: Path) -> None:
+        """Temporarily unload one owned LaunchAgent for bounded maintenance."""
+        executable = shutil.which("launchctl")
+        if not executable:
+            raise OSError("launchctl unavailable")
+        completed = subprocess.run(
+            (executable, "bootout", f"gui/{os.getuid()}", str(plist)),
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+        if completed.returncode:
+            raise OSError(completed.stderr.strip() or "launchd quiesce failed")
+        # A process signal is not enough: both observations must prove launchd
+        # no longer owns a runnable job, preventing KeepAlive replacement.
+        if self.inspect(label) or self.inspect(label):
+            raise OSError("LaunchAgent remained loaded after maintenance quiesce")
+
+    def resume(self, label: str, plist: Path) -> None:
+        """Reload a temporarily quiesced owned LaunchAgent and start it."""
+        executable = shutil.which("launchctl")
+        if not executable:
+            raise OSError("launchctl unavailable")
+        completed = subprocess.run(
+            (executable, "bootstrap", f"gui/{os.getuid()}", str(plist)),
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+        if completed.returncode:
+            raise OSError(completed.stderr.strip() or "launchd resume failed")
+        self.restart(label)
+
+
+class ICloudInboxProvider:
+    def status(self) -> ProviderStatus:
+        return ProviderStatus("icloud_inbox", "configured", True, "workspace path is resolved by the watcher")
+
+
+class TailscaleProvider:
+    _TAILSCALE_NETWORK = IPv4Network("100.64.0.0/10")
+
+    def ipv4_address(self) -> str | None:
+        """Return only the local, routable Tailscale IPv4 address.
+
+        This is a read-only diagnostic query.  It never changes Tailnet
+        configuration, ACLs, Funnel, or port-forwarding state.
+        """
+        executable = shutil.which("tailscale")
+        if not executable:
+            return None
+        observed = subprocess.run((executable, "ip", "-4"), text=True, capture_output=True, check=False)
+        if observed.returncode:
+            return None
+        for candidate in observed.stdout.splitlines():
+            try:
+                address = IPv4Address(candidate.strip())
+            except ValueError:
+                continue
+            if address in self._TAILSCALE_NETWORK:
+                return str(address)
+        return None
+
+    def status(self) -> ProviderStatus:
+        executable = shutil.which("tailscale")
+        if not executable:
+            return ProviderStatus("tailscale", "configured", False, "tailscale unavailable")
+        observed = subprocess.run((executable, "status", "--json"), text=True, capture_output=True, check=False)
+        return ProviderStatus("tailscale", "configured", observed.returncode == 0, "connected" if observed.returncode == 0 else "not connected")
+
+
+def registry(root: Path) -> dict[str, ProviderStatus]:
+    """Return the deterministic current-provider registry."""
+    return {"runtime": CodexCliProvider().status(), "repository": GitHubProvider().status(root), "service_manager": LaunchdProvider().status(), "remote_submission": ICloudInboxProvider().status(), "private_remote_access": TailscaleProvider().status()}

engineering_platform/qualification.py

@@ -0,0 +1,220 @@
+"""Deterministic local qualification for Engineering Platform capabilities."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+import time
+
+from .platform_version import EngineeringPlatformManifest
+from .resources import package_path
+from .platform_api import PlatformConfiguration
+from .providers import CodexCliProvider, GitProvider
+
+
+@dataclass(frozen=True)
+class QualificationScenario:
+    capability: str
+    expected_behavior: str
+
+
+SCENARIOS = tuple(
+    QualificationScenario(
+        capability,
+        "Deterministic local contract passes; failures report evidence without changing lifecycle authority.",
+    )
+    for capability in (
+        "Repository Initialization",
+        "Checkpoint Resume",
+        "Implementation Lifecycle",
+        "Validation Loop",
+        "Repair Loop",
+        "Owner Authorization",
+        "Ready For Review",
+        "Automatic Merge",
+        "Repository Reconciliation",
+        "Finalization",
+        "Repository Cleanup",
+        "Engineering Memory",
+        "Progress Reporting",
+        "Engineering Reports",
+        "Capability-aware Reviewers",
+        "Diagnostics",
+        "BLOCKED Recovery",
+        "Failure Recovery",
+        "Long-running Transactions",
+        "Remote Status Model",
+        "Private Dashboard",
+        "Repository Handoff",
+        "Remote Engineering Readiness",
+        "Platform Identity",
+        "Workspace Identity",
+        "Provider Registry",
+        "Capability Registry",
+        "Public Platform API",
+        "Configuration Hierarchy",
+        "Configuration Migration",
+        "Provider Compatibility",
+        "Extraction Readiness Audit",
+        "Repository Bootstrap",
+        "Project Template",
+        "Workspace Provisioning",
+        "Genesis Lifecycle",
+        "Strict Inbox Sequencing",
+        "Local Engineering Evidence Storage",
+        "Component Logging and Read-only Advice",
+    )
+)
+
+
+def execute_qualification(
+    root: Path,
+    checks: dict[str, bool] | None = None,
+    *,
+    ep_repository_root: Path | None = None,
+    evidence_root: Path | None = None,
+) -> dict[str, object]:
+    """Execute all registered local scenarios and write immutable local evidence.
+
+    ``evidence_root`` is for read-only source checkouts such as the Golden
+    scenario.  It changes only where the receipt is stored, never the
+    repository whose contracts are being checked.
+    """
+    started = time.monotonic()
+    manifest = EngineeringPlatformManifest.load(
+        package_path("ENGINEERING_PLATFORM_VERSION.json")
+    )
+    supplied = checks or {}
+    results = []
+    for scenario in SCENARIOS:
+        passed = supplied.get(
+            scenario.capability,
+            _default_check(root, scenario.capability, ep_repository_root=ep_repository_root),
+        )
+        results.append(
+            {
+                "capability": scenario.capability,
+                "status": "PASS" if passed else "FAIL",
+                "duration_ms": 0,
+                "diagnostic": None if passed else "Scenario contract failed.",
+                "evidence": scenario.expected_behavior,
+            }
+        )
+    passed = sum(item["status"] == "PASS" for item in results)
+    report = {
+        "engineering_platform_version": manifest.platform_version,
+        "repository_version": _repository_version(root),
+        "codex_cli_version": _codex_version(),
+        "qualification": "PASS" if passed == len(results) else "FAIL",
+        "executed_at": datetime.now(timezone.utc).isoformat(),
+        "duration_ms": round((time.monotonic() - started) * 1000),
+        "scenarios": results,
+        "coverage_percent": round(passed * 100 / len(results), 1),
+        "failures": len(results) - passed,
+        "blocked": 0,
+    }
+    _write_report(evidence_root or root, report)
+    return report
+
+
+def dashboard(report: dict[str, object]) -> str:
+    scenarios = report["scenarios"]
+    return "\n".join(
+        (
+            "Engineering Platform Qualification",
+            f"Version: {report['engineering_platform_version']}",
+            f"Qualification: {report['qualification']}",
+            f"Scenarios: {sum(item['status'] == 'PASS' for item in scenarios)} / {len(scenarios)}",
+            f"Failures: {report['failures']}",
+            f"Blocked: {report['blocked']}",
+            f"Coverage: {report['coverage_percent']}%",
+        )
+    )
+
+
+def latest_qualification(root: Path) -> dict[str, object] | None:
+    directory = root / ".engineering" / "qualification"
+    reports = sorted(directory.glob("qualification-*.json"))
+    if not reports:
+        return None
+    try:
+        raw = json.loads(reports[-1].read_text(encoding="utf-8"))
+        return raw if isinstance(raw, dict) else None
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _default_check(
+    root: Path, capability: str, *, ep_repository_root: Path | None = None
+) -> bool:
+    ep_source = (
+        ep_repository_root / "src" / "engineering_platform"
+        if ep_repository_root is not None
+        else None
+    )
+
+    def source_file(name: str) -> bool:
+        return bool(ep_source and (ep_source / name).is_file())
+
+    def configuration_is_compatible() -> bool:
+        try:
+            return PlatformConfiguration.load(root).platform.version == EngineeringPlatformManifest.load(
+                package_path("ENGINEERING_PLATFORM_VERSION.json")
+            ).platform_version
+        except (OSError, ValueError):
+            return False
+    contracts = {
+        "Repository Initialization": bool(ep_repository_root and (ep_repository_root / "BOOTSTRAP.md").is_file()),
+        "Checkpoint Resume": source_file("agent_state.py"),
+        "Engineering Memory": source_file("execution_host.py"),
+        "Capability-aware Reviewers": source_file("capability_review.py"),
+        "Remote Status Model": source_file("status_model.py"),
+        "Private Dashboard": source_file("server.py") and source_file("console_presentation.py"),
+        "Repository Handoff": source_file("repository_handoff.py"),
+        "Remote Engineering Readiness": source_file("execution_readiness.py"),
+        "Platform Identity": configuration_is_compatible(),
+        "Workspace Identity": configuration_is_compatible(),
+        "Provider Registry": configuration_is_compatible(),
+        "Capability Registry": source_file("platform_api.py"),
+        "Public Platform API": source_file("platform_api.py"),
+        "Configuration Hierarchy": configuration_is_compatible(),
+        "Configuration Migration": configuration_is_compatible(),
+        "Provider Compatibility": configuration_is_compatible(),
+        "Extraction Readiness Audit": bool(
+            ep_repository_root
+            and (ep_repository_root / "scripts" / "engineering" / "audit_ep_extraction_baseline.py").is_file()
+        ),
+        "Repository Bootstrap": source_file("platform_bootstrap.py"),
+        "Project Template": bool(ep_source and (ep_source / "templates" / "workspace-config.json").is_file()),
+        "Workspace Provisioning": source_file("platform_bootstrap.py"),
+        "Genesis Lifecycle": source_file("execution_host.py"),
+        "Strict Inbox Sequencing": source_file("file_inbox.py"),
+        "Local Engineering Evidence Storage": source_file("file_inbox.py") and source_file("submission_intake.py"),
+        "Component Logging and Read-only Advice": source_file("component_logging.py") and source_file("codex_chat.py"),
+    }
+    return contracts.get(capability, source_file("execution_host.py"))
+
+
+def _write_report(root: Path, report: dict[str, object]) -> None:
+    directory = root / ".engineering" / "qualification"
+    directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+    stamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H-%M-%SZ")
+    (directory / f"qualification-{stamp}.json").write_text(
+        json.dumps(report, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+    )
+    (directory / f"qualification-{stamp}.md").write_text(dashboard(report) + "\n", encoding="utf-8")
+
+
+def _repository_version(root: Path) -> str:
+    completed = GitProvider().execute(root, "git", "rev-parse", "HEAD")
+    return completed.stdout.strip() if completed.returncode == 0 else "unavailable"
+
+
+def _codex_version() -> str:
+    try:
+        completed = CodexCliProvider().command("--version")
+    except OSError:
+        return "unavailable"
+    return completed.stdout.strip() if completed.returncode == 0 else "unavailable"