engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/templates/workspace-config.json

@@ -0,0 +1,25 @@
+{
+  "schema_version": 2,
+  "platform": {
+    "id": "engineering-platform",
+    "name": "Engineering Platform",
+    "version": "2.2.0",
+    "generation": 2,
+    "documentation_namespace": "engineering-platform",
+    "capability_registry_version": 1
+  },
+  "workspace": {
+    "id": "replace-workspace-id",
+    "name": "Replace Workspace Name",
+    "repository": {"provider": "github", "owner": "replace-owner", "name": "replace-repository", "default_branch": "main"},
+    "branding": {"dashboard_title": "Replace Workspace Name"},
+    "workspace_authorization": {
+      "allowed_roots": [],
+      "allowed_repositories": [],
+      "denied_repositories": [],
+      "symlink_policy": "reject",
+      "case_sensitivity": "host"
+    }
+  },
+  "providers": {"runtime": "codex_cli", "repository": "github", "service_manager": "launchd", "remote_submission": "icloud_inbox", "private_remote_access": "tailscale", "dashboard": "private_http"}
+}

engineering_platform/validation_identity.py

@@ -0,0 +1,50 @@
+"""Structural identities for repository-defined validation controls."""
+from __future__ import annotations
+
+import shlex
+
+
+CANONICAL_DASHBOARD_COMMAND = "npm run test:engineering-dashboard"
+_CANONICAL_DASHBOARD_TOKENS = ("npm", "run", "test:engineering-dashboard")
+_SHELL_CONTROL_TOKENS = frozenset({";", "&&", "||", "|", "&", "<", ">"})
+
+
+def canonical_validation_launcher(command: str) -> str | None:
+    """Return the planned launcher carried by a transparent shell transport.
+
+    A provider may report its ``/bin/zsh -lc`` transport command rather than
+    the command requested by the validation plan.  Peel only that one
+    lossless transport envelope; compositions and diagnostics remain ineligible.
+    """
+    if not isinstance(command, str) or not command.strip():
+        return None
+    try:
+        tokens = tuple(shlex.split(command))
+    except ValueError:
+        return None
+    if len(tokens) == 3 and tokens[0] in {"zsh", "/bin/zsh"} and tokens[1] == "-lc":
+        return tokens[2]
+    return command
+
+
+def is_canonical_dashboard_command(command: str) -> bool:
+    """Return whether *command* structurally invokes the dashboard launcher.
+
+    The optional arguments after ``--`` belong to npm's script invocation.
+    Browser-related command text, diagnostics, and shell compositions are not
+    dashboard validation controls.
+    """
+    command = canonical_validation_launcher(command)
+    if command is None:
+        return False
+    try:
+        tokens = tuple(shlex.split(command))
+    except ValueError:
+        return False
+    if any(token in _SHELL_CONTROL_TOKENS for token in tokens):
+        return False
+    return tokens == _CANONICAL_DASHBOARD_TOKENS or (
+        len(tokens) > len(_CANONICAL_DASHBOARD_TOKENS)
+        and tokens[:len(_CANONICAL_DASHBOARD_TOKENS)] == _CANONICAL_DASHBOARD_TOKENS
+        and tokens[len(_CANONICAL_DASHBOARD_TOKENS)] == "--"
+    )

engineering_platform/validation_profile.py

@@ -0,0 +1,211 @@
+"""Conservative, diff-derived Engineering validation profile selection."""
+from __future__ import annotations
+import argparse
+from dataclasses import dataclass
+from pathlib import Path
+import re
+import subprocess
+import sys
+
+DOCUMENTATION_PREFIXES = ("docs/",)
+DASHBOARD_PREFIXES = ("src/engineering_platform/assets/",)
+DASHBOARD_FILES = {"src/engineering_platform/server_console_services.py", "src/engineering_platform/server.py", "tests/engineering/dashboard.spec.mjs", "package.json", "package-lock.json"}
+RUNTIME_PREFIXES = ("src/engineering_platform/", "tests/engineering/", ".github/workflows/")
+VALIDATION_PROFILE_VERSION = "1.0"
+REQUIRED_CONTROLS = {
+    "DOCUMENTATION": ("git_diff_check", "documentation_contract"),
+    "DASHBOARD": ("git_diff_check", "engineering_python", "console_route_ownership", "ui_localization", "dashboard_browser"),
+    "RUNTIME_UI": ("git_diff_check", "engineering_python", "console_route_ownership", "ui_localization", "dashboard_browser"),
+    "RUNTIME": ("git_diff_check", "engineering_python", "console_route_ownership", "dashboard_browser"),
+    "FULL": ("git_diff_check", "repository_suite"),
+    # A governed P-CENTRAL-CORE change retains the full Python/core suite but
+    # deliberately does not claim the deferred Operations Console browser
+    # qualification.  It is selected only by the CI phase boundary below.
+    "P_CENTRAL_CORE": ("git_diff_check", "engineering_python"),
+}
+P_CENTRAL_CORE_BRANCH = re.compile(r"^codex/phase-p-central-core(?:-.+)?$")
+
+
+@dataclass(frozen=True)
+class ValidationControlLauncher:
+    """One deterministic launcher for a resolved validation-control identity.
+
+    Profiles select identities; this registry owns the repository-local
+    implementation of those identities. Lifecycle code only schedules the
+    persisted identities and never branches on a project-specific control.
+    """
+
+    validation_id: str
+    category: str
+    control_identity: str
+    command: tuple[str, ...]
+
+
+class ValidationProfileResolutionError(ValueError):
+    """The selected run profile is absent or does not match this registry."""
+
+
+def _python_command(*arguments: str) -> tuple[str, ...]:
+    return (sys.executable, *arguments)
+
+
+CONTROL_LAUNCHERS = {
+    "git_diff_check": ValidationControlLauncher(
+        "git_diff_check", "repository", "git diff --check", ("git", "diff", "--check"),
+    ),
+    "documentation_contract": ValidationControlLauncher(
+        "documentation_contract", "documentation",
+        "python3 -m unittest tests.engineering.test_engineering_operational_documentation",
+        _python_command("-m", "unittest", "tests.engineering.test_engineering_operational_documentation"),
+    ),
+    "engineering_python": ValidationControlLauncher(
+        "engineering_python", "python", "python3 -m unittest discover -s tests/engineering",
+        _python_command("-m", "unittest", "discover", "-s", "tests/engineering"),
+    ),
+    "dashboard_browser": ValidationControlLauncher(
+        "dashboard_browser", "browser", "npm run test:engineering-dashboard",
+        ("npm", "run", "test:engineering-dashboard"),
+    ),
+    "ui_localization": ValidationControlLauncher(
+        "ui_localization", "browser", "npm run test:ui-localization",
+        ("npm", "run", "test:ui-localization"),
+    ),
+    "console_route_ownership": ValidationControlLauncher(
+        "console_route_ownership", "python", "Console route ownership guard",
+        _python_command("tools/qualification/console_route_ownership_guard.py", "--source-root", "src"),
+    ),
+    "repository_suite": ValidationControlLauncher(
+        "repository_suite", "repository", "python3 -m unittest discover",
+        _python_command("-m", "unittest", "discover"),
+    ),
+}
+
+
+def control_launcher(validation_id: str) -> ValidationControlLauncher | None:
+    """Resolve a persisted required-control identity to its canonical launcher."""
+    return CONTROL_LAUNCHERS.get(validation_id)
+
+
+def control_binding(validation_id: str) -> dict[str, object] | None:
+    """Return the immutable launcher snapshot for one registry control."""
+    launcher = control_launcher(validation_id)
+    if launcher is None:
+        return None
+    return {
+        "validation_id": launcher.validation_id,
+        "required": True,
+        "category": launcher.category,
+        "control_identity": launcher.control_identity,
+        "command": list(launcher.command),
+    }
+
+
+def resolve_producer_profile(payload: object) -> tuple["ValidationProfile", str]:
+    """Resolve a producer-selected profile against the canonical registry.
+
+    A validation-only request carries the selection as structured execution
+    context; prose is never a selection input.  The producer may select a
+    registry profile, but may not substitute its own control set.
+    """
+    if not isinstance(payload, dict):
+        raise ValidationProfileResolutionError("Selected validation profile is unavailable.")
+    tier, version, controls = payload.get("tier"), payload.get("version"), payload.get("required_controls")
+    if not isinstance(tier, str) or tier not in REQUIRED_CONTROLS:
+        raise ValidationProfileResolutionError("Selected validation profile is invalid.")
+    if version != VALIDATION_PROFILE_VERSION:
+        raise ValidationProfileResolutionError("Selected validation profile version is unavailable.")
+    expected = REQUIRED_CONTROLS[tier]
+    if not isinstance(controls, list) or tuple(controls) != expected:
+        raise ValidationProfileResolutionError("Selected validation profile controls are invalid.")
+    return ValidationProfile(tier, (), tuple()), f"validation-profile-registry:{tier}@{version}"
+
+
+def producer_profile_payload(tier: object) -> dict[str, object]:
+    """Build the one allowed producer envelope value for a registry tier.
+
+    Producers select only the canonical tier.  The registry remains the sole
+    owner of profile version and required-control identities, so a caller
+    cannot create a second profile representation or substitute controls.
+    """
+    if not isinstance(tier, str) or tier not in REQUIRED_CONTROLS:
+        raise ValidationProfileResolutionError("Selected validation profile is invalid.")
+    payload: dict[str, object] = {
+        "tier": tier,
+        "version": VALIDATION_PROFILE_VERSION,
+        "required_controls": list(REQUIRED_CONTROLS[tier]),
+    }
+    resolve_producer_profile(payload)
+    return payload
+
+
+def profile_control_bindings(profile: "ValidationProfile") -> tuple[dict[str, object], ...]:
+    """Snapshot every launcher selected by a profile before execution."""
+    bindings = tuple(control_binding(validation_id) for validation_id in profile.required_controls)
+    if any(binding is None for binding in bindings):
+        raise ValidationProfileResolutionError("Selected validation profile launcher is unavailable.")
+    return tuple(binding for binding in bindings if binding is not None)
+
+@dataclass(frozen=True)
+class ValidationProfile:
+    tier: str
+    paths: tuple[str, ...]
+    commands: tuple[str, ...]
+
+    @property
+    def required_controls(self) -> tuple[str, ...]:
+        return REQUIRED_CONTROLS[self.tier]
+
+def classify(paths: list[str] | tuple[str, ...], *, governed_phase: str | None = None) -> ValidationProfile:
+    items = tuple(sorted({path.strip() for path in paths if path.strip()}))
+    if governed_phase == "P_CENTRAL_CORE":
+        return ValidationProfile("P_CENTRAL_CORE", items, ("relevant Engineering Python tests", "P-CENTRAL-CONSOLE browser deferred"))
+    if items and all(path.startswith(DOCUMENTATION_PREFIXES) or path.endswith(".md") for path in items):
+        return ValidationProfile("DOCUMENTATION", items, ("markdown/link/document-contract validation",))
+    if items and all(path.startswith(DASHBOARD_PREFIXES) or path in DASHBOARD_FILES for path in items):
+        return ValidationProfile("DASHBOARD", items, ("relevant Engineering Python tests", "npm run test:engineering-dashboard"))
+    if any(path.startswith(DASHBOARD_PREFIXES) or path in DASHBOARD_FILES for path in items):
+        return ValidationProfile("RUNTIME_UI", items, ("relevant Engineering Python tests", "UI-GOLDEN-LOCALIZATION", "npm run test:engineering-dashboard"))
+    if items and all(path.startswith(RUNTIME_PREFIXES) for path in items):
+        return ValidationProfile("RUNTIME", items, ("relevant Engineering Python tests", "npm run test:engineering-dashboard when projection is affected"))
+    return ValidationProfile("FULL", items, ("full required repository suite",))
+
+
+def browser_dashboard_required(profile: ValidationProfile) -> bool:
+    """Browser coverage is mandatory except for the governed CORE boundary."""
+    return profile.tier not in {"DOCUMENTATION", "P_CENTRAL_CORE"}
+
+
+def localization_required(profile: ValidationProfile) -> bool:
+    """Make the five-locale gate mandatory whenever a Console surface changes."""
+    return profile.tier in {"DASHBOARD", "RUNTIME_UI"}
+
+
+def phase_for_branch(branch: str | None) -> str | None:
+    """Return the only branch-governed exception to the browser requirement."""
+    return "P_CENTRAL_CORE" if isinstance(branch, str) and P_CENTRAL_CORE_BRANCH.fullmatch(branch) else None
+
+def changed_paths(root: Path, base: str) -> tuple[str, ...]:
+    completed = subprocess.run(("git", "diff", "--name-only", f"{base}...HEAD"), cwd=root, text=True, capture_output=True, check=False)
+    if completed.returncode:
+        return ()
+    return tuple(completed.stdout.splitlines())
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--base", required=True)
+    parser.add_argument("--github-output")
+    parser.add_argument("--branch")
+    args = parser.parse_args()
+    phase = phase_for_branch(args.branch)
+    profile = classify(changed_paths(Path.cwd(), args.base), governed_phase=phase)
+    if args.github_output:
+        with Path(args.github_output).open("a", encoding="utf-8") as output:
+            output.write(f"tier={profile.tier}\n")
+            output.write(f"phase={phase or 'DEFAULT'}\n")
+            output.write(f"browser_dashboard_required={'true' if browser_dashboard_required(profile) else 'false'}\n")
+            output.write(f"localization_required={'true' if localization_required(profile) else 'false'}\n")
+    print(profile.tier)
+    return 0
+
+if __name__ == "__main__":
+    raise SystemExit(main())

engineering_platform/workspace_preflight.py

@@ -0,0 +1,263 @@
+"""Fail-closed Level 2 checks for an Engineering execution workspace.
+
+The checks in this module inspect only the selected target repository.  They
+never claim Inbox work, change a branch, contact a remote, or execute an
+engineering action.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import tempfile
+from time import monotonic
+
+from .platform_api import PlatformConfiguration, PlatformConfigurationError, RepositoryAuthorization
+from .drift_diagnostics import evidence_for_checks, guidance, persist as persist_drift_evidence
+from .providers import GitProvider
+
+
+@dataclass(frozen=True)
+class WorkspacePreflightCheck:
+    identifier: str
+    outcome: str
+    reason: str
+    recovery: str
+
+
+@dataclass(frozen=True)
+class WorkspacePreflightResult:
+    outcome: str
+    workspace: str
+    target_repository: str
+    branch: str
+    execution_mode: str
+    timestamp: str
+    duration_ms: int
+    checks: tuple[WorkspacePreflightCheck, ...]
+    canonical_target_path: str | None = None
+    authorization_match: str | None = None
+    authorization_policy: str | None = None
+    drift_evidence: tuple[dict[str, str], ...] = ()
+    resume_guidance: dict[str, object] | None = None
+
+    def payload(self, run_id: str | None = None) -> dict[str, object]:
+        value = asdict(self)
+        value["checks"] = [asdict(check) for check in self.checks]
+        value["run_id"] = run_id
+        return value
+
+
+def _check(identifier: str, passed: bool, reason: str, recovery: str) -> WorkspacePreflightCheck:
+    return WorkspacePreflightCheck(identifier, "PASS" if passed else "FAIL", reason, recovery)
+
+
+def _git(target: Path, *arguments: str):
+    return GitProvider().execute(target, "git", *arguments)
+
+
+def _prompt_value(prompt: str, field: str) -> str | None:
+    lines = prompt.splitlines()
+    for index, line in enumerate(lines):
+        if line.strip().casefold() == f"{field}:".casefold():
+            for following in lines[index + 1 :]:
+                value = following.strip()
+                if value:
+                    return value
+        prefix = f"{field}:"
+        if line.strip().casefold().startswith(prefix.casefold()):
+            value = line.strip()[len(prefix) :].strip()
+            return value or None
+    return None
+
+
+def _execution_mode(prompt: str) -> str:
+    return "GENESIS" if (_prompt_value(prompt, "Execution Mode") or "").casefold() == "genesis" else "MANAGED"
+
+
+def _resolve_target(root: Path, prompt: str, mode: str, configuration: PlatformConfiguration | None) -> Path | None:
+    if mode == "MANAGED":
+        return root.resolve()
+    requested = _prompt_value(prompt, "Target repository")
+    if not requested:
+        return None
+    return Path(requested).expanduser()
+
+
+def _writable(path: Path) -> bool:
+    if not path.is_dir():
+        return False
+    try:
+        descriptor, temporary = tempfile.mkstemp(prefix=".workspace-preflight-", dir=path)
+        os.close(descriptor)
+        Path(temporary).unlink(missing_ok=True)
+        return True
+    except OSError:
+        return False
+
+
+def _git_index_lock_transaction(target: Path, git_directory: Path) -> tuple[bool, str]:
+    """Prove that Git's real index-lock path can be claimed and released.
+
+    A generic temporary file proves only directory permissions.  Git commits
+    through ``index.lock`` specifically, so admission verifies that exact
+    atomic create/unlink operation before allowing a managed execution.
+    """
+    lock = git_directory / "index.lock"
+    descriptor: int | None = None
+    created = False
+    try:
+        descriptor = os.open(lock, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        created = True
+        os.close(descriptor)
+        descriptor = None
+        status = _git(target, "status", "--porcelain=v1", "--untracked-files=no")
+        if status.returncode != 0:
+            return False, "Git cannot read the repository index while its index lock is held."
+        lock.unlink()
+        return True, "Git can create, read through and clear the repository index lock."
+    except FileExistsError:
+        return False, "Git index lock already exists."
+    except OSError as error:
+        return False, f"Git cannot create the repository index lock: {error.strerror or 'write access denied'}."
+    finally:
+        if descriptor is not None:
+            os.close(descriptor)
+        # Only remove a lock we successfully created in this transaction.
+        if created and lock.exists():
+            try:
+                lock.unlink()
+            except OSError:
+                pass
+
+
+def _persist(root: Path, result: WorkspacePreflightResult, run_id: str | None) -> None:
+    directory = root / ".engineering" / "status"
+    if not _writable(directory):
+        return
+    temporary: str | None = None
+    try:
+        descriptor, temporary = tempfile.mkstemp(prefix=".workspace-preflight-", dir=directory)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(json.dumps(result.payload(run_id), separators=(",", ":"), sort_keys=True) + "\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, directory / "workspace_preflight.json")
+    except OSError:
+        if temporary:
+            Path(temporary).unlink(missing_ok=True)
+
+
+def execute(root: Path, prompt: str, *, run_id: str | None = None) -> WorkspacePreflightResult:
+    """Run Level 2 workspace checks without mutating the selected repository."""
+    started = monotonic()
+    timestamp = datetime.now(timezone.utc).isoformat()
+    checks: list[WorkspacePreflightCheck] = []
+    try:
+        configuration = PlatformConfiguration.load(root)
+        checks.append(_check("workspace_identity", True, "Workspace identity is available.", "No action required."))
+    except PlatformConfigurationError:
+        configuration = None
+        checks.append(_check("workspace_identity", False, "Workspace identity is unavailable.", "Restore a valid Engineering Platform configuration."))
+    mode = _execution_mode(prompt)
+    target = _resolve_target(root, prompt, mode, configuration)
+    target_display = str(target) if target else "unavailable"
+    target_exists = target is not None and target.is_dir()
+    try:
+        canonical_candidate = str(target.resolve(strict=True)) if target and target_exists else None
+    except OSError:
+        canonical_candidate = None
+    checks.append(_check("target_repository", target_exists, "Target repository resolves to an existing directory." if target_exists else "Target repository cannot be resolved to an existing directory.", "Select an existing engineering target repository."))
+    authorization: RepositoryAuthorization | None = None
+    if target and target_exists and configuration:
+        authorization = configuration.authorize_target_repository(target, mode)
+    authorized = bool(authorization and authorization.authorized)
+    canonical_target = (authorization.canonical_target if authorization else None) or canonical_candidate
+    checks.append(_check(
+        "WORKSPACE_TARGET_AUTHORIZED",
+        authorized,
+        authorization.reason if authorization else "Workspace authorization configuration is unavailable.",
+        authorization.recovery if authorization else "Restore trusted workspace authorization configuration.",
+    ))
+
+    git_directory: Path | None = None
+    if target_exists:
+        repository = _git(target, "rev-parse", "--git-dir")
+        if repository.returncode == 0 and repository.stdout.strip():
+            git_directory = Path(repository.stdout.strip())
+            if not git_directory.is_absolute():
+                git_directory = (target / git_directory).resolve()
+    checks.append(_check("git_repository", git_directory is not None, "Target is a valid Git repository." if git_directory else "Target is not a valid Git repository.", "Initialize or select a valid Git repository."))
+    if git_directory:
+        checks.append(_check("git_metadata_access", git_directory.is_dir(), "Git metadata is accessible." if git_directory.is_dir() else "Git metadata is inaccessible.", "Restore access to the repository Git metadata."))
+        metadata_writable = _writable(git_directory)
+        checks.append(_check("git_metadata_writable", metadata_writable, "Git metadata is writable." if metadata_writable else "Git metadata is not writable.", "Restore write access to the repository Git metadata."))
+        lock_transaction, lock_reason = _git_index_lock_transaction(target, git_directory)
+        checks.append(_check(
+            "git_index_lock_transaction",
+            lock_transaction,
+            lock_reason,
+            "Stop competing Git processes and restore write access to the repository index before retrying.",
+        ))
+        status = _git(target, "status", "--porcelain=v1", "--untracked-files=all")
+        entries = status.stdout.splitlines() if status.returncode == 0 else []
+        staged = any(len(entry) >= 2 and entry[:2] != "??" and entry[0] != " " for entry in entries)
+        unstaged = any(len(entry) >= 2 and entry[:2] != "??" and entry[1] != " " for entry in entries)
+        untracked = any(entry.startswith("??") for entry in entries)
+        checks.extend((
+            _check("worktree_staged", not staged, "No staged changes are present." if not staged else "Staged changes are present.", "Commit, stash, or remove staged changes before execution."),
+            _check("worktree_unstaged", not unstaged, "No unstaged changes are present." if not unstaged else "Unstaged changes are present.", "Commit, stash, or remove unstaged changes before execution."),
+            _check("worktree_untracked", not untracked, "No untracked files are present." if not untracked else "Untracked files are present.", "Commit, remove, or explicitly ignore untracked files before execution."),
+        ))
+        operation_checks = (
+            ("git_index_lock", git_directory / "index.lock", "Remove the stale Git index lock after confirming no Git process is running."),
+            ("git_merge", git_directory / "MERGE_HEAD", "Finish or abort the merge before execution."),
+            ("git_rebase", git_directory / "rebase-merge", "Finish or abort the rebase before execution."),
+            ("git_cherry_pick", git_directory / "CHERRY_PICK_HEAD", "Finish or abort the cherry-pick before execution."),
+            ("git_revert", git_directory / "REVERT_HEAD", "Finish or abort the revert before execution."),
+            ("git_bisect", git_directory / "BISECT_LOG", "Finish or reset the bisect before execution."),
+        )
+        for identifier, marker, recovery in operation_checks:
+            checks.append(_check(identifier, not marker.exists(), "No unfinished Git operation is present." if not marker.exists() else "An unfinished Git operation is present.", recovery))
+    branch = "unavailable"
+    if git_directory and target:
+        branch_result = _git(target, "branch", "--show-current")
+        branch = branch_result.stdout.strip() or "detached"
+        checks.append(_check("target_repository_identity", branch != "unavailable", "Target repository identity is available." if branch != "unavailable" else "Target repository identity is unavailable.", "Restore repository metadata and branch identity."))
+        if mode == "GENESIS":
+            checks.append(_check("genesis_local_repository", branch != "detached", "Genesis target is a local repository." if branch != "detached" else "Genesis target has no active local branch.", "Select a local repository with an active branch."))
+        else:
+            expected = configuration.workspace.default_branch if configuration else "main"
+            checks.append(_check("managed_expected_branch", branch == expected, "Managed target is on the expected branch." if branch == expected else f"Managed target is not on the expected branch {expected}.", f"Switch the repository to {expected} before submitting work."))
+            remote = _git(target, "remote", "get-url", "origin")
+            remote_valid = remote.returncode == 0 and bool(remote.stdout.strip())
+            checks.append(_check("managed_remote", remote_valid, "Managed target has a valid origin remote." if remote_valid else "Managed target has no valid origin remote.", "Configure the managed repository origin remote."))
+            divergence = _git(target, "rev-list", "--left-right", "--count", "@{upstream}...HEAD") if remote_valid else None
+            synchronized = bool(divergence and divergence.returncode == 0 and divergence.stdout.strip() == "0\t0")
+            checks.append(_check("managed_synchronization", synchronized, "Managed target is synchronized with its upstream." if synchronized else "Managed target is not synchronized with its upstream.", "Synchronize the expected branch with its configured upstream."))
+    workspace = configuration.workspace.name if configuration else "unavailable"
+    outcome = "FAIL" if any(check.outcome == "FAIL" for check in checks) else "PASS"
+    drift_evidence = persist_drift_evidence(root, evidence_for_checks(
+        checks, stage="Workspace Preflight", repository=str((target or root).resolve())
+    ))
+    result = WorkspacePreflightResult(
+        outcome, workspace, target_display, branch, mode, timestamp, round((monotonic() - started) * 1000), tuple(checks),
+        canonical_target, authorization.matched if authorization else None, authorization.scope if authorization else None,
+        drift_evidence, guidance(drift_evidence),
+    )
+    _persist(root, result, run_id)
+    return result
+
+
+def latest(root: Path) -> dict[str, object]:
+    """Return compact, safe Workspace Preflight evidence."""
+    try:
+        payload = json.loads((root / ".engineering" / "status" / "workspace_preflight.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    if not isinstance(payload, dict):
+        return {}
+    return {key: payload[key] for key in ("outcome", "workspace", "target_repository", "canonical_target_path", "authorization_match", "authorization_policy", "branch", "execution_mode", "timestamp", "duration_ms", "checks", "drift_evidence", "resume_guidance", "run_id") if key in payload}