@guanlin4924/devflow-pi 0.1.94 → 0.1.96

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

@@ -0,0 +1,647 @@
+#!/usr/bin/env python3
+"""LEGACY: export case descriptions as TestAgent import payloads (project_id + dsl_json).
+
+This exporter is NOT part of the Devflow acceptance gate.  Its output uses the
+old TestAgent DSL (structured_first + Midscene fallback, ai_only verification,
+xpath/near_text targets) and can never be bound to ``devflow_playwright``,
+approved as an execution plan, or counted as an acceptance result.  The gate
+uses ``compile_dsl.py`` (devflow-test-dsl/v1, one file per frozen TC).
+
+Run it only when a developer explicitly asks for a TestAgent import file:
+
+    python3 export_legacy_testagent.py legacy-case-descriptions.json \
+        --output .devflow/planning/generated-cases/<feature>/legacy-testagent-import.json
+
+The input is the legacy simplified format (``text:`` / ``placeholder:`` /
+``near:`` locators, ``verify`` steps, optional ``auth``), not the v1
+``case-descriptions.json`` consumed by ``compile_dsl.py``.
+"""Compile AI-friendly case descriptions into strict DSL JSON.
+
+AI 产出简化的用例描述（locator 用 "type:value" 字符串格式），
+本脚本负责编译成符合系统 DslTarget 严格格式的 DSL JSON。
+这是硬约束层 —— 所有 target key、strategy、assertion 由脚本决定，AI 无法编造。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from copy import deepcopy
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# 硬约束常量 — 唯一权威定义
+# ---------------------------------------------------------------------------
+
+VALID_TARGET_KEYS = {"css", "xpath", "label", "placeholder", "role", "name", "near_text", "exact"}
+EXACT_LOCATOR_KEYS = {"css", "xpath", "role"}  # 精确匹配，必须有 source evidence
+SEMANTIC_LOCATOR_KEYS = {"label", "placeholder", "near_text"}  # 语义匹配，需检查唯一性
+
+# 高风险 label — 表格行常见操作文本，用 label 定位时几乎一定不唯一
+HIGH_RISK_LABELS = {
+    "编辑", "删除", "查看", "详情", "启用", "禁用", "停用",
+    "新增", "添加", "修改", "复制", "移动", "导出", "导入", "下载",
+    "上传", "设置", "配置", "操作", "更多", "取消", "确定", "保存",
+    "提交", "重置", "刷新", "搜索", "查询", "筛选", "排序",
+}
+
+MIN_CSS_LENGTH = 10
+
+DEFAULT_UI_STRATEGY = {"mode": "structured_first", "fallback": "midscene"}
+AI_ONLY_STRATEGY = {"mode": "ai_only"}
+
+# ---------------------------------------------------------------------------
+# Locator 字符串解析器
+# ---------------------------------------------------------------------------
+
+LOCATOR_RE = re.compile(
+    r"^(?P<type>text|placeholder|css|xpath|role|near)"
+    r":(?P<value>.+)$"
+)
+ROLE_LOCATOR_RE = re.compile(r"^role:(?P<role>[^:]+):(?P<name>.+)$")
+SCOPE_RE = re.compile(r"^row:(?P<row>\d+)$")
+
+
+def parse_locator(raw: str) -> dict[str, str]:
+    """Parse 'type:value' string into flat target dict.
+
+    Returns {'label': '...'} for text:, {'placeholder': '...'} for placeholder:, etc.
+    Raises ValueError on unrecognized format.
+    """
+    raw = raw.strip()
+
+    # role:button:确定
+    m = ROLE_LOCATOR_RE.match(raw)
+    if m:
+        return {"role": m.group("role"), "name": m.group("name")}
+
+    m = LOCATOR_RE.match(raw)
+    if not m:
+        raise ValueError(
+            f"Invalid locator format: '{raw}'. "
+            f"Expected: text:<text> | placeholder:<text> | css:<selector> | "
+            f"xpath:<expr> | role:<role>:<name> | near:<text>"
+        )
+
+    loc_type = m.group("type")
+    value = m.group("value").strip()
+
+    if not value:
+        raise ValueError(f"Locator '{raw}' has empty value.")
+
+    if loc_type == "text":
+        return {"label": value}
+    if loc_type == "placeholder":
+        return {"placeholder": value}
+    if loc_type == "css":
+        return {"css": value}
+    if loc_type == "xpath":
+        return {"xpath": value}
+    if loc_type == "near":
+        return {"near_text": value}
+
+    raise ValueError(f"Unknown locator type: {loc_type}")
+
+
+# ---------------------------------------------------------------------------
+# CSS 编造检测 — 零容忍
+# ---------------------------------------------------------------------------
+
+# 明显是 AI 编造的 CSS class 特征
+HALLUCINATED_CSS_PATTERNS: list[tuple[str, str]] = [
+    # 包含 % 的伪 Tailwind class（w-100%, h-50% 等）
+    (r"\b[a-z]+-\d+%", "contains invented utility class with % (e.g. w-100%)"),
+    # 裸的百分比值
+    (r"%", "contains '%' — not valid in CSS selector without escaping"),
+    # 纯表单容器通用类，不指定具体字段
+    (r"^\.el-form-item(__content)?$", "matches all form items, not a specific field"),
+    # 明显编造的随机 class 名模式
+    (r"\b[a-z]{1,3}-\d{3,}\b", "looks like a made-up class (random letters+numbers)"),
+]
+
+# fill/select 动作在非 placeholder 情况下，CSS 禁止匹配纯容器类
+GENERIC_FORM_CLASSES = [
+    ".el-form-item",
+    ".el-form-item__content",
+    ".el-form-item__label",
+    ".ant-form-item",
+    ".ant-form-item-control",
+    ".form-item",
+    ".form-group",
+]
+
+
+def _validate_css_not_hallucinated(css_value: str, step_name: str) -> None:
+    """Reject CSS selectors that show signs of AI hallucination. Hard gate."""
+    errors: list[str] = []
+
+    # Check against hallucination patterns
+    for pattern, description in HALLUCINATED_CSS_PATTERNS:
+        if re.search(pattern, css_value):
+            errors.append(
+                f"CSS selector '{css_value}' rejected: {description}. "
+                f"Step: {step_name}"
+            )
+
+    # Check if CSS is purely generic form classes (no specific target)
+    stripped = css_value.strip()
+    parts = [p.strip() for p in stripped.split() if p.strip()]
+    if parts and all(
+        any(p == g or p.startswith(g) for g in GENERIC_FORM_CLASSES)
+        for p in parts
+    ):
+        errors.append(
+            f"CSS selector '{css_value}' only matches generic form containers, "
+            f"not a specific field. Use 'near:<label文本>' instead. "
+            f"Step: {step_name}"
+        )
+
+    # Too short = probably made up
+    if len(css_value) < MIN_CSS_LENGTH:
+        errors.append(
+            f"CSS selector '{css_value}' is too generic ({len(css_value)} chars, min {MIN_CSS_LENGTH}). "
+            f"Step: {step_name}"
+        )
+
+    if errors:
+        raise ValueError("CSS HALLUCINATION DETECTED:\n" + "\n".join(f"  - {e}" for e in errors))
+
+
+# ---------------------------------------------------------------------------
+# Fill 动作 locator 硬决策链
+# ---------------------------------------------------------------------------
+
+FILL_ALLOWED_LOCATORS = {"placeholder", "near"}  # fill 只能用这两个
+
+
+def _validate_fill_locator(step_name: str, locator_raw: str) -> None:
+    """Hard decision chain for fill actions: placeholder → near → ai_only. CSS/xpath forbidden."""
+    if not locator_raw:
+        raise ValueError(
+            f"Fill step '{step_name}' has no locator. "
+            f"Use 'placeholder:<text>', 'near:<label文本>', or change action to 'act' with ai_only."
+        )
+
+    loc_type = locator_raw.split(":", 1)[0].strip()
+    if loc_type not in FILL_ALLOWED_LOCATORS:
+        raise ValueError(
+            f"Fill step '{step_name}' uses locator type '{loc_type}', which is forbidden for fill actions. "
+            f"Fill hard chain: placeholder → near → ai_only. "
+            f"Got '{locator_raw}'. "
+            f"Use 'placeholder:<text>' if the field has a placeholder, "
+            f"'near:<label文本>' if there's a label next to the field, "
+            f"or change action to 'act' with ai_only strategy."
+        )
+
+
+# ---------------------------------------------------------------------------
+# Target 编译 — 硬约束规则
+# ---------------------------------------------------------------------------
+
+def compile_target(
+    locator_raw: str,
+    scope: str | None = None,
+    step_name: str = "",
+) -> dict[str, Any]:
+    """Compile a locator string + scope into a valid DslTarget dict.
+
+    Rules (in priority order):
+    1. text:<unique_button> + page scope → label + exact
+    2. text:<common_action> + row:N scope → label + css row selector
+    3. text:<text> + dialog scope → label (dialog内默认唯一)
+    4. placeholder:<text> → placeholder
+    5. css:<selector> → css (validated for specificity)
+    6. role:<role>:<name> → role + name
+    7. near:<text> → near_text
+    8. xpath:<expr> → xpath (last resort)
+    """
+    target = parse_locator(locator_raw)
+    errors: list[str] = []
+
+    # text: → label
+    if "label" in target:
+        label_value = target["label"]
+
+        # Determine scope
+        if scope:
+            scope_match = SCOPE_RE.match(scope)
+            if scope_match:
+                # row scope: label + css row selector
+                row_n = int(scope_match.group("row"))
+                target["css"] = (
+                    f".el-table__body tr:nth-child({row_n}) "
+                    f"td:last-child .el-button--small"
+                )
+            elif scope == "dialog":
+                # dialog scope: label within dialog, no extra css needed
+                pass
+            # other scopes just use label as-is
+
+        # exact match for page-unique items
+        if label_value not in HIGH_RISK_LABELS:
+            target["exact"] = True
+
+        # High-risk label without row scope → warn but don't block
+        if label_value in HIGH_RISK_LABELS and not (scope and SCOPE_RE.match(scope)):
+            # Still produce valid target, but record warning
+            pass
+
+    # css: → hard hallucination check
+    if "css" in target:
+        css_value = target["css"]
+        _validate_css_not_hallucinated(css_value, step_name)
+
+    # role: → ensure name is present (already handled by parse_locator)
+
+    if errors:
+        raise ValueError("\n".join(errors))
+
+    return target
+
+
+# ---------------------------------------------------------------------------
+# Strategy 决策 — 硬约束
+# ---------------------------------------------------------------------------
+
+VERIFICATION_ACTIONS = {"verify", "assert_text", "assert_visible", "assert_url_contains", "assert_any_visible"}
+
+
+def compile_strategy(action: str) -> dict[str, Any]:
+    """Decide strategy based on action type. Hard rule: verification → ai_only."""
+    if action in VERIFICATION_ACTIONS:
+        return deepcopy(AI_ONLY_STRATEGY)
+    if action == "act":
+        return deepcopy(AI_ONLY_STRATEGY)
+    return deepcopy(DEFAULT_UI_STRATEGY)
+
+
+# ---------------------------------------------------------------------------
+# Step 编译
+# ---------------------------------------------------------------------------
+
+def compile_step(step: dict[str, Any], index: int) -> dict[str, Any]:
+    """Compile one simplified step into strict DSL step."""
+    name = str(step.get("name") or f"Step {index}")
+    action = str(step.get("action") or "").lower().strip()
+
+    compiled: dict[str, Any] = {
+        "id": f"s{index:02d}",
+        "name": name,
+        "depends_on": [],
+        "timeout_ms": int(step.get("timeout_ms", 30_000)),
+        "on_failure": step.get("on_failure", "stop"),
+    }
+
+    # --- Navigate → web/goto ---
+    if action == "navigate":
+        compiled["driver"] = "web"
+        compiled["action"] = "goto"
+        compiled["params"] = {"url": step.get("url", "")}
+        return compiled
+
+    # --- Wait ---
+    if action == "wait":
+        compiled["driver"] = "web"
+        compiled["action"] = "wait"
+        compiled["params"] = {"wait_for": step.get("wait_for", "load")}
+        compiled["timeout_ms"] = int(step.get("timeout_ms", 15_000))
+        return compiled
+
+    # --- Inject token ---
+    if action == "inject_token":
+        compiled["driver"] = "web"
+        compiled["action"] = "evaluate_js"
+        compiled["params"] = {"script": step.get("script", "")}
+        return compiled
+
+    # --- API step ---
+    if action in {"get", "post", "put", "patch", "delete"}:
+        compiled["driver"] = "api"
+        compiled["action"] = action
+        compiled["params"] = deepcopy(step.get("params", {}))
+        compiled["assertions"] = _compile_api_assertions(step.get("assertions", []))
+        compiled["extract_vars"] = deepcopy(step.get("extract_vars", {}))
+        return compiled
+
+    # --- UI action steps ---
+    if action in {"click", "fill", "select", "hover"}:
+        compiled["driver"] = "ui"
+        compiled["action"] = action
+        locator_raw = step.get("locator", "")
+        if locator_raw:
+            compiled["target"] = compile_target(
+                locator_raw,
+                scope=step.get("scope"),
+                step_name=name,
+            )
+        compiled["strategy"] = compile_strategy(action)
+        if action == "fill":
+            compiled["params"] = {"value": step.get("value", "")}
+            _validate_fill_locator(name, locator_raw)
+        return compiled
+
+    # --- UI verification step ---
+    if action == "verify":
+        compiled["driver"] = "ui"
+        compiled["action"] = "act"
+        locator_raw = step.get("locator", "")
+        if locator_raw:
+            compiled["target"] = compile_target(locator_raw, scope=step.get("scope"), step_name=name)
+        compiled["strategy"] = deepcopy(AI_ONLY_STRATEGY)
+        expect = step.get("expect", "")
+        compiled["prompt"] = _build_verify_prompt(name, expect, step)
+        compiled["timeout_ms"] = int(step.get("timeout_ms", 15_000))
+        return compiled
+
+    # --- AI act step (with prompt) ---
+    if action == "act":
+        compiled["driver"] = "ui"
+        compiled["action"] = "act"
+        locator_raw = step.get("locator", "")
+        if locator_raw:
+            compiled["target"] = compile_target(locator_raw, scope=step.get("scope"), step_name=name)
+        compiled["strategy"] = deepcopy(AI_ONLY_STRATEGY)
+        compiled["prompt"] = step.get("prompt", "")
+        compiled["timeout_ms"] = int(step.get("timeout_ms", 15_000))
+        return compiled
+
+    # Fallback
+    raise ValueError(f"Unknown action '{action}' in step '{name}'")
+
+
+def _compile_api_assertions(raw_assertions: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Compile simplified API assertions into strict format."""
+    compiled: list[dict[str, Any]] = []
+    for a in raw_assertions:
+        atype = str(a.get("type", "status_code"))
+        compiled.append({
+            "type": atype,
+            "expected": a.get("expected"),
+            "path": a.get("path"),
+        })
+    return compiled
+
+
+def _build_verify_prompt(step_name: str, expect: str, step: dict[str, Any]) -> str:
+    """Build AI prompt for verification step."""
+    if step.get("prompt"):
+        return step["prompt"]
+    if expect.startswith("text:"):
+        text = expect[5:]
+        return f"检查页面是否出现'{text}'的提示消息，确认操作已成功完成"
+    if expect == "dialog_visible":
+        return "检查对话框是否已打开并显示"
+    if expect == "dialog_closed":
+        return "检查对话框是否已关闭"
+    return f"验证：{expect}"
+
+
+# ---------------------------------------------------------------------------
+# Auth setup 编译
+# ---------------------------------------------------------------------------
+
+def compile_auth_steps(auth: dict[str, Any] | None, base_url: str = "${base_url}") -> list[dict[str, Any]]:
+    """Compile auth config into API login + web inject steps."""
+    if not auth:
+        return []
+
+    method = str(auth.get("method", "")).lower()
+    steps: list[dict[str, Any]] = []
+
+    if method == "api_login":
+        login_url = auth.get("login_url", f"{base_url}/auth/login_by_id")
+        login_body = auth.get("login_body", {})
+        token_path = auth.get("token_path", "headers.X-Jwt-Token")
+        app_id = auth.get("app_id")
+
+        steps.append({
+            "id": "api_auth_login",
+            "name": "获取JWT令牌",
+            "driver": "api",
+            "action": "post",
+            "params": {"url": login_url, "json": login_body},
+            "assertions": [
+                {"type": "status_code", "expected": 200},
+                {"type": "json_path_exists", "path": token_path},
+            ],
+            "extract_vars": {"jwt_token": {"path": token_path, "source": "jsonpath"}},
+            "depends_on": [],
+            "timeout_ms": 15_000,
+            "on_failure": "stop",
+        })
+
+        if app_id:
+            steps.append({
+                "id": "api_app_token",
+                "name": "获取应用访问Token",
+                "driver": "api",
+                "action": "post",
+                "params": {
+                    "url": auth.get("app_token_url", f"{base_url}/admin/app/access"),
+                    "json": {"id": app_id},
+                    "headers": {"Authorization": "Bearer ${jwt_token}"},
+                },
+                "assertions": [{"type": "status_code", "expected": 200}],
+                "extract_vars": {"token_url": {"path": "body.data.url", "source": "jsonpath"}},
+                "depends_on": ["api_auth_login"],
+                "timeout_ms": 15_000,
+                "on_failure": "stop",
+            })
+
+            steps.append({
+                "id": "web_auth_inject",
+                "name": "Token注入",
+                "driver": "web",
+                "action": "goto",
+                "params": {"url": "${token_url}"},
+                "depends_on": ["api_app_token"],
+                "timeout_ms": 30_000,
+                "on_failure": "stop",
+            })
+
+    return steps
+
+
+# ---------------------------------------------------------------------------
+# Main compile entry
+# ---------------------------------------------------------------------------
+
+def _check_terminology(steps: list[dict[str, Any]]) -> list[str]:
+    """Check for terminology hallucination in step names vs locator values."""
+    # Commonly hallucinated term pairs: (AI-invented, source-code-actual)
+    TERM_PAIRS: list[tuple[str, str]] = [
+        ("搜索", "查询"),
+        ("搜索", "筛选"),
+        ("新增", "添加"),
+        ("编辑", "修改"),
+        ("删除", "移除"),
+        ("保存", "提交"),
+        ("关闭", "取消"),
+    ]
+    warnings: list[str] = []
+    for step in steps:
+        name = str(step.get("name", ""))
+        locator_raw = str(step.get("_locator_raw", ""))
+        for ai_term, src_term in TERM_PAIRS:
+            if ai_term in name and src_term in locator_raw:
+                warnings.append(
+                    f"Step '{name}' uses '{ai_term}' but locator contains '{src_term}'. "
+                    f"Verify the button text in source code — use the exact source text."
+                )
+    return warnings
+
+
+def compile_case(case_desc: dict[str, Any]) -> dict[str, Any]:
+    """Compile one simplified case description into strict DSL."""
+    name = str(case_desc.get("name") or "Unnamed Case")
+    tags = list(case_desc.get("tags") or ["ui-mainflow"])
+    variables = dict(case_desc.get("variables") or {})
+    base_url = variables.get("base_url", "${base_url}")
+
+    # Compile auth
+    auth_steps = compile_auth_steps(case_desc.get("auth"), base_url)
+
+    # Compile business steps
+    raw_steps = list(case_desc.get("steps") or [])
+    business_steps: list[dict[str, Any]] = []
+    for i, raw_step in enumerate(raw_steps):
+        compiled_step = compile_step(raw_step, i + 1)
+        # Preserve original locator string for terminology checking
+        compiled_step["_locator_raw"] = raw_step.get("locator", "")
+        business_steps.append(compiled_step)
+
+    # Terminology check (warning, not error)
+    term_warnings = _check_terminology(business_steps)
+    if term_warnings:
+        for w in term_warnings:
+            print(f"TERMINOLOGY WARNING: {w}", file=__import__("sys").stderr)
+
+    # Merge: auth steps first, then business steps
+    all_steps = auth_steps + business_steps
+
+    # Wire dependencies: auth steps are already wired; business steps depend on previous
+    first_business_idx = len(auth_steps)
+    for i, step in enumerate(all_steps):
+        if i >= first_business_idx and i > 0:
+            prev_id = all_steps[i - 1]["id"]
+            if not step.get("depends_on"):
+                step["depends_on"] = [prev_id]
+
+    dsl = {
+        "name": name,
+        "description": case_desc.get("description", ""),
+        "tags": tags,
+        "variables": variables,
+        "steps": all_steps,
+    }
+
+    return {
+        "project_id": int(case_desc.get("project_id", 1)),
+        "name": name,
+        "description": case_desc.get("description", ""),
+        "tags": tags,
+        "dsl_json": dsl,
+    }
+
+
+def compile_all(payload: dict[str, Any], frozen_mainflow_tc_ids: set[str] | None = None) -> dict[str, Any]:
+    """Compile all cases in the payload."""
+    metadata = dict(payload.get("metadata") or {})
+    descriptions = list(payload.get("cases", []))
+    tc_ids: list[str] = []
+    if frozen_mainflow_tc_ids is not None:
+        for index, description in enumerate(descriptions):
+            tc_id = description.get("tc_id") if isinstance(description, dict) else None
+            if not isinstance(tc_id, str) or tc_id not in frozen_mainflow_tc_ids:
+                raise ValueError(f"cases[{index}].tc_id must reference a frozen api/page TC that is positive")
+            tc_ids.append(tc_id)
+        if len(tc_ids) != len(set(tc_ids)):
+            raise ValueError("each frozen positive api/page TC may generate at most one mainflow case")
+    cases = [compile_case(c) for c in descriptions]
+
+    return {
+        "metadata": {
+            **metadata,
+            **({"frozen_tc_ids": tc_ids} if frozen_mainflow_tc_ids is not None else {}),
+            "compiled_at": datetime.now(timezone.utc).isoformat(),
+            "compiled_by": "export_legacy_testagent.py (legacy, not an acceptance gate)",
+            "legacy_export": True,
+        },
+        "cases": cases,
+    }
+
+
+def frozen_mainflow_tc_ids_from_cwd(cwd: Path) -> set[str] | None:
+    """Return the frozen API/page suite for new workflows, else preserve legacy compilation."""
+    state_path = cwd / ".devflow/planning" / "STATE.md"
+    if not state_path.is_file():
+        return None
+    match = re.search(r"^current_feature:\s*['\"]?([^'\"\n]+)", state_path.read_text(encoding="utf-8"), re.MULTILINE)
+    if not match:
+        return None
+    suite_path = cwd / ".devflow/planning" / "requirements" / match.group(1).strip() / "tests.json"
+    if not suite_path.is_file():
+        return None
+    suite = json.loads(suite_path.read_text(encoding="utf-8"))
+    if suite.get("frozen") is not True:
+        raise ValueError("current TC suite exists but is not frozen and fresh")
+    eligible = {
+        node.get("id")
+        for node in suite.get("nodes", [])
+        if isinstance(node, dict)
+        and node.get("kind") == "test_case"
+        and node.get("status") == "confirmed"
+        and isinstance(node.get("data"), dict)
+        and node["data"].get("test_type") in {"api", "page"}
+        # A generated API TC with an error-code oracle is a negative/exception
+        # test. It belongs to run-acceptance-tests, never to the positive
+        # mainflow importer even though its broad test_type is "api".
+        and not (
+            isinstance(node["data"].get("generated_case_key"), str)
+            and isinstance(node["data"].get("execution"), dict)
+            and isinstance(node["data"]["execution"].get("expect"), dict)
+            and "error_code" in node["data"]["execution"]["expect"]
+        )
+    }
+    return {value for value in eligible if isinstance(value, str)}
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        allow_abbrev=False,
+        description="LEGACY (not a gate): export case descriptions as TestAgent import payloads."
+    )
+    parser.add_argument("input", help="Legacy simplified case descriptions JSON")
+    parser.add_argument("--output", required=True, help="Output path for the legacy TestAgent import payload")
+    args = parser.parse_args()
+
+    input_path = Path(args.input)
+    output_path = Path(args.output)
+
+    raw = json.loads(input_path.read_text(encoding="utf-8"))
+
+    # Accept both array and {cases: [...]} format
+    if isinstance(raw, list):
+        raw = {"metadata": {}, "cases": raw}
+
+    try:
+        result = compile_all(raw, frozen_mainflow_tc_ids_from_cwd(Path.cwd()))
+    except ValueError as exc:
+        print(f"COMPILE ERROR: {exc}", file=__import__("sys").stderr)
+        return 1
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps({"output": str(output_path), "case_count": len(result["cases"])}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -1,5 +1,12 @@
 #!/usr/bin/env python3
-"""Normalize draft mainflow case payloads into import payloads."""
+"""LEGACY: normalize draft TestAgent case payloads into a TestAgent import payload.
+
+Not part of the Devflow acceptance gate and not used by the workflow.  The
+output (``dsl_json`` with structured_first/Midscene strategies) is the legacy
+TestAgent import format: it can never be bound to ``devflow_playwright``,
+approved as an execution plan, or counted as an acceptance result.  The gate
+DSL is produced by ``compile_dsl.py`` (devflow-test-dsl/v1).
+"""
 
 from __future__ import annotations
 
@@ -140,9 +147,9 @@ def normalize_case(case: dict[str, Any], metadata: dict[str, Any]) -> tuple[dict
 
 
 def main() -> int:
-    parser = argparse.ArgumentParser()
+    parser = argparse.ArgumentParser(allow_abbrev=False)
     parser.add_argument("input", help="legacy raw case payload JSON")
-    parser.add_argument("--output", required=True, help="case-import-payloads.json")
+    parser.add_argument("--output", required=True, help="legacy TestAgent import payload path")
     args = parser.parse_args()
 
     draft_path = Path(args.input)