@michaelxwb/code-flow 0.6.4 → 0.8.1

package/src/core/code-flow/scripts/codeflow/acceptance/cf_check_registration.py

@@ -0,0 +1,326 @@
+"""Validate test registration against a bounded, real collection command."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import re
+import shlex
+import time
+from typing import Mapping, Sequence
+
+from codeflow.acceptance.cf_acceptance_schema import scenario_check_ids, validate_checks
+from codeflow.core.cf_exec_base import run_command
+
+
+REGISTRATION_FIELDS = ("suite", "test_ids", "markers", "collect", "level", "environment_revision", "evidence_ttl_seconds")
+
+
+class CollectionError(ValueError):
+    def __init__(self, code: str, details: Mapping[str, object]) -> None:
+        super().__init__(code)
+        self.code = code
+        self.details = dict(details)
+
+
+def _pytest_markers(argv: Sequence[str]) -> list[str]:
+    positions = [index for index, value in enumerate(argv[:-1]) if value == "-m" and argv[index + 1] != "pytest"]
+    expression = argv[positions[-1] + 1] if positions else ""
+    markers = [value.strip() for value in expression.split(" and ")] if expression else []
+    if any(not re.fullmatch(r"[a-zA-Z_][a-zA-Z0-9_]*", value) for value in markers):
+        raise ValueError("check_collection_marker_expression_invalid")
+    return markers
+
+
+def _pytest_collection(output: str, argv: Sequence[str]) -> list[dict[str, object]]:
+    markers = _pytest_markers(argv)
+    return [{"id": line.strip(), "markers": markers,
+             "capabilities": ["browser"] if "browser" in markers else []}
+            for line in output.splitlines() if re.fullmatch(r"[^\s]+\.py::[^\s]+", line.strip())]
+
+
+def _objects(value: object) -> list[Mapping[str, object]]:
+    if not isinstance(value, list) or not all(isinstance(item, Mapping) for item in value):
+        raise ValueError("check_collection_invalid_playwright_structure")
+    return value
+
+
+def _browser_projects(config: Mapping[str, object]) -> set[str]:
+    projects: set[str] = set()
+    for project in _objects(config.get("projects", [])):
+        metadata = project.get("metadata", {})
+        capabilities = metadata.get("capabilities", []) if isinstance(metadata, Mapping) else None
+        if not isinstance(capabilities, list) or not all(isinstance(value, str) for value in capabilities):
+            raise ValueError("check_collection_invalid_project_capabilities")
+        if "browser" in capabilities:
+            projects.add(str(project.get("name", "")).lower())
+    return projects | {"chromium", "firefox", "webkit", "browser"}
+
+
+def _playwright_spec(spec: Mapping[str, object], suite: Mapping[str, object], report_root: Path,
+                     root: str, projects: set[str]) -> list[dict[str, object]]:
+    file = spec.get("file", suite.get("file", ""))
+    tags = spec.get("tags", [])
+    if not isinstance(file, str) or not isinstance(tags, list) or not all(isinstance(value, str) for value in tags):
+        raise ValueError("check_collection_invalid_playwright_spec")
+    if type(spec.get("line")) is not int:
+        raise ValueError("check_collection_invalid_playwright_location")
+    file = (report_root / file).resolve().relative_to(Path(root).resolve()).as_posix()
+    tests: list[dict[str, object]] = []
+    for case in _objects(spec.get("tests", [])):
+        project = case.get("projectName", "")
+        if not isinstance(project, str):
+            raise ValueError("check_collection_invalid_playwright_project")
+        tests.append({"id": f"{file}:{spec['line']}@{project}", "markers": [tag.lstrip("@") for tag in tags],
+                      "capabilities": ["browser"] if project.lower() in projects else []})
+    return tests
+
+
+def _playwright_collection(data: Mapping[str, object], root: str) -> list[dict[str, object]]:
+    tests: list[dict[str, object]] = []
+    config = data.get("config", {})
+    if not isinstance(config, Mapping) or not isinstance(config.get("rootDir", root), str):
+        raise ValueError("check_collection_invalid_playwright_config")
+    report_root = Path(str(config.get("rootDir", root)))
+    projects = _browser_projects(config)
+    pending = list(_objects(data.get("suites", [])))
+    while pending:
+        suite = pending.pop()
+        if not isinstance(suite, Mapping):
+            raise ValueError("check_collection_invalid_playwright_suite")
+        pending.extend(_objects(suite.get("suites", [])))
+        for spec in _objects(suite.get("specs", [])):
+            tests.extend(_playwright_spec(spec, suite, report_root, root, projects))
+    return tests
+
+
+def _parse_collection(output: str, config: Mapping[str, object], root: str) -> list[Mapping[str, object]]:
+    fmt = config.get("format", "json")
+    if fmt == "pytest":
+        return _pytest_collection(output, config["argv"])
+    try:
+        data = json.loads(output)
+    except json.JSONDecodeError as exc:
+        raise ValueError("check_collection_invalid_json") from exc
+    if not isinstance(data, Mapping):
+        raise ValueError("check_collection_invalid_tests")
+    tests = _playwright_collection(data, root) if fmt == "playwright" else data.get("tests")
+    if fmt not in ("json", "pytest", "playwright") or not isinstance(tests, list):
+        raise ValueError("check_collection_invalid_format")
+    for test in tests:
+        if not isinstance(test, Mapping) or not isinstance(test.get("id"), str):
+            raise ValueError("check_collection_invalid_tests")
+        for field in ("capabilities", "markers"):
+            values = test.get(field, [])
+            if not isinstance(values, list) or not all(isinstance(value, str) for value in values):
+                raise ValueError("check_collection_invalid_tests")
+    return tests
+
+
+def _finding(code: str, scenario: str, check: str, message: str) -> dict[str, str]:
+    return {"code": code, "scenario": scenario, "check_id": check, "message": message}
+
+
+def _execution_argv(root: str, check: Mapping[str, object]) -> list[str]:
+    command = check.get("command")
+    if not isinstance(command, list) or not all(isinstance(value, str) for value in command):
+        return []
+    expanded = list(command)
+    for _ in range(4):
+        if not expanded or Path(expanded[0]).name not in ("npm", "pnpm", "yarn"):
+            return expanded
+        offset = 2 if len(expanded) > 1 and expanded[1] == "run" else 1
+        if len(expanded) <= offset:
+            return []
+        package = Path(root) / str(check.get("cwd", ".")) / "package.json"
+        data = json.loads(package.read_text(encoding="utf-8"))
+        script = data.get("scripts", {}).get(expanded[offset])
+        if not isinstance(script, str):
+            return []
+        lexer = shlex.shlex(script, posix=True, punctuation_chars=True)
+        lexer.whitespace_split = True
+        tokens = list(lexer)
+        if any(value in ("&&", "||", ";", "|", ">", ">>", "&") for value in tokens):
+            raise ValueError("check_execution_script_requires_direct_command")
+        expanded = tokens + [value for value in expanded[offset + 1:] if value != "--"]
+    return []
+
+
+def _execution_matches(root: str, check: Mapping[str, object], selected: Sequence[Mapping[str, object]]) -> bool:
+    from codeflow.acceptance.cf_check_inputs import match_path
+    argv = _execution_argv(root, check)
+    if not argv or not selected or any(value in argv for value in ("-k", "-g", "--grep", "--grep-invert")):
+        return False
+    pytest = any(Path(value).name in ("pytest", "py.test") for value in argv)
+    markers = _pytest_markers(argv) if pytest else []
+    if markers and any(not set(markers) <= set(item.get("markers", [])) for item in selected):
+        return False
+    selectors: list[str] = []
+    for value in argv:
+        normalized = value.replace("\\", "/").removeprefix("./")
+        if normalized.startswith(str(Path(root).resolve()) + "/"):
+            normalized = normalized[len(str(Path(root).resolve())) + 1:]
+        if re.fullmatch(r"[\w./*?:-]+\.(?:py|[cm]?[jt]sx?)(?::[\w:\[\].-]+)?", normalized):
+            selectors.append(normalized)
+    if selectors:
+        return all(any(match_path(str(item["id"]).split("@", 1)[0], selector)
+                       or match_path(str(item["id"]).split("@", 1)[0].split(":", 1)[0], selector)
+                       for selector in selectors) for item in selected)
+    if pytest:
+        return bool(markers)
+    return any(Path(value).name in ("playwright", "cypress") for value in argv)
+
+
+def _collected(root: str, check: Mapping[str, object], deadline: float | None = None) -> dict[str, Mapping[str, object]]:
+    config = check.get("collect")
+    if not isinstance(config, Mapping):
+        raise ValueError("check_collection_missing")
+    argv = config.get("argv")
+    if not isinstance(argv, list) or not argv or not all(isinstance(item, str) for item in argv):
+        raise ValueError("check_collection_invalid")
+    timeout = config.get("timeout", 10)
+    if isinstance(timeout, bool) or not isinstance(timeout, (float, int)) or not 0 < timeout <= 60:
+        raise ValueError("check_collection_timeout_invalid")
+    directory = (Path(root) / str(check.get("cwd", "."))).resolve()
+    if directory != Path(root).resolve() and Path(root).resolve() not in directory.parents:
+        raise ValueError("check_collection_outside_project")
+    result = run_command(argv, str(directory), float(timeout), deadline)
+    if result.get("status") != "ok" or result.get("returncode") != 0:
+        raise CollectionError("check_collection_failed", {"command": argv, "cwd": str(directory),
+            "exit_code": result.get("returncode"), "status": result.get("status"),
+            "output": (str(result.get("stdout", "")) + str(result.get("stderr", "")))[-4000:]})
+    output = str(result.get("stdout", ""))
+    if len(output.encode()) > 2_000_000:
+        raise ValueError("check_collection_too_large")
+    tests = _parse_collection(output, config, root)
+    if len({item["id"] for item in tests}) != len(tests):
+        raise ValueError("check_collection_duplicate_test")
+    return {str(item["id"]): item for item in tests}
+
+
+def _requirements(row: Mapping[str, object]) -> tuple[bool, set[str]]:
+    browser = str(row.get("level", row.get("kind", ""))).lower() == "e2e"
+    markers: set[str] = set()
+    if row.get("smoke"):
+        markers.add("smoke")
+    if row.get("level") == "capacity" or "capacity" in row.get("tags", []):
+        markers.add("capacity")
+    return browser, markers
+
+
+def registration_required(row: Mapping[str, object]) -> bool:
+    """Return whether a scenario needs collection-backed registration."""
+    browser, markers = _requirements(row)
+    return bool(browser or markers)
+
+
+def _collection_config(root: str, check: Mapping[str, object], markers: set[str]) -> dict[str, object]:
+    argv = _execution_argv(root, check)
+    if any(Path(value).name in ("pytest", "py.test") for value in argv):
+        if "-k" in argv:
+            raise ValueError("check_execution_selection_mismatch: use concrete pytest node IDs")
+        selected_markers = set(_pytest_markers(argv)) | markers
+        argv = [value for value in argv if not re.fullmatch(r"-q+|--quiet", value)]
+        argv += ["--collect-only", "--verbosity=-1"]
+        if selected_markers:
+            argv += ["-m", " and ".join(sorted(selected_markers))]
+        return {"argv": argv, "format": "pytest", "timeout": 10}
+    if any(Path(value).name == "playwright" for value in argv):
+        return {"argv": argv + ["--list", "--reporter=json"], "format": "playwright", "timeout": 10}
+    raise ValueError("check_collection_inference_unsupported: supply --registration-file")
+
+
+def register_check(root: str, check: dict[str, object], rows: Sequence[Mapping[str, object]],
+                   deadline: float) -> list[dict[str, str]]:
+    """Collect, populate and validate one check against all of its scenarios."""
+    validate_checks([check])
+    effective_rows = [{**row, "level": check.get("level", row.get("level"))} for row in rows]
+    requirements = [_requirements(row) for row in effective_rows]
+    browser = any(item[0] for item in requirements)
+    markers = set().union(*(item[1] for item in requirements))
+    if "collect" not in check:
+        check["collect"] = _collection_config(root, check, markers | ({"browser"} if browser else set()))
+    collected = _collected(root, check, deadline)
+    if not collected:
+        raise ValueError("check_collection_empty")
+    check.setdefault("test_ids", sorted(collected))
+    selected = [collected[value] for value in check["test_ids"] if value in collected]
+    actual_markers = set.intersection(*(set(item.get("markers", [])) for item in selected)) if selected else set()
+    check.setdefault("markers", sorted(actual_markers))
+    if browser and selected and all("browser" in item.get("capabilities", []) for item in selected):
+        check.setdefault("suite", "browser")
+    validate_checks([check])
+    return [issue for row in effective_rows for issue in _registration_issues(root, row, check, collected)]
+
+
+def _registration_issues(root: str, row: Mapping[str, object], check: Mapping[str, object],
+                          collected: Mapping[str, Mapping[str, object]]) -> list[dict[str, str]]:
+    scenario, check_id = str(row.get("id", "")), str(check.get("id", ""))
+    browser, markers = _requirements(row)
+    errors: list[dict[str, str]] = []
+    test_ids = check.get("test_ids", [])
+    if not isinstance(test_ids, list) or not test_ids or not all(isinstance(value, str) for value in test_ids):
+        return [_finding("check_test_ids_missing", scenario, check_id, "check 必须登记具体测试 ID")]
+    selected = [collected[value] for value in test_ids if value in collected]
+    if len(selected) != len(test_ids):
+        errors.append(_finding("check_test_not_collected", scenario, check_id, "登记的测试 ID 未全部被真实收集"))
+    try:
+        matches = _execution_matches(root, check, selected)
+    except (OSError, ValueError) as exc:
+        errors.append(_finding("check_execution_config_invalid", scenario, check_id, str(exc)))
+        matches = False
+    if not matches:
+        errors.append(_finding("check_execution_selection_mismatch", scenario, check_id,
+                               "实际执行命令必须选择登记用例；不可验证的 grep/-k 过滤请改用具体测试 ID"))
+    if browser and (check.get("suite") != "browser" or any("browser" not in item.get("capabilities", []) for item in selected)):
+        errors.append(_finding("e2e_check_not_browser", scenario, check_id, "E2E check 必须属于 browser 套件并收集到浏览器能力用例"))
+    if check.get("level") and check.get("level") != "e2e" and any(
+        "browser" in item.get("capabilities", []) for item in selected
+    ):
+        errors.append(_finding("check_level_browser_mismatch", scenario, check_id, "浏览器用例必须声明 e2e 层级"))
+    for marker in sorted(markers):
+        if marker not in check.get("markers", []) or any(marker not in item.get("markers", []) for item in selected):
+            code = "capacity_check_not_marked" if marker == "capacity" else "smoke_check_not_registered"
+            errors.append(_finding(code, scenario, check_id, f"check 与真实收集用例必须包含 {marker} 标记"))
+    return errors
+
+
+def validate_registration(root: str, scenarios: Sequence[Mapping[str, object]],
+                           checks: Sequence[Mapping[str, object]]) -> dict[str, object]:
+    by_id = {str(check["id"]): check for check in checks}
+    cache: dict[str, dict[str, Mapping[str, object]] | Exception] = {}
+    errors: list[dict[str, object]] = []
+    deadline = time.monotonic() + 60
+    runnable_smoke = runnable_browser = 0
+    for row in scenarios:
+        browser, markers = _requirements(row)
+        ids = scenario_check_ids(row)
+        has_browser_check = any(by_id.get(check_id, {}).get("level") == "e2e" for check_id in ids)
+        if not browser and not markers and not has_browser_check:
+            continue
+        row_errors: list[dict[str, object]] = []
+        if not ids:
+            row_errors.append(_finding("scenario_check_missing", str(row["id"]), "", "需要可执行 check 绑定"))
+        for check_id in ids:
+            check = by_id.get(check_id)
+            if check is None:
+                row_errors.append(_finding("unknown_check", str(row["id"]), check_id, "引用的 check 不存在"))
+                continue
+            effective = {**row, "level": check.get("level", row.get("level"))}
+            if not registration_required(effective):
+                continue
+            if check_id not in cache:
+                try:
+                    cache[check_id] = _collected(root, check, deadline)
+                except (OSError, ValueError) as exc:
+                    cache[check_id] = exc
+            collected = cache[check_id]
+            if isinstance(collected, Exception):
+                detail = collected.details if isinstance(collected, CollectionError) else {}
+                row_errors.append({**_finding(str(collected), str(row["id"]), check_id, "无法验证测试收集与套件登记"), **detail})
+            else:
+                row_errors.extend(_registration_issues(root, effective, check, collected))
+        errors.extend(row_errors)
+        runnable_smoke += int(bool(row.get("smoke")) and not row_errors)
+        runnable_browser += int(browser and not row_errors)
+    return {"ok": not errors, "errors": errors, "runnable_smoke_count": runnable_smoke,
+            "runnable_browser_count": runnable_browser, "collected_checks": len(cache)}

package/src/core/code-flow/scripts/{cf_checks.py → codeflow/acceptance/cf_checks.py}

@@ -15,12 +15,13 @@ Contract (spec-quality-loop.design.md §2.3.2 / §3.4 / §3.5):
 import fnmatch
 import os
 import re
-import sys
 from typing import Mapping
 from concurrent.futures import ThreadPoolExecutor
 from concurrent.futures import TimeoutError as FutureTimeout
 
-from cf_core import _FRONTMATTER_RE, normalize_path
+from codeflow.core import cf_log
+from codeflow.core.cf_core import normalize_path
+from codeflow.core.cf_markdown import frontmatter_block
 
 CHECK_TIMEOUT_SECONDS = 2.0
 MAX_CONTENT_BYTES = 256 * 1024
@@ -39,10 +40,6 @@ FP_DISABLE_COUNT = 3
 FP_DISABLE_RATE = 0.10
 
 
-def _log(msg: str) -> None:
-    sys.stderr.write(f"[cf-checks] {msg}\n")
-
-
 def state_path(project_root: str) -> str:
     return os.path.join(project_root, ".code-flow", STATE_NAME)
 
@@ -67,7 +64,7 @@ def save_check_state(project_root: str, state: dict) -> bool:
             json.dump(state, f, ensure_ascii=False)
         return True
     except Exception as exc:
-        _log(f"save_check_state failed: {exc}")
+        cf_log.warn(f"save_check_state failed: {exc}")
         return False
 
 
@@ -165,12 +162,12 @@ def parse_spec_checks(content: str) -> tuple:
     """Parse frontmatter checks → (checks, errors). Both lists, never raises."""
     if not isinstance(content, str):
         return [], []
-    match = _FRONTMATTER_RE.match(content)
-    if not match or "checks:" not in match.group(1):
+    match = frontmatter_block(content)
+    if match is None or "checks:" not in match:
         return [], []
     try:
         import yaml
-        meta = yaml.safe_load(match.group(1)) or {}
+        meta = yaml.safe_load(match) or {}
     except Exception as exc:
         return [], [f"frontmatter YAML 解析失败: {exc}"]
     raw = meta.get("checks")
@@ -204,7 +201,7 @@ def load_spec_checks(spec_abs_path: str) -> tuple:
         with open(spec_abs_path, "r", encoding="utf-8") as f:
             checks, errors = parse_spec_checks(f.read())
     except Exception as exc:
-        _log(f"load_spec_checks failed {spec_abs_path}: {exc}")
+        cf_log.warn(f"load_spec_checks failed {spec_abs_path}: {exc}")
         return [], []
     _checks_cache[spec_abs_path] = {
         "mtime": mtime, "checks": checks, "errors": errors,

package/src/core/code-flow/scripts/codeflow/acceptance/cf_plan_quality.py

@@ -0,0 +1,197 @@
+"""One executable plan gate for manifest identity, semantics and design closure."""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from shlex import quote
+from typing import Mapping, Optional
+
+
+@dataclass(frozen=True)
+class FileSnapshot:
+    """One file read once, with a stat fingerprint for drift detection."""
+
+    path: str
+    text: str
+    size: int
+    mtime_ns: int
+
+    def drift(self) -> bool:
+        try:
+            stat = Path(self.path).stat()
+        except OSError:
+            return True
+        return stat.st_size != self.size or stat.st_mtime_ns != self.mtime_ns
+
+
+@dataclass(frozen=True)
+class PlanSnapshot:
+    """Verified inputs of one verify_plan operation; no persistent cache."""
+
+    task: FileSnapshot
+    manifest: FileSnapshot
+    scenario_file: str
+    scenario: Optional[FileSnapshot]
+
+    def drift(self) -> bool:
+        if self.task.drift() or self.manifest.drift():
+            return True
+        return self.scenario is not None and self.scenario.drift()
+
+
+def _read_snapshot(path: Path) -> FileSnapshot:
+    stat = path.stat()
+    return FileSnapshot(str(path), path.read_text(encoding="utf-8"), stat.st_size, stat.st_mtime_ns)
+
+
+def load_plan_snapshot(directory: str, task_file: str,
+                       require_scenarios: bool = False) -> PlanSnapshot:
+    """Read TASK, manifest and scenario source at most once for one operation."""
+    from codeflow.acceptance.cf_scenario_source import ScenarioError
+    base = Path(directory)
+    manifest = _read_snapshot(base / ".acceptance-manifest.json")
+    task = _read_snapshot(Path(task_file))
+    try:
+        data = json.loads(manifest.text)
+    except ValueError:
+        data = {}
+    try:
+        source_file = _source(base, data if isinstance(data, Mapping) else {}, require_scenarios)
+    except ScenarioError:
+        source_file = ""
+    source = _read_snapshot(Path(source_file)) if source_file and Path(source_file).is_file() else None
+    return PlanSnapshot(task, manifest, source_file, source)
+
+
+def _root(directory: Path) -> Path:
+    return next((parent.parent for parent in (directory, *directory.parents)
+                 if parent.name == ".code-flow"), directory)
+
+
+def _source(directory: Path, manifest: Mapping[str, object], required: bool) -> str:
+    from codeflow.acceptance.cf_scenario_source import require_source
+    named = manifest.get("scenarios_file")
+    if isinstance(named, str) and named:
+        return str(directory / named)
+    candidates = sorted(directory.glob("*.scenarios.md"))
+    if required or candidates:
+        return str(require_source(directory))
+    return ""
+
+
+def _projection(source: Mapping[str, object], manifest: Mapping[str, object]) -> list[dict[str, object]]:
+    from codeflow.acceptance.cf_acceptance_schema import scenario_check_ids
+    rows = {str(row["id"]): row for row in manifest.get("scenarios", [])}
+    checks = {str(check["id"]) for check in manifest.get("checks", [])}
+    findings: list[dict[str, object]] = []
+    for row in source["scenarios"]:
+        required = scenario_check_ids(row)
+        current = rows.get(str(row["id"]), {})
+        unknown = set(required) - checks
+        if unknown:
+            findings.append({"code": "unknown_check", "scenario": row["id"], "checks": sorted(unknown)})
+        if required and set(required) != set(scenario_check_ids(current)):
+            findings.append({"code": "scenario_checks_not_projected", "scenario": row["id"]})
+    return findings
+
+
+def _scenario_snapshot(snapshot: PlanSnapshot, source_file: str) -> Optional[FileSnapshot]:
+    scenario = snapshot.scenario
+    if not source_file:
+        return None
+    if scenario is not None and Path(scenario.path).resolve() == Path(source_file).resolve():
+        return scenario
+    return _read_snapshot(Path(source_file)) if Path(source_file).is_file() else None
+
+
+def _scenario_ids(text: str) -> set[str]:
+    """Expand explicit IDs and `S-01~04` / `S-01~S-04` ranges."""
+    ids = {item.upper() for item in re.findall(r"\b(?:S|E|B)-\d+\b", text, re.IGNORECASE)}
+    for match in re.finditer(r"\b([SEB])-(\d+)\s*~\s*(?:\1-)?(\d+)\b", text, re.IGNORECASE):
+        prefix, start, end = match.group(1).upper(), int(match.group(2)), int(match.group(3))
+        width = max(len(match.group(2)), len(match.group(3)))
+        for value in range(start, end + 1):
+            ids.add(f"{prefix}-{value:0{width}d}")
+    return ids
+
+
+def _checklist_issues(text: str) -> list[dict[str, str]]:
+    """Flag scenario IDs used in a Checklist but not declared in Acceptance-Refs.
+
+    Cross-task boundaries start as this mismatch: a task writes another task's
+    scenario into its checklist, then the plan assigns the scenario to only one
+    owner. Reported as a non-blocking warning for existing plans.
+    """
+    from codeflow.task.cf_task_doc import TaskDocumentError, parse_task_document
+    try:
+        document = parse_task_document(text)
+    except TaskDocumentError:
+        return []
+    issues: list[dict[str, str]] = []
+    for task in document.tasks:
+        declared = _scenario_ids(str(task.fields.get("Acceptance-Refs", "")))
+        checklist = task.body.partition("### Checklist")[2].partition("### Acceptance Contract")[0]
+        used = _scenario_ids(checklist)
+        for scenario in sorted(used - declared):
+            issues.append({"code": "checklist_scenario_not_in_refs", "task": task.id, "scenario": scenario})
+        for scenario in sorted(declared - used):
+            issues.append({"code": "acceptance_ref_not_in_checklist", "task": task.id, "scenario": scenario})
+    return issues
+
+
+def verify_plan(directory: str, task_file: str, require_scenarios: bool = False,
+                *, snapshot: Optional[PlanSnapshot] = None) -> dict[str, object]:
+    from codeflow.acceptance.cf_acceptance_manifest_core import validate_manifest
+    from codeflow.acceptance.cf_acceptance_schema import load_manifest
+    from codeflow.acceptance.cf_check_registration import validate_registration
+    from codeflow.cli.cf_design_lint import lint_requirement
+    from codeflow.acceptance.cf_scenario_source import parse_scenarios, validate_e2e_quality
+    from codeflow.spec.cf_spec_context_model import load_context
+    from codeflow.spec.cf_stage_gate import result_to_data, validate_plan_coverage, validate_stage
+    base = Path(directory)
+    path = base / ".acceptance-manifest.json"
+    if not path.is_file():
+        return {"decision": "block", "reason": "acceptance_manifest_missing"}
+    plan = snapshot if snapshot is not None else load_plan_snapshot(directory, task_file, require_scenarios)
+    if plan.drift():
+        return {"decision": "block", "reason": "plan_snapshot_drift"}
+    try:
+        manifest = load_manifest(path, text=plan.manifest.text)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        return {"decision": "block", "reason": f"acceptance_manifest_invalid: {exc}"}
+    source_file = _source(base, manifest, require_scenarios)
+    scenario = _scenario_snapshot(plan, source_file)
+    valid, reason = validate_manifest(task_file, str(path), task_text=plan.task.text,
+                                      manifest=manifest, scenario_file=source_file,
+                                      scenario_text=scenario.text if scenario is not None else None)
+    if not valid:
+        return {"decision": "block", "reason": reason}
+    if scenario is not None:
+        source = parse_scenarios(scenario.path, text=scenario.text)
+    elif source_file:
+        source = parse_scenarios(source_file)
+    else:
+        source = {"scenarios": manifest["scenarios"]}
+    quality = validate_e2e_quality(source["scenarios"])
+    projection = _projection(source, manifest)
+    registration = validate_registration(str(_root(base)), manifest["scenarios"], manifest.get("checks", []))
+    quality.update({"runnable_smoke_count": registration["runnable_smoke_count"],
+                    "runnable_browser_count": registration["runnable_browser_count"],
+                    "registration_status": "passed" if registration["ok"] else "failed"})
+    design = lint_requirement(task_file, source_file, task_text=plan.task.text,
+                              scenarios=source["scenarios"] if source_file else None)
+    context = load_context(str(base / "spec-context.yml"))
+    gate = validate_stage(context, "plan", root=str(_root(base)), task_dir=directory)
+    coverage = validate_plan_coverage(context, task_file, text=plan.task.text)
+    checklist = _checklist_issues(plan.task.text)
+    blocked = (not quality["ok"] or projection or not registration["ok"] or
+               design["decision"] != "pass" or gate.decision != "pass" or coverage.decision != "pass")
+    recovery = (["code-flow spec refresh --task-dir " + quote(str(base)) +
+                 " --root " + quote(str(_root(base))) + " --json"]
+                if any(issue.code == "rule_artifact_stale" for issue in gate.errors) else [])
+    return {"decision": "block" if blocked else "pass", "gate": result_to_data(gate), "next": recovery,
+            "coverage": result_to_data(coverage), "e2e_quality": quality,
+            "registration": registration, "design_lint": design, "projection": projection,
+            "checklist": checklist}