@guanlin4924/devflow-pi 0.1.40 → 0.1.48

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/templates/feature-development.yaml

@@ -223,6 +223,30 @@ checkpoints:
       - approve
       - needs_fix
     skip_policy: never
+    resume_behavior: "user confirms, then continue with wireframe-proposal"
+  CP-WIREFRAME:
+    name: Low-fidelity wireframe confirmation
+    gate_after: wireframe-review
+    producing_step: wireframe-review
+    required_outputs:
+      - ".planning/features/{feature}/canonical.json"
+      - ".planning/features/{feature}/canonical.meta.json"
+      - ".planning/features/{feature}/wireframes/preview.md"
+      - ".planning/features/{feature}/wireframes/flow.svg"
+    required_meta_output: ".planning/features/{feature}/canonical.meta.json"
+    required_meta_fields:
+      - prototype_fingerprint
+      - source_document_fingerprint
+      - state_revision
+    summary_fields:
+      - prototype_fingerprint
+      - source_document_fingerprint
+      - state_revision
+    prompt: "确认页面、元素、动作和平台范围；阻塞问题必须已回答，并允许进入 API 契约设计。"
+    confirm_options:
+      - approve
+      - needs_fix
+    skip_policy: never
     resume_behavior: "user confirms, then continue with api-contract"
   CP-API:
     name: API contract confirmation
@@ -487,6 +511,84 @@ steps:
         traceability_status: { type: string, required: true }
     checkpoint: CP-1
 
+  - id: wireframe-proposal
+    order: 11
+    label: Wireframe proposal
+    skill: wireframe-proposal
+    engine_evidence_gate: enforced
+    depends_on:
+      - requirement-baseline
+    inputs:
+      - ".planning/requirements/baseline.md"
+      - ".planning/requirements/{feature}/traceability.json"
+      - ".planning/features/{feature}/questions.yaml"
+    outputs:
+      - path: ".planning/features/{feature}/proposal.yaml"
+        type: wireframe-proposal
+        required: true
+      - path: ".planning/features/{feature}/questions.yaml"
+        type: wireframe-questions
+        required: false
+
+  - id: wireframe-validate
+    order: 12
+    label: Validate wireframe proposal
+    skill: wireframe-validate
+    engine_evidence_gate: enforced
+    depends_on:
+      - wireframe-proposal
+    inputs:
+      - ".planning/features/{feature}/proposal.yaml"
+      - ".planning/features/{feature}/questions.yaml"
+      - ".planning/requirements/{feature}/traceability.json"
+    outputs:
+      - path: ".planning/features/{feature}/canonical.json"
+        type: wireframe-canonical
+        required: true
+    meta_output:
+      path: ".planning/features/{feature}/wireframe-validation.meta.json"
+      fields:
+        verdict: { type: string, required: true }
+        canonical_fingerprint: { type: string, required: false }
+        unresolved_question_count: { type: integer, required: true }
+
+  - id: wireframe-render
+    order: 13
+    label: Render wireframe previews
+    skill: wireframe-render
+    engine_evidence_gate: enforced
+    depends_on:
+      - wireframe-validate
+    inputs:
+      - ".planning/features/{feature}/canonical.json"
+      - ".planning/features/{feature}/canonical.meta.json"
+    outputs:
+      - path: ".planning/features/{feature}/wireframes/preview.md"
+        type: wireframe-preview
+        required: true
+      - path: ".planning/features/{feature}/wireframes/flow.svg"
+        type: wireframe-flow
+        required: true
+
+  - id: wireframe-review
+    order: 14
+    label: Wireframe review
+    skill: wireframe-review
+    engine_evidence_gate: enforced
+    depends_on:
+      - wireframe-render
+    inputs:
+      - ".planning/features/{feature}/canonical.json"
+      - ".planning/features/{feature}/canonical.meta.json"
+      - ".planning/features/{feature}/questions.yaml"
+      - ".planning/features/{feature}/wireframes/preview.md"
+      - ".planning/features/{feature}/wireframes/flow.svg"
+    outputs:
+      - path: ".planning/features/{feature}/approval.json"
+        type: wireframe-approval
+        required: false
+    checkpoint: CP-WIREFRAME
+
   - id: api-contract
     order: 15
     label: API contract
@@ -878,7 +980,7 @@ steps:
     skill: workflow-generate-mainflow-cases
     engine_evidence_gate: enforced
     depends_on:
-      - code-index-refresh
+      - execute
     inputs:
       - ".planning/STATE.md"
       - ".planning/navigation/INDEX.md"
@@ -892,6 +994,9 @@ steps:
       - ".planning/features/{feature}/PROGRESS.md"
       - ".planning/requirements/{feature}/tests.json"
     outputs:
+      - path: ".planning/generated-cases/{feature}/codebase-discovery.json"
+        type: mainflow-codebase-discovery
+        required: true
       - path: ".planning/generated-cases/{feature}/source-map.md"
         type: mainflow-source-map
         required: true

package/plugins/devflow-implementation/agents/implementation-worker.md

@@ -18,6 +18,12 @@ autoloadSkills:
 
 Implement only the assigned plan slice. Do not re-plan the feature, compare alternatives, or explore unrelated modules. Read only the approved files, their immediate dependencies, and the focused tests needed for this slice. Preserve unrelated work and report deviations instead of silently expanding scope.
 
+Before any protected source access, read the project's required code-index evidence
+files in the exact order listed by INDEX_GATE (typically `.planning/code-index/INDEX.md`
+followed by the ordered files named by the gate). Do not attempt `grep`, `rg`, or source
+reads first: each subagent has its own evidence session and cannot inherit the parent's
+observations. If the gate lists different files, follow that list exactly.
+
 If the execution contract is missing, ambiguous, or contradicted by the code, stop before editing and return `STATUS: escalate` with the conflicting evidence. Run the smallest focused validation once; report failures rather than repeatedly trying speculative fixes.
 
 For a task whose frozen `test-bindings.json` marks `test_mode: tdd_required`, use the Core tool in this exact order: `devflow_tdd_evidence(action="prepare")` before changing declared production paths; create/change the test and record `red`; implement; record `green`; then record `regression`. Do not mark the task done if any phase is missing or fails. The tool may write only its own Core-owned TDD evidence record; this exception does not authorize edits to any other Devflow control-plane file.