@guanlin4924/devflow-pi 0.1.39 → 0.1.47

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

@@ -0,0 +1,457 @@
+#!/usr/bin/env python3
+"""Fail-closed validator and canonical builder for wireframe proposals."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import subprocess
+import sys
+import unicodedata
+from pathlib import Path
+from typing import Any
+
+DEFAULT_SCHEMA = Path(__file__).resolve().parents[1] / "contracts" / "proposal.schema.yaml"
+DEFAULT_QUESTIONS_SCHEMA = Path(__file__).resolve().parents[1] / "contracts" / "questions.schema.yaml"
+ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")
+STATES = {"default", "empty", "loading", "error"}
+PRESENTATIONS = {"page", "modal", "drawer"}
+PLATFORMS = {"web", "mobile"}
+ACTION_TYPES = {"open", "close", "back"}
+ELEMENT_TYPES = set()
+ELEMENT_ALLOWED: dict[str, set[str]] = {}
+ATOMIC = {"input", "select", "button", "icon_button"}
+
+
+def load_yaml(path: Path) -> Any:
+    try:
+        import yaml  # type: ignore
+        return yaml.safe_load(path.read_text(encoding="utf-8"))
+    except ImportError:
+        result = subprocess.run(
+            ["ruby", "-ryaml", "-rjson", "-e", "puts JSON.generate(YAML.safe_load(File.read(ARGV.fetch(0))))", str(path)],
+            text=True, capture_output=True, check=False,
+        )
+        if result.returncode != 0:
+            raise ValueError(result.stderr.strip() or "YAML parse failed")
+        return json.loads(result.stdout)
+
+
+def schema_values(schema: dict[str, Any]) -> tuple[re.Pattern[str], set[str], set[str], set[str], set[str], dict[str, set[str]]]:
+    pattern = str(schema.get("id_pattern", r"^[A-Za-z0-9][A-Za-z0-9_-]*$"))
+    screens = schema.get("screen", {})
+    screen_props = screens.get("properties", {}) if isinstance(screens, dict) else {}
+    states = set(screen_props.get("states", {}).get("values", ["default", "empty", "loading", "error"]))
+    presentations = set(screen_props.get("presentation", {}).get("values", ["page", "modal", "drawer"]))
+    platforms = set(screen_props.get("platforms", {}).get("values", ["web", "mobile"]))
+    actions = schema.get("action", {}).get("properties", {}).get("type", {}).get("values", ["open", "close", "back"])
+    element_specs = schema.get("elements", {})
+    element_allowed = {typ: {"id", "type"} | set(spec) for typ, spec in element_specs.items() if isinstance(spec, dict)}
+    return re.compile(pattern), states, presentations, platforms, set(actions), element_allowed
+
+
+def issue(errors: list[dict[str, str]], code: str, path: str, message: str) -> None:
+    errors.append({"code": code, "path": path, "message": message})
+
+
+def unknown_keys(value: Any, allowed: set[str], path: str, errors: list[dict[str, str]]) -> None:
+    if not isinstance(value, dict):
+        return
+    for key in value:
+        if key not in allowed:
+            issue(errors, "WIREFRAME_UNKNOWN_FIELD", f"{path}.{key}", f"unknown field {key}")
+
+
+def require_id(value: Any, code: str, path: str, errors: list[dict[str, str]], seen: set[str]) -> None:
+    if not isinstance(value, str) or not value:
+        issue(errors, code, path, "id is required")
+    elif not ID_RE.fullmatch(value):
+        issue(errors, code, path, "id must match ^[A-Za-z0-9][A-Za-z0-9_-]*$")
+    elif value in seen:
+        issue(errors, "WIREFRAME_DUPLICATE_ELEMENT_ID" if code == "WIREFRAME_ELEMENT_ID_MISSING" else "WIREFRAME_DUPLICATE_SCREEN_ID", path, f"duplicate id {value}")
+    else:
+        seen.add(value)
+
+
+def non_empty(value: Any, code: str, path: str, errors: list[dict[str, str]]) -> None:
+    if not isinstance(value, str) or not value.strip():
+        issue(errors, code, path, "non-empty string required")
+
+
+def validate_questions(value: Any, feature: str, schema: dict[str, Any]) -> tuple[list[dict[str, str]], list[str], dict[str, Any]]:
+    errors: list[dict[str, str]] = []
+    blocking_open: list[str] = []
+    metadata = {"status": "present", "unresolved": []}
+    if not isinstance(value, dict):
+        issue(errors, "WIREFRAME_QUESTION_SCHEMA_INVALID", "$", "questions root must be an object")
+        return errors, blocking_open, {"status": "invalid", "unresolved": []}
+    unknown_keys(value, {"schema_version", "feature", "questions"}, "$", errors)
+    if value.get("schema_version") != schema.get("schema_version", 1):
+        issue(errors, "WIREFRAME_QUESTION_SCHEMA_INVALID", "schema_version", "must match questions schema")
+    if value.get("feature") != feature:
+        issue(errors, "WIREFRAME_QUESTION_SCHEMA_INVALID", "feature", "must match proposal feature")
+    questions = value.get("questions")
+    if not isinstance(questions, list):
+        issue(errors, "WIREFRAME_QUESTION_SCHEMA_INVALID", "questions", "must be an array")
+        return errors, blocking_open, metadata
+    ids: set[str] = set()
+    for i, question in enumerate(questions):
+        path = f"questions[{i}]"
+        if not isinstance(question, dict):
+            issue(errors, "WIREFRAME_QUESTION_SCHEMA_INVALID", path, "question must be an object")
+            continue
+        unknown_keys(question, {"id", "text", "kind", "status", "target", "answer"}, path, errors)
+        qid = question.get("id")
+        if not isinstance(qid, str) or not ID_RE.fullmatch(qid):
+            issue(errors, "WIREFRAME_QUESTION_ID_MISSING", f"{path}.id", "id must match the proposal id pattern")
+        elif qid in ids:
+            issue(errors, "WIREFRAME_DUPLICATE_QUESTION_ID", f"{path}.id", f"duplicate id {qid}")
+        else:
+            ids.add(qid)
+        non_empty(question.get("text"), "WIREFRAME_QUESTION_TEXT_MISSING", f"{path}.text", errors)
+        if question.get("kind") not in {"blocking", "informational"}:
+            issue(errors, "WIREFRAME_QUESTION_SCHEMA_INVALID", f"{path}.kind", "must be blocking or informational")
+        if question.get("status") not in {"open", "resolved"}:
+            issue(errors, "WIREFRAME_QUESTION_SCHEMA_INVALID", f"{path}.status", "must be open or resolved")
+        target = question.get("target")
+        if target is not None:
+            if not isinstance(target, dict):
+                issue(errors, "WIREFRAME_QUESTION_SCHEMA_INVALID", f"{path}.target", "must be an object")
+            else:
+                unknown_keys(target, {"screen", "element"}, f"{path}.target", errors)
+                if any(not isinstance(target.get(k), str) or not ID_RE.fullmatch(target[k]) for k in target):
+                    issue(errors, "WIREFRAME_QUESTION_SCHEMA_INVALID", f"{path}.target", "target IDs must match the proposal id pattern")
+        if "answer" in question and question["answer"] is not None and not isinstance(question["answer"], str):
+            issue(errors, "WIREFRAME_QUESTION_SCHEMA_INVALID", f"{path}.answer", "answer must be null or a string")
+        if question.get("kind") == "blocking" and question.get("status") == "open" and isinstance(qid, str):
+            blocking_open.append(qid)
+    metadata["unresolved"] = blocking_open
+    return errors, blocking_open, metadata
+
+
+def validate_inline(element: dict[str, Any], index: int, errors: list[dict[str, str]]) -> None:
+    typ = element.get("type")
+    path = f"screens[].elements[{index}]"
+    if typ == "page_header":
+        non_empty(element.get("title"), "WIREFRAME_MISSING_FIELD", f"{path}.title", errors)
+        refs = element.get("action_refs", [])
+        if not isinstance(refs, list) or not all(isinstance(x, str) for x in refs):
+            issue(errors, "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.action_refs", "must be an array of IDs")
+    elif typ == "filter_bar":
+        fields = element.get("fields")
+        if not isinstance(fields, list) or not fields:
+            issue(errors, "WIREFRAME_MISSING_FIELD", f"{path}.fields", "fields must be a non-empty array")
+        else:
+            ids: set[str] = set()
+            for j, field in enumerate(fields):
+                if not isinstance(field, dict):
+                    issue(errors, "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.fields[{j}]", "field must be an object")
+                    continue
+                unknown_keys(field, {"id", "label", "type"}, f"{path}.fields[{j}]", errors)
+                require_id(field.get("id"), "WIREFRAME_ELEMENT_ID_MISSING", f"{path}.fields[{j}].id", errors, ids)
+                non_empty(field.get("label"), "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.fields[{j}].label", errors)
+                if field.get("type") not in {"input", "select"}:
+                    issue(errors, "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.fields[{j}].type", "must be input or select")
+    elif typ == "table":
+        columns = element.get("columns")
+        if not isinstance(columns, list) or not columns:
+            issue(errors, "WIREFRAME_MISSING_FIELD", f"{path}.columns", "columns must be a non-empty array")
+        else:
+            ids: set[str] = set()
+            for j, col in enumerate(columns):
+                if not isinstance(col, dict):
+                    issue(errors, "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.columns[{j}]", "column must be an object")
+                    continue
+                unknown_keys(col, {"id", "label"}, f"{path}.columns[{j}]", errors)
+                require_id(col.get("id"), "WIREFRAME_ELEMENT_ID_MISSING", f"{path}.columns[{j}].id", errors, ids)
+                non_empty(col.get("label"), "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.columns[{j}].label", errors)
+    elif typ == "card_list":
+        items = element.get("items")
+        if not isinstance(items, list) or not items:
+            issue(errors, "WIREFRAME_MISSING_FIELD", f"{path}.items", "items must be a non-empty array")
+        else:
+            ids: set[str] = set()
+            for j, item in enumerate(items):
+                if not isinstance(item, dict):
+                    issue(errors, "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.items[{j}]", "item must be an object")
+                    continue
+                unknown_keys(item, {"id", "title", "meta"}, f"{path}.items[{j}]", errors)
+                require_id(item.get("id"), "WIREFRAME_ELEMENT_ID_MISSING", f"{path}.items[{j}].id", errors, ids)
+                non_empty(item.get("title"), "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.items[{j}].title", errors)
+                meta = item.get("meta", [])
+                if not isinstance(meta, list) or any(not isinstance(x, dict) or set(x) != {"label", "value"} for x in meta):
+                    issue(errors, "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.items[{j}].meta", "must contain label/value objects")
+    elif typ == "bottom_navigation":
+        items = element.get("items")
+        if not isinstance(items, list) or not items:
+            issue(errors, "WIREFRAME_MISSING_FIELD", f"{path}.items", "items must be a non-empty array")
+        else:
+            for j, item in enumerate(items):
+                if not isinstance(item, dict):
+                    issue(errors, "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.items[{j}]", "item must be an object")
+                    continue
+                unknown_keys(item, {"id", "label", "action_ref"}, f"{path}.items[{j}]", errors)
+                non_empty(item.get("id"), "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.items[{j}].id", errors)
+                non_empty(item.get("label"), "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.items[{j}].label", errors)
+                if "action_ref" in item:
+                    non_empty(item.get("action_ref"), "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.items[{j}].action_ref", errors)
+    elif typ == "tabs":
+        tabs = element.get("tabs")
+        if not isinstance(tabs, list) or not tabs:
+            issue(errors, "WIREFRAME_MISSING_FIELD", f"{path}.tabs", "tabs must be a non-empty array")
+        else:
+            for j, tab in enumerate(tabs):
+                if not isinstance(tab, dict):
+                    issue(errors, "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.tabs[{j}]", "tab must be an object")
+                    continue
+                unknown_keys(tab, {"id", "label"}, f"{path}.tabs[{j}]", errors)
+                non_empty(tab.get("id"), "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.tabs[{j}].id", errors)
+                non_empty(tab.get("label"), "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.tabs[{j}].label", errors)
+    elif typ in ATOMIC:
+        non_empty(element.get("label"), "WIREFRAME_MISSING_FIELD", f"{path}.label", errors)
+
+
+def validate(data: Any, traceability: Any, schema: dict[str, Any], business_model: Any = None) -> tuple[list[dict[str, str]], dict[str, Any] | None]:
+    global ID_RE, STATES, PRESENTATIONS, PLATFORMS, ACTION_TYPES, ELEMENT_TYPES, ELEMENT_ALLOWED, ATOMIC
+    ID_RE, STATES, PRESENTATIONS, PLATFORMS, ACTION_TYPES, ELEMENT_ALLOWED = schema_values(schema)
+    ELEMENT_TYPES = set(ELEMENT_ALLOWED)
+    ATOMIC = ELEMENT_TYPES - {"page_header", "filter_bar", "table", "card_list", "bottom_navigation", "tabs"}
+    errors: list[dict[str, str]] = []
+    business_actions = set()
+    if business_model is not None and isinstance(business_model, dict):
+        business_actions = {item.get("id") for item in business_model.get("actions", []) if isinstance(item, dict)}
+        if not business_actions:
+            issue(errors, "WIREFRAME_BUSINESS_MODEL_INVALID", "business_model", "business model has no actions")
+    if not isinstance(data, dict):
+        issue(errors, "WIREFRAME_SCHEMA_VERSION_INVALID", "$", "root must be an object")
+        return errors, None
+    unknown_keys(data, {"schema_version", "feature", "screens"}, "$", errors)
+    if data.get("schema_version") != 1:
+        issue(errors, "WIREFRAME_SCHEMA_VERSION_INVALID", "schema_version", "must be 1")
+    non_empty(data.get("feature"), "WIREFRAME_FEATURE_MISSING", "feature", errors)
+    screens = data.get("screens")
+    if not isinstance(screens, list) or not screens:
+        issue(errors, "WIREFRAME_SCREENS_MISSING", "screens", "must be a non-empty array")
+        return errors, None
+    reqs = set()
+    if isinstance(traceability, dict):
+        reqs = {r.get("id") for r in traceability.get("requirements", []) if isinstance(r, dict) and r.get("status") in {"confirmed", "approved"} and r.get("scope", "in") == "in"}
+    screen_ids: set[str] = set()
+    canonical_screens: list[dict[str, Any]] = []
+    for i, screen in enumerate(screens):
+        path = f"screens[{i}]"
+        if not isinstance(screen, dict):
+            issue(errors, "WIREFRAME_SCREENS_MISSING", path, "screen must be an object")
+            continue
+        unknown_keys(screen, {"id", "title", "presentation", "platforms", "requirement_refs", "elements", "actions", "states"}, path, errors)
+        sid = screen.get("id")
+        if not isinstance(sid, str) or not sid:
+            issue(errors, "WIREFRAME_SCREEN_ID_MISSING", f"{path}.id", "id is required")
+        elif not ID_RE.fullmatch(sid):
+            issue(errors, "WIREFRAME_SCREEN_ID_MISSING", f"{path}.id", "id format is invalid")
+        elif sid in screen_ids:
+            issue(errors, "WIREFRAME_DUPLICATE_SCREEN_ID", f"{path}.id", f"duplicate id {sid}")
+        else:
+            screen_ids.add(sid)
+        non_empty(screen.get("title"), "WIREFRAME_SCREEN_TITLE_MISSING", f"{path}.title", errors)
+        presentation = screen.get("presentation", "page")
+        if presentation not in PRESENTATIONS:
+            issue(errors, "WIREFRAME_INVALID_PRESENTATION", f"{path}.presentation", "invalid presentation")
+        platforms = screen.get("platforms", ["web", "mobile"])
+        if not isinstance(platforms, list) or not platforms or any(x not in PLATFORMS for x in platforms) or len(set(platforms)) != len(platforms):
+            issue(errors, "WIREFRAME_INVALID_PLATFORM", f"{path}.platforms", "must be unique web/mobile values")
+        refs = screen.get("requirement_refs")
+        if not isinstance(refs, list) or not refs:
+            issue(errors, "WIREFRAME_SCREEN_REQUIREMENT_REFS_EMPTY", f"{path}.requirement_refs", "at least one requirement ref is required")
+        else:
+            for j, ref in enumerate(refs):
+                if ref not in reqs:
+                    issue(errors, "WIREFRAME_UNKNOWN_REQUIREMENT_REF", f"{path}.requirement_refs[{j}]", f"unknown confirmed requirement {ref}")
+        elements = screen.get("elements")
+        if not isinstance(elements, list):
+            issue(errors, "WIREFRAME_MISSING_FIELD", f"{path}.elements", "elements must be an array")
+            elements = []
+        actions = screen.get("actions", [])
+        if not isinstance(actions, list):
+            issue(errors, "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.actions", "actions must be an array")
+            actions = []
+        states = screen.get("states")
+        if not isinstance(states, list):
+            issue(errors, "WIREFRAME_STATES_MISSING", f"{path}.states", "states must be an array")
+            states = []
+        if "default" not in states:
+            issue(errors, "WIREFRAME_STATE_DEFAULT_MISSING", f"{path}.states", "default state is required")
+        if len(states) != len(set(states)):
+            issue(errors, "WIREFRAME_INVALID_STATE", f"{path}.states", "states must not contain duplicates")
+        for j, state in enumerate(states):
+            if state not in STATES:
+                issue(errors, "WIREFRAME_INVALID_STATE", f"{path}.states[{j}]", "invalid state")
+        element_ids: set[str] = set()
+        for j, element in enumerate(elements):
+            if not isinstance(element, dict):
+                issue(errors, "WIREFRAME_INVALID_FIELD_VALUE", f"{path}.elements[{j}]", "element must be an object")
+                continue
+            typ = element.get("type")
+            allowed = ELEMENT_ALLOWED.get(typ, {"id", "type"})
+            unknown_keys(element, allowed, f"{path}.elements[{j}]", errors)
+            require_id(element.get("id"), "WIREFRAME_ELEMENT_ID_MISSING", f"{path}.elements[{j}].id", errors, element_ids)
+            if typ not in ELEMENT_TYPES:
+                issue(errors, "WIREFRAME_UNKNOWN_ELEMENT_TYPE", f"{path}.elements[{j}].type", f"unknown element type {typ}")
+            else:
+                validate_inline(element, j, errors)
+        action_ids: set[str] = set()
+        for j, action in enumerate(actions):
+            apath = f"{path}.actions[{j}]"
+            if not isinstance(action, dict):
+                issue(errors, "WIREFRAME_INVALID_FIELD_VALUE", apath, "action must be an object")
+                continue
+            unknown_keys(action, {"id", "type", "target", "business_action_ref"}, apath, errors)
+            aid = action.get("id")
+            if not isinstance(aid, str) or not aid:
+                issue(errors, "WIREFRAME_ACTION_ID_MISSING", f"{apath}.id", "id is required")
+            elif not ID_RE.fullmatch(aid):
+                issue(errors, "WIREFRAME_ACTION_ID_MISSING", f"{apath}.id", "id format is invalid")
+            elif aid in action_ids:
+                issue(errors, "WIREFRAME_DUPLICATE_ACTION_ID", f"{apath}.id", f"duplicate id {aid}")
+            else:
+                action_ids.add(aid)
+            if action.get("type") not in ACTION_TYPES:
+                issue(errors, "WIREFRAME_INVALID_ACTION_TYPE", f"{apath}.type", "must be open, close or back")
+            elif action.get("type") == "open" and not isinstance(action.get("target"), str):
+                issue(errors, "WIREFRAME_ACTION_TARGET_SHAPE", f"{apath}.target", "open target must be a screen id")
+            elif action.get("type") in {"close", "back"} and action.get("target") is not None:
+                issue(errors, "WIREFRAME_ACTION_TARGET_SHAPE", f"{apath}.target", "close/back target must be null")
+            if business_model is not None and action.get("type") == "open":
+                ref = action.get("business_action_ref")
+                if not isinstance(ref, str) or not ref:
+                    issue(errors, "WIREFRAME_BUSINESS_ACTION_REF_MISSING", f"{apath}.business_action_ref", "open action must reference a business action")
+                elif ref not in business_actions:
+                    issue(errors, "WIREFRAME_BUSINESS_ACTION_REF_UNRESOLVED", f"{apath}.business_action_ref", f"business action {ref} does not exist")
+        refs_used: list[str] = []
+        for element in elements:
+            if isinstance(element, dict):
+                refs_used += element.get("action_refs", []) if isinstance(element.get("action_refs"), list) else []
+                if isinstance(element.get("action_ref"), str): refs_used.append(element["action_ref"])
+                if element.get("type") == "bottom_navigation":
+                    refs_used += [x.get("action_ref") for x in element.get("items", []) if isinstance(x, dict) and isinstance(x.get("action_ref"), str)]
+        for ref in refs_used:
+            if ref not in action_ids:
+                issue(errors, "WIREFRAME_ACTION_REF_UNRESOLVED", f"{path}.elements", f"action ref {ref} is not defined on this screen")
+        canonical = dict(screen)
+        canonical.setdefault("presentation", "page")
+        canonical.setdefault("platforms", ["web", "mobile"])
+        canonical.setdefault("actions", [])
+        canonical_screens.append(canonical)
+    # Validate targets after the full screen namespace is known; forward screen
+    # references are valid and must not depend on YAML traversal order.
+    for i, screen in enumerate(screens):
+        if not isinstance(screen, dict) or not isinstance(screen.get("actions", []), list):
+            continue
+        for j, action in enumerate(screen.get("actions", [])):
+            if isinstance(action, dict) and action.get("type") == "open" and action.get("target") not in screen_ids:
+                issue(errors, "WIREFRAME_INVALID_ACTION_TARGET", f"screens[{i}].actions[{j}].target", "target screen does not exist")
+    canonical = {"schema_version": 1, "feature": data.get("feature"), "screens": canonical_screens}
+    return errors, canonical
+
+
+def normalize(value: Any) -> Any:
+    if isinstance(value, str):
+        return unicodedata.normalize("NFKC", value).rstrip()
+    if isinstance(value, list):
+        return [normalize(x) for x in value]
+    if isinstance(value, dict):
+        return {k: normalize(v) for k, v in value.items()}
+    return value
+
+
+ROOT_ORDER = ["schema_version", "feature", "screens"]
+SCREEN_ORDER = ["id", "title", "presentation", "platforms", "requirement_refs", "elements", "actions", "states"]
+ELEMENT_ORDER = ["id", "type", "title", "label", "action_refs", "action_ref", "fields", "columns", "items", "tabs"]
+ACTION_ORDER = ["id", "type", "target", "business_action_ref"]
+INLINE_ORDER = ["id", "label", "type", "title", "meta", "value", "action_ref"]
+
+
+def reorder(value: Any, order: list[str]) -> Any:
+    if isinstance(value, list):
+        return [reorder(x, INLINE_ORDER) for x in value]
+    if not isinstance(value, dict):
+        return value
+    keys = [key for key in order if key in value]
+    keys += sorted(key for key in value if key not in keys)
+    return {key: reorder(value[key], INLINE_ORDER) for key in keys}
+
+
+def canonical_order(value: dict[str, Any]) -> dict[str, Any]:
+    result = {"schema_version": value["schema_version"], "feature": value["feature"], "screens": []}
+    for screen in value["screens"]:
+        ordered_screen = {key: screen[key] for key in SCREEN_ORDER if key in screen}
+        ordered_screen["elements"] = []
+        for element in screen.get("elements", []):
+            ordered_element = {key: element[key] for key in ELEMENT_ORDER if key in element}
+            ordered_element = reorder(ordered_element, ELEMENT_ORDER)
+            ordered_screen["elements"].append(ordered_element)
+        ordered_screen["actions"] = [reorder(action, ACTION_ORDER) for action in screen.get("actions", [])]
+        ordered_screen["states"] = list(screen.get("states", []))
+        result["screens"].append(ordered_screen)
+    return result
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--proposal", required=True, type=Path)
+    parser.add_argument("--traceability", required=True, type=Path)
+    parser.add_argument("--schema", type=Path, default=DEFAULT_SCHEMA)
+    parser.add_argument("--questions", type=Path)
+    parser.add_argument("--questions-schema", type=Path, default=DEFAULT_QUESTIONS_SCHEMA)
+    parser.add_argument("--canonical-out", type=Path)
+    parser.add_argument("--business-canonical", type=Path)
+    args = parser.parse_args()
+    try:
+        proposal = load_yaml(args.proposal)
+        schema = load_yaml(args.schema)
+        questions_schema = load_yaml(args.questions_schema)
+        traceability = json.loads(args.traceability.read_text(encoding="utf-8"))
+        business_model = json.loads(args.business_canonical.read_text(encoding="utf-8")) if args.business_canonical else None
+    except Exception as error:
+        print(json.dumps({"valid": False, "errors": [{"code": "WIREFRAME_PARSE_ERROR", "path": "$", "message": str(error)}]}, ensure_ascii=False))
+        return 1
+    if not isinstance(schema, dict):
+        print(json.dumps({"valid": False, "errors": [{"code": "WIREFRAME_PARSE_ERROR", "path": "schema", "message": "schema root must be an object"}]}, ensure_ascii=False))
+        return 1
+    errors, canonical = validate(proposal, traceability, schema, business_model)
+    questions_path = args.questions
+    if questions_path is None and isinstance(proposal, dict) and proposal.get("feature"):
+        questions_path = Path(".planning") / "features" / str(proposal["feature"]) / "questions.yaml"
+    question_meta: dict[str, Any]
+    blocking_open: list[str] = []
+    if questions_path is None or not questions_path.exists():
+        question_meta = {"status": "unavailable", "unresolved": []}
+    else:
+        try:
+            questions = load_yaml(questions_path)
+            if not isinstance(questions_schema, dict):
+                raise ValueError("questions schema root must be an object")
+            question_errors, blocking_open, question_meta = validate_questions(questions, proposal.get("feature", "") if isinstance(proposal, dict) else "", questions_schema)
+            errors.extend(question_errors)
+        except Exception as error:
+            issue(errors, "WIREFRAME_QUESTION_SCHEMA_INVALID", str(questions_path), str(error))
+            question_meta = {"status": "invalid", "unresolved": []}
+    if errors or canonical is None:
+        print(json.dumps({"valid": False, "verdict": "block_unsafe", "questions": question_meta, "errors": errors}, ensure_ascii=False, indent=2))
+        return 1
+    if blocking_open:
+        print(json.dumps({"valid": False, "verdict": "await_user", "questions": question_meta, "errors": [{"code": "WIREFRAME_QUESTIONS_UNRESOLVED", "path": "questions", "message": "blocking questions remain open: " + ", ".join(blocking_open), "question_ids": blocking_open}]}, ensure_ascii=False, indent=2))
+        return 1
+    canonical = canonical_order(normalize(canonical))
+    encoded = json.dumps(canonical, ensure_ascii=False, separators=(",", ":"), sort_keys=False) + "\n"
+    fingerprint = "sha256:" + hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+    if args.canonical_out:
+        args.canonical_out.parent.mkdir(parents=True, exist_ok=True)
+        args.canonical_out.write_text(encoded, encoding="utf-8")
+    print(json.dumps({"valid": True, "verdict": "allow", "questions": question_meta, "canonical_fingerprint": fingerprint, "canonical": canonical}, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -4,6 +4,11 @@
 # Validates the existing workflow topology as a GateContract source.  This is
 # intentionally declarative and read-only: it does not advance STATE or alter
 # failure-branch behavior.
+require "json"
+require "optparse"
+require "yaml"
+require_relative "checker_registry"
+
 module WorkflowGateContract
   CHECKPOINT_FIELDS = %w[gate_after producing_step required_outputs required_meta_output required_meta_fields prompt confirm_options skip_policy resume_behavior].freeze
 
@@ -11,6 +16,11 @@ module WorkflowGateContract
 
   def validate(workflow)
     errors = []
+    unless workflow.is_a?(Hash)
+      return [error("WORKFLOW_SCHEMA_INVALID", "workflow must be a mapping")]
+    end
+    steps = Array(workflow["steps"])
+    step_by_id = steps.each_with_object({}) { |step, index| index[step["id"].to_s] = step if step.is_a?(Hash) && step["id"] }
     checkpoints = workflow["checkpoints"]
     unless checkpoints.is_a?(Hash)
       return [error("CHECKPOINTS_SCHEMA_INVALID", "workflow checkpoints must be a mapping")]
@@ -33,13 +43,79 @@ module WorkflowGateContract
       errors << error("CHECKPOINT_REF_NOT_FOUND", "enforced checkpoint is not defined", checkpoint: id) unless checkpoints.key?(id)
     end
 
+    step_checkers = workflow.dig("governance", "step_checkers")
+    if step_checkers.is_a?(Hash)
+      step_checkers.each do |step_id, checker_ids|
+        errors << error("CHECKER_STEP_REF_NOT_FOUND", "checker declaration references an unknown step", step: step_id) unless step_by_id.key?(step_id.to_s)
+        Array(checker_ids).each do |checker_id|
+          errors << error("UNKNOWN_CHECKER_ID", "workflow references an unknown checker", step: step_id, checker: checker_id) unless CheckerRegistry.known?(checker_id)
+        end
+      end
+    end
+
     Array(workflow["parallel_windows"]).each do |window|
-      errors << error("PARALLEL_WINDOW_SCHEMA_INVALID", "parallel window must define join_step and branches", window: window["id"]) unless window.is_a?(Hash) && window["join_step"] && window["branches"].is_a?(Hash)
-      next unless window.is_a?(Hash)
+      unless window.is_a?(Hash) && window["join_step"] && window["branches"].is_a?(Hash)
+        errors << error("PARALLEL_WINDOW_SCHEMA_INVALID", "parallel window must define join_step and branches", window: window.is_a?(Hash) && window["id"])
+        next
+      end
+      window_id = window["id"]
+      errors << error("PARALLEL_AFTER_STEP_NOT_FOUND", "parallel window after_step is not a workflow step", window: window_id, step: window["after_step"]) if window["after_step"] && !step_by_id.key?(window["after_step"].to_s)
+      errors << error("PARALLEL_JOIN_STEP_NOT_FOUND", "parallel join_step is not a workflow step", window: window_id, step: window["join_step"]) unless step_by_id.key?(window["join_step"].to_s)
       errors << error("PARALLEL_WINDOW_CHECKPOINT_INVALID", "parallel join checkpoint is not defined", window: window["id"], checkpoint: window["checkpoint"]) if window["checkpoint"] && !checkpoints.key?(window["checkpoint"])
+      policy = window["execution_policy"]
+      scheduler = policy.is_a?(Hash) && policy["scheduler"]
+      unless scheduler.is_a?(Hash)
+        errors << error("PARALLEL_SCHEDULER_SCHEMA_INVALID", "parallel window must define execution_policy.scheduler", window: window_id)
+      else
+        errors << error("PARALLEL_SCHEDULER_FIELD_INVALID", "one_agent_per_step must be boolean", window: window_id, field: "one_agent_per_step") unless [true, false].include?(scheduler["one_agent_per_step"])
+        errors << error("PARALLEL_SCHEDULER_FIELD_INVALID", "max_concurrency must be a positive integer", window: window_id, field: "max_concurrency") unless scheduler["max_concurrency"].is_a?(Integer) && scheduler["max_concurrency"] > 0
+        errors << error("PARALLEL_SCHEDULER_FIELD_INVALID", "track_order must be declared", window: window_id, field: "track_order") unless scheduler["track_order"] == "declared"
+      end
+      errors << error("PARALLEL_BRANCH_STEPS_INVALID", "branch_steps must be an array", window: window_id) if window.key?("branch_steps") && !window["branch_steps"].is_a?(Array)
+      Array(window["branch_steps"]).each do |step_id|
+        errors << error("PARALLEL_BRANCH_STEP_NOT_FOUND", "branch_steps references an unknown step", window: window_id, step: step_id) unless step_by_id.key?(step_id.to_s)
+      end
+      branch_ids = []
+      step_tracks = {}
+      window["branches"].each do |track, branch_steps|
+        unless branch_steps.is_a?(Array) && !branch_steps.empty?
+          errors << error("PARALLEL_TRACK_STEPS_INVALID", "parallel track must contain an ordered step array", window: window_id, track: track)
+          next
+        end
+        positions = branch_steps.each_with_index.to_h { |step_id, position| [step_id.to_s, position] }
+        branch_steps.each_with_index do |step_id, position|
+          if positions.count { |candidate, _| candidate == step_id.to_s } > 1
+            errors << error("PARALLEL_TRACK_DUPLICATE_STEP", "parallel track repeats a step", window: window_id, track: track, step: step_id)
+          end
+          branch_ids << step_id.to_s
+          step_tracks[step_id.to_s] = track.to_s
+          errors << error("PARALLEL_BRANCH_STEP_NOT_FOUND", "parallel track references an unknown step", window: window_id, track: track, step: step_id) unless step_by_id.key?(step_id.to_s)
+          Array(step_by_id.dig(step_id.to_s, "depends_on")).each do |dependency|
+            dependency_position = positions[dependency.to_s]
+            next unless dependency_position
+            errors << error("PARALLEL_TRACK_ORDER_INVALID", "track dependency must precede dependent step", window: window_id, track: track, step: step_id, dependency: dependency) if dependency_position >= position
+          end
+        end
+      end
+      window["branches"].each do |track, branch_steps|
+        Array(branch_steps).each do |step_id|
+          Array(step_by_id.dig(step_id.to_s, "depends_on")).each do |dependency|
+            dependency_track = step_tracks[dependency.to_s]
+            next unless dependency_track && dependency_track != track.to_s
+
+            errors << error("PARALLEL_CROSS_TRACK_DEPENDENCY", "parallel branch depends on a step in another track", window: window_id, track: track, step: step_id, dependency: dependency, dependency_track: dependency_track)
+          end
+        end
+      end
+      counts = branch_ids.each_with_object(Hash.new(0)) { |step_id, result| result[step_id] += 1 }
+      duplicate_steps = counts.select { |_, count| count > 1 }.keys
+      duplicate_steps.each { |step_id| errors << error("PARALLEL_STEP_DUPLICATED", "step appears in multiple parallel branches", window: window_id, step: step_id) }
+      errors << error("PARALLEL_JOIN_IN_BRANCH", "join_step cannot also be a branch step", window: window_id, step: window["join_step"]) if branch_ids.include?(window["join_step"].to_s)
     end
 
     (workflow["failure_branches"] || {}).each do |source_step, branch|
+      errors << error("FAILURE_SOURCE_STEP_NOT_FOUND", "failure branch source step is not defined", source_step: source_step) unless step_by_id.key?(source_step.to_s)
+      errors << error("FAILURE_BRANCH_SCHEMA_INVALID", "failure branch must be a mapping", source_step: source_step) unless branch.is_a?(Hash)
       resume = branch.is_a?(Hash) && branch["resume_after_success"]
       unless resume.is_a?(Hash) && %w[flow step status checkpoint].all? { |field| resume.key?(field) }
         errors << error("FAILURE_RETURN_TO_INVALID", "failure branch must declare flow, step, status and checkpoint", source_step: source_step)
@@ -54,3 +130,19 @@ module WorkflowGateContract
     { "code" => code, "message" => message }.merge(extra)
   end
 end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+  options = {}
+  OptionParser.new do |opts|
+    opts.on("--workflow PATH") { |value| options[:workflow] = value }
+    opts.on("--json") { options[:json] = true }
+  end.parse!
+  raise ArgumentError, "--workflow is required" unless options[:workflow]
+  result = WorkflowGateContract.validate(YAML.safe_load(File.read(options[:workflow]), permitted_classes: [], aliases: false))
+  puts(options[:json] ? JSON.generate(result) : YAML.dump(result))
+  rescue StandardError => e
+    warn e.message
+    exit 1
+  end
+end