@guanlin4924/devflow-pi 0.1.93 → 0.1.95

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

@@ -1,627 +1,568 @@
 #!/usr/bin/env python3
-"""Compile AI-friendly case descriptions into strict DSL JSON.
-
-AI 产出简化的用例描述（locator 用 "type:value" 字符串格式），
-本脚本负责编译成符合系统 DslTarget 严格格式的 DSL JSON。
-这是硬约束层 —— 所有 target key、strategy、assertion 由脚本决定，AI 无法编造。
+"""Compile AI-friendly case descriptions into devflow-test-dsl/v1 files.
+
+Input:  ``.devflow/planning/generated-cases/<feature>/case-descriptions.json``
+        (format: ``references/intermediate-format.md``).
+Output: one DSL file per frozen TC at
+        ``.devflow/planning/generated-cases/<feature>/TC-xxxx.json``.
+
+This script is the hard-constraint layer between AI judgement and the gate:
+
+- every case must reference a frozen, confirmed, ``automated`` TC whose
+  ``execution_surface`` is ``ui`` or ``api_flow`` (legacy page TCs derive to
+  ``ui`` through the single Core implementation ``execution_surface.derive``);
+- ``tc_sha256`` is always computed here with Core ``tc_hash`` (never copied
+  from the AI input);
+- locators are compiled to v1 targets, ``testid`` first; ``xpath``, ``near``,
+  ``ai_only``, Midscene, prompts, scripts and token injection are rejected;
+- every generated document is validated with Core ``dsl_v1`` (Schema +
+  semantics) and ``dsl_coverage`` (``covers`` structural coverage) and nothing
+  is written unless every case passes.
+
+Output bytes are deterministic (no timestamps), so re-compiling an unchanged
+description keeps ``dsl_sha256`` and therefore an existing execution_plan
+approval valid.  The legacy TestAgent import payload lives in
+``export_legacy_testagent.py`` and is not part of the gate.
 """
-
 from __future__ import annotations
 
 import argparse
 import json
+import os
 import re
-from copy import deepcopy
-from datetime import datetime, timezone
+import sys
 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 = {
-    "编辑", "删除", "查看", "详情", "启用", "禁用", "停用",
-    "新增", "添加", "修改", "复制", "移动", "导出", "导入", "下载",
-    "上传", "设置", "配置", "操作", "更多", "取消", "确定", "保存",
-    "提交", "重置", "刷新", "搜索", "查询", "筛选", "排序",
+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 SCHEMA_VERSION, validate as validate_dsl  # noqa: E402
+from execution_surface import derive as derive_surface  # noqa: E402
+from tc_hash import tc_sha256  # noqa: E402
+
+
+FEATURE_RE = re.compile(r"^[^/\\\x00-\x1f\x7f]+$")
+TC_ID_RE = re.compile(r"^TC-[0-9]{4,}$")
+GENERATABLE_SURFACES = frozenset({"ui", "api_flow"})
+
+UI_ACTIONS = frozenset({"goto", "click", "fill", "select", "check", "uncheck", "wait_for",
+                        "assert_visible", "assert_text", "assert_url", "screenshot"})
+TARGET_ACTIONS = UI_ACTIONS - {"goto", "assert_url", "screenshot"}
+HTTP_METHODS = ("GET", "POST", "PUT", "PATCH", "DELETE")
+API_SHORTHAND = {method.lower(): method for method in HTTP_METHODS}
+
+COMMON_KEYS = {"id", "name", "action", "covers", "timeout_ms"}
+UI_KEYS = {
+    "goto": {"url"},
+    "click": {"locator", "exact"},
+    "fill": {"locator", "exact", "value"},
+    "select": {"locator", "exact", "value"},
+    "check": {"locator", "exact"},
+    "uncheck": {"locator", "exact"},
+    "wait_for": {"locator", "exact", "state"},
+    "assert_visible": {"locator", "exact"},
+    "assert_text": {"locator", "exact", "expected", "match", "normalize_whitespace", "case_sensitive"},
+    "assert_url": {"expected", "match"},
+    "screenshot": {"full_page"},
 }
+API_KEYS = {"method", "url", "headers", "query", "json", "expect_status", "assertions", "extract", "retry", "idempotent"}
+CASE_KEYS = {"tc_id", "name", "description", "variables", "data", "steps", "source_evidence", "tags"}
+DATA_KEYS = {"namespace", "owner", "accounts", "repeatable", "setup", "cleanup"}
+
+# Keys and values of the retired TestAgent/Midscene format.  They are rejected
+# with a pointed message instead of being silently dropped.
+FORBIDDEN_KEYS = {
+    "strategy": "strategies (structured_first/ai_only/Midscene) do not exist in devflow-test-dsl/v1",
+    "prompt": "AI prompts are not executable in the gate; write a deterministic assert_* step",
+    "scope": "row/dialog scopes are not supported; use a data-testid or another unique locator",
+    "auth": "auth shortcuts are not supported; write explicit data.setup API steps or UI login steps",
+    "script": "scripts are not allowed in the DSL",
+    "params": "legacy params{} is not supported; put url/json/query/headers directly on the step",
+    "extract_vars": "use extract: {name: \"/json/pointer\"}",
+    "depends_on": "steps run in order; depends_on is not supported",
+    "on_failure": "a failed step always stops the case",
+    "driver": "the compiler derives driver from action",
+    "target": "write locator: \"testid:...\" (the compiler builds the target)",
+}
+FORBIDDEN_ACTIONS = {
+    "verify": "use assert_text / assert_visible / assert_url with a deterministic expectation",
+    "act": "ai_only actions are not allowed; use a deterministic UI action",
+    "navigate": "use goto",
+    "wait": "fixed or load waits are not allowed; use wait_for with a locator and state",
+    "inject_token": "token injection scripts are not allowed; log in via UI or data.setup API steps",
+    "evaluate_js": "JavaScript is not allowed in the DSL",
+    "hover": "hover is not in devflow-test-dsl/v1",
+    "assert_url_contains": "use assert_url with match: \"contains\"",
+    "assert_any_visible": "use assert_visible on one unique target",
+}
+FORBIDDEN_TEXT_RE = re.compile(r"\b(ai_only|midscene)\b", re.I)
 
+LOCATOR_TYPES = ("testid", "role", "label", "placeholder", "text", "css")
+REJECTED_LOCATOR_TYPES = {
+    "xpath": "XPath is not supported in devflow-test-dsl/v1; use testid/role/label/placeholder/text/css",
+    "near": "near_text is not supported; ask for a data-testid or use label/placeholder",
+}
+# Row-repeated action texts: with a non-testid locator these almost always
+# match several elements, which fails under strict mode.
+HIGH_RISK_TEXTS = {
+    "编辑", "删除", "查看", "详情", "启用", "禁用", "停用", "新增", "添加", "修改", "复制", "移动", "导出", "导入", "下载",
+    "上传", "设置", "配置", "操作", "更多", "取消", "确定", "保存", "提交", "重置", "刷新", "搜索", "查询", "筛选", "排序",
+}
 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"%", "contains '%' (invented utility class such as w-100%)"),
+    (r"^\.el-form-item(__content)?$", "matches every form item, not a specific field"),
     (r"\b[a-z]{1,3}-\d{3,}\b", "looks like a made-up class (random letters+numbers)"),
+    (r"^(tr|td|li|div|span|button)?:nth-(child|of-type)\(", "position-only selector is not stable"),
 ]
+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")
 
-# 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))
+class CompileError(ValueError):
+    pass
 
 
 # ---------------------------------------------------------------------------
-# Fill 动作 locator 硬决策链
+# Suite
 # ---------------------------------------------------------------------------
 
-FILL_ALLOWED_LOCATORS = {"placeholder", "near"}  # fill 只能用这两个
-
+def current_feature(root: Path) -> str | None:
+    state = root / ".devflow/planning" / "STATE.md"
+    if not state.is_file():
+        return None
+    match = re.search(r"^current_feature:\s*['\"]?([^'\"\n]+)", state.read_text(encoding="utf-8"), re.MULTILINE)
+    return match.group(1).strip() if match else None
 
-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."
-        )
+def load_suite(path: Path) -> dict[str, Any]:
+    try:
+        suite = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as error:
+        raise CompileError(f"frozen TC suite not found: {path}") from error
+    except json.JSONDecodeError as error:
+        raise CompileError(f"frozen TC suite is not valid JSON: {error}") from error
+    if not isinstance(suite, dict) or not isinstance(suite.get("nodes"), list):
+        raise CompileError("TC suite must be an object with nodes[]")
+    if suite.get("frozen") is not True:
+        raise CompileError("TC suite is not frozen: DSL can only be generated for a CP-3 frozen suite")
+    return suite
+
+
+def eligible_cases(suite: dict[str, Any]) -> tuple[dict[str, dict[str, Any]], dict[str, str]]:
+    """Return ({tc_id: data} generatable, {tc_id: reason} for known but ineligible TCs)."""
+    eligible: dict[str, dict[str, Any]] = {}
+    rejected: dict[str, str] = {}
+    for node in suite["nodes"]:
+        if not isinstance(node, dict) or node.get("kind") != "test_case" or not isinstance(node.get("id"), str):
+            continue
+        tc_id, data = node["id"], node.get("data")
+        if not isinstance(data, dict):
+            rejected[tc_id] = "has no data"
+        elif node.get("status") != "confirmed":
+            rejected[tc_id] = f"status is {node.get('status')!r}, not confirmed"
+        elif data.get("automation_mode") != "automated":
+            rejected[tc_id] = f"automation_mode is {data.get('automation_mode')!r}; only automated TCs get a DSL"
+        else:
+            surface, legacy = derive_surface(data)
+            if surface not in GENERATABLE_SURFACES:
+                suffix = " (legacy_unclassified)" if legacy else ""
+                rejected[tc_id] = f"execution_surface is {surface!r}{suffix}; DSL is only generated for ui/api_flow"
+            else:
+                eligible[tc_id] = data
+    return eligible, rejected
 
 
 # ---------------------------------------------------------------------------
-# Target 编译 — 硬约束规则
+# Locators
 # ---------------------------------------------------------------------------
 
-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))
-
+def _css_errors(css: str) -> list[str]:
+    errors = [f"css '{css}' rejected: {reason}" for pattern, reason in HALLUCINATED_CSS_PATTERNS if re.search(pattern, css)]
+    parts = [part for part in css.split() if part]
+    if parts and all(any(part.startswith(generic) for generic in GENERIC_FORM_CLASSES) for part in parts):
+        errors.append(f"css '{css}' only matches generic form containers, not a specific field")
+    if len(css) < MIN_CSS_LENGTH:
+        errors.append(f"css '{css}' is too generic ({len(css)} chars, min {MIN_CSS_LENGTH})")
+    return errors
+
+
+def compile_target(raw: Any, exact: Any, label: str, warnings: list[str]) -> dict[str, Any]:
+    """'type:value' → one v1 target.  testid first; role/label/placeholder/text default to exact."""
+    if not isinstance(raw, str) or ":" not in raw:
+        raise CompileError(f"{label}.locator must be 'testid:<id>' | 'role:<role>:<name>' | 'label:<text>' | "
+                           "'placeholder:<text>' | 'text:<text>' | 'css:<selector>'")
+    kind, _, value = raw.strip().partition(":")
+    kind = kind.strip().lower()
+    if kind in REJECTED_LOCATOR_TYPES:
+        raise CompileError(f"{label}.locator: {REJECTED_LOCATOR_TYPES[kind]}")
+    if kind not in LOCATOR_TYPES:
+        raise CompileError(f"{label}.locator type '{kind}' is unknown; use one of {', '.join(LOCATOR_TYPES)}")
+    if exact is not None and not isinstance(exact, bool):
+        raise CompileError(f"{label}.exact must be a boolean")
+    if kind == "testid":
+        if exact is not None:
+            raise CompileError(f"{label}.exact does not apply to testid locators")
+        if not value.strip():
+            raise CompileError(f"{label}.locator has an empty value")
+        return {"testid": value.strip()}
+    if kind == "css":
+        if exact is not None:
+            raise CompileError(f"{label}.exact does not apply to css locators")
+        errors = _css_errors(value.strip())
+        if errors:
+            raise CompileError(f"{label}: " + "; ".join(errors))
+        warnings.append(f"{label} uses a css locator; prefer a data-testid and cite the selector source in source-map.md")
+        return {"css": value.strip()}
+    if kind == "role":
+        role, _, name = value.partition(":")
+        if not re.fullmatch(r"[a-z]+", role.strip()) or not name.strip():
+            raise CompileError(f"{label}.locator role form is 'role:<aria-role>:<accessible name>'")
+        target: dict[str, Any] = {"role": role.strip(), "name": name.strip()}
+        text = name.strip()
+    else:
+        if not value.strip():
+            raise CompileError(f"{label}.locator has an empty value")
+        target = {kind: value.strip()}
+        text = value.strip()
+    target["exact"] = True if exact is None else exact
+    if text in HIGH_RISK_TEXTS:
+        warnings.append(f"{label} locates '{text}' by {kind}; this text usually repeats per row/dialog and fails strict mode — use a data-testid")
+    else:
+        warnings.append(f"{label} uses {kind} instead of a data-testid")
     return target
 
 
 # ---------------------------------------------------------------------------
-# Strategy 决策 — 硬约束
+# covers
 # ---------------------------------------------------------------------------
 
-VERIFICATION_ACTIONS = {"verify", "assert_text", "assert_visible", "assert_url_contains", "assert_any_visible"}
+def _indexes(value: str, label: str) -> list[int]:
+    match = re.fullmatch(r"(\d+)(?:-(\d+))?", value.strip())
+    if not match:
+        raise CompileError(f"{label}: '{value}' must be N or N-M")
+    start, end = int(match.group(1)), int(match.group(2) or match.group(1))
+    if start < 1 or end < start:
+        raise CompileError(f"{label}: '{value}' is not a valid 1-based range")
+    return list(range(start, end + 1))
 
 
-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)
+def compile_covers(raw: Any, label: str) -> dict[str, Any] | None:
+    """Accept {preconditions, steps, oracle} or shorthand 'pre:1' / 'step:2-3' / 'oracle' (string or list)."""
+    if raw is None:
+        return None
+    if isinstance(raw, dict):
+        unknown = set(raw) - {"preconditions", "steps", "oracle"}
+        if unknown:
+            raise CompileError(f"{label}.covers has unknown keys {sorted(unknown)}")
+        covers: dict[str, Any] = {}
+        for key in ("preconditions", "steps"):
+            if key in raw:
+                values = raw[key]
+                if not isinstance(values, list) or not values or not all(isinstance(item, int) and not isinstance(item, bool) for item in values):
+                    raise CompileError(f"{label}.covers.{key} must be a non-empty list of 1-based integers")
+                covers[key] = sorted(set(values))
+        if "oracle" in raw:
+            if raw["oracle"] is not True:
+                raise CompileError(f"{label}.covers.oracle may only be true")
+            covers["oracle"] = True
+        if not covers:
+            raise CompileError(f"{label}.covers is empty")
+        return covers
+    items = [raw] if isinstance(raw, str) else raw
+    if not isinstance(items, list) or not items or not all(isinstance(item, str) for item in items):
+        raise CompileError(f"{label}.covers must be an object, a string, or a list of strings")
+    found: dict[str, set[int]] = {"preconditions": set(), "steps": set()}
+    oracle = False
+    for item in items:
+        text = item.strip().lower()
+        if text == "oracle":
+            oracle = True
+            continue
+        prefix, _, rest = text.partition(":")
+        key = {"pre": "preconditions", "precondition": "preconditions", "preconditions": "preconditions",
+               "step": "steps", "steps": "steps"}.get(prefix)
+        if key is None or not rest:
+            raise CompileError(f"{label}.covers item '{item}' must be 'pre:N', 'step:N', 'step:N-M' or 'oracle'")
+        for part in rest.split(","):
+            found[key].update(_indexes(part, f"{label}.covers"))
+    covers = {key: sorted(values) for key, values in found.items() if values}
+    if oracle:
+        covers["oracle"] = True
+    return covers
 
 
 # ---------------------------------------------------------------------------
-# Step 编译
+# Steps
 # ---------------------------------------------------------------------------
 
-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"),
-    }
+def _check_forbidden(step: dict[str, Any], label: str) -> None:
+    for key, reason in FORBIDDEN_KEYS.items():
+        if key in step:
+            raise CompileError(f"{label}.{key} is not allowed: {reason}")
+    for key, value in step.items():
+        if isinstance(value, str) and FORBIDDEN_TEXT_RE.search(value):
+            raise CompileError(f"{label}.{key} mentions ai_only/Midscene, which is not allowed in the gate DSL")
+
 
-    # --- 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"),
-        })
+def _base(step: dict[str, Any], default_id: str, label: str) -> dict[str, Any]:
+    step_id = step.get("id", default_id)
+    compiled: dict[str, Any] = {"id": step_id}
     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}"
+def _extract(raw: Any, label: str) -> dict[str, Any]:
+    if not isinstance(raw, dict):
+        raise CompileError(f"{label}.extract must map variable names to JSON Pointers")
+    compiled: dict[str, Any] = {}
+    for name, spec in raw.items():
+        if isinstance(spec, str):
+            compiled[name] = {"pointer": spec}
+        elif isinstance(spec, dict):
+            compiled[name] = dict(spec)
+        else:
+            raise CompileError(f"{label}.extract.{name} must be a JSON Pointer string or {{pointer, sensitive}}")
+    return compiled
 
 
-# ---------------------------------------------------------------------------
-# Auth setup 编译
-# ---------------------------------------------------------------------------
+def compile_api_step(step: dict[str, Any], method: str | None, default_id: str, label: str) -> dict[str, Any]:
+    allowed = COMMON_KEYS | API_KEYS
+    unknown = set(step) - allowed
+    if unknown:
+        raise CompileError(f"{label} has unsupported keys {sorted(unknown)} for an API request (allowed: {sorted(allowed)})")
+    raw_method = method or step.get("method")
+    if not isinstance(raw_method, str) or raw_method.upper() not in HTTP_METHODS:
+        raise CompileError(f"{label}.method must be one of {', '.join(HTTP_METHODS)}")
+    if method and "method" in step and str(step["method"]).upper() != method:
+        raise CompileError(f"{label}.method conflicts with action {step.get('action')}")
+    compiled = _base(step, default_id, label)
+    compiled.update({"driver": "api", "action": "request", "method": raw_method.upper(), "url": step.get("url")})
+    for key in ("headers", "query", "json", "expect_status", "assertions", "retry", "idempotent", "timeout_ms"):
+        if key in step:
+            compiled[key] = step[key]
+    if "extract" in step:
+        compiled["extract"] = _extract(step["extract"], label)
+    covers = compile_covers(step.get("covers"), label)
+    if covers:
+        compiled["covers"] = covers
+    return compiled
 
-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
 
+def compile_step(step: Any, default_id: str, label: str, warnings: list[str], api_only: bool = False) -> dict[str, Any]:
+    if not isinstance(step, dict):
+        raise CompileError(f"{label} must be an object")
+    _check_forbidden(step, label)
+    action = str(step.get("action") or "").strip()
+    lowered = action.lower()
+    if lowered in FORBIDDEN_ACTIONS:
+        raise CompileError(f"{label}.action '{action}' is not allowed: {FORBIDDEN_ACTIONS[lowered]}")
+    if lowered == "request" or lowered in API_SHORTHAND:
+        return compile_api_step(step, API_SHORTHAND.get(lowered), default_id, label)
+    if api_only:
+        raise CompileError(f"{label}: data.setup/cleanup may only contain API request steps")
+    if lowered not in UI_ACTIONS:
+        raise CompileError(f"{label}.action '{action}' is unknown; UI actions: {', '.join(sorted(UI_ACTIONS))}; "
+                           f"API: request or {'/'.join(API_SHORTHAND)}")
+    allowed = COMMON_KEYS | UI_KEYS[lowered]
+    unknown = set(step) - allowed
+    if unknown:
+        raise CompileError(f"{label} has unsupported keys {sorted(unknown)} for action {lowered} (allowed: {sorted(allowed)})")
+    compiled = _base(step, default_id, label)
+    compiled.update({"driver": "ui", "action": lowered})
+    if lowered in TARGET_ACTIONS:
+        if "locator" not in step:
+            raise CompileError(f"{label}.locator is required for {lowered}")
+        compiled["target"] = compile_target(step["locator"], step.get("exact"), label, warnings)
+    if lowered == "goto":
+        compiled["url"] = step.get("url")
+    elif lowered in {"fill", "select"}:
+        compiled["value"] = step.get("value")
+    elif lowered == "wait_for":
+        compiled["state"] = step.get("state", "visible")
+    elif lowered == "assert_text":
+        compiled["match"] = step.get("match", "exact")
+        compiled["expected"] = step.get("expected")
+        for key in ("normalize_whitespace", "case_sensitive"):
+            if key in step:
+                compiled[key] = step[key]
+    elif lowered == "assert_url":
+        compiled["match"] = step.get("match", "contains")
+        compiled["expected"] = step.get("expected")
+    elif lowered == "screenshot":
+        compiled["name"] = step.get("id", default_id) if isinstance(step.get("id", default_id), str) else default_id
+        if "full_page" in step:
+            compiled["full_page"] = step["full_page"]
+    if "timeout_ms" in step:
+        compiled["timeout_ms"] = step["timeout_ms"]
+    covers = compile_covers(step.get("covers"), label)
+    if covers:
+        compiled["covers"] = covers
+    return compiled
 
-# ---------------------------------------------------------------------------
-# 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]
+def compile_variables(raw: Any, label: str) -> dict[str, Any]:
+    if raw is None:
+        return {}
+    if not isinstance(raw, dict):
+        raise CompileError(f"{label}.variables must be an object")
+    compiled: dict[str, Any] = {}
+    for name, value in raw.items():
+        if isinstance(value, dict):
+            compiled[name] = dict(value)
+        elif isinstance(value, (str, int, float, bool)):
+            compiled[name] = {"value": value}
+        else:
+            raise CompileError(f"{label}.variables.{name} must be a scalar, {{value, sensitive}} or {{secret}}")
+    return compiled
+
 
+def compile_case(desc: Any, index: int, eligible: dict[str, dict[str, Any]], rejected: dict[str, str]) -> tuple[str, dict[str, Any], list[str]]:
+    label = f"cases[{index}]"
+    if not isinstance(desc, dict):
+        raise CompileError(f"{label} must be an object")
+    unknown = set(desc) - CASE_KEYS
+    for key in sorted(unknown):
+        raise CompileError(f"{label}.{key} is not allowed: {FORBIDDEN_KEYS.get(key, 'unknown case field')}")
+    tc_id = desc.get("tc_id")
+    if not isinstance(tc_id, str) or not TC_ID_RE.fullmatch(tc_id):
+        raise CompileError(f"{label}.tc_id must reference a frozen TC (TC-xxxx)")
+    if tc_id not in eligible:
+        reason = rejected.get(tc_id, "is not in the frozen TC suite")
+        raise CompileError(f"{label}.tc_id {tc_id} {reason}")
+    label = f"{label}({tc_id})"
+    warnings: list[str] = []
+    data_raw = desc.get("data") or {}
+    if not isinstance(data_raw, dict):
+        raise CompileError(f"{label}.data must be an object")
+    unknown_data = set(data_raw) - DATA_KEYS
+    if unknown_data:
+        raise CompileError(f"{label}.data has unsupported keys {sorted(unknown_data)}")
+    data: dict[str, Any] = {"namespace": data_raw.get("namespace", "${execution_id}")}
+    for key in ("owner", "accounts", "repeatable"):
+        if key in data_raw:
+            data[key] = data_raw[key]
+    for phase in ("setup", "cleanup"):
+        steps = data_raw.get(phase, [])
+        if not isinstance(steps, list):
+            raise CompileError(f"{label}.data.{phase} must be an array")
+        data[phase] = [compile_step(step, f"{phase}-{i:02d}", f"{label}.data.{phase}[{i - 1}]", warnings, api_only=True)
+                       for i, step in enumerate(steps, start=1)]
+    raw_steps = desc.get("steps")
+    if not isinstance(raw_steps, list) or not raw_steps:
+        raise CompileError(f"{label}.steps must be a non-empty array")
+    steps = [compile_step(step, f"s{i:02d}", f"{label}.steps[{i - 1}]", warnings) for i, step in enumerate(raw_steps, start=1)]
+    source = eligible[tc_id]
+    name = desc.get("name")
     dsl = {
-        "name": name,
-        "description": case_desc.get("description", ""),
-        "tags": tags,
-        "variables": variables,
-        "steps": all_steps,
+        "schema_version": SCHEMA_VERSION,
+        "tc_id": tc_id,
+        "tc_sha256": tc_sha256(source),
+        "name": name if isinstance(name, str) and name.strip() else tc_id,
+        "variables": compile_variables(desc.get("variables"), label),
+        "data": data,
+        "steps": steps,
     }
+    errors = [f"{label}: {error}" for error in validate_dsl(dsl)]
+    if not errors:
+        errors = [f"{label}: coverage: {error}" for error in coverage_check(source, dsl)]
+    if errors:
+        raise CompileError("\n".join(errors))
+    return tc_id, dsl, [f"{label}: {warning}" for warning in warnings]
 
-    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: Any, suite: dict[str, Any]) -> tuple[dict[str, dict[str, Any]], list[str], list[str]]:
+    """Return ({tc_id: dsl}, warnings, errors).  Errors are collected per case."""
+    cases = payload.get("cases") if isinstance(payload, dict) else payload
+    if not isinstance(cases, list):
+        raise CompileError("case descriptions must be {\"cases\": [...]} or an array")
+    eligible, rejected = eligible_cases(suite)
+    compiled: dict[str, dict[str, Any]] = {}
+    warnings: list[str] = []
+    errors: list[str] = []
+    for index, desc in enumerate(cases):
+        try:
+            tc_id, dsl, case_warnings = compile_case(desc, index, eligible, rejected)
+        except CompileError as error:
+            errors.append(str(error))
+            continue
+        if tc_id in compiled:
+            errors.append(f"cases[{index}]: duplicate case for {tc_id}; each frozen TC has exactly one DSL file")
+            continue
+        compiled[tc_id] = dsl
+        warnings.extend(case_warnings)
+    return compiled, warnings, errors
 
-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": "compile_dsl.py (hard-constraint layer)",
-        },
-        "cases": cases,
-    }
 
+def render(dsl: dict[str, Any]) -> bytes:
+    return (json.dumps(dsl, ensure_ascii=False, indent=2) + "\n").encode("utf-8")
 
-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 / ".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 / ".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)}
 
+def write_atomic(path: Path, content: bytes) -> None:
+    temporary = path.with_name(f".{path.name}.tmp")
+    temporary.write_bytes(content)
+    temporary.replace(path)
 
-# ---------------------------------------------------------------------------
-# CLI
-# ---------------------------------------------------------------------------
 
 def main() -> int:
-    parser = argparse.ArgumentParser(
-        description="Compile AI-friendly case descriptions into strict DSL JSON."
-    )
-    parser.add_argument("input", help="Simplified case descriptions JSON")
-    parser.add_argument("--output", required=True, help="Output path for case-import-payloads.json")
-    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}
-
+    # allow_abbrev=False: the removed `--output` must not silently abbreviate to `--output-dir`.
+    parser = argparse.ArgumentParser(description="Compile case descriptions into one devflow-test-dsl/v1 file per frozen TC.",
+                                     allow_abbrev=False)
+    parser.add_argument("input", help="case-descriptions.json (see references/intermediate-format.md)")
+    parser.add_argument("--feature", help="feature name (default: current_feature in .devflow/planning/STATE.md)")
+    parser.add_argument("--suite", help="frozen TC suite (default: .devflow/planning/requirements/<feature>/tests.json)")
+    parser.add_argument("--output-dir", help="default: .devflow/planning/generated-cases/<feature>")
+    args, unknown = parser.parse_known_args()
+    if unknown:
+        removed = [item for item in unknown if item == "--output" or item.startswith("--output=")]
+        hint = (" `--output` was removed: the compiler writes one TC-xxxx.json per frozen TC into a directory; "
+                "use --output-dir (default .devflow/planning/generated-cases/<feature>)." if removed else "")
+        parser.error(f"unrecognized arguments: {' '.join(unknown)}.{hint}")
+
+    root = Path.cwd().resolve()
+    feature = args.feature or current_feature(root)
     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)
+        if not feature or not FEATURE_RE.fullmatch(feature):
+            raise CompileError("feature is required (--feature or current_feature in .devflow/planning/STATE.md)")
+        suite = load_suite(Path(args.suite) if args.suite else root / ".devflow/planning" / "requirements" / feature / "tests.json")
+        try:
+            payload = json.loads(Path(args.input).read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise CompileError(f"cannot read case descriptions: {error}") from error
+        compiled, warnings, errors = compile_all(payload, suite)
+    except CompileError as error:
+        print(f"COMPILE ERROR: {error}", file=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))
+    for warning in warnings:
+        print(f"WARNING: {warning}", file=sys.stderr)
+    if errors:
+        # All-or-nothing: never leave a partially regenerated execution plan on disk.
+        print("COMPILE ERROR: no DSL file was written\n" + "\n".join(f"- {error}" for error in errors), file=sys.stderr)
+        return 1
+    output_dir = Path(args.output_dir) if args.output_dir else root / ".devflow/planning" / "generated-cases" / feature
+    output_dir.mkdir(parents=True, exist_ok=True)
+    files: list[dict[str, Any]] = []
+    for tc_id in sorted(compiled):
+        path = output_dir / f"{tc_id}.json"
+        content = render(compiled[tc_id])
+        unchanged = path.is_file() and path.read_bytes() == content
+        if not unchanged:
+            write_atomic(path, content)
+        files.append({"tc_id": tc_id, "path": path.relative_to(root).as_posix() if path.is_relative_to(root) else str(path),
+                      "changed": not unchanged})
+    print(json.dumps({"status": "compiled", "feature": feature, "case_count": len(files), "files": files,
+                      "warnings": len(warnings)}, ensure_ascii=False, indent=2))
     return 0