@guanlin4924/devflow-pi 0.1.93 → 0.1.95

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

@@ -43,7 +43,7 @@ OptionParser.new do |o|
 end.parse!
 
 def load_state(root)
-  document = File.read(File.join(root, ".planning/STATE.md"))
+  document = File.read(File.join(root, ".devflow/planning/STATE.md"))
   front = document.match(/\A---\n(.*?)\n---/m)&.[](1)
   raise "STATE.md has no YAML front matter" unless front
   YAML.safe_load(front, permitted_classes: [], aliases: false)
@@ -57,7 +57,7 @@ def render_execution_contract_markdown(contract)
   lines = [
     "# Execution Contract",
     "",
-    "> Core-generated derived view. The immutable contract JSON under `.planning/contracts/` is authoritative.",
+    "> Core-generated derived view. The immutable contract JSON under `.devflow/planning/contracts/` is authoritative.",
     "",
     "- Contract ID: `#{contract.fetch("contract_id")}`",
     "- Feature: `#{contract.fetch("feature")}`",
@@ -106,7 +106,7 @@ begin
   # omitting production_paths strands implementation workers in a contract
   # that can write summaries but never code.
   if options[:step] == "execute"
-    binding_path = File.join(root, ".planning/features", options[:feature], "test-bindings.json")
+    binding_path = File.join(root, ".devflow/planning/features", options[:feature], "test-bindings.json")
     if File.file?(binding_path)
       bindings = JSON.parse(File.read(binding_path))
       Array(bindings["tasks"]).each do |task|
@@ -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"]),
@@ -142,10 +143,10 @@ begin
     result = { "ok" => true, "contract" => frozen }
   else
     raise ArgumentError, "--write is required" unless options[:write]
-    destination = File.join(root, ".planning/contracts", options[:feature], "#{contract_id}.json")
+    destination = File.join(root, ".devflow/planning/contracts", options[:feature], "#{contract_id}.json")
     DevflowControlIO.atomic_write(destination, JSON.pretty_generate(frozen) + "\n")
-    DevflowControlIO.atomic_write(File.join(root, ".planning/execution-contract.md"), render_execution_contract_markdown(frozen) + "\n")
-    audit = File.join(root, ".planning/contracts", options[:feature], "control-events.jsonl")
+    DevflowControlIO.atomic_write(File.join(root, ".devflow/planning/execution-contract.md"), render_execution_contract_markdown(frozen) + "\n")
+    audit = File.join(root, ".devflow/planning/contracts", options[:feature], "control-events.jsonl")
     existing = File.exist?(audit) ? File.read(audit) : ""
     DevflowControlIO.atomic_write(audit, existing + JSON.generate({ "event" => "execution_contract_frozen", "contract_id" => contract_id, "state_revision" => state["revision"], "graph_revision" => graph["revision"], "frozen_hash" => frozen["frozen_hash"] }) + "\n")
     result = { "ok" => true, "path" => destination.sub("#{root}/", ""), "contract" => frozen }

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

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""Single implementation of frozen-TC execution_surface derivation and consistency rules.
+
+execution_surface is a top-level field of the frozen TC node data (http | ui |
+api_flow | project_test).  Legacy TCs without the field are derived
+conservatively; only the project_test fallback is marked legacy_unclassified.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+
+SURFACES = ("http", "ui", "api_flow", "project_test")
+FEATURE_RE = re.compile(r"^[^/\\\x00-\x1f\x7f]+$")
+# Allowed binding kinds per surface (方案 §4.3).  manual/blocked are modes, not adapters.
+ADAPTERS_BY_SURFACE = {
+    "http": {"http"},
+    "ui": {"devflow_playwright"},
+    "api_flow": {"devflow_playwright"},
+    "project_test": {"command"},
+}
+
+
+def http_execution_error(source: dict[str, Any]) -> str | None:
+    execution = source.get("execution")
+    if not isinstance(execution, dict) or execution.get("protocol") != "http":
+        return "frozen TC has no HTTP execution definition"
+    request = execution.get("request")
+    expect = execution.get("expect")
+    if not isinstance(request, dict) or not isinstance(expect, dict):
+        return "frozen TC HTTP execution requires request and expect"
+    if not isinstance(request.get("method"), str) or not re.fullmatch(r"[A-Z]+", request["method"]):
+        return "frozen TC HTTP request method is invalid"
+    if not isinstance(request.get("path"), str) or not request["path"].startswith("/"):
+        return "frozen TC HTTP request path is invalid"
+    if not isinstance(expect.get("http_status"), int) or isinstance(expect.get("http_status"), bool) or not 100 <= expect["http_status"] <= 599:
+        return "frozen TC HTTP expectation http_status is invalid"
+    for key in ("path_params", "query", "headers", "body"):
+        if key in request and not isinstance(request[key], dict):
+            return f"frozen TC HTTP request {key} must be an object"
+    if "error_code" in expect and (not isinstance(expect["error_code"], str) or not expect["error_code"].strip()):
+        return "frozen TC HTTP expectation error_code is invalid"
+    if "error_code_pointer" in expect and (not isinstance(expect["error_code_pointer"], str) or not expect["error_code_pointer"].startswith("/")):
+        return "frozen TC HTTP expectation error_code_pointer is invalid"
+    return None
+
+
+def _declares_http(data: dict[str, Any]) -> bool:
+    execution = data.get("execution")
+    return isinstance(execution, dict) and execution.get("protocol") == "http"
+
+
+def derive(data: dict[str, Any]) -> tuple[str | None, bool]:
+    """Return (surface, legacy_unclassified); surface is None for an invalid explicit value."""
+    if "execution_surface" in data:
+        value = data.get("execution_surface")
+        return (value, False) if value in SURFACES else (None, False)
+    if _declares_http(data) and http_execution_error(data) is None:
+        return "http", False
+    if data.get("test_type") == "page":
+        return "ui", False
+    return "project_test", True
+
+
+def consistency_errors(data: dict[str, Any], require_explicit: bool = False) -> list[str]:
+    errors: list[str] = []
+    explicit = "execution_surface" in data
+    if require_explicit and not explicit:
+        return ["execution_surface is required for a newly frozen TC"]
+    surface, _legacy = derive(data)
+    if surface is None:
+        return [f"execution_surface must be one of {', '.join(SURFACES)}"]
+    if _declares_http(data) and surface != "http":
+        errors.append("TC with execution.protocol=http must have execution_surface=http")
+    if surface == "http":
+        http_error = http_execution_error(data)
+        if http_error:
+            errors.append(f"execution_surface=http requires a valid execution.protocol=http definition ({http_error})")
+    if data.get("test_type") == "page":
+        if surface != "ui":
+            errors.append("test_type=page requires execution_surface=ui")
+        if _declares_http(data):
+            errors.append("test_type=page must not declare execution.protocol=http")
+    if surface in {"ui", "api_flow"} and "execution" in data:
+        errors.append(f"execution_surface={surface} must not carry an execution object")
+    return errors
+
+
+def _test_cases(suite: dict[str, Any]) -> list[tuple[str, dict[str, Any]]]:
+    cases: list[tuple[str, dict[str, Any]]] = []
+    for node in suite.get("nodes", []) if isinstance(suite.get("nodes"), list) else []:
+        if isinstance(node, dict) and node.get("kind") == "test_case":
+            cases.append((str(node.get("id")), node.get("data") if isinstance(node.get("data"), dict) else {}))
+    return cases
+
+
+def check_suite(suite: dict[str, Any], require_explicit: bool = True) -> list[str]:
+    """Consistency errors for every TC; a new freeze requires the explicit field."""
+    errors: list[str] = []
+    for tc_id, data in _test_cases(suite):
+        errors.extend(f"{tc_id}: {error}" for error in consistency_errors(data, require_explicit=require_explicit))
+    return errors
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("action", choices=("check-suite",))
+    parser.add_argument("--feature", required=True)
+    parser.add_argument("--allow-legacy", action="store_true", help="derive missing fields instead of requiring them")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+    root = Path.cwd().resolve()
+    if not FEATURE_RE.fullmatch(args.feature):
+        result: dict[str, Any] = {"ok": False, "reason": "execution_surface_mismatch", "errors": ["invalid feature"]}
+    else:
+        path = root / ".devflow/planning" / "requirements" / args.feature / "tests.json"
+        try:
+            suite = json.loads(path.read_text(encoding="utf-8"))
+            if not isinstance(suite, dict):
+                raise ValueError("TC suite root must be an object")
+            errors = check_suite(suite, require_explicit=not args.allow_legacy)
+            if not _test_cases(suite):
+                errors.append("TC suite contains no test_case nodes")
+        except (OSError, ValueError) as error:
+            errors = [f"cannot read TC suite: {error}"]
+        result = {"ok": not errors, "feature": args.feature, "errors": errors}
+        if errors:
+            result["reason"] = "execution_surface_mismatch"
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -87,7 +87,7 @@ module GateRuntime
           invalid_outputs = validate_declared_inputs(contract.dig("outputs", "required_inputs"), root, workflow_state, purpose: :completion)
           return GateResult.block(**base, code: "REQUIRED_OUTPUT_INVALID", message: "required step input/output fact is invalid", details: { "invalid" => invalid_outputs }) unless invalid_outputs.empty?
           if step_id == "code-review"
-            contract_view = File.join(root, ".planning/execution-contract.md")
+            contract_view = File.join(root, ".devflow/planning/execution-contract.md")
             contract_id = if File.file?(contract_view) && !File.symlink?(contract_view)
                             File.read(contract_view).match(/^- Contract ID: `(EC-[0-9a-f]{16})`$/)&.[](1)
                           end
@@ -234,9 +234,9 @@ module GateRuntime
         case validation
         when "static-runtime-context"
           pointer_path = payload.fetch("path")
-          raise "invalid pointer path" unless pointer_path.start_with?(".context/static-runtime-context/revisions/")
+          raise "invalid pointer path" unless pointer_path.start_with?(".devflow/context/static-runtime-context/revisions/")
           root_real = File.realpath(root)
-          revisions_root = File.realpath(File.join(root, ".context/static-runtime-context/revisions"))
+          revisions_root = File.realpath(File.join(root, ".devflow/context/static-runtime-context/revisions"))
           snapshot_real = File.realpath(File.expand_path(pointer_path, root))
           raise "snapshot path escapes project root" unless snapshot_real.start_with?("#{root_real}#{File::SEPARATOR}")
           raise "snapshot path escapes revisions directory" unless snapshot_real.start_with?("#{revisions_root}#{File::SEPARATOR}")