@guanlin4924/devflow-pi 0.1.94 → 0.1.95

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

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Structural coverage of a frozen TC by its v1 DSL (方案 §6.1, first layer).
+
+Every frozen precondition and step must be covered by at least one DSL step;
+the oracle must be covered by at least one non-weak assertion.  This only
+detects omissions and obviously weak assertions; semantic adequacy remains the
+job of the human-approved execution plan.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from dsl_v1 import UI_ASSERTIONS, UI_INTERACTIONS, all_steps
+
+
+def is_assertion(step: dict[str, Any]) -> bool:
+    if step.get("driver") == "ui":
+        return step.get("action") in UI_ASSERTIONS
+    return step.get("driver") == "api" and (bool(step.get("assertions")) or "expect_status" in step)
+
+
+def weak_reason(step: dict[str, Any], preceding: list[dict[str, Any]]) -> str | None:
+    """MVP weak assertions: assert_visible of a static entry element; 2xx-only API checks."""
+    if step.get("driver") == "api":
+        status = step.get("expect_status")
+        if not step.get("assertions") and (status is None or 200 <= status <= 299):
+            return "API assertion only checks a 2xx status without response body assertions"
+        return None
+    if step.get("action") != "assert_visible":
+        return None
+    interactions = [item for item in preceding if (item.get("driver") == "ui" and item.get("action") in UI_INTERACTIONS)
+                    or (item.get("driver") == "api" and item.get("method") != "GET")]
+    if not interactions:
+        return "assert_visible before any interaction only proves a static entry element is present"
+    if any(item.get("target") == step.get("target") for item in interactions):
+        return "assert_visible on an element the flow itself interacted with does not verify an outcome"
+    return None
+
+
+def _count(data: dict[str, Any], key: str) -> int:
+    value = data.get(key)
+    if isinstance(value, list):
+        return len(value)
+    return 1 if isinstance(value, str) and value.strip() else 0
+
+
+def check(tc_data: dict[str, Any], dsl: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    counts = {"preconditions": _count(tc_data, "preconditions"), "steps": _count(tc_data, "steps")}
+    covered: dict[str, set[int]] = {"preconditions": set(), "steps": set()}
+    oracle = tc_data.get("oracle")
+    has_oracle = (isinstance(oracle, str) and bool(oracle.strip())) or (isinstance(oracle, list) and bool(oracle))
+    oracle_assertions: list[tuple[str, dict[str, Any], str | None]] = []
+    main: list[dict[str, Any]] = []
+    for phase, path, step in all_steps(dsl):
+        covers = step.get("covers") if isinstance(step.get("covers"), dict) else {}
+        if phase == "cleanup" and covers:
+            errors.append(f"{path}.covers is not allowed on cleanup steps")
+            continue
+        for key in ("preconditions", "steps"):
+            for index in covers.get(key, []):
+                if not isinstance(index, int) or isinstance(index, bool) or not 1 <= index <= counts[key]:
+                    errors.append(f"{path}.covers.{key} index {index} is outside the frozen TC {key} (1..{counts[key]})")
+                else:
+                    covered[key].add(index)
+        if covers.get("oracle") is True:
+            if not is_assertion(step):
+                errors.append(f"{path} covers the oracle but {step.get('action')} is not an assertion")
+            elif phase != "main":
+                errors.append(f"{path} covers the oracle outside the main steps")
+            else:
+                oracle_assertions.append((path, step, weak_reason(step, main)))
+        if phase == "main":
+            main.append(step)
+    for key in ("preconditions", "steps"):
+        missing = sorted(set(range(1, counts[key] + 1)) - covered[key])
+        if missing:
+            errors.append(f"frozen TC {key} not covered by any DSL step: {', '.join(map(str, missing))}")
+    if has_oracle and not oracle_assertions:
+        errors.append("frozen TC oracle is not covered by any assertion step")
+    elif oracle_assertions and all(reason for _path, _step, reason in oracle_assertions):
+        errors.extend(f"{path}: weak oracle assertion ({reason})" for path, _step, reason in oracle_assertions)
+        errors.append("frozen TC oracle is covered only by weak assertions")
+    if tc_data.get("execution_surface") == "ui" or (tc_data.get("execution_surface") is None and tc_data.get("test_type") == "page"):
+        if oracle_assertions and not any(step.get("driver") == "ui" and not reason for _path, step, reason in oracle_assertions):
+            errors.append("UI TC oracle must be covered by a non-weak page assertion; API checks cannot replace it")
+    return errors

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

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+"""Pure-data validator for devflow-test-dsl/v1 (standard library only).
+
+Structural validation interprets the shipped JSON Schema
+(RT/devflow-test-dsl-v1.schema.json) with a small 2020-12 subset evaluator, so
+the Python gate and the Runtime judge the shared corpus from one source.
+Semantic rules the schema cannot express (unique ids, variable scoping, retry
+safety, secret headers) are checked afterwards.  Nothing here imports or
+executes code from the project under test.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from tc_hash import canonicalize
+
+
+SCHEMA_NAME = "devflow-test-dsl-v1.schema.json"
+SCHEMA_VERSION = "devflow-test-dsl/v1"
+BUILTIN_VARIABLES = frozenset({"execution_id", "namespace"})
+VARIABLE_REF_RE = re.compile(r"\$\{([^}]*)\}")
+VARIABLE_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,63}$")
+SECRET_HEADERS = frozenset({"authorization", "proxy-authorization", "cookie", "x-api-key", "x-auth-token"})
+UI_ASSERTIONS = frozenset({"assert_visible", "assert_text", "assert_url"})
+UI_INTERACTIONS = frozenset({"click", "fill", "select", "check", "uncheck"})
+_IGNORED_KEYWORDS = {"$schema", "$id", "title", "description", "$defs", "default", "examples"}
+
+
+def runtime_dir_candidates() -> list[Path]:
+    """Script-relative package first, then DEVFLOW_KIT_ROOT (…/plugins/devflow-core/skills)."""
+    candidates = [Path(__file__).resolve().parents[4] / "devflow-quality" / "runtime" / "playwright"]
+    configured = os.environ.get("DEVFLOW_KIT_ROOT")
+    if configured:
+        candidates.append(Path(configured).expanduser().resolve().parents[1] / "devflow-quality" / "runtime" / "playwright")
+    return candidates
+
+
+def schema_path() -> Path | None:
+    return next((candidate / SCHEMA_NAME for candidate in runtime_dir_candidates() if (candidate / SCHEMA_NAME).is_file()), None)
+
+
+@lru_cache(maxsize=4)
+def _load_schema(path: str) -> dict[str, Any]:
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def load_schema() -> dict[str, Any]:
+    path = schema_path()
+    if path is None:
+        raise FileNotFoundError(f"{SCHEMA_NAME} not found in the Devflow runtime directory")
+    return _load_schema(str(path))
+
+
+def _json_equal(left: Any, right: Any) -> bool:
+    try:
+        return canonicalize(left) == canonicalize(right)
+    except ValueError:
+        return False
+
+
+def _type_ok(value: Any, expected: str) -> bool:
+    if expected == "object":
+        return isinstance(value, dict)
+    if expected == "array":
+        return isinstance(value, list)
+    if expected == "string":
+        return isinstance(value, str)
+    if expected == "boolean":
+        return isinstance(value, bool)
+    if expected == "null":
+        return value is None
+    if expected == "integer":
+        return (isinstance(value, int) and not isinstance(value, bool)) or (isinstance(value, float) and value.is_integer())
+    if expected == "number":
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    raise ValueError(f"unsupported schema type: {expected}")
+
+
+class _Validator:
+    def __init__(self, root: dict[str, Any]) -> None:
+        self.root = root
+
+    def resolve(self, schema: dict[str, Any]) -> dict[str, Any]:
+        while "$ref" in schema:
+            reference = schema["$ref"]
+            if not reference.startswith("#/"):
+                raise ValueError(f"unsupported $ref: {reference}")
+            target: Any = self.root
+            for token in reference[2:].split("/"):
+                target = target[token.replace("~1", "/").replace("~0", "~")]
+            schema = target
+        return schema
+
+    def errors(self, value: Any, schema: dict[str, Any] | bool, path: str) -> list[str]:
+        if schema is True:
+            return []
+        if schema is False:
+            return [f"{path} is not allowed"]
+        schema = self.resolve(schema)
+        unknown = set(schema) - _IGNORED_KEYWORDS - {
+            "type", "const", "enum", "pattern", "minLength", "maxLength", "minimum", "maximum", "minItems", "maxItems",
+            "uniqueItems", "items", "properties", "required", "additionalProperties", "patternProperties",
+            "minProperties", "maxProperties", "oneOf"}
+        if unknown:
+            raise ValueError(f"unsupported schema keywords: {sorted(unknown)}")
+        if "oneOf" in schema:
+            return self.one_of(value, schema["oneOf"], path)
+        found: list[str] = []
+        if "type" in schema:
+            types = schema["type"] if isinstance(schema["type"], list) else [schema["type"]]
+            if not any(_type_ok(value, name) for name in types):
+                return [f"{path} must be of type {' or '.join(types)}"]
+        if "const" in schema and not _json_equal(value, schema["const"]):
+            found.append(f"{path} must equal {json.dumps(schema['const'], ensure_ascii=False)}")
+        if "enum" in schema and not any(_json_equal(value, item) for item in schema["enum"]):
+            found.append(f"{path} must be one of {', '.join(json.dumps(item, ensure_ascii=False) for item in schema['enum'])}")
+        if isinstance(value, str):
+            if "minLength" in schema and len(value) < schema["minLength"]:
+                found.append(f"{path} must be at least {schema['minLength']} characters")
+            if "maxLength" in schema and len(value) > schema["maxLength"]:
+                found.append(f"{path} must be at most {schema['maxLength']} characters")
+            if "pattern" in schema and not re.search(schema["pattern"], value):
+                found.append(f"{path} does not match pattern {schema['pattern']}")
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            if "minimum" in schema and value < schema["minimum"]:
+                found.append(f"{path} must be >= {schema['minimum']}")
+            if "maximum" in schema and value > schema["maximum"]:
+                found.append(f"{path} must be <= {schema['maximum']}")
+        if isinstance(value, list):
+            if "minItems" in schema and len(value) < schema["minItems"]:
+                found.append(f"{path} must contain at least {schema['minItems']} items")
+            if "maxItems" in schema and len(value) > schema["maxItems"]:
+                found.append(f"{path} must contain at most {schema['maxItems']} items")
+            if schema.get("uniqueItems") and len({canonicalize(item) for item in value}) != len(value):
+                found.append(f"{path} items must be unique")
+            if "items" in schema:
+                for index, item in enumerate(value):
+                    found.extend(self.errors(item, schema["items"], f"{path}[{index}]"))
+        if isinstance(value, dict):
+            if "minProperties" in schema and len(value) < schema["minProperties"]:
+                found.append(f"{path} must contain at least {schema['minProperties']} properties")
+            if "maxProperties" in schema and len(value) > schema["maxProperties"]:
+                found.append(f"{path} must contain at most {schema['maxProperties']} properties")
+            for key in schema.get("required", []):
+                if key not in value:
+                    found.append(f"{path}.{key} is required")
+            properties = schema.get("properties", {})
+            patterns = schema.get("patternProperties", {})
+            for key, child in value.items():
+                child_path = f"{path}.{key}"
+                matched = False
+                if key in properties:
+                    matched = True
+                    found.extend(self.errors(child, properties[key], child_path))
+                for pattern, child_schema in patterns.items():
+                    if re.search(pattern, key):
+                        matched = True
+                        found.extend(self.errors(child, child_schema, child_path))
+                if not matched and "additionalProperties" in schema:
+                    additional = schema["additionalProperties"]
+                    if additional is False:
+                        found.append(f"{child_path} is not an allowed property")
+                    else:
+                        found.extend(self.errors(child, additional, child_path))
+        return found
+
+    def one_of(self, value: Any, branches: list[Any], path: str) -> list[str]:
+        results = [self.errors(value, branch, path) for branch in branches]
+        passing = [index for index, errors in enumerate(results) if not errors]
+        if len(passing) == 1:
+            return []
+        if len(passing) > 1:
+            return [f"{path} matches more than one allowed form"]
+        # Report the branch selected by const discriminators (e.g. driver + action).
+        applicable: list[int] = []
+        discriminators: set[str] = set()
+        for index, branch in enumerate(branches):
+            resolved = self.resolve(branch) if isinstance(branch, dict) else {}
+            consts = {key: child["const"] for key, child in resolved.get("properties", {}).items() if isinstance(child, dict) and "const" in child}
+            discriminators.update(consts)
+            if consts and isinstance(value, dict) and all(key in value and _json_equal(value[key], expected) for key, expected in consts.items()):
+                applicable.append(index)
+        if len(applicable) == 1:
+            return results[applicable[0]]
+        if discriminators and isinstance(value, dict):
+            shown = ", ".join(f"{key}={json.dumps(value.get(key), ensure_ascii=False)}" for key in sorted(discriminators))
+            return [f"{path} has an unsupported combination ({shown})"]
+        if isinstance(value, dict) and not value:
+            return [f"{path} must not be empty"]
+        return [f"{path} must match exactly one allowed form"]
+
+
+def schema_errors(document: Any) -> list[str]:
+    schema = load_schema()
+    return _Validator(schema).errors(document, schema, "$")
+
+
+def _strings(value: Any, path: str) -> list[tuple[str, str]]:
+    if isinstance(value, str):
+        return [(path, value)]
+    if isinstance(value, dict):
+        return [item for key, child in value.items() for item in _strings(child, f"{path}.{key}")]
+    if isinstance(value, list):
+        return [item for index, child in enumerate(value) for item in _strings(child, f"{path}[{index}]")]
+    return []
+
+
+def _references(value: Any, path: str, known: set[str], errors: list[str]) -> set[str]:
+    used: set[str] = set()
+    for location, text in _strings(value, path):
+        for match in VARIABLE_REF_RE.finditer(text):
+            name = match.group(1)
+            if not VARIABLE_NAME_RE.fullmatch(name):
+                errors.append(f"{location} has an invalid variable reference ${{{name}}}")
+            elif name not in known:
+                errors.append(f"{location} references undefined variable ${{{name}}}")
+            used.add(name)
+        stripped = VARIABLE_REF_RE.sub("", text)
+        if "${" in stripped:
+            errors.append(f"{location} has an unterminated variable reference")
+    return used
+
+
+def all_steps(dsl: dict[str, Any]) -> list[tuple[str, str, dict[str, Any]]]:
+    """(phase, json-path, step) in execution order: setup, main, cleanup."""
+    data = dsl.get("data") if isinstance(dsl.get("data"), dict) else {}
+    out: list[tuple[str, str, dict[str, Any]]] = []
+    for phase, items, base in (("setup", data.get("setup"), "$.data.setup"), ("main", dsl.get("steps"), "$.steps"), ("cleanup", data.get("cleanup"), "$.data.cleanup")):
+        for index, step in enumerate(items if isinstance(items, list) else []):
+            if isinstance(step, dict):
+                out.append((phase, f"{base}[{index}]", step))
+    return out
+
+
+def semantic_errors(dsl: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    variables = dsl.get("variables", {})
+    sensitive: set[str] = set()
+    for name, spec in variables.items():
+        if name in BUILTIN_VARIABLES:
+            errors.append(f"$.variables.{name} redefines a built-in variable")
+        if "secret" in spec or spec.get("sensitive") is True:
+            sensitive.add(name)
+    known = set(variables) | {"execution_id"}
+    _references(dsl["data"]["namespace"], "$.data.namespace", known, errors)
+    known.add("namespace")
+    seen_ids: dict[str, str] = {}
+    for _phase, path, step in all_steps(dsl):
+        step_id = step["id"]
+        if step_id in seen_ids:
+            errors.append(f"{path}.id duplicates step id '{step_id}' ({seen_ids[step_id]})")
+        seen_ids.setdefault(step_id, path)
+        payload = {key: value for key, value in step.items() if key not in {"id", "driver", "action", "covers", "extract", "assertions", "retry"}}
+        _references(payload, path, known, errors)
+        if step["driver"] != "api":
+            continue
+        for index, assertion in enumerate(step.get("assertions", [])):
+            _references(assertion.get("value"), f"{path}.assertions[{index}].value", known, errors)
+            has_value = "value" in assertion
+            if assertion["op"] in {"exists", "not_exists"} and has_value:
+                errors.append(f"{path}.assertions[{index}] op {assertion['op']} must not have a value")
+            if assertion["op"] not in {"exists", "not_exists"} and not has_value:
+                errors.append(f"{path}.assertions[{index}] op {assertion['op']} requires a value")
+        if "retry" in step and step["method"] in {"POST", "PATCH"} and step.get("idempotent") is not True:
+            errors.append(f"{path}.retry on {step['method']} requires idempotent=true")
+        for header, value in step.get("headers", {}).items():
+            if header.lower() in SECRET_HEADERS:
+                refs = {match.group(1) for match in VARIABLE_REF_RE.finditer(value)}
+                if not refs or not refs <= sensitive:
+                    errors.append(f"{path}.headers.{header} must be built only from secret or sensitive variables")
+        for name, spec in step.get("extract", {}).items():
+            if name in known:
+                errors.append(f"{path}.extract.{name} redefines an existing variable")
+            known.add(name)
+            if spec.get("sensitive") is True:
+                sensitive.add(name)
+    return errors
+
+
+def validate(dsl: Any) -> list[str]:
+    try:
+        errors = schema_errors(dsl)
+    except (OSError, ValueError, KeyError) as error:
+        return [f"DSL v1 schema unavailable: {error}"]
+    return errors or semantic_errors(dsl)
+
+
+def load_file(path: Path) -> tuple[Any, list[str]]:
+    try:
+        return json.loads(path.read_text(encoding="utf-8")), []
+    except FileNotFoundError:
+        return None, [f"DSL file is missing: {path.as_posix()}"]
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        return None, [f"DSL file is not valid JSON: {error}"]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate devflow-test-dsl/v1 files.")
+    parser.add_argument("paths", nargs="+")
+    args = parser.parse_args()
+    report: dict[str, Any] = {}
+    for raw in args.paths:
+        document, errors = load_file(Path(raw))
+        report[raw] = errors or validate(document)
+    ok = not any(report.values())
+    print(json.dumps({"ok": ok, "errors": report}, ensure_ascii=False, indent=2))
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""Load and validate .devflow/planning/test-environments/<profile>.json.
+
+The profile hash is the SHA-256 of the raw file bytes; only an
+environment_profile approval pinned to that hash makes a profile usable.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+
+PROFILE_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$")
+SECRET_KEY_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,63}$")
+ENV_NAME_RE = re.compile(r"^[A-Z_][A-Z0-9_]{0,127}$")
+ORIGIN_RE = re.compile(r"^https?://(\[[0-9A-Fa-f:.]+\]|[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?)(:[0-9]{1,5})?$")
+RESERVED_ENV = frozenset({
+    "DEVFLOW_DSL_FILE", "DEVFLOW_DSL_SHA256", "DEVFLOW_TC_ID", "DEVFLOW_TC_SHA256", "DEVFLOW_EXECUTION_ID",
+    "DEVFLOW_EXECUTION_NONCE", "DEVFLOW_RESULT_FILE", "DEVFLOW_ARTIFACT_DIR", "DEVFLOW_ENVIRONMENT_FILE",
+    "PATH", "HOME", "TMPDIR", "LANG", "PLAYWRIGHT_BROWSERS_PATH", "SHELL", "USER", "PWD",
+})
+RESERVED_ENV_PREFIXES = ("NODE_", "LD_", "DYLD_", "PLAYWRIGHT_", "PYTHON", "BUN_", "NPM_", "DEVFLOW_HOME", "DEVFLOW_KIT", "DEVFLOW_SOFT")
+SUBRESOURCE_POLICIES = ("same-site-plus-declared", "declared-only")
+ARTIFACT_MODES = ("on_failure", "off")
+TOP_LEVEL = {"profile", "base_url", "api_base_url", "navigation_origins", "api_origins", "subresources", "secret_env", "trace", "screenshots"}
+
+
+def profile_path(root: Path, name: str) -> Path:
+    return root / ".devflow/planning" / "test-environments" / f"{name}.json"
+
+
+def origin_of(url: str) -> str | None:
+    parts = urlsplit(url)
+    if parts.scheme not in {"http", "https"} or not parts.hostname or parts.username or parts.password:
+        return None
+    origin = f"{parts.scheme}://{parts.netloc}"
+    return origin if ORIGIN_RE.fullmatch(origin) else None
+
+
+def _origins(value: Any, label: str, errors: list[str], required: bool) -> list[str]:
+    if not isinstance(value, list) or (required and not value):
+        errors.append(f"{label} must be a {'non-empty ' if required else ''}array of origins")
+        return []
+    origins: list[str] = []
+    for index, item in enumerate(value):
+        if not isinstance(item, str) or not ORIGIN_RE.fullmatch(item):
+            errors.append(f"{label}[{index}] must be an exact http(s) origin without path, wildcard, or credentials")
+        elif item in origins:
+            errors.append(f"{label}[{index}] duplicates {item}")
+        else:
+            origins.append(item)
+    return origins
+
+
+def validate_profile(profile: Any, name: str) -> list[str]:
+    if not isinstance(profile, dict):
+        return ["environment profile root must be an object"]
+    errors = [f"environment profile field is not allowed: {key}" for key in sorted(set(profile) - TOP_LEVEL)]
+    if profile.get("profile") != name:
+        errors.append("environment profile 'profile' must equal the profile file name")
+    navigation = _origins(profile.get("navigation_origins"), "navigation_origins", errors, required=True)
+    api = _origins(profile.get("api_origins", []), "api_origins", errors, required=False)
+    for key, allowed in (("base_url", navigation), ("api_base_url", api)):
+        if key not in profile and key == "api_base_url":
+            continue
+        value = profile.get(key)
+        origin = origin_of(value) if isinstance(value, str) else None
+        if origin is None:
+            errors.append(f"{key} must be an absolute http(s) URL")
+        elif origin not in allowed:
+            errors.append(f"{key} origin {origin} must be listed in {'navigation_origins' if key == 'base_url' else 'api_origins'}")
+    subresources = profile.get("subresources", {"policy": "same-site-plus-declared", "allowed_origins": []})
+    if not isinstance(subresources, dict) or set(subresources) - {"policy", "allowed_origins"}:
+        errors.append("subresources must be an object with policy and allowed_origins")
+    else:
+        if subresources.get("policy") not in SUBRESOURCE_POLICIES:
+            errors.append(f"subresources.policy must be one of {', '.join(SUBRESOURCE_POLICIES)}")
+        _origins(subresources.get("allowed_origins", []), "subresources.allowed_origins", errors, required=False)
+    secret_env = profile.get("secret_env", {})
+    if not isinstance(secret_env, dict):
+        errors.append("secret_env must be an object mapping secret keys to environment variable names")
+    else:
+        for key, env_name in secret_env.items():
+            if not SECRET_KEY_RE.fullmatch(key):
+                errors.append(f"secret_env key is invalid: {key}")
+            if not isinstance(env_name, str) or not ENV_NAME_RE.fullmatch(env_name):
+                errors.append(f"secret_env.{key} must name an upper-case environment variable")
+            elif env_name in RESERVED_ENV or env_name.startswith(RESERVED_ENV_PREFIXES):
+                errors.append(f"secret_env.{key} uses a reserved environment variable: {env_name}")
+    for key in ("trace", "screenshots"):
+        if key in profile and profile[key] not in ARTIFACT_MODES:
+            errors.append(f"{key} must be one of {', '.join(ARTIFACT_MODES)}")
+    return errors
+
+
+def load(root: Path, name: str) -> tuple[dict[str, Any] | None, str | None, list[str]]:
+    """Return (profile, sha256 of raw bytes, errors)."""
+    if not isinstance(name, str) or not PROFILE_NAME_RE.fullmatch(name):
+        return None, None, [f"invalid environment profile name: {name!r}"]
+    path = profile_path(root, name)
+    try:
+        if path.is_symlink():
+            return None, None, [f"environment profile must not be a symlink: {path.relative_to(root).as_posix()}"]
+        raw = path.read_bytes()
+    except FileNotFoundError:
+        return None, None, [f"environment profile is missing: {path.relative_to(root).as_posix()}"]
+    except OSError as error:
+        return None, None, [f"environment profile is unreadable: {error}"]
+    sha256 = hashlib.sha256(raw).hexdigest()
+    try:
+        profile = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        return None, sha256, [f"environment profile is not valid JSON: {error}"]
+    errors = validate_profile(profile, name)
+    return (profile if not errors else None), sha256, errors
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("name")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+    _profile, sha256, errors = load(Path.cwd().resolve(), args.name)
+    print(json.dumps({"ok": not errors, "profile": args.name, "sha256": sha256, "errors": errors}, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -130,6 +130,7 @@ begin
       devflow_api_test_matrix devflow_tdd_evidence devflow_run_acceptance_tests devflow_mainflow
       devflow_requirement_graph devflow_static_runtime_context
       devflow_architecture_constraint devflow_architecture_feasibility devflow_architecture_brief
+      devflow_approval
     ],
     "tool_budget" => policy["budget"], "hard_gate_mode" => (workflow.dig("governance", "hard_gate_mode").to_s.empty? ? "chain" : workflow.dig("governance", "hard_gate_mode").to_s), "acceptance" => Array(graph["nodes"]).select { |node| node["kind"] == "acceptance" }.map { |node| node["id"] },
     "allowed_graph_delta" => Array(policy["allowed_graph_delta"]),