@michaelxwb/code-flow 0.6.5 → 0.8.1

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

@@ -0,0 +1,202 @@
+"""E2E precision and scope for a TASK start.
+
+Plan locks E2E quality fields; Start must turn them into a concrete execution
+scope. A TASK writes tests only for its owned E2E scenarios and runs its owned
+scenarios plus the global smoke set. Unrelated E2E journeys stay deferred
+instead of turning every small change into a full-suite run.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Mapping
+
+from codeflow.acceptance.cf_acceptance_manifest_core import validate_execution_baseline
+from codeflow.acceptance.cf_acceptance_schema import load_manifest, scenario_check_ids
+
+_PLACEHOLDERS = frozenset(("", "-", "n/a", "na", "none", "无", "todo", "tbd", "待定"))
+
+
+def _meaningful(value: object) -> bool:
+    return str(value or "").strip().lower() not in _PLACEHOLDERS
+
+
+def _task_scenario_ids(task_file: str, task_id: str) -> set[str]:
+    text = Path(task_file).read_text(encoding="utf-8")
+    section = re.search(
+        rf"(?ms)^##\s+{re.escape(task_id)}:.*?(?=^##\s+TASK-|\Z)", text
+    )
+    if section is None:
+        raise ValueError(f"task_not_found: {task_id}")
+    refs = re.search(
+        r"(?m)^- \*\*Acceptance-Refs\*\*:[ \t]*([^\n]*)", section.group(0)
+    )
+    if refs is None:
+        return set()
+    return set(re.findall(r"\b(?:S|E|B)-\d+\b", refs.group(1)))
+
+
+def _item(row: Mapping[str, object]) -> dict[str, object]:
+    return {
+        **{field: row[field] for field in ("level", "env", "components", "steps", "expected", "expected_refs", "assertions",
+                                          "preconditions", "defer_reason", "defer_owner", "target_phase", "features", "tags")
+           if field in row},
+        "id": str(row.get("id", "")),
+        "title": str(row.get("title", "")),
+        "owner": row.get("owner") if isinstance(row.get("owner"), str) else "",
+        "priority": row.get("priority") if isinstance(row.get("priority"), str) else "",
+        "exec": row.get("exec") if isinstance(row.get("exec"), str) else "",
+        "boundary": str(row.get("boundary", "")),
+        "why_e2e": str(row.get("why_e2e", "")),
+        "trigger_paths": list(row.get("trigger_paths") or []),
+        "smoke": bool(row.get("smoke")),
+        "check": row.get("check") if isinstance(row.get("check"), str) else "",
+        "checks": scenario_check_ids(row),
+        "command": list(row.get("command") or []) if isinstance(row.get("command"), list) else [],
+    }
+
+
+def _quality_errors(items: list[dict[str, object]]) -> list[dict[str, object]]:
+    errors: list[dict[str, object]] = []
+    for item in items:
+        scenario_id = str(item.get("id", ""))
+        priority = str(item.get("priority", "")).upper()
+        if priority not in ("P0", "P1"):
+            errors.append({
+                "code": "e2e_priority_not_critical",
+                "scenario": scenario_id,
+                "message": "E2E 只允许 P0/P1 关键旅程；请改为 component/contract/integration。",
+            })
+        if not _meaningful(item.get("why_e2e")):
+            errors.append({
+                "code": "e2e_justification_missing",
+                "scenario": scenario_id,
+                "message": "E2E 必须说明为什么低层测试无法覆盖。",
+            })
+        if not _meaningful(item.get("boundary")):
+            errors.append({
+                "code": "e2e_boundary_missing",
+                "scenario": scenario_id,
+                "message": "E2E 必须声明真实边界。",
+            })
+        if str(item.get("exec", "")).lower() == "aspirational":
+            errors.append({
+                "code": "e2e_aspirational",
+                "scenario": scenario_id,
+                "message": "aspirational E2E 不能进入 TASK 执行范围。",
+            })
+        trigger_paths = [
+            str(path) for path in item.get("trigger_paths", []) or [] if _meaningful(path)
+        ]
+        if not item.get("smoke") and not trigger_paths:
+            errors.append({
+                "code": "e2e_trigger_paths_missing",
+                "scenario": scenario_id,
+                "message": "非 smoke E2E 必须声明触发路径，避免小改动跑全量。",
+            })
+    return errors
+
+
+def _group_scenarios(data: Mapping[str, object], owned_ids: set[str], task_id: str
+                     ) -> tuple[list[dict[str, object]], list[dict[str, object]], list[dict[str, object]]]:
+    owned: list[dict[str, object]] = []
+    smoke: list[dict[str, object]] = []
+    deferred: list[dict[str, object]] = []
+    for row in data.get("scenarios", []) or []:
+        if not isinstance(row, Mapping):
+            continue
+        kind = str(row.get("kind") or row.get("level") or "").lower()
+        if kind != "e2e":
+            continue
+        item = _item(row)
+        scenario_id = str(item["id"])
+        scenario_owner = str(item.get("owner") or "")
+        if scenario_id in owned_ids and (not scenario_owner or scenario_owner == task_id):
+            owned.append(item)
+        elif item["smoke"]:
+            smoke.append(item)
+        else:
+            deferred.append(item)
+    return owned, smoke, deferred
+
+
+def _scoped_quality(data: Mapping[str, object], scheduled: list[dict[str, object]], root: Path
+                    ) -> tuple[list[dict[str, object]], list[dict[str, object]], bool]:
+    errors = _quality_errors(scheduled)
+    warnings: list[dict[str, object]] = []
+    if data.get("scenarios_file"):
+        from codeflow.acceptance.cf_scenario_quality import quality_report
+        strict = [{**item, "level": "e2e", "owner": item.get("defer_owner") or item.get("owner", "")}
+                  for item in scheduled]
+        quality_errors = quality_report(strict)["errors"]
+        if data.get("quality_schema", 1) >= 2:
+            from codeflow.acceptance.cf_check_registration import validate_registration
+            errors = quality_errors + validate_registration(str(root), scheduled, data.get("checks", []))["errors"]
+        elif scheduled:
+            warnings.extend({**item, "code": f"legacy_{item['code']}"} for item in quality_errors)
+            warnings.append({"code": "legacy_quality_schema", "message":
+                "旧计划保留原 E2E 门禁；补齐 expected_refs/延期信息，运行 acceptance manifest --register-checks 重锁，"
+                "再用 --verify-plan 检查质量和测试登记。新质量检查尚未通过。"})
+    gate_required = data.get("e2e_gate") in (1, True, "required")
+    if errors and not gate_required:
+        # Existing projects upgraded mid-flight remain startable, but every
+        # legacy E2E is surfaced for re-planning instead of being silently
+        # treated as a scoped critical journey.
+        warnings.extend({**item, "code": f"legacy_{item['code']}"} for item in errors)
+        warnings.append({
+            "code": "legacy_e2e_plan",
+            "message": "旧 manifest 未声明 why_e2e/trigger_paths；先用 plan --verify-plan 重新锁定。",
+        })
+        errors = []
+    return errors, warnings, gate_required
+
+
+def build_e2e_plan(
+    manifest_file: str,
+    task_file: str,
+    task_id: str,
+    validate_baseline: bool = True,
+) -> dict[str, object]:
+    path = Path(manifest_file)
+    owned_ids = _task_scenario_ids(task_file, task_id)
+    if not path.is_file():
+        return {
+            "task": task_id,
+            "manifest": str(path),
+            "owned": [],
+            "smoke": [],
+            "scheduled": [],
+            "deferred_count": 0,
+            "deferred_ids": [],
+            "quality": {"ok": True, "errors": [], "warnings": [], "gate": "none"},
+        }
+    data = load_manifest(path)
+    if validate_baseline:
+        validate_execution_baseline(path, data)
+    owned, smoke, deferred = _group_scenarios(data, owned_ids, task_id)
+    # 延后场景不在编码阶段调度：由需求级 verify-e2e/人工门禁执行。
+    scheduled = [item for item in [*owned, *smoke] if item.get("exec") != "deferred"]
+    deferred.extend(item for item in [*owned, *smoke] if item.get("exec") == "deferred")
+    root = next((parent.parent for parent in path.parents if parent.name == ".code-flow"), path.parent)
+    errors, warnings, gate_required = _scoped_quality(data, scheduled, root)
+    if not scheduled:
+        warnings.append({
+            "code": "no_scheduled_e2e",
+            "message": "本 TASK 没有需要编写或执行的 E2E；不要把其他场景补进来。",
+        })
+    return {
+        "task": task_id,
+        "manifest": str(path),
+        "owned": owned,
+        "smoke": smoke,
+        "scheduled": scheduled,
+        "deferred_count": len(deferred),
+        "deferred_ids": [str(item["id"]) for item in deferred],
+        "quality": {
+            "ok": not errors,
+            "errors": errors,
+            "warnings": warnings,
+            "gate": "required" if gate_required else "legacy",
+        },
+    }

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

@@ -0,0 +1,60 @@
+"""Author check registration through real collection before locking a plan."""
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Mapping
+
+from codeflow.acceptance.cf_acceptance_schema import scenario_check_ids
+from codeflow.acceptance.cf_check_registration import (
+    REGISTRATION_FIELDS, CollectionError, register_check, registration_required,
+)
+
+
+class RegistrationError(ValueError):
+    def __init__(self, report: Mapping[str, object]) -> None:
+        self.report = dict(report)
+        super().__init__("check_registration_failed")
+
+
+def _overrides(file: str, ids: set[str]) -> dict[str, Mapping[str, object]]:
+    if not file:
+        return {}
+    data = json.loads(Path(file).read_text(encoding="utf-8"))
+    checks = data.get("checks") if isinstance(data, dict) else None
+    if not isinstance(checks, dict) or set(checks) - ids:
+        raise ValueError("registration_file_invalid_check_ids")
+    for check_id, config in checks.items():
+        if not isinstance(config, dict) or set(config) - set(REGISTRATION_FIELDS):
+            raise ValueError(f"registration_file_invalid_fields:{check_id}")
+    return checks
+
+
+def register_checks(manifest: dict[str, object], root: str, file: str = "") -> dict[str, object]:
+    checks = manifest.get("checks", [])
+    overrides = _overrides(file, {str(check["id"]) for check in checks})
+    report: dict[str, object] = {"ok": True, "registered": [], "errors": []}
+    deadline = time.monotonic() + 60
+    for check in checks:
+        check_id = str(check["id"])
+        rows = [row for row in manifest["scenarios"] if check_id in scenario_check_ids(row)
+                and (registration_required({**row, "level": check.get("level", row.get("level"))})
+                     or registration_required(row) or check_id in overrides)]
+        if not rows:
+            continue
+        check.update(overrides.get(check_id, {}))
+        try:
+            issues = register_check(root, check, rows, deadline)
+            if issues:
+                raise RegistrationError({"ok": False, "errors": issues})
+        except (OSError, ValueError) as exc:
+            details = exc.report if isinstance(exc, RegistrationError) else (
+                exc.details if isinstance(exc, CollectionError) else {})
+            report["errors"].append({"check_id": check_id, "error": str(exc), **details})
+        else:
+            report["registered"].append(check_id)
+    report["ok"] = not report["errors"]
+    if not report["ok"]:
+        raise RegistrationError(report)
+    return report

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

@@ -0,0 +1,73 @@
+"""User-confirmed risk acceptance, scoped to the owning TASK and scenarios."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import re
+from typing import Mapping, Optional
+
+from codeflow.acceptance.cf_acceptance_schema import scenario_check_ids
+
+AGENT_IDENTITIES = frozenset(("agent", "assistant", "claude", "claude code", "codex",
+                            "opencode", "costrict", "ai", "bot"))
+
+
+def risk_scenario_ids(data: Mapping[str, object], check_id: str, owner: str) -> list[str]:
+    """Resolve the locked plan's ownership; never accept a free-form owner."""
+    rows = data.get("scenarios", [])
+    if not isinstance(rows, list) or re.fullmatch(r"TASK-\d+", owner) is None:
+        return []
+    return sorted(str(row["id"]) for row in rows if isinstance(row, Mapping)
+                  and row.get("owner") == owner and row.get("id")
+                  and check_id in scenario_check_ids(row))
+
+
+def _matches_scenario(risk: Mapping[str, object], check: Mapping[str, object],
+                      scenario: Mapping[str, object]) -> bool:
+    if risk.get("owner") != scenario.get("owner"):
+        return False
+    if check.get("id") not in scenario_check_ids(scenario):
+        return False
+    ids = risk.get("scenario_ids")
+    scenario_id = scenario.get("scenario_ref") or scenario.get("id")
+    # Legacy records remain valid only for scenarios owned by the recorded TASK.
+    return ids is None or (isinstance(ids, list) and scenario_id in ids)
+
+
+def accepted_risk(check: Optional[Mapping[str, object]],
+                  scenario: Optional[Mapping[str, object]] = None) -> Optional[dict[str, object]]:
+    if not isinstance(check, Mapping) or not isinstance(check.get("accepted_risk"), Mapping):
+        return None
+    risk = check["accepted_risk"]
+    fields = ("owner", "reason", "confirmed_by", "confirmed_at", "source", "expires_at")
+    if any(not isinstance(risk.get(key), str) or not str(risk[key]).strip() for key in fields):
+        return None
+    if re.fullmatch(r"TASK-\d+", str(risk["owner"])) is None:
+        return None
+    if str(risk["confirmed_by"]).strip().lower().split(":", 1)[0] in AGENT_IDENTITIES:
+        return None
+    expires = str(risk["expires_at"]).strip()
+    try:
+        deadline = datetime.fromisoformat(expires.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if re.fullmatch(r"\d{4}-\d{2}-\d{2}", expires):
+        deadline = deadline.replace(hour=23, minute=59, second=59, microsecond=999999)
+    if deadline.tzinfo is None:
+        deadline = deadline.replace(tzinfo=timezone.utc)
+    if deadline <= datetime.now(timezone.utc):
+        return None
+    if scenario is not None and not _matches_scenario(risk, check, scenario):
+        return None
+    return dict(risk)
+
+
+def risk_counts(data: Mapping[str, object]) -> dict[str, int]:
+    checks, rows = data.get("checks", []), data.get("scenarios", [])
+    checks = checks if isinstance(checks, list) else []
+    rows = rows if isinstance(rows, list) else []
+    recorded = [check for check in checks if isinstance(check, Mapping)
+                and isinstance(check.get("accepted_risk"), Mapping)]
+    active = sum(any(accepted_risk(check, row) is not None for row in rows
+                     if isinstance(row, Mapping)) for check in recorded)
+    return {"accepted_risks": active, "recorded_risks": len(recorded),
+            "inactive_risks": len(recorded) - active}

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

@@ -0,0 +1,282 @@
+"""Validated acceptance records shared by execution and lifecycle gates."""
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+from typing import Mapping, Optional
+
+
+EXEC_MODES = ("auto", "manual", "deferred", "aspirational")
+
+
+def scenario_check_ids(row: Mapping[str, object]) -> list[str]:
+    """The plural mapping is authoritative when present and non-empty."""
+    checks = row.get("checks")
+    if isinstance(checks, list) and checks:
+        return list(dict.fromkeys(str(value) for value in checks))
+    check = row.get("check")
+    return [check] if isinstance(check, str) and check else []
+
+
+def recorded_check_hash(row: Mapping[str, object], check_id: str) -> str:
+    """Read one check's proof; never reuse an aggregate hash for many checks."""
+    evidence = row.get("evidence")
+    if not isinstance(evidence, Mapping):
+        return ""
+    hashes = evidence.get("check_hashes")
+    if isinstance(hashes, Mapping):
+        value = hashes.get(check_id)
+    elif scenario_check_ids(row) == [check_id]:
+        value = evidence.get("input_hash") or evidence.get("fingerprint")
+    else:
+        return ""
+    return value if isinstance(value, str) else ""
+
+
+def check_outcome(result: Mapping[str, object], check_id: str) -> Mapping[str, object]:
+    """Prefer the executed check's outcome over the enclosing scenario verdict."""
+    if "check_results" not in result:
+        return result  # Compatibility with evidence written before per-check outcomes.
+    outcomes = result.get("check_results")
+    outcome = outcomes.get(check_id) if isinstance(outcomes, Mapping) else None
+    shared = {key: value for key, value in result.items()
+              if key not in ("status", "exit_code", "risk", "error")}
+    return {**shared, "status": "incomplete", "exit_code": 1,
+            **(outcome if isinstance(outcome, Mapping) else {})}
+
+
+def verified_evidence(row: Mapping[str, object], fingerprint: str = "") -> bool:
+    evidence = row.get("evidence")
+    if row.get("status") != "verified" or not isinstance(evidence, dict):
+        return False
+    if row.get("kind") != "manual" and row.get("exec") != "manual":
+        if fingerprint and evidence.get("fingerprint") != fingerprint:
+            return False
+        return evidence.get("status") == "passed" and evidence.get("exit_code") == 0
+    author, detail = evidence.get("confirmed_by"), evidence.get("evidence")
+    agents = {"agent", "assistant", "codex", "claude", "opencode", "costrict"}
+    return (isinstance(author, str) and bool(author.strip())
+            and author.strip().lower().split(":", 1)[0] not in agents
+            and isinstance(detail, str) and bool(detail.strip()))
+
+
+def validate_scenarios(value: object) -> list[dict[str, object]]:
+    if not isinstance(value, list):
+        raise ValueError("invalid manifest scenarios: expected list")
+    seen: set[str] = set()
+    for item in value:
+        if not isinstance(item, dict):
+            raise ValueError("invalid scenario: expected object")
+        scenario_id = item.get("id")
+        if not isinstance(scenario_id, str) or not scenario_id.strip():
+            raise ValueError("scenario id missing")
+        if scenario_id in seen:
+            raise ValueError(f"duplicate scenario id: {scenario_id}")
+        seen.add(scenario_id)
+        for field in ("kind", "owner", "cwd"):
+            if field in item and not isinstance(item[field], str):
+                raise ValueError(f"invalid scenario {scenario_id}:{field}")
+        command = item.get("command")
+        if command is not None and (not isinstance(command, list) or not all(isinstance(x, str) for x in command)):
+            raise ValueError(f"invalid scenario {scenario_id}:command")
+        check = item.get("check")
+        if check is not None and not isinstance(check, str):
+            raise ValueError(f"invalid scenario {scenario_id}:check")
+        checks = item.get("checks")
+        if checks is not None and (not isinstance(checks, list) or not all(isinstance(x, str) for x in checks)):
+            raise ValueError(f"invalid scenario {scenario_id}:checks")
+        timeout = item.get("timeout", 60)
+        if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError(f"invalid scenario {scenario_id}:timeout")
+        deps = item.get("depends_on", [])
+        if not isinstance(deps, list) or not all(isinstance(x, str) for x in deps):
+            raise ValueError(f"invalid scenario {scenario_id}:depends_on")
+        if "runs" in item and not isinstance(item["runs"], list):
+            raise ValueError(f"invalid scenario {scenario_id}:runs")
+        revision = item.get("revision", 0)
+        if isinstance(revision, bool) or not isinstance(revision, int) or revision < 0:
+            raise ValueError(f"invalid scenario {scenario_id}:revision")
+        _validate_scenario_metadata(scenario_id, item)
+    for item in value:
+        unknown = set(item.get("depends_on", [])) - seen
+        if unknown:
+            raise ValueError(f"acceptance scenario dependency missing: {', '.join(sorted(unknown))}")
+    return value
+
+
+def _validate_scenario_metadata(scenario_id: str, item: Mapping[str, object]) -> None:
+    """Execution metadata mirrors design §2.5 and manifest v3 checks."""
+    priority = item.get("priority")
+    if priority is not None and (not isinstance(priority, str) or not priority.strip()):
+        raise ValueError(f"invalid scenario {scenario_id}:priority")
+    exec_mode = item.get("exec")
+    if exec_mode is not None and (not isinstance(exec_mode, str) or exec_mode not in EXEC_MODES):
+        raise ValueError(f"invalid scenario {scenario_id}:exec")
+    env = item.get("env")
+    if env is not None and (not isinstance(env, str) or not env.strip()):
+        raise ValueError(f"invalid scenario {scenario_id}:env")
+    inputs = item.get("inputs")
+    if inputs is not None and (
+        not isinstance(inputs, list) or not all(isinstance(value, str) and value for value in inputs)
+    ):
+        raise ValueError(f"invalid scenario {scenario_id}:inputs")
+    why_e2e = item.get("why_e2e")
+    if why_e2e is not None and not isinstance(why_e2e, str):
+        raise ValueError(f"invalid scenario {scenario_id}:why_e2e")
+    trigger_paths = item.get("trigger_paths")
+    if trigger_paths is not None and (
+        not isinstance(trigger_paths, list)
+        or not all(isinstance(value, str) and value for value in trigger_paths)
+    ):
+        raise ValueError(f"invalid scenario {scenario_id}:trigger_paths")
+    smoke = item.get("smoke")
+    if smoke is not None and not isinstance(smoke, bool):
+        raise ValueError(f"invalid scenario {scenario_id}:smoke")
+    _validate_contract_metadata(scenario_id, item)
+
+
+def _validate_contract_metadata(scenario_id: str, item: Mapping[str, object]) -> None:
+    if "expected_checks" in item:
+        from codeflow.acceptance.cf_scenario_quality import validate_expected_checks
+        validate_expected_checks(item)
+    for field in ("components", "steps", "expected", "assertions", "preconditions", "features", "tags"):
+        if field in item and (not isinstance(item[field], list) or not all(isinstance(value, str) for value in item[field])):
+            raise ValueError(f"invalid scenario {scenario_id}:{field}")
+    for field in ("defer_reason", "defer_owner", "target_phase"):
+        if field in item and not isinstance(item[field], str):
+            raise ValueError(f"invalid scenario {scenario_id}:{field}")
+    refs = item.get("expected_refs", [])
+    if not isinstance(refs, list) or not all(isinstance(value, Mapping) for value in refs):
+        raise ValueError(f"invalid scenario {scenario_id}:expected_refs")
+
+
+def validate_checks(value: object) -> list[dict[str, object]]:
+    """Validate the manifest v3 checks array (execution identity)."""
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        raise ValueError("invalid manifest checks: expected list")
+    seen: set[str] = set()
+    for item in value:
+        if not isinstance(item, dict):
+            raise ValueError("invalid check: expected object")
+        check_id = item.get("id")
+        if not isinstance(check_id, str) or not check_id.strip():
+            raise ValueError("check id missing")
+        if check_id in seen:
+            raise ValueError(f"duplicate check id: {check_id}")
+        seen.add(check_id)
+        command = item.get("command")
+        if not isinstance(command, list) or not command or not all(isinstance(x, str) for x in command):
+            raise ValueError(f"invalid check {check_id}:command")
+        cwd = item.get("cwd", ".")
+        if not isinstance(cwd, str):
+            raise ValueError(f"invalid check {check_id}:cwd")
+        timeout = item.get("timeout", 60)
+        if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError(f"invalid check {check_id}:timeout")
+        _validate_check_environment(check_id, item)
+        _validate_check_registration(check_id, item)
+    return value
+
+
+def validate_check_levels(scenarios: list[dict[str, object]], checks: list[dict[str, object]]) -> None:
+    """A mixed-level composition must declare every member's level."""
+    by_id = {str(check["id"]): check for check in checks}
+    for row in scenarios:
+        members = [by_id[check_id] for check_id in scenario_check_ids(row) if check_id in by_id]
+        levels = {str(check.get("level") or row.get("level") or "") for check in members}
+        if len(levels) > 1 and any("level" not in check for check in members):
+            raise ValueError(f"scenario {row.get('id')} mixed checks require explicit levels")
+
+
+def _validate_check_registration(check_id: str, item: Mapping[str, object]) -> None:
+    from codeflow.acceptance.cf_scenario_source import LEVELS
+    if "level" in item and (not isinstance(item["level"], str) or item["level"] not in LEVELS):
+        raise ValueError(f"invalid check {check_id}:level")
+    if "suite" in item and item["suite"] not in ("unit", "component", "contract", "integration", "system", "browser", "capacity"):
+        raise ValueError(f"invalid check {check_id}:suite")
+    for field in ("test_ids", "markers"):
+        if field not in item:
+            continue
+        values = item[field]
+        if not isinstance(values, list) or not all(isinstance(value, str) and value.strip() for value in values):
+            raise ValueError(f"invalid check {check_id}:{field}")
+        if len(values) != len(set(values)):
+            raise ValueError(f"duplicate check {check_id}:{field}")
+    if "collect" in item and not isinstance(item["collect"], Mapping):
+        raise ValueError(f"invalid check {check_id}:collect")
+
+
+_ENV_SCOPES = ("shared", "isolated")
+
+
+def _validate_check_environment(check_id: str, item: Mapping[str, object]) -> None:
+    """env/env_scope/preflight/parallel_safe describe how a check may run."""
+    env = item.get("env", "none")
+    if not isinstance(env, str) or not env.strip():
+        raise ValueError(f"invalid check {check_id}:env")
+    revision = item.get("environment_revision")
+    if revision is not None and (not isinstance(revision, str) or not revision.strip()):
+        raise ValueError(f"invalid check {check_id}:environment_revision")
+    ttl = item.get("evidence_ttl_seconds")
+    if ttl is not None and (isinstance(ttl, bool) or not isinstance(ttl, (int, float))
+                            or not math.isfinite(ttl) or ttl <= 0):
+        raise ValueError(f"invalid check {check_id}:evidence_ttl_seconds")
+    scope = item.get("env_scope", "shared")
+    if not isinstance(scope, str) or scope not in _ENV_SCOPES:
+        raise ValueError(f"invalid check {check_id}:env_scope")
+    if "parallel_safe" in item and not isinstance(item["parallel_safe"], bool):
+        raise ValueError(f"invalid check {check_id}:parallel_safe")
+    preflight = item.get("preflight", [])
+    if not isinstance(preflight, list):
+        raise ValueError(f"invalid check {check_id}:preflight")
+    for entry in preflight:
+        if isinstance(entry, str):
+            if not entry.strip():
+                raise ValueError(f"invalid check {check_id}:preflight")
+        elif isinstance(entry, list):
+            if not entry or not all(isinstance(token, str) and token for token in entry):
+                raise ValueError(f"invalid check {check_id}:preflight")
+        else:
+            raise ValueError(f"invalid check {check_id}:preflight")
+    paths = item.get("paths")
+    if paths is not None and (
+        not isinstance(paths, list)
+        or not all(isinstance(path, str) and path.strip() for path in paths)
+    ):
+        raise ValueError(f"invalid check {check_id}:paths")
+
+
+def load_manifest(path: Path, *, text: Optional[str] = None) -> dict[str, object]:
+    data = json.loads(path.read_text(encoding="utf-8") if text is None else text)
+    if not isinstance(data, dict):
+        raise ValueError("invalid acceptance manifest: expected object")
+    quality_schema = data.get("quality_schema", 1)
+    if type(quality_schema) is not int or quality_schema not in (1, 2):
+        raise ValueError(f"unsupported acceptance quality_schema: {quality_schema!r}")
+    validate_scenarios(data.get("scenarios"))
+    if "checks" in data:
+        validate_checks(data.get("checks"))
+        validate_check_levels(data["scenarios"], data["checks"])
+    check_ids = {
+        item.get("id") for item in data.get("checks", [])
+        if isinstance(item, dict)
+    } if isinstance(data.get("checks"), list) else set()
+    for scenario in data.get("scenarios", []):
+        if not isinstance(scenario, dict):
+            continue
+        single = scenario.get("check")
+        if isinstance(single, str) and single and single not in check_ids:
+            raise ValueError(f"scenario {scenario.get('id')} references missing check: {single}")
+        multiple = scenario.get("checks")
+        if isinstance(multiple, list):
+            unknown = [str(value) for value in multiple if str(value) not in check_ids]
+            if unknown:
+                raise ValueError(
+                    f"scenario {scenario.get('id')} references missing checks: {', '.join(unknown)}"
+                )
+    if "task_file" in data and not isinstance(data["task_file"], str):
+        raise ValueError("invalid acceptance manifest: task_file")
+    return data