@guanlin4924/devflow-pi 0.1.93 → 0.1.95

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/playwright_adapter.py

@@ -0,0 +1,515 @@
+#!/usr/bin/env python3
+"""Core devflow_playwright adapter: trust contract between Core and the fixed Runtime.
+
+Core alone decides what runs: it resolves the packaged runner/config/CLI,
+checks approvals and the runtime manifest, creates a fresh run directory with
+an execution id + nonce, launches Node in its own process group with a
+sanitized environment, and then verifies result.json and every artifact before
+normalizing the Runtime's local verdict (方案 §8, 变更清单 §1.3–§1.6).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import secrets
+import shutil
+import signal
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from approval_store import REQUIRES_DATABASE, valid_approval
+from dsl_v1 import runtime_dir_candidates
+from environment_profile import load as load_profile
+from tc_hash import tc_sha256
+
+
+ADAPTER_KIND = "devflow_playwright"
+ADAPTER_KEYS = frozenset({"kind", "dsl_file", "environment_profile", "timeout_seconds", "artifacts"})
+FORBIDDEN_ADAPTER_KEYS = frozenset({"argv", "env", "runner", "config", "result_file", "spec"})
+ARTIFACT_KEYS = frozenset({"trace", "screenshots", "max_total_bytes"})
+ARTIFACT_MODES = ("on_failure", "off")
+DEFAULT_TIMEOUT_SECONDS, MIN_TIMEOUT_SECONDS, MAX_TIMEOUT_SECONDS = 600, 30, 1800
+DEFAULT_MAX_ARTIFACT_BYTES, MAX_ARTIFACT_BYTES = 104857600, 1073741824
+MAX_DSL_BYTES = 2 * 1024 * 1024
+RUNTIME_FILES = ("runner.spec.mjs", "playwright.config.mjs", "reporter.mjs", "devflow-test-dsl-v1.schema.json")
+PASSTHROUGH_ENV = ("PATH", "HOME", "TMPDIR", "LANG", "PLAYWRIGHT_BROWSERS_PATH")
+RESULT_ORIGIN = "devflow_playwright_runtime"
+RESULT_STATUSES = frozenset({"passed", "failed", "blocked", "invalid"})
+ARTIFACT_KINDS = frozenset({"trace", "screenshot", "network"})
+EXECUTION_ID_RE = re.compile(r"^[0-9]{8}T[0-9]{6}Z-[0-9a-f]{8}$")
+SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+KILL_GRACE_SECONDS = 5
+STEP_SUMMARY_KEYS = ("id", "phase", "driver", "action", "status", "duration_ms", "locator", "match_count", "http_status", "assertion", "error")
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def sha256_bytes(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def generated_cases_dir(root: Path, feature: str) -> Path:
+    return root / ".devflow/planning" / "generated-cases" / feature
+
+
+def dsl_path(root: Path, feature: str, raw: Any) -> tuple[Path | None, str | None]:
+    """dsl_file must be a regular JSON file under .devflow/planning/generated-cases/<feature>/."""
+    if not isinstance(raw, str) or not raw.strip() or "\x00" in raw:
+        return None, "dsl_file must be a project-relative path"
+    candidate = Path(raw)
+    if candidate.is_absolute() or ".." in candidate.parts or candidate.suffix != ".json":
+        return None, f"dsl_file must be a relative .json path inside the project: {raw}"
+    root_real = root.resolve()
+    resolved = (root_real / candidate).resolve()
+    try:
+        resolved.relative_to(generated_cases_dir(root_real, feature).resolve())
+    except ValueError:
+        return None, f"dsl_file must be under .devflow/planning/generated-cases/{feature}/: {raw}"
+    return resolved, None
+
+
+def adapter_settings(adapter: dict[str, Any]) -> dict[str, Any]:
+    artifacts = adapter.get("artifacts") if isinstance(adapter.get("artifacts"), dict) else {}
+    return {"timeout_seconds": adapter.get("timeout_seconds", DEFAULT_TIMEOUT_SECONDS),
+            "trace": artifacts.get("trace", "on_failure"), "screenshots": artifacts.get("screenshots", "on_failure"),
+            "max_total_bytes": artifacts.get("max_total_bytes", DEFAULT_MAX_ARTIFACT_BYTES)}
+
+
+def adapter_errors(root: Path, feature: str, adapter: dict[str, Any]) -> list[str]:
+    """Binding-shape errors only; the binding can never name a runner, argv, env, result path, or hash."""
+    errors: list[str] = []
+    keys = set(adapter)
+    forbidden = sorted(key for key in keys if key in FORBIDDEN_ADAPTER_KEYS or key.endswith("_sha256"))
+    if forbidden:
+        errors.append(f"devflow_playwright adapter must not provide {', '.join(forbidden)} (Core resolves runner, environment, results and trusted hashes)")
+    unknown = sorted(keys - ADAPTER_KEYS - set(forbidden))
+    if unknown:
+        errors.append(f"devflow_playwright adapter has unsupported keys: {', '.join(unknown)}")
+    _path, path_error = dsl_path(root, feature, adapter.get("dsl_file"))
+    if path_error:
+        errors.append(path_error)
+    profile = adapter.get("environment_profile")
+    if not isinstance(profile, str) or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]{0,63}", profile):
+        errors.append("devflow_playwright adapter requires a valid environment_profile name")
+    timeout = adapter.get("timeout_seconds", DEFAULT_TIMEOUT_SECONDS)
+    if not isinstance(timeout, int) or isinstance(timeout, bool) or not MIN_TIMEOUT_SECONDS <= timeout <= MAX_TIMEOUT_SECONDS:
+        errors.append(f"timeout_seconds must be an integer in [{MIN_TIMEOUT_SECONDS}, {MAX_TIMEOUT_SECONDS}]")
+    artifacts = adapter.get("artifacts", {})
+    if not isinstance(artifacts, dict):
+        errors.append("artifacts must be an object")
+    else:
+        bad = sorted(key for key in artifacts if key not in ARTIFACT_KEYS)
+        if bad:
+            errors.append(f"artifacts has unsupported keys: {', '.join(bad)}")
+        for key in ("trace", "screenshots"):
+            if key in artifacts and artifacts[key] not in ARTIFACT_MODES:
+                errors.append(f"artifacts.{key} must be one of {', '.join(ARTIFACT_MODES)}")
+        limit = artifacts.get("max_total_bytes", DEFAULT_MAX_ARTIFACT_BYTES)
+        if not isinstance(limit, int) or isinstance(limit, bool) or not 1 <= limit <= MAX_ARTIFACT_BYTES:
+            errors.append(f"artifacts.max_total_bytes must be an integer in [1, {MAX_ARTIFACT_BYTES}]")
+    return errors
+
+
+def read_dsl(path: Path) -> tuple[bytes | None, Any, str | None]:
+    try:
+        if path.is_symlink() or not path.is_file():
+            return None, None, "DSL file is missing or not a regular file"
+        raw = path.read_bytes()
+    except OSError as error:
+        return None, None, f"DSL file is unreadable: {error}"
+    if len(raw) > MAX_DSL_BYTES:
+        return None, None, f"DSL file exceeds {MAX_DSL_BYTES} bytes"
+    try:
+        return raw, json.loads(raw.decode("utf-8")), None
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        return raw, None, f"DSL file is not valid JSON: {error}"
+
+
+# ---- Runtime location and integrity (A03) ---------------------------------------------------
+
+def locate_runtime() -> Path | None:
+    return next((candidate for candidate in runtime_dir_candidates() if (candidate / "runtime-manifest.json").is_file()), None)
+
+
+def verify_manifest(runtime: Path) -> tuple[dict[str, Any] | None, str | None, list[str]]:
+    """Return (manifest, manifest sha256, errors) after re-hashing every pinned runtime file."""
+    try:
+        raw = (runtime / "runtime-manifest.json").read_bytes()
+        manifest = json.loads(raw.decode("utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        return None, None, [f"runtime manifest is unreadable: {error}"]
+    errors: list[str] = []
+    files = manifest.get("files") if isinstance(manifest, dict) else None
+    if not isinstance(manifest, dict) or manifest.get("schema_version") != 1 or not isinstance(files, dict):
+        return None, None, ["runtime manifest must have schema_version 1 and a files map"]
+    if not isinstance(manifest.get("runtime_version"), str) or not manifest["runtime_version"]:
+        errors.append("runtime manifest runtime_version is missing")
+    for name in RUNTIME_FILES:
+        expected = files.get(name)
+        path = runtime / name
+        if not isinstance(expected, str) or not SHA256_RE.fullmatch(expected):
+            errors.append(f"runtime manifest does not pin {name}")
+        elif path.is_symlink() or not path.is_file():
+            errors.append(f"runtime file is missing: {name}")
+        elif sha256_bytes(path.read_bytes()) != expected:
+            errors.append(f"runtime file hash mismatch: {name}")
+    return (manifest if not errors else None), sha256_bytes(raw), errors
+
+
+def sanitized_base_env() -> dict[str, str]:
+    return {key: os.environ[key] for key in PASSTHROUGH_ENV if os.environ.get(key)}
+
+
+def package_root(runtime: Path) -> Path:
+    return runtime.resolve().parents[3]
+
+
+def resolve_playwright_cli(runtime: Path, project_root: Path, expected_version: str | None) -> tuple[Path | None, str | None]:
+    """Resolve @playwright/test/cli from the Runtime directory with Node's resolver, never the project's."""
+    env = sanitized_base_env()
+    node = shutil.which("node", path=env.get("PATH"))
+    if node is None:
+        return None, "node is not available on PATH"
+    script = "process.stdout.write(require.resolve('@playwright/test/cli', {paths: [process.argv[1]]}))"
+    try:
+        completed = subprocess.run([node, "-e", script, str(runtime.resolve())], cwd=runtime, env=env, text=True,
+                                   stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=30, check=False)
+    except (OSError, subprocess.TimeoutExpired) as error:
+        return None, f"cannot resolve the Runtime Playwright CLI: {error}"
+    if completed.returncode != 0 or not completed.stdout.strip():
+        return None, "the Runtime Playwright CLI (@playwright/test/cli) is not installed"
+    cli = Path(completed.stdout.strip()).resolve()
+    project_real = project_root.resolve()
+    owner = package_root(runtime)
+    inside_project = cli.is_relative_to(project_real)
+    if inside_project and not (owner.is_relative_to(project_real) and cli.is_relative_to(owner)):
+        return None, f"Playwright CLI resolved into the project under test: {cli}"
+    package_json = next((parent / "package.json" for parent in cli.parents if parent.name == "test" and parent.parent.name == "@playwright"), None)
+    if expected_version:
+        try:
+            version = json.loads(package_json.read_text(encoding="utf-8")).get("version") if package_json else None
+        except (OSError, ValueError):
+            version = None
+        if version != expected_version:
+            return None, f"Runtime Playwright version {version!r} does not match manifest {expected_version!r}"
+    return cli, None
+
+
+def launch_argv(runtime: Path, project_root: Path, manifest: dict[str, Any]) -> tuple[list[str] | None, str | None]:
+    cli, error = resolve_playwright_cli(runtime, project_root, manifest.get("playwright_version"))
+    if cli is None:
+        return None, error
+    node = shutil.which("node", path=sanitized_base_env().get("PATH"))
+    return [str(node), str(cli), "test", "--config", str(runtime.resolve() / "playwright.config.mjs")], None
+
+
+# ---- Execution (A02) ------------------------------------------------------------------------
+
+def new_execution_id() -> str:
+    return f"{datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')}-{secrets.token_hex(4)}"
+
+
+def runs_dir(root: Path, feature: str) -> Path:
+    return root / ".devflow" / "runs" / feature
+
+
+def blocked(error_code: str, message: str, **extra: Any) -> dict[str, Any]:
+    return {"status": "blocked", "error_code": error_code, "error": message, **extra}
+
+
+def terminate_group(process: subprocess.Popen[Any]) -> None:
+    try:
+        os.killpg(process.pid, signal.SIGTERM)
+    except (ProcessLookupError, PermissionError):
+        return
+    try:
+        process.wait(timeout=KILL_GRACE_SECONDS)
+    except subprocess.TimeoutExpired:
+        pass
+    try:
+        os.killpg(process.pid, signal.SIGKILL)
+    except (ProcessLookupError, PermissionError):
+        pass
+    process.wait()
+
+
+def _identity_errors(result: Any, expected: dict[str, Any]) -> list[str]:
+    if not isinstance(result, dict):
+        return ["result.json root must be an object"]
+    errors = [f"result.json {key} does not match" for key, value in expected.items() if result.get(key) != value]
+    if result.get("status") not in RESULT_STATUSES:
+        errors.append("result.json status is invalid")
+    for key in ("started_at", "finished_at"):
+        if not isinstance(result.get(key), str) or not result[key]:
+            errors.append(f"result.json {key} is required")
+    if not isinstance(result.get("steps"), list) or not all(isinstance(step, dict) for step in result["steps"]):
+        errors.append("result.json steps must be an array of objects")
+    if not isinstance(result.get("artifacts", []), list):
+        errors.append("result.json artifacts must be an array")
+    cleanup = result.get("cleanup", {})
+    if not isinstance(cleanup, dict):
+        errors.append("result.json cleanup must be an object")
+    if not errors and result["status"] == "passed":
+        if any(step.get("status") in {"failed", "blocked"} for step in result["steps"]):
+            errors.append("result.json reports passed with failed or blocked steps")
+        if cleanup.get("status") == "failed":
+            errors.append("result.json reports passed although cleanup failed")
+    return errors
+
+
+def verify_artifacts(root: Path, run_dir: Path, entries: list[Any], max_total_bytes: int) -> tuple[list[dict[str, Any]], list[str]]:
+    run_real = run_dir.resolve()
+    root_real = root.resolve()
+    verified: list[dict[str, Any]] = []
+    errors: list[str] = []
+    total = 0
+    for index, entry in enumerate(entries):
+        label = f"artifacts[{index}]"
+        if not isinstance(entry, dict) or entry.get("kind") not in ARTIFACT_KINDS or not isinstance(entry.get("path"), str):
+            errors.append(f"{label} must declare kind and path")
+            continue
+        raw = entry["path"]
+        candidate = Path(raw)
+        if not raw or "\x00" in raw or candidate.is_absolute() or ".." in candidate.parts:
+            errors.append(f"{label} path escapes the run directory: {raw}")
+            continue
+        unresolved = run_real / candidate
+        resolved = unresolved.resolve()
+        if not resolved.is_relative_to(run_real) or any(parent.is_symlink() for parent in [unresolved, *unresolved.parents] if parent.is_relative_to(run_real) and parent != run_real):
+            errors.append(f"{label} path escapes the run directory: {raw}")
+            continue
+        if not resolved.is_file():
+            errors.append(f"{label} file is missing: {raw}")
+            continue
+        content = resolved.read_bytes()
+        digest = sha256_bytes(content)
+        if entry.get("bytes") is not None and entry.get("bytes") != len(content):
+            errors.append(f"{label} size does not match result.json")
+        if entry.get("sha256") is not None and entry.get("sha256") != digest:
+            errors.append(f"{label} sha256 does not match result.json")
+        total += len(content)
+        verified.append({"path": resolved.relative_to(root_real).as_posix(), "kind": entry["kind"], "bytes": len(content), "sha256": digest})
+    if total > max_total_bytes:
+        errors.append(f"artifacts total {total} bytes exceed max_total_bytes {max_total_bytes}")
+    return verified, errors
+
+
+def normalize(result_status: str | None, exit_code: int | None, runtime_error_code: Any) -> tuple[str, str | None, list[str]]:
+    """方案 §8.3: the Runtime status is a local verdict; the exit code is only a consistency check."""
+    if result_status == "passed":
+        return ("passed", None, []) if exit_code == 0 else ("blocked", "runtime_integrity_error", [])
+    if result_status == "failed":
+        return "failed", runtime_error_code if isinstance(runtime_error_code, str) else None, (["result_exit_conflict"] if exit_code == 0 else [])
+    if result_status in {"blocked", "invalid"}:
+        return "blocked", runtime_error_code if isinstance(runtime_error_code, str) and runtime_error_code else f"runtime_{result_status}", []
+    return "blocked", "runtime_result_invalid", []
+
+
+def resolve_trust(root: Path, feature: str, tc_id: str, tc_data: dict[str, Any], suite: dict[str, Any], adapter: dict[str, Any]) -> dict[str, Any]:
+    """Re-derive, from current files and approvals, everything Core trusts before a run.
+
+    Shared by execute() (run time) and acceptance_test_runner.validate_results() (gate time) so both
+    apply exactly the same DSL/TC identity, execution_plan approval and environment_profile checks.
+    Returns {"base", "failure", "profile", "profile_name", "raw_profile", "raw_dsl", "dsl_sha", "tc_sha"};
+    ``failure`` is a complete Core-normalized blocked result (or None when everything is valid).
+    """
+    meta = suite.get("view_meta") if isinstance(suite.get("view_meta"), dict) else {}
+    current_tc = tc_sha256(tc_data)
+    trust: dict[str, Any] = {"base": {}, "failure": None, "profile": None, "profile_name": None, "raw_profile": None, "raw_dsl": None, "dsl_sha": None, "tc_sha": current_tc}
+    path, path_error = dsl_path(root, feature, adapter.get("dsl_file"))
+    raw_dsl, dsl, dsl_error = read_dsl(path) if path else (None, None, path_error)
+    if raw_dsl is None or dsl is None:
+        trust["failure"] = blocked("runtime_result_invalid", dsl_error or "DSL is unavailable")
+        return trust
+    dsl_sha = sha256_bytes(raw_dsl)
+    base = {"tc_sha256": current_tc, "dsl_sha256": dsl_sha}
+    trust.update({"base": base, "raw_dsl": raw_dsl, "dsl_sha": dsl_sha})
+    if not isinstance(dsl, dict) or dsl.get("tc_id") != tc_id or dsl.get("tc_sha256") != current_tc:
+        trust["failure"] = blocked("dsl_not_approved", "DSL no longer matches the frozen TC", **base)
+        return trust
+
+    # Pins are recomputed by approval_pins from the approved request; the DSL the
+    # binding names, the frozen TC and the suite must be exactly what was approved.
+    plan = valid_approval(root, feature, "execution_plan", tc_id, {"suite_graph_revision": suite.get("graph_revision"), "suite_fingerprint": meta.get("fingerprint"),
+                                                                   "tc_sha256": current_tc, "dsl_sha256": dsl_sha})
+    if not plan["ok"]:
+        code = REQUIRES_DATABASE if plan["reason"] == REQUIRES_DATABASE else "dsl_not_approved"
+        trust["failure"] = blocked(code, f"execution plan approval is not valid: {plan['message']}", dsl_approval="none", **base)
+        return trust
+    base["dsl_approval"] = {"status": "approved", "approval_id": plan["approval"]["id"], "approved_at": plan["approval"]["approved_at"]}
+
+    profile_name = adapter["environment_profile"]
+    profile, profile_sha, profile_errors = load_profile(root, profile_name)
+    if profile is None or profile_sha is None:
+        trust["failure"] = blocked("environment_profile_not_approved", "; ".join(profile_errors), **base)
+        return trust
+    profile_approval = valid_approval(root, feature, "environment_profile", profile_name, {"profile_sha256": profile_sha})
+    if not profile_approval["ok"]:
+        code = REQUIRES_DATABASE if profile_approval["reason"] == REQUIRES_DATABASE else "environment_profile_not_approved"
+        trust["failure"] = blocked(code, f"environment profile approval is not valid: {profile_approval['message']}", **base)
+        return trust
+    base["environment_profile"] = {"name": profile_name, "sha256": profile_sha, "approval_id": profile_approval["approval"]["id"]}
+    raw_profile = (root / ".devflow/planning/test-environments" / f"{profile_name}.json").read_bytes()
+    if sha256_bytes(raw_profile) != profile_sha:
+        trust["failure"] = blocked("environment_profile_not_approved", "environment profile changed while starting the run", **base)
+        return trust
+    trust.update({"profile": profile, "profile_name": profile_name, "raw_profile": raw_profile})
+    return trust
+
+
+def recorded_run_errors(root: Path, feature: str, tc_id: str, entry: dict[str, Any], run_dir_expired: bool = False) -> list[str]:
+    """Re-verify the on-disk evidence a recorded result entry points at (result.json + artifacts).
+
+    Missing/changed evidence is an error.  When the whole run directory is gone and ``run_dir_expired``
+    is true (the feature is past its post-closeout retention window, so GC legitimately removed it)
+    the file checks are skipped; every other field is still verified by the caller.
+    """
+    execution_id = entry.get("execution_id")
+    if not isinstance(execution_id, str) or not EXECUTION_ID_RE.fullmatch(execution_id):
+        return ["execution_id is missing or malformed"]
+    root_real = root.resolve()
+    run_dir = runs_dir(root_real, feature) / execution_id
+    expected_relative = run_dir.relative_to(root_real).as_posix()
+    if entry.get("run_dir") != expected_relative:
+        return [f"run_dir {entry.get('run_dir')!r} does not match execution_id (expected {expected_relative})"]
+    if run_dir.is_symlink() or not run_dir.is_dir():
+        return [] if run_dir_expired and not run_dir.is_symlink() and not run_dir.exists() else [f"run directory is missing: {expected_relative}"]
+    errors: list[str] = []
+    recorded_sha = entry.get("result_sha256")
+    result_file = run_dir / "result.json"
+    if result_file.is_symlink() or not result_file.is_file():
+        errors.append(f"result.json is missing: {expected_relative}/result.json")
+    else:
+        raw = result_file.read_bytes()
+        if sha256_bytes(raw) != recorded_sha:
+            errors.append("result.json sha256 differs from the recorded result_sha256 (evidence changed)")
+        else:
+            try:
+                result = json.loads(raw.decode("utf-8"))
+            except (UnicodeDecodeError, ValueError):
+                result = None
+            expected = {"origin": RESULT_ORIGIN, "execution_id": execution_id, "tc_id": tc_id, "tc_sha256": entry.get("tc_sha256"), "dsl_sha256": entry.get("dsl_sha256")}
+            if not isinstance(result, dict):
+                errors.append("result.json is not a JSON object")
+            else:
+                errors.extend(f"result.json {key} does not match the recorded entry" for key, value in expected.items() if result.get(key) != value)
+    artifacts = entry.get("artifacts")
+    if not isinstance(artifacts, list):
+        errors.append("artifacts must be a recorded array")
+        return errors
+    for index, artifact in enumerate(artifacts):
+        raw_path = artifact.get("path") if isinstance(artifact, dict) else None
+        if not isinstance(raw_path, str) or not raw_path or not isinstance(artifact.get("sha256"), str):
+            errors.append(f"artifacts[{index}] must record path and sha256")
+            continue
+        candidate = Path(raw_path)
+        resolved = (root_real / candidate).resolve()
+        if candidate.is_absolute() or ".." in candidate.parts or not resolved.is_relative_to(run_dir.resolve()):
+            errors.append(f"artifacts[{index}] path is outside the run directory: {raw_path}")
+        elif not resolved.is_file():
+            errors.append(f"artifact is missing: {raw_path}")
+        elif sha256_bytes(resolved.read_bytes()) != artifact["sha256"]:
+            errors.append(f"artifact sha256 differs from the recorded value (evidence changed): {raw_path}")
+    return errors
+
+
+def execute(root: Path, feature: str, tc_id: str, tc_data: dict[str, Any], suite: dict[str, Any], adapter: dict[str, Any]) -> dict[str, Any]:
+    """Run one bound TC through the Runtime and return the Core-normalized result fields."""
+    settings = adapter_settings(adapter)
+    trust = resolve_trust(root, feature, tc_id, tc_data, suite, adapter)
+    if trust["failure"] is not None:
+        return trust["failure"]
+    base, profile, raw_profile, raw_dsl, dsl_sha, current_tc = trust["base"], trust["profile"], trust["raw_profile"], trust["raw_dsl"], trust["dsl_sha"], trust["tc_sha"]
+
+    secret_env: dict[str, str] = {}
+    for key, env_name in profile.get("secret_env", {}).items():
+        if not os.environ.get(env_name):
+            return blocked("environment_secret_missing", f"secret environment variable for '{key}' is unset: {env_name}", **base)
+        secret_env[env_name] = os.environ[env_name]
+
+    runtime = locate_runtime()
+    if runtime is None:
+        return blocked("runtime_integrity_error", "Devflow Playwright Runtime is not installed (runtime-manifest.json not found)", **base)
+    manifest, manifest_sha, manifest_errors = verify_manifest(runtime)
+    if manifest is None:
+        return blocked("runtime_integrity_error", "; ".join(manifest_errors), **base)
+    base["runtime"] = {"version": manifest["runtime_version"], "playwright_version": manifest.get("playwright_version"), "manifest_sha256": manifest_sha}
+    argv, launch_error = launch_argv(runtime, root, manifest)
+    if argv is None:
+        return blocked("runtime_integrity_error", launch_error or "Runtime launcher is unavailable", **base)
+
+    execution_id = new_execution_id()
+    nonce = secrets.token_hex(16)
+    run_dir = runs_dir(root, feature) / execution_id
+    try:
+        run_dir.parent.mkdir(parents=True, exist_ok=True)
+        run_dir.mkdir(mode=0o700)
+        (run_dir / "artifacts").mkdir(mode=0o700)
+    except OSError as error:
+        return blocked("runtime_result_invalid", f"cannot create a fresh run directory: {error}", **base)
+    base["execution_id"] = execution_id
+    base["run_dir"] = run_dir.relative_to(root.resolve() if run_dir.is_relative_to(root.resolve()) else root).as_posix()
+    dsl_copy = run_dir / "dsl.json"
+    environment_copy = run_dir / "environment.json"
+    dsl_copy.write_bytes(raw_dsl)
+    environment_copy.write_bytes(raw_profile)
+    result_file = run_dir / "result.json"
+    env = {**sanitized_base_env(), **secret_env,
+           "DEVFLOW_DSL_FILE": str(dsl_copy.resolve()), "DEVFLOW_DSL_SHA256": dsl_sha,
+           "DEVFLOW_TC_ID": tc_id, "DEVFLOW_TC_SHA256": current_tc,
+           "DEVFLOW_EXECUTION_ID": execution_id, "DEVFLOW_EXECUTION_NONCE": nonce,
+           "DEVFLOW_RESULT_FILE": str(result_file.resolve()), "DEVFLOW_ARTIFACT_DIR": str((run_dir / "artifacts").resolve()),
+           "DEVFLOW_ENVIRONMENT_FILE": str(environment_copy.resolve())}
+    started_at = utc_now()
+    exit_code: int | None = None
+    timed_out = False
+    with open(run_dir / "runtime.log", "wb") as log:
+        try:
+            process = subprocess.Popen(argv, cwd=runtime, env=env, stdin=subprocess.DEVNULL, stdout=log, stderr=subprocess.STDOUT, start_new_session=True)
+        except OSError as error:
+            return blocked("runtime_integrity_error", f"Runtime could not start: {error}", **base)
+        try:
+            exit_code = process.wait(timeout=settings["timeout_seconds"])
+        except subprocess.TimeoutExpired:
+            timed_out = True
+            terminate_group(process)
+        finally:
+            try:  # reap any browser left in the group after the leader exited
+                os.killpg(process.pid, signal.SIGKILL)
+            except (ProcessLookupError, PermissionError):
+                pass
+    base.update({"started_at": started_at, "finished_at": utc_now(), "exit_code": exit_code})
+    if timed_out:
+        return blocked("runtime_timeout", f"Runtime exceeded timeout_seconds={settings['timeout_seconds']}", **base)
+
+    try:
+        if result_file.is_symlink() or not result_file.is_file():
+            raise ValueError("result.json is missing")
+        raw_result = result_file.read_bytes()
+        result = json.loads(raw_result.decode("utf-8"))
+    except (OSError, UnicodeDecodeError, ValueError) as error:
+        return blocked("runtime_result_invalid", str(error), **base)
+    base["result_sha256"] = sha256_bytes(raw_result)
+    identity_errors = _identity_errors(result, {"schema_version": 1, "origin": RESULT_ORIGIN, "execution_id": execution_id, "nonce": nonce,
+                                                "tc_id": tc_id, "tc_sha256": current_tc, "dsl_sha256": dsl_sha,
+                                                "runtime_version": manifest["runtime_version"]})
+    if identity_errors:
+        return blocked("runtime_result_invalid", "; ".join(identity_errors), **base)
+    artifacts, artifact_errors = verify_artifacts(root, run_dir, result.get("artifacts", []), settings["max_total_bytes"])
+    base["artifacts"] = artifacts
+    base["steps"] = [{key: step[key] for key in STEP_SUMMARY_KEYS if key in step} for step in result["steps"]]
+    base["cleanup"] = result.get("cleanup", {})
+    base["runtime_status"] = result["status"]
+    if artifact_errors:
+        return blocked("runtime_artifact_invalid", "; ".join(artifact_errors), **base)
+    status, error_code, conflicts = normalize(result["status"], exit_code, result.get("error_code"))
+    base.update({"status": status, "error_code": error_code})
+    if conflicts:
+        base["conflicts"] = conflicts
+    return base

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/repair_control_plane.rb

@@ -9,7 +9,7 @@ require_relative "control_io"
 require_relative "validate_state"
 require_relative "phase_ownership"
 
-options = { state: ".planning/STATE.md", expected_revision: nil, confirm: false, write: false, json: false }
+options = { state: ".devflow/planning/STATE.md", expected_revision: nil, confirm: false, write: false, json: false }
 OptionParser.new do |opts|
   opts.banner = "Usage: repair_control_plane.rb --expected-revision N --confirm --write"
   opts.on("--state PATH") { |value| options[:state] = value }

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/requirement_coverage.rb

@@ -14,7 +14,7 @@ module RequirementCoverage
   module_function
 
   def generate(root:, feature:, source:)
-    state = YAML.safe_load(File.read(File.join(root, ".planning/STATE.md")).split(/^---\s*$/, 3)[1], permitted_classes: [Date], aliases: false)
+    state = YAML.safe_load(File.read(File.join(root, ".devflow/planning/STATE.md")).split(/^---\s*$/, 3)[1], permitted_classes: [Date], aliases: false)
     raise ArgumentError, "source generation requires the active wayfinder step" unless state["current_feature"] == feature && state["current_step"] == "requirement-wayfinder"
     source_path = File.realpath(File.expand_path(source, root))
     raise ArgumentError, "source must be a project file" unless source_path.start_with?(File.realpath(root) + File::SEPARATOR)

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/requirement_graph.rb

@@ -18,7 +18,7 @@ module RequirementGraph
   # graphs are migrated in memory and re-written only by this Core writer.
   SCHEMA_VERSION = 5
   SUPPORTED_SCHEMA_VERSIONS = [1, 2, 3, 4, SCHEMA_VERSION].freeze
-  ROOT = ".planning/requirements"
+  ROOT = ".devflow/planning/requirements"
   KINDS = {
     "source" => "SRC", "code" => "CODE", "term" => "TERM", "object" => "OBJECT",
     "behavior" => "BEH", "requirement" => "REQ", "rule" => "BR", "boundary" => "BC",
@@ -56,7 +56,7 @@ module RequirementGraph
   end
 
   def active_feature(root)
-    state_path = File.join(root, ".planning", "STATE.md")
+    state_path = File.join(root, ".devflow/planning", "STATE.md")
     return nil unless File.file?(state_path)
     front = File.read(state_path).match(/\A---\n(.*?)\n---/m)&.[](1)
     return nil unless front
@@ -553,7 +553,7 @@ module RequirementGraph
     end
     matrix["imported_graph_revision"] = graph["revision"]
     DevflowControlIO.atomic_write(matrix_path, JSON.pretty_generate(matrix) + "\n")
-    template_path = File.join(root, ".planning", "features", graph["feature"], "api-acceptance-bindings.template.json")
+    template_path = File.join(root, ".devflow/planning", "features", graph["feature"], "api-acceptance-bindings.template.json")
     template = {
       "schema_version" => 1, "origin" => "core_api_test_matrix_template", "feature" => graph["feature"],
       "case_set_fingerprint" => matrix["case_set_fingerprint"],

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/review_preflight.py

@@ -81,7 +81,7 @@ def preflight(root: Path, feature: str, step: str, contract_path: str,
             return {"status": "human_confirmation", "evidence": evidence,
                     "issues": [{"code": "STALE_WORKFLOW_SNAPSHOT"}]}
         workflow = load_workflow(workflow_path)
-        state = load_state(within(root, ".planning/STATE.md"))
+        state = load_state(within(root, ".devflow/planning/STATE.md"))
         if state.get("revision") != current["state_revision"] or state.get("current_feature") != feature or state.get("current_step") != step:
             return {"status": "human_confirmation", "evidence": evidence,
                     "issues": [{"code": "STALE_STATE_SNAPSHOT"}]}
@@ -100,7 +100,7 @@ def preflight(root: Path, feature: str, step: str, contract_path: str,
             else:
                 issues.append({"code": "INVALID_WORKFLOW_INPUT", "detail": "unrecognized input obligation"})
                 continue
-            if required and relative != ".planning/execution-contract.md":
+            if required and relative != ".devflow/planning/execution-contract.md":
                 derived.append({"path": render(relative), "producer": "existing"})
         for item in step_definition.get("outputs", []):
             if isinstance(item, dict) and item.get("required") is True and isinstance(item.get("path"), str):
@@ -113,7 +113,7 @@ def preflight(root: Path, feature: str, step: str, contract_path: str,
                          "required_obligation_count": len(derived),
                          "checker_ids": current.get("checker_ids", [])})
         if step == "code-review":
-            graph_relative = f".planning/requirements/{feature}/governance.json"
+            graph_relative = f".devflow/planning/requirements/{feature}/governance.json"
             graph_path = within(root, graph_relative)
             if not graph_path.is_file():
                 issues.append({"code": "CONFIRMED_EXPECTATIONS_UNAVAILABLE", "path": graph_relative})