@michaelxwb/code-flow 0.6.2 → 0.6.4

package/src/core/code-flow/scripts/cf_acceptance_manifest.py

@@ -6,14 +6,19 @@ from __future__ import annotations
 import argparse
 import hashlib
 import json
+import shlex
 from pathlib import Path
 import re
 import sys
-from typing import IO, Mapping, Optional, Sequence
+from typing import IO, Callable, Mapping, Optional, Sequence
+
+from cf_acceptance_schema import load_manifest, validate_scenarios
 
 
 _ROW_RE = re.compile(r"^\|\s*([SEB]-\d+)\s*\|(.+?)\|$")
 
+_MANIFEST_SCHEMA = 2
+
 
 def _kind(level: str) -> str:
     """Map test level to execution kind.
@@ -21,25 +26,70 @@ def _kind(level: str) -> str:
     - functional: auto-executed in Done Gate (unit, integration)
     - e2e: deferred until explicit --verify-e2e (needs external dependencies)
     - manual: user confirmation required, never auto-executed
+
+    层级单元格允许带注解（如 `E2E（Playwright）`、`e2e/chrome`、`manual(chrome)`），
+    取分隔符前的词元判定；避免带注解的 E2E 被误判为 functional 而每任务执行。
     """
-    normalized = level.strip().lower()
-    if normalized == "manual":
+    head = level.strip().lower()
+    for separator in ("(", "（", "[", "/", ",", "，", " ", "—", "-"):
+        head = head.split(separator, 1)[0]
+    head = head.strip()
+    if head in ("manual", "手工", "手动"):
         return "manual"
-    if normalized == "e2e":
-        return "e2e"  # Keep as separate kind, not functional
+    if head in ("e2e", "端到端", "end"):
+        return "e2e"
     return "functional"
 
 
-def _manifest_hash(rows: list[dict[str, str]]) -> str:
-    immutable = [{key: item[key] for key in ("id", "source", "level", "kind", "boundary", "owner")} for item in rows]
+def _parse_command(cell: str, scenario_id: str) -> Optional[list[str]]:
+    """Parse the optional 命令 column: argv JSON array preferred, else shell words.
+
+    Empty / `-` / `planned` → None (not yet registered, not executable).
+    """
+    text = (cell or "").strip()
+    if not text or text in {"-", "planned", "pending", "TBD", "tbd"}:
+        return None
+    if text.startswith("["):
+        try:
+            value = json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"{scenario_id} 命令列不是合法 argv JSON: {exc}") from exc
+        if not isinstance(value, list) or not value or not all(isinstance(item, str) for item in value):
+            raise ValueError(f"{scenario_id} 命令列必须是 argv 字符串数组")
+        return list(value)
+    return shlex.split(text)
+
+
+def _parse_float(cell: str, default: float) -> float:
+    try:
+        return float((cell or "").strip() or default)
+    except (TypeError, ValueError):
+        return default
+
+
+def _manifest_hash(rows: list[dict[str, object]]) -> str:
+    immutable = [
+        {key: item[key] for key in ("id", "source", "level", "kind", "boundary", "owner", "command", "cwd", "timeout", "depends_on")}
+        for item in rows
+    ]
     payload = json.dumps(immutable, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
     return hashlib.sha256(payload).hexdigest()
 
 
-def extract_manifest(task_file: str) -> dict[str, object]:
+def _legacy_kind(level: str) -> str:
+    """v1 精确匹配：仅用于识别旧版锁定的 manifest，不做新语义判定。"""
+    normalized = level.strip().lower()
+    if normalized == "manual":
+        return "manual"
+    if normalized == "e2e":
+        return "e2e"
+    return "functional"
+
+
+def _extract_rows(task_file: str, kind_fn: Callable[[str], str]) -> dict[str, object]:
     path = Path(task_file)
     text = path.read_text(encoding="utf-8")
-    rows: list[dict[str, str]] = []
+    rows: list[dict[str, object]] = []
     in_table = False
     seen: set[str] = set()
     for line in text.splitlines():
@@ -54,13 +104,33 @@ def extract_manifest(task_file: str) -> dict[str, object]:
         if not match or set(match.group(2).replace("|", "").strip()) <= {"-", " "}:
             continue
         fields = [item.strip() for item in match.group(2).split("|")]
-        if len(fields) < 5 or match.group(1) in seen:
-            continue
+        if match.group(1) in seen:
+            raise ValueError(f"duplicate scenario id: {match.group(1)}")
+        if len(fields) < 5:
+            raise ValueError(f"Acceptance Coverage missing columns: {match.group(1)}")
         seen.add(match.group(1))
-        rows.append({"id": match.group(1), "source": fields[0], "level": fields[1], "kind": _kind(fields[1]), "boundary": fields[2], "owner": fields[3], "status": fields[4]})
+        depends = [item.strip() for item in (fields[8] if len(fields) > 8 else "").split(",") if item.strip()]
+        rows.append({
+            "id": match.group(1),
+            "source": fields[0],
+            "level": fields[1],
+            "kind": kind_fn(fields[1]),
+            "boundary": fields[2],
+            "owner": fields[3],
+            "status": fields[4],
+            "command": _parse_command(fields[5], match.group(1)) if len(fields) > 5 else None,
+            "cwd": (fields[6] if len(fields) > 6 else "").strip() or ".",
+            "timeout": _parse_float(fields[7], 60.0) if len(fields) > 7 else 60.0,
+            "depends_on": depends,
+        })
     if not rows:
         raise ValueError("Acceptance Coverage 缺失或为空")
-    return {"schema": 1, "task_file": str(path), "task_sha256": _manifest_hash(rows), "scenarios": rows}
+    validate_scenarios(rows)
+    return {"schema": _MANIFEST_SCHEMA, "task_file": str(path), "task_sha256": _manifest_hash(rows), "scenarios": rows}
+
+
+def extract_manifest(task_file: str, kind_fn: Callable[[str], str] = _kind) -> dict[str, object]:
+    return _extract_rows(task_file, kind_fn)
 
 
 def write_manifest(task_file: str, output: str) -> dict[str, object]:
@@ -75,24 +145,69 @@ def write_manifest(task_file: str, output: str) -> dict[str, object]:
     return manifest
 
 
+_IMMUTABLE_SCENARIO_FIELDS = (
+    "id", "source", "level", "kind", "boundary", "owner", "command", "cwd", "timeout", "depends_on",
+)
+
+
+def _heal_legacy_kinds(manifest_file: Path, manifest: dict[str, object], expected: dict[str, object]) -> None:
+    """旧版 `_kind` 精确匹配把带注解的 E2E 锁成 functional；任务内容未变时
+    原地升级 kind 并重锁哈希，保留 execution evidence 等运行态字段。"""
+    by_id: dict[str, dict[str, object]] = {}
+    scenarios = expected.get("scenarios")
+    if isinstance(scenarios, list):
+        for item in scenarios:
+            if isinstance(item, dict) and isinstance(item.get("id"), str):
+                by_id[item["id"]] = item
+    current = manifest.get("scenarios")
+    if isinstance(current, list):
+        for item in current:
+            if not isinstance(item, dict):
+                continue
+            target = by_id.get(item.get("id")) if isinstance(item.get("id"), str) else None
+            if target is not None:
+                item["kind"] = target.get("kind")
+    manifest["task_sha256"] = expected["task_sha256"]
+    manifest_file.write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
 def validate_manifest(task_file: str, manifest_file: str) -> tuple[bool, str]:
     try:
-        manifest = json.loads(Path(manifest_file).read_text(encoding="utf-8"))
+        manifest = load_manifest(Path(manifest_file))
         expected = extract_manifest(task_file)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
         return False, f"acceptance_manifest_invalid: {exc}"
-    if manifest.get("schema") != 1 or manifest.get("task_sha256") != expected["task_sha256"]:
+    if manifest.get("schema") != _MANIFEST_SCHEMA:
         return False, "acceptance_manifest_drift"
-    actual = {item.get("id") for item in manifest.get("scenarios", []) if isinstance(item, Mapping)}
+    if manifest.get("task_sha256") != expected["task_sha256"]:
+        legacy = extract_manifest(task_file, _legacy_kind)
+        if manifest.get("task_sha256") != legacy["task_sha256"]:
+            return False, "acceptance_manifest_drift"
+        _heal_legacy_kinds(Path(manifest_file), manifest, expected)
+    stored_task = manifest.get("task_file", "")
+    if not stored_task or (Path(manifest_file).parent / stored_task).resolve() != Path(task_file).resolve():
+        return False, "acceptance_manifest_task_mismatch"
+    if not isinstance(manifest.get("scenarios"), list):
+        return False, "acceptance_manifest_scenarios_changed"
+    stored = {
+        item.get("id"): item
+        for item in manifest["scenarios"]
+        if isinstance(item, Mapping) and isinstance(item.get("id"), str)
+    }
     required = {item["id"] for item in expected["scenarios"]}
-    if actual != required:
+    if set(stored) != required:
         return False, "acceptance_manifest_scenarios_changed"
+    for item in expected["scenarios"]:
+        current = stored[item["id"]]
+        for field in _IMMUTABLE_SCENARIO_FIELDS:
+            if current.get(field) != item.get(field):
+                return False, f"acceptance_manifest_field_changed:{item['id']}:{field}"
     text = Path(task_file).read_text(encoding="utf-8")
     for scenario in expected["scenarios"]:
         owner = scenario["owner"]
         section = re.search(rf"(?ms)^##\s+{re.escape(owner)}:.*?(?=^##\s+TASK-|\Z)", text)
-        refs = section.group(0).partition("Acceptance-Refs")[2] if section else ""
-        if scenario["id"] not in refs:
+        refs = re.search(r"(?m)^- \*\*Acceptance-Refs\*\*:[ \t]*([^\n]*)", section.group(0)) if section else None
+        if not refs or scenario["id"] not in re.findall(r"\b[SEB]-\d+\b", refs.group(1)):
             return False, "acceptance_manifest_owner_missing"
     return True, ""
 
@@ -101,7 +216,7 @@ def record_manual_evidence(manifest_file: str, scenario_id: str, confirmed_by: s
     if not confirmed_by or confirmed_by.lower().split(":", 1)[0] in {"agent", "assistant", "codex", "claude", "opencode", "costrict"}:
         raise ValueError("manual evidence must be confirmed by a user")
     path = Path(manifest_file)
-    data = json.loads(path.read_text(encoding="utf-8"))
+    data = load_manifest(path)
     scenarios = data.get("scenarios")
     if not isinstance(scenarios, list):
         raise ValueError("invalid manifest scenarios")
@@ -127,28 +242,8 @@ def record_manual_evidence(manifest_file: str, scenario_id: str, confirmed_by: s
 
 
 def _sync_task_evidence(task_file: Path, scenario_id: str, confirmed_by: str, evidence: str, owner: str = "") -> None:
-    text = task_file.read_text(encoding="utf-8")
-    if owner:
-        section_match = re.search(rf"(?ms)^##\s+{re.escape(owner)}:.*?(?=^##\s+TASK-|\Z)", text)
-    else:
-        section_match = re.search(r"(?ms)^##\s+TASK-\d+:.*?(?=^##\s+TASK-|\Z)", text)
-    if section_match is None:
-        return
-    section = section_match.group(0)
-    line = f"- {scenario_id}: verified — {evidence} (confirmed_by: {confirmed_by})"
-    contract_match = re.search(r"(?ms)^### Acceptance Contract\s*$\n(.*?)(?=^### |^## |\Z)", section)
-    if contract_match and scenario_id in contract_match.group(1) and "verified" not in contract_match.group(1).lower():
-        body = contract_match.group(1)
-        body = "\n".join((f"{item} — verified" if scenario_id in item else item) for item in body.splitlines())
-        section = section[:contract_match.start(1)] + body + section[contract_match.end(1):]
-    evidence_match = re.search(r"(?ms)^### Acceptance Evidence\s*$\n(.*?)(?=^### |^## |\Z)", section)
-    if evidence_match:
-        body = evidence_match.group(1)
-        replacement = body.rstrip() + "\n" + line + "\n"
-        section = section[:evidence_match.start(1)] + replacement + section[evidence_match.end(1):]
-    else:
-        section = section.rstrip() + "\n\n### Acceptance Evidence\n" + line + "\n"
-    task_file.write_text(text[:section_match.start()] + section + text[section_match.end():], encoding="utf-8")
+    from cf_acceptance_evidence import sync_task_evidence
+    sync_task_evidence(task_file, scenario_id, confirmed_by, evidence, owner)
 
 
 def main(argv: Optional[Sequence[str]] = None, stdout: IO[str] = sys.stdout) -> int:

package/src/core/code-flow/scripts/cf_acceptance_runner.py

@@ -6,17 +6,25 @@ from __future__ import annotations
 import argparse
 import json
 from pathlib import Path
-import subprocess
 import sys
 from typing import IO, Mapping, Optional, Sequence
 
+from cf_exec_base import execution_key, run_command, invalidate_executions
+from cf_acceptance_schema import load_manifest, validate_execution_baseline
+from cf_acceptance_evidence import persist_results
 
-def _run(item: Mapping[str, object], root: Path, include_e2e: bool = False) -> dict[str, object]:
+
+def _run(
+    item: Mapping[str, object], root: Path, include_e2e: bool = False, deadline: Optional[float] = None,
+    only_e2e: bool = False,
+) -> dict[str, object]:
     scenario_id = str(item.get("id", "unknown"))
     kind = str(item.get("kind", "functional"))
+    if only_e2e and kind != "e2e":
+        return {"id": scenario_id, "kind": kind, "status": "not_included"}
     if kind == "manual":
         return {"id": scenario_id, "kind": kind, "status": "manual_pending"}
-    if kind == "e2e" and not include_e2e:
+    if kind == "e2e" and not include_e2e and not only_e2e:
         return {"id": scenario_id, "kind": kind, "status": "e2e_deferred"}
     command = item.get("command")
     if not isinstance(command, list) or not command or not all(isinstance(value, str) for value in command):
@@ -24,13 +32,18 @@ def _run(item: Mapping[str, object], root: Path, include_e2e: bool = False) -> d
     timeout = item.get("timeout", 60)
     timeout_value = float(timeout) if isinstance(timeout, (int, float)) else 60.0
     cwd = item.get("cwd", ".") if isinstance(item.get("cwd", "."), str) else "."
-    try:
-        result = subprocess.run(command, cwd=str(root / cwd), capture_output=True, timeout=timeout_value, check=False)
-    except subprocess.TimeoutExpired:
-        return {"id": scenario_id, "kind": kind, "status": "failed", "error": "timeout"}
-    except OSError as exc:
-        return {"id": scenario_id, "kind": kind, "status": "failed", "error": str(exc)}
-    return {"id": scenario_id, "kind": kind, "status": "passed" if result.returncode == 0 else "failed", "exit_code": result.returncode}
+    outcome = run_command(command, str(root / cwd), timeout_value, deadline)
+    if outcome["status"] == "deadline_exceeded":
+        return {"id": scenario_id, "kind": kind, "status": "incomplete", "error": "deadline_exceeded"}
+    if outcome["status"] == "timeout":
+        return {"id": scenario_id, "kind": kind, "status": "failed", "error": "timeout",
+                "output": str(outcome.get("stdout", ""))}
+    if outcome["status"] == "spawn_error":
+        return {"id": scenario_id, "kind": kind, "status": "failed", "error": str(outcome.get("stderr", ""))}
+    if outcome["returncode"] == 0:
+        return {"id": scenario_id, "kind": kind, "status": "passed", "exit_code": 0}
+    output = (str(outcome.get("stdout", "")) + str(outcome.get("stderr", ""))).strip()[-4000:]
+    return {"id": scenario_id, "kind": kind, "status": "failed", "exit_code": outcome["returncode"], "output": output}
 
 
 def _ordered(items: list[Mapping[str, object]]) -> list[Mapping[str, object]]:
@@ -56,35 +69,104 @@ def _ordered(items: list[Mapping[str, object]]) -> list[Mapping[str, object]]:
     return ordered
 
 
-def run_manifest(manifest_file: str, root: str, write_evidence: bool = False, include_e2e: bool = False) -> dict[str, object]:
-    data = json.loads(Path(manifest_file).read_text(encoding="utf-8"))
-    scenarios = data.get("scenarios", [])
-    if not isinstance(scenarios, list):
-        raise ValueError("invalid scenarios")
-    items = [item for item in scenarios if isinstance(item, Mapping)]
+def _executable(items: list[Mapping[str, object]]) -> bool:
+    """Draft completeness vs execution gate: at least one scenario must be
+    executable — a functional scenario with a registered command, or a
+    manual / e2e scenario with its own confirmation/deferral path. Zero
+    executable scenarios must block execution acceptance, never pass it."""
+    for item in items:
+        command = item.get("command")
+        if isinstance(command, list) and command and all(isinstance(value, str) for value in command):
+            return True
+        if str(item.get("kind", "")) in ("manual", "e2e"):
+            return True
+    return False
+
+
+def _owned(items: list[Mapping[str, object]], owner: str) -> list[Mapping[str, object]]:
+    """Keep scenarios owned by the active TASK; ownerless legacy scenarios stay
+    included so old manifests keep working. Cross-TASK depends_on edges are
+    pruned: single-TASK ordering is enforced here, whole-demand ordering at
+    the final (archive/E2E) gate."""
+    if not owner:
+        return items
+    kept = [
+        item for item in items
+        if not isinstance(item.get("owner"), str) or not item.get("owner") or item.get("owner") == owner
+    ]
+    kept_ids = {str(item.get("id")) for item in kept}
+    pruned: list[Mapping[str, object]] = []
+    for item in kept:
+        if not isinstance(item, dict):
+            pruned.append(item)
+            continue
+        deps = item.get("depends_on")
+        if isinstance(deps, list):
+            item = {**item, "depends_on": [dep for dep in deps if str(dep) in kept_ids]}
+        pruned.append(item)
+    return pruned
+
+
+def _run_unique(
+    ordered: list[Mapping[str, object]], root: Path, include_e2e: bool, deadline: Optional[float] = None,
+    only_e2e: bool = False,
+) -> list[dict[str, object]]:
+    """Reuse identical execution semantics within a dependency-free batch."""
+    cache: dict[str, Mapping[str, object]] = {}
+    results: list[dict[str, object]] = []
+    for item in ordered:
+        scenario_id = str(item.get("id", "unknown"))
+        command = item.get("command")
+        key: Optional[str] = None
+        if isinstance(command, list) and command and all(isinstance(value, str) for value in command):
+            key = execution_key(command, str(root / str(item.get("cwd", "."))), float(item.get("timeout", 60)))
+            key += json.dumps([item.get("kind", "functional"), include_e2e, only_e2e])
+        if item.get("depends_on"):
+            cache.clear()
+            invalidate_executions()
+        if key is not None and key in cache:
+            shared = dict(cache[key])
+            shared["id"] = scenario_id
+            results.append(shared)
+            continue
+        result = _run(item, root, include_e2e, deadline, only_e2e)
+        if key is not None:
+            cache[key] = result
+        results.append(result)
+    return results
+
+
+def run_manifest(
+    manifest_file: str,
+    root: str,
+    write_evidence: bool = False,
+    include_e2e: bool = False,
+    owner: str = "",
+    deadline: Optional[float] = None,
+    only_e2e: bool = False,
+) -> dict[str, object]:
+    data = load_manifest(Path(manifest_file))
+    validate_execution_baseline(Path(manifest_file), data)
+    scenarios = data["scenarios"]
+    _ordered(scenarios)  # Validate the complete DAG before owner filtering.
+    items = _owned(scenarios, owner)
     ordered = _ordered(items)
-    results = [_run(item, Path(root), include_e2e) for item in ordered]
-    configured = any(isinstance(item.get("command"), list) for item in items)
-    allowed = ("passed", "manual_pending", "e2e_deferred", "not_configured") if not configured else ("passed", "manual_pending", "e2e_deferred")
-    decision = "pass" if all(item["status"] in allowed for item in results) else "block"
+    results = _run_unique(ordered, Path(root), include_e2e or only_e2e, deadline, only_e2e)
     if write_evidence:
-        for item, result in zip(ordered, results):
-            if isinstance(item, dict) and result["status"] == "passed":
-                item["status"] = "verified"
-                item["evidence"] = result
-        Path(manifest_file).write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
-        task_file = data.get("task_file")
-        if isinstance(task_file, str) and task_file:
-            from cf_acceptance_manifest import _sync_task_evidence
-
-            task_path = Path(task_file)
-            if not task_path.is_absolute():
-                task_path = Path(manifest_file).parent / task_path
-            for item, result in zip(ordered, results):
-                if result["status"] == "passed":
-                    owner = item.get("owner") if isinstance(item.get("owner"), str) else ""
-                    _sync_task_evidence(task_path, str(result["id"]), "runner", "automated command passed", owner)
-    return {"decision": decision, "results": results}
+        persist_results(Path(manifest_file), data, results)
+    if not _executable(items):
+        return {"decision": "block", "results": results, "error": "no_executable_scenarios"}
+    allowed = ("passed", "manual_pending", "e2e_deferred", "not_included")
+    decision = "pass" if all(item["status"] in allowed for item in results) else "block"
+    error = ""
+    if decision == "block":
+        pending = sorted({str(item["id"]) for item in results if item["status"] == "incomplete"})
+        failed = sorted({str(item["id"]) for item in results if item["status"] not in (*allowed, "incomplete")})
+        error = ",".join((["incomplete:" + ",".join(pending)] if pending else []) + (["failed:" + ",".join(failed)] if failed else [])) or "acceptance scenario failed"
+    outcome: dict[str, object] = {"decision": decision, "results": results}
+    if error:
+        outcome["error"] = error
+    return outcome
 
 
 def main(argv: Optional[Sequence[str]] = None, stdout: IO[str] = sys.stdout) -> int:
@@ -93,9 +175,12 @@ def main(argv: Optional[Sequence[str]] = None, stdout: IO[str] = sys.stdout) ->
     parser.add_argument("--root", required=True)
     parser.add_argument("--write-evidence", action="store_true")
     parser.add_argument("--include-e2e", action="store_true", help="Execute E2E scenarios (deferred by default)")
+    parser.add_argument("--only-e2e", action="store_true", help="Execute only E2E scenarios; functional/manual are reported not_included")
+    parser.add_argument("--owner", default="", help="Only execute scenarios owned by this TASK (plus ownerless legacy ones)")
+    parser.add_argument("--deadline", type=float, default=0.0, help="Absolute monotonic deadline propagated from the entry gate (0 = unbounded)")
     args = parser.parse_args(argv)
     try:
-        result = run_manifest(args.manifest, args.root, args.write_evidence, args.include_e2e)
+        result = run_manifest(args.manifest, args.root, args.write_evidence, args.include_e2e, args.owner, args.deadline or None, args.only_e2e)
         stdout.write(json.dumps(result, ensure_ascii=False))
         return 0 if result["decision"] == "pass" else 3
     except (OSError, ValueError, json.JSONDecodeError) as exc:

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

@@ -0,0 +1,83 @@
+"""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
+
+
+def verified_evidence(row: Mapping[str, object]) -> bool:
+    evidence = row.get("evidence")
+    if row.get("status") != "verified" or not isinstance(evidence, dict):
+        return False
+    if row.get("kind") != "manual":
+        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")
+        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")
+    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 load_manifest(path: Path) -> dict[str, object]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError("invalid acceptance manifest: expected object")
+    validate_scenarios(data.get("scenarios"))
+    if "task_file" in data and not isinstance(data["task_file"], str):
+        raise ValueError("invalid acceptance manifest: task_file")
+    return data
+
+
+def validate_execution_baseline(path: Path, data: Mapping[str, object]) -> None:
+    """Legacy standalone manifests remain usable; locked plans must match."""
+    task_name = data.get("task_file")
+    if not isinstance(task_name, str) or not task_name:
+        return
+    task = Path(task_name)
+    task = task if task.is_absolute() else path.parent / task
+    if not task.is_file():
+        raise ValueError(f"acceptance task file missing: {task}")
+    if "## Acceptance Coverage" in task.read_text(encoding="utf-8"):
+        from cf_acceptance_manifest import validate_manifest
+        valid, reason = validate_manifest(str(task), str(path))
+        if not valid:
+            raise ValueError(reason)

package/src/core/code-flow/scripts/cf_core.py

@@ -13,6 +13,12 @@ _effective_mapping_cache: dict = {}
 _ext_set_cache: dict = {}
 
 
+def project_instruction_file(project_root: str, platform: str = "") -> str:
+    """Select the installed platform's instruction file, with legacy fallback."""
+    names = ("CLAUDE.md", "AGENTS.md") if platform in ("claude", "costrict") else ("AGENTS.md", "CLAUDE.md")
+    return next((name for name in names if os.path.isfile(os.path.join(project_root, name))), names[0])
+
+
 def load_config(project_root: str) -> dict:
     config_path = os.path.join(project_root, ".code-flow", "config.yml")
     if not os.path.exists(config_path):
@@ -49,6 +55,31 @@ def normalize_path(path: str) -> str:
     return path.replace("\\", "/")
 
 
+def effective_project_root(project_root: str, absolute_path: str) -> str:
+    """Resolve the project root that owns an edited file.
+
+    Parallel subagents edit `.code-flow/worktrees/<run>/<TASK>/...`; the nearest
+    `.code-flow` ancestor is that worktree's root, not the session root. Files
+    outside the session root and unresolvable paths fall back to `project_root`.
+    Lexical `abspath` (not `realpath`) keeps caller/returned paths in the same
+    coordinates (macOS /var ↔ /private/var symlink).
+    """
+    root = os.path.abspath(project_root)
+    target = os.path.abspath(absolute_path) if absolute_path else root
+    if target != root and not target.startswith(root + os.sep):
+        return root
+    current = target
+    while True:
+        if os.path.isdir(os.path.join(current, ".code-flow")):
+            return current
+        if current == root:
+            return root
+        parent = os.path.dirname(current)
+        if parent == current:
+            return root
+        current = parent
+
+
 def _spec_path_from_entry(entry) -> str:
     cfg = normalize_spec_entry(entry)
     return normalize_path(cfg.get("path", ""))
@@ -468,7 +499,8 @@ def resolve_quality_loop(config: dict) -> dict:
     """
     if not isinstance(config, dict):
         return {"enabled": False, "post_check": False,
-                "stop_check": False, "correction_capture": False,
+                "stop_check": False, "finish_check": False,
+                "correction_capture": False,
                 "compress_reminder": False}
     cfg = config.get("quality_loop")
     cfg = cfg if isinstance(cfg, dict) else {}
@@ -481,6 +513,7 @@ def resolve_quality_loop(config: dict) -> dict:
         "enabled": enabled,
         "post_check": _sub("post_check"),
         "stop_check": _sub("stop_check"),
+        "finish_check": _sub("finish_check"),
         "correction_capture": _sub("correction_capture"),
         "compress_reminder": _sub("compress_reminder"),
     }