@guanlin4924/devflow-pi 0.1.93 → 0.1.95

package/plugins/devflow-quality/skills/workflow-generate-mainflow-cases/scripts/validate_case_payloads.py

@@ -1,11 +1,23 @@
 #!/usr/bin/env python3
-"""Validate normalized mainflow case import payloads."""
-
+"""Validate generated devflow-test-dsl/v1 cases as pure data.
+
+The normal input is the whole ``.devflow/planning/generated-cases/<feature>``
+directory: every ``TC-xxxx.json`` in it is validated (the file name must match
+the DSL ``tc_id``), other files such as ``case-descriptions.json`` are not DSL
+and are ignored, and automated ``ui``/``api_flow`` TCs without a DSL file are
+reported as warnings.  A single DSL file or a ``{"cases": [...]}`` payload is
+accepted too.
+
+Validation never imports or executes code from the project under test: the
+Schema, semantic rules, structural coverage and tc_sha256 come from Devflow
+Core (dsl_v1, dsl_coverage, tc_hash).  ``--discovery`` is accepted only for
+backwards-compatible invocations and is ignored.
+"""
 from __future__ import annotations
 
 import argparse
-import importlib
 import json
+import os
 import re
 import sys
 from datetime import datetime, timezone
@@ -13,47 +25,29 @@ from pathlib import Path
 from typing import Any
 
 
-MAINFLOW_TAGS = {"api-mainflow", "ui-mainflow"}
-ALLOWED_DRIVERS = {"api", "web", "ui"}
-VALID_TARGET_KEYS = {"css", "xpath", "label", "placeholder", "role", "name", "near_text", "exact"}
-# 精确匹配器：严格对应DOM结构，必须来自 source code 证据，不能凭空编造
-EXACT_LOCATOR_KEYS = {"css", "xpath", "role"}
-# 语义匹配器：通过用户可见文本/属性定位，更抗DOM变化但需检查唯一性
-SEMANTIC_LOCATOR_KEYS = {"label", "placeholder", "near_text"}
-# 表格行常见操作文本 — 用 label 定位时几乎一定不唯一
-HIGH_RISK_LABELS = {
-    "编辑", "删除", "查看", "详情", "启用", "禁用", "停用", "启用",
-    "新增", "添加", "修改", "复制", "移动", "导出", "导入", "下载",
-    "上传", "设置", "配置", "操作", "更多", "取消", "确定", "保存",
-    "提交", "重置", "刷新", "搜索", "查询", "筛选", "排序",
-}
-# CSS 选择器最小长度 — 太短的选择器通常是编造的，缺乏 scope
-MIN_CSS_LENGTH = 10
-# 验证类 action — 应使用 ai_only
-VERIFICATION_ACTIONS = {"assert_visible", "assert_text", "assert_url_contains", "assert_any_visible"}
-VALID_ASSERTION_TYPES = {
-    "equals", "json_path_equals", "status_code", "not_equals", "contains",
-    "not_contains", "greater_than", "less_than", "json_path_exists",
-    "regex", "is_empty", "is_not_empty", "in", "not_in",
-}
-API_ACTIONS = {"get", "post", "put", "patch", "delete", "head", "options"}
-WEB_UI_ACTIONS = {
-    "goto",
-    "navigate",
-    "click",
-    "fill",
-    "input",
-    "select",
-    "hover",
-    "wait",
-    "assert_visible",
-    "assert_text",
-    "assert_url_contains",
-    "assert_any_visible",
-    "evaluate_js",
-    "screenshot",
-    "act",
-}
+def _core_scripts() -> Path:
+    candidates = [Path(__file__).resolve().parents[4] / "devflow-core" / "skills" / "workflow-orchestrator" / "scripts"]
+    configured = os.environ.get("DEVFLOW_KIT_ROOT")
+    if configured:
+        candidates.append(Path(configured).expanduser() / "workflow-orchestrator" / "scripts")
+    for candidate in candidates:
+        if (candidate / "dsl_v1.py").is_file():
+            return candidate.resolve()
+    raise RuntimeError("Devflow Core scripts (dsl_v1.py) not found")
+
+
+sys.path.insert(0, str(_core_scripts()))
+from dsl_coverage import check as coverage_check  # noqa: E402
+from dsl_v1 import validate as validate_dsl  # noqa: E402
+from execution_surface import derive as derive_surface  # noqa: E402
+from tc_hash import tc_sha256  # noqa: E402
+
+DSL_FILE_RE = re.compile(r"^(TC-[0-9]{4,})\.json$")
+# Inputs/support files that live next to the DSL files but are not DSL.
+NON_DSL_FILES = frozenset({"case-descriptions.json", "codebase-discovery.json"})
+GENERATABLE_SURFACES = frozenset({"ui", "api_flow"})
+
+
 SECRET_KEY_RE = re.compile(r"(token|password|passwd|secret|api[_-]?key|authorization|cookie)", re.I)
 SECRET_VALUE_RE = re.compile(
     r"(sk-[A-Za-z0-9_\-]{16,}|ghp_[A-Za-z0-9_]{16,}|xox[baprs]-[A-Za-z0-9\-]{16,}|"
@@ -62,33 +56,6 @@ SECRET_VALUE_RE = re.compile(
 PLACEHOLDER_RE = re.compile(r"^(\$\{[A-Za-z_][A-Za-z0-9_]*\}|<[^>]+>|REPLACE_ME|dummy|example|your-.+)$", re.I)
 
 
-def load_payload(path: Path) -> dict[str, Any]:
-    raw = json.loads(path.read_text(encoding="utf-8"))
-    if isinstance(raw, list):
-        return {"metadata": {}, "cases": raw}
-    if isinstance(raw, dict) and isinstance(raw.get("cases"), list):
-        return raw
-    raise ValueError("payload must be a JSON object with cases[] or a JSON array")
-
-
-def backend_root_from_discovery(path: Path) -> Path:
-    data = json.loads(path.read_text(encoding="utf-8"))
-    for codebase in data.get("codebases", []):
-        if codebase.get("domain") == "backend" or "后端" in str(codebase.get("type", "")):
-            root = Path(str(codebase.get("root", "")))
-            if root.exists():
-                return root
-    raise ValueError("no existing backend codebase root found in discovery")
-
-
-def load_project_validators(discovery_path: Path):
-    backend_root = backend_root_from_discovery(discovery_path)
-    sys.path.insert(0, str(backend_root.resolve()))
-    case_module = importlib.import_module("app.schemas.case")
-    dsl_module = importlib.import_module("app.services.dsl_parser")
-    return case_module.CaseCreate, dsl_module.validate_dsl
-
-
 def is_placeholder(value: str) -> bool:
     return bool(PLACEHOLDER_RE.match(value.strip())) or "${" in value
 
@@ -104,266 +71,189 @@ def walk_values(value: Any, path: str = "$") -> list[tuple[str, Any]]:
     return found
 
 
-def detect_secrets(case: dict[str, Any]) -> list[str]:
+VARIABLE_SECRET_REF_RE = re.compile(r"^\$\.variables\.[^.\[]+\.secret$")
+VARIABLE_LITERAL_RE = re.compile(r"^\$\.variables\.([^.\[]+)\.value$")
+
+
+def detect_secrets(case: Any) -> list[str]:
     errors: list[str] = []
     for path, value in walk_values(case):
         if isinstance(value, str) and SECRET_VALUE_RE.search(value) and not is_placeholder(value):
             errors.append(f"{path} contains a token-like literal")
+        if VARIABLE_SECRET_REF_RE.match(path):
+            continue  # {"secret": "ENV_KEY"} names an environment key; the value is not a credential
+        literal = VARIABLE_LITERAL_RE.match(path)
+        if literal and SECRET_KEY_RE.search(literal.group(1)) and isinstance(value, str) and value.strip() and not is_placeholder(value):
+            errors.append(f"{path} holds a literal for secret-looking variable '{literal.group(1)}'; declare it as {{\"secret\": \"ENV_KEY\"}}")
+            continue
         key = path.rsplit(".", 1)[-1].lower()
         if SECRET_KEY_RE.search(key) and isinstance(value, str) and value.strip() and not is_placeholder(value):
             errors.append(f"{path} contains a secret-looking literal")
     return errors
 
 
-def validate_case_payload_shape(case: dict[str, Any], CaseCreate: Any) -> list[str]:
-    errors: list[str] = []
-    try:
-        if hasattr(CaseCreate, "model_validate"):
-            CaseCreate.model_validate(case)
-        else:
-            CaseCreate(**case)
-    except Exception as exc:  # noqa: BLE001
-        errors.append(f"CaseCreate validation failed: {exc}")
-    return errors
-
+class LoadError:
+    """A directory entry that could not be parsed; reported as a failed case."""
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+
+
+def load_cases(path: Path) -> tuple[list[tuple[str, Any]], list[str]]:
+    """The generated-cases directory, a single DSL file, or {"cases": [...]} / [...].
+
+    Returns (named documents, warnings).  In directory mode only ``TC-xxxx.json``
+    files are DSL; a stray ``case-import-payloads.json`` (legacy TestAgent
+    export) or any other JSON file is never validated as DSL.
+    """
+    if path.is_dir():
+        cases: list[tuple[str, Any]] = []
+        warnings: list[str] = []
+        for item in sorted(path.iterdir()):
+            if not item.is_file() or item.suffix != ".json" or item.name.startswith("."):
+                continue
+            if DSL_FILE_RE.fullmatch(item.name):
+                try:
+                    cases.append((item.name, json.loads(item.read_text(encoding="utf-8"))))
+                except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
+                    cases.append((item.name, LoadError(f"{item.name} is not valid JSON: {error}")))
+            elif item.name not in NON_DSL_FILES:
+                warnings.append(f"ignored {item.name}: only TC-xxxx.json files are Runtime DSL"
+                                + (" (case-import-payloads.json is a legacy TestAgent export, never a Runtime DSL artifact)"
+                                   if item.name == "case-import-payloads.json" else ""))
+        return cases, warnings
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    if isinstance(raw, dict) and isinstance(raw.get("cases"), list):
+        raw = raw["cases"]
+    if isinstance(raw, list):
+        return [(f"cases[{index}]", item) for index, item in enumerate(raw)], []
+    if isinstance(raw, dict):
+        return [(path.name, raw)], []
+    raise ValueError("input must be a generated-cases directory, a DSL object, an array of DSL objects, or {\"cases\": [...]}")
 
-def validate_dsl_static(dsl: dict[str, Any], tags: list[str]) -> list[str]:
-    errors: list[str] = []
-    if not dsl.get("name"):
-        errors.append("dsl_json.name is required")
-    steps = dsl.get("steps")
-    if not isinstance(steps, list) or not steps:
-        errors.append("dsl_json.steps must be a non-empty list")
-        return errors
 
-    step_ids: set[str] = set()
-    for index, step in enumerate(steps):
-        path = f"dsl_json.steps[{index}]"
-        if not isinstance(step, dict):
-            errors.append(f"{path} must be an object")
+def missing_dsl_warnings(suite_nodes: list[Any], present: set[str]) -> list[str]:
+    """Automated ui/api_flow TCs without a DSL file: advisory, the gate blocks them as dsl_not_approved."""
+    warnings: list[str] = []
+    for node in suite_nodes:
+        if not (isinstance(node, dict) and node.get("kind") == "test_case" and isinstance(node.get("id"), str) and isinstance(node.get("data"), dict)):
             continue
-        step_id = step.get("id")
-        if not step_id:
-            errors.append(f"{path}.id is required")
-        elif step_id in step_ids:
-            errors.append(f"{path}.id duplicates '{step_id}'")
-        else:
-            step_ids.add(step_id)
-
-        driver = step.get("driver")
-        action = str(step.get("action") or "").lower()
-        if driver not in ALLOWED_DRIVERS:
-            errors.append(f"{path}.driver must be one of {sorted(ALLOWED_DRIVERS)}")
-        if not action:
-            errors.append(f"{path}.action is required")
-        elif driver == "api" and action not in API_ACTIONS:
-            errors.append(f"{path}.action is not a valid API method")
-        elif driver in {"web", "ui"} and action not in WEB_UI_ACTIONS:
-            errors.append(f"{path}.action is not a valid UI/Web action")
-
-        params = step.get("params") or {}
-        if driver == "api" and not params.get("url"):
-            errors.append(f"{path}.params.url is required for API steps")
-        if driver == "ui":
-            strategy = step.get("strategy") or {}
-            target = step.get("target") or {}
-            strategy_mode = strategy.get("mode", "")
-            if strategy_mode != "ai_only" and not any(target.values()):
-                errors.append(f"{path}.target is required for non-ai_only UI steps")
-            unknown_keys = set(target.keys()) - VALID_TARGET_KEYS
-            if unknown_keys:
-                errors.append(
-                    f"{path}.target contains invalid keys {sorted(unknown_keys)}. "
-                    f"Valid keys: {sorted(VALID_TARGET_KEYS)}"
-                )
-
-            # --- Locator quality rules ---
-
-            # Rule 1: 精确匹配器 (css/xpath/role) 必须来自 source evidence，检查选择器质量
-            for exact_key in EXACT_LOCATOR_KEYS & set(target.keys()):
-                value = str(target.get(exact_key, "")).strip()
-                if not value:
-                    continue
-                if exact_key == "css":
-                    if len(value) < MIN_CSS_LENGTH:
-                        errors.append(
-                            f"{path}.target.css='{value}' is too generic ({len(value)} chars, min {MIN_CSS_LENGTH}). "
-                            f"CSS selectors are exact matchers and must be scoped. "
-                            f"Add context: dialog footer, table row, form item, etc."
-                        )
-                    # CSS 选择器不应是裸的 tag/class 名（无组合器、无伪类）
-                    if " " not in value and "." not in value and "#" not in value:
-                        errors.append(
-                            f"{path}.target.css='{value}' looks like a bare identifier. "
-                            f"Use a scoped selector like '.el-dialog__footer .el-button--primary'."
-                        )
-                if exact_key == "role":
-                    if "name" not in target or not str(target.get("name", "")).strip():
-                        errors.append(
-                            f"{path}.target has 'role' but missing 'name'. "
-                            f"role+name is a paired exact matcher; role alone is not scoped enough."
-                        )
-
-            # Rule 2: 语义匹配器 — label 用于高风险文本时检查唯一性
-            label_value = str(target.get("label", "")).strip()
-            if label_value and label_value in HIGH_RISK_LABELS:
-                has_scope = bool(target.get("css") or target.get("near_text") or target.get("xpath"))
-                if not has_scope:
-                    errors.append(
-                        f"{path}.target.label='{label_value}' is a high-risk label "
-                        f"(common table-row action, likely appears on multiple rows). "
-                        f"Add scope with 'css' for row-specific selector, or use 'near_text' to bind to a row identifier."
-                    )
-
-            # Rule 3: 验证步骤必须用 ai_only
-            if action in VERIFICATION_ACTIONS and strategy_mode != "ai_only":
-                errors.append(
-                    f"{path}.action='{action}' is a verification step but strategy.mode='{strategy_mode}'. "
-                    f"Verification steps must use strategy.mode='ai_only'. "
-                    f"Visual verification of transient UI (toast, dialogs) is inherently an AI task."
-                )
-            # act + prompt 也是验证，同样要求 ai_only
-            if action == "act" and step.get("prompt") and strategy_mode != "ai_only":
-                errors.append(
-                    f"{path}.action='act' with prompt indicates an AI-driven step but strategy.mode='{strategy_mode}'. "
-                    f"Use strategy.mode='ai_only' for AI-driven verification/action steps."
-                )
-
-        if driver == "api":
-            for ai, assertion in enumerate(step.get("assertions") or []):
-                atype = str(assertion.get("type") or "")
-                if atype and atype not in VALID_ASSERTION_TYPES:
-                    errors.append(
-                        f"{path}.assertions[{ai}].type '{atype}' is not a valid assertion type. "
-                        f"Valid types: {sorted(VALID_ASSERTION_TYPES)}"
-                    )
-
-        # Web/UI steps: catch assertions that look like confused actions
-        if driver in {"web", "ui"}:
-            for ai, assertion in enumerate(step.get("assertions") or []):
-                atype = str(assertion.get("type") or "").lower()
-                if atype in {"text", "visible", "url_contains", "any_visible"}:
-                    errors.append(
-                        f"{path}.assertions[{ai}].type '{atype}' is not a valid assertion type. "
-                        f"For web/ui steps, use action='assert_{atype}' instead of assertions[]."
-                    )
-
-    for index, step in enumerate(steps):
-        for dep in step.get("depends_on") or []:
-            if dep not in step_ids:
-                errors.append(f"dsl_json.steps[{index}].depends_on references missing step '{dep}'")
-
-    case_tags = set(tags)
-    dsl_tags = set(dsl.get("tags") or [])
-    if not case_tags:
-        errors.append("tags must include api-mainflow or ui-mainflow")
-    elif not case_tags.issubset(MAINFLOW_TAGS):
-        errors.append(f"tags contain non-mainflow values: {tags}")
-    if not dsl_tags:
-        errors.append("dsl_json.tags must include api-mainflow or ui-mainflow")
-    elif not dsl_tags.issubset(MAINFLOW_TAGS):
-        errors.append(f"dsl_json.tags contain non-mainflow values: {dsl.get('tags')}")
+        data = node["data"]
+        if node.get("status") != "confirmed" or data.get("automation_mode") != "automated":
+            continue
+        surface, _legacy = derive_surface(data)
+        if surface in GENERATABLE_SURFACES and node["id"] not in present:
+            warnings.append(f"automated {surface} TC {node['id']} has no DSL file; it will be blocked (dsl_not_approved) until one is compiled and approved, or the TC is downgraded")
+    return warnings
 
-    return errors
+
+def load_suite_nodes(path: Path) -> list[Any]:
+    suite = json.loads(path.read_text(encoding="utf-8"))
+    nodes = suite.get("nodes") if isinstance(suite, dict) else None
+    if not isinstance(nodes, list):
+        raise ValueError("TC suite must contain nodes[]")
+    return nodes
+
+
+def suite_cases(nodes: list[Any]) -> dict[str, dict[str, Any]]:
+    return {node["id"]: node["data"] for node in nodes
+            if isinstance(node, dict) and node.get("kind") == "test_case" and isinstance(node.get("id"), str) and isinstance(node.get("data"), dict)}
 
 
-def validate_project_dsl(dsl: dict[str, Any], validate_dsl: Any) -> list[str]:
-    result = validate_dsl(dsl)
-    if getattr(result, "valid", False):
-        return []
-    return [f"project dsl_parser: {error}" for error in getattr(result, "errors", [])]
+def validate_case(dsl: Any, suite: dict[str, dict[str, Any]], file_name: str | None = None) -> list[str]:
+    if isinstance(dsl, LoadError):
+        return [dsl.message]
+    errors = validate_dsl(dsl)
+    errors.extend(detect_secrets(dsl))
+    if errors or not isinstance(dsl, dict):
+        return errors
+    match = DSL_FILE_RE.fullmatch(file_name or "")
+    if match and match.group(1) != dsl["tc_id"]:
+        errors.append(f"file {file_name} contains tc_id {dsl['tc_id']}; the file must be named <tc_id>.json")
+    tc = suite.get(dsl["tc_id"])
+    if tc is None:
+        return [f"tc_id {dsl['tc_id']} is not in the frozen TC suite"]
+    if dsl["tc_sha256"] != tc_sha256(tc):
+        errors.append("tc_sha256 does not match the frozen TC data (JCS SHA-256)")
+    errors.extend(coverage_check(tc, dsl))
+    return errors
 
 
 def render_report(results: list[dict[str, Any]], warnings: list[str], payload_path: Path) -> str:
     total_errors = sum(len(item["errors"]) for item in results)
     status = "passed" if total_errors == 0 else "failed"
     lines = [
-        "# Mainflow Case Validation Report",
-        "",
+        "# Mainflow Case Validation Report", "",
         f"- Payload: `{payload_path}`",
         f"- Generated at: {datetime.now(timezone.utc).isoformat()}",
         f"- Status: **{status}**",
         f"- Cases: {len(results)}",
         f"- Errors: {total_errors}",
-        f"- Warnings: {len(warnings)}",
-        "",
-        "## Case Results",
-        "",
-        "| Case | Tags | Status | Errors |",
+        f"- Warnings: {len(warnings)}", "",
+        "## Case Results", "",
+        "| Case | TC | Status | Errors |",
         "|---|---|---:|---:|",
     ]
     for item in results:
-        case_status = "passed" if not item["errors"] else "failed"
-        lines.append(f"| {item['name']} | {', '.join(item['tags'])} | {case_status} | {len(item['errors'])} |")
-
+        lines.append(f"| {item['name']} | {item['tc_id']} | {'passed' if not item['errors'] else 'failed'} | {len(item['errors'])} |")
     if warnings:
         lines.extend(["", "## Warnings", ""])
         lines.extend(f"- {warning}" for warning in warnings)
-
     failed = [item for item in results if item["errors"]]
     if failed:
         lines.extend(["", "## Errors", ""])
         for item in failed:
             lines.append(f"### {item['name']}")
-            for error in item["errors"]:
-                lines.append(f"- {error}")
+            lines.extend(f"- {error}" for error in item["errors"])
             lines.append("")
-
     return "\n".join(lines).rstrip() + "\n"
 
 
 def main() -> int:
-    parser = argparse.ArgumentParser()
-    parser.add_argument("input", help="case-import-payloads.json")
-    parser.add_argument("--discovery", required=True, help="codebase-discovery.json")
-    parser.add_argument("--output", required=True, help="validation-report.md")
+    parser = argparse.ArgumentParser(allow_abbrev=False)
+    parser.add_argument("input", help=".devflow/planning/generated-cases/<feature> directory (all TC-xxxx.json), a DSL v1 file, or {\"cases\": [...]}")
+    parser.add_argument("--suite", required=True, help="frozen TC suite (.devflow/planning/requirements/<feature>/tests.json)")
+    parser.add_argument("--output", required=True, help="validation report path (validation-report.md)")
+    parser.add_argument("--discovery", help="deprecated and ignored: validation never loads project code")
     args = parser.parse_args()
 
     payload_path = Path(args.input)
-    discovery_path = Path(args.discovery)
     output_path = Path(args.output)
     warnings: list[str] = []
-    results: list[dict[str, Any]] = []
-
+    if args.discovery:
+        warnings.append("--discovery is ignored: DSL validation is pure data and never imports project code.")
     try:
-        payload = load_payload(payload_path)
-        if payload.get("cases"):
-            CaseCreate, project_validate_dsl = load_project_validators(discovery_path)
-        else:
-            CaseCreate = project_validate_dsl = None
-    except Exception as exc:  # noqa: BLE001
+        cases, load_warnings = load_cases(payload_path)
+        suite_nodes = load_suite_nodes(Path(args.suite))
+        suite = suite_cases(suite_nodes)
+    except (OSError, ValueError, KeyError) as exc:
         output_path.parent.mkdir(parents=True, exist_ok=True)
-        output_path.write_text(
-            "# Mainflow Case Validation Report\n\n"
-            f"- Payload: `{payload_path}`\n"
-            "- Status: **failed**\n\n"
-            "## Errors\n\n"
-            f"- Validation bootstrap failed: {exc}\n",
-            encoding="utf-8",
-        )
+        output_path.write_text(f"# Mainflow Case Validation Report\n\n- Payload: `{payload_path}`\n- Status: **failed**\n\n## Errors\n\n- Validation bootstrap failed: {exc}\n", encoding="utf-8")
         print(f"ERROR: {exc}", file=sys.stderr)
         return 2
-
-    if not payload.get("cases"):
+    warnings.extend(load_warnings)
+    if payload_path.is_dir():
+        warnings.extend(missing_dsl_warnings(suite_nodes, {dsl["tc_id"] for _, dsl in cases if isinstance(dsl, dict) and isinstance(dsl.get("tc_id"), str)}))
+    if not cases:
         warnings.append("No cases were generated.")
 
-    for index, case in enumerate(payload.get("cases") or [], start=1):
-        name = str(case.get("name") or f"case-{index}")
-        tags = list(case.get("tags") or [])
-        dsl = case.get("dsl_json") or {}
-        errors: list[str] = []
-        errors.extend(validate_case_payload_shape(case, CaseCreate))
-        errors.extend(validate_dsl_static(dsl, tags))
-        errors.extend(detect_secrets(case))
-        errors.extend(validate_project_dsl(dsl, project_validate_dsl))
-        results.append({"name": name, "tags": tags, "errors": errors})
-
-    report = render_report(results, warnings, payload_path)
+    results: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for name, dsl in cases:
+        errors = validate_case(dsl, suite, name if payload_path.is_dir() else None)
+        tc_id = dsl.get("tc_id") if isinstance(dsl, dict) else None
+        if isinstance(tc_id, str):
+            if tc_id in seen:
+                errors.append(f"duplicate DSL for {tc_id}: each TC must have exactly one DSL file")
+            seen.add(tc_id)
+        results.append({"name": name, "tc_id": tc_id or "?", "errors": errors})
+
     output_path.parent.mkdir(parents=True, exist_ok=True)
-    output_path.write_text(report, encoding="utf-8")
+    output_path.write_text(render_report(results, warnings, payload_path), encoding="utf-8")
     total_errors = sum(len(item["errors"]) for item in results)
-    print(json.dumps({"status": "passed" if total_errors == 0 else "failed", "errors": total_errors}, ensure_ascii=False))
-    return 0 if total_errors == 0 else 1
+    status = "passed" if total_errors == 0 else "failed"
+    print(json.dumps({"status": status, "cases": len(results), "errors": total_errors}, ensure_ascii=False))
+    return 0 if status == "passed" else 1
 
 
 if __name__ == "__main__":

package/plugins/devflow-quality/skills/workflow-human-acceptance/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: workflow-human-acceptance
+description: "Use after code review to execute frozen manual TC cases, capture human evidence, submit them as human_result approvals for the user to confirm, and synchronize findings to developers for final acceptance aggregation."
+---
+
+# 人工验收与开发者同步
+
+本步骤在 `code-review` 完成后运行。它只执行冻结套件中 `automation_mode: manual` 的 `TC-*`，并将实际结果、问题和复测要求同步给开发者。不得修改 TC 的步骤、oracle 或范围。自动化 `ui|api_flow` TC 的 DSL 生成与 `execution_plan` 批准属于 `run-acceptance-tests` 的绑定阶段（`workflow-generate-mainflow-cases`），不在本步骤内。
+
+## 输入
+
+1. `.devflow/planning/requirements/{feature}/tests.json` 中已冻结且未 stale 的 TC。
+2. `.devflow/planning/phases/{phase}/REVIEW.md` 的代码审查结论。
+3. `.devflow/planning/features/{feature}/验收测试设计.md` 的环境、账号和数据要求。
+
+## 过程
+
+1. 确认 `code-review` 已完成，测试套件已由 CP-3 冻结。
+2. 只筛选 `automation_mode: manual` 的 TC；`automated` 由后续 Core runner 执行，`blocked` 保持阻塞。
+3. 人工按冻结步骤执行，逐条收集实际结果和项目内证据文件；Agent 不得代填 `passed|failed|blocked` 结论。
+4. 本步骤不生成自动化用例，也不改变自动化 TC 的模式；需要降级为 `manual` 的自动化 TC 必须先有有效的 `mode_override` approval，随后才按人工 TC 处理。
+5. 对每个 manual TC 调用 `devflow_approval(action="propose", feature="...", kind="human_result", items=[{"subject":"TC-xxxx","evidence_files":[...]}])`。Agent 只能提交证据，不得提交 status、actual_result 或 pins。
+6. 用户在 `/devflow` → “待审批”中逐 TC 查看 oracle、步骤和证据，自行选择 `passed|failed|blocked` 并填写实际结果；只有该 UI 确认产生的 `human_result` approval 才是最终人工结果。
+7. 写入开发者交接，包含已批准、失败/阻塞、尚待确认 TC、首个偏差、证据、复现步骤、责任人和复测条件。
+
+当冻结套件不含 manual TC 时，不创建 `human_result` proposal，并在开发者交接中说明“无人工 TC”。`human_result` 只在 database authority 模式下受支持；兼容（文件）模式下会返回 `approval_requires_database_authority`，manual TC 保持 blocked，不得改用草稿文件放行。
+
+## 人工结果草稿
+
+如需在确认前暂存观察，可写 `.devflow/planning/test-runs/{feature}/human-acceptance-results.json`，但它只是可丢弃草稿，不能被 runner 当作 verdict：
+
+```json
+{
+  "schema_version": 1,
+  "origin": "devflow_human_acceptance",
+  "feature": "<feature>",
+  "test_suite": { "graph_revision": 1, "fingerprint": "..." },
+  "results": [
+    {
+      "tc_id": "TC-0001",
+      "tester": "<name>",
+      "executed_at": "<ISO-8601>",
+      "actual_result": "<observed result>",
+      "evidence_files": ["artifacts/acceptance/TC-0001.png"]
+    }
+  ]
+}
+```
+
+草稿不得作为版本通过证据。每个 manual TC 的最终 verdict 和 actual_result 只从 control.db 中仍有效的 `human_result` approval 读取；`passed` 必须固定至少一个项目内证据文件及其哈希。
+
+## 开发者交接
+
+写入 `.devflow/planning/test-runs/{feature}/developer-handoff.md`，至少包含：
+
+- 人工 TC 通过、失败、阻塞数量。
+- 问题与证据路径。
+- 开发者修复和复测要求。
+- 待用户在 `/devflow` → “待审批”确认的 `human_result` 与 `execution_plan` proposal 列表（如有）。
+
+本 Skill 不调用 `devflow_transition`；人工验收产物展示给用户后，由 Runtime 执行确认和状态迁移。