@guanlin4924/devflow-pi 0.1.19 → 0.1.20

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/tdd_evidence.py

@@ -0,0 +1,311 @@
+#!/usr/bin/env python3
+"""Core-owned RED/GREEN/REGRESSION command evidence for a frozen task binding."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from test_task_binding_check import FEATURE_RE, validate as validate_bindings
+from test_command_policy import validate_test_command
+
+
+STAGES = ("red", "green", "regression")
+
+
+def sha256_bytes(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def read_json(path: Path) -> dict[str, Any] | None:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError):
+        return None
+    return value if isinstance(value, dict) else None
+
+
+def write_json(path: Path, value: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.tmp")
+    temporary.write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    temporary.replace(path)
+
+
+def safe_project_path(root: Path, raw: str) -> Path | None:
+    candidate = Path(raw)
+    if candidate.is_absolute() or ".." in candidate.parts or not raw or "\x00" in raw:
+        return None
+    resolved = (root / candidate).resolve()
+    try:
+        resolved.relative_to(root.resolve())
+    except ValueError:
+        return None
+    return resolved
+
+
+def source_snapshot(root: Path, paths: list[str]) -> tuple[dict[str, str], list[str]]:
+    values: dict[str, str] = {}
+    errors: list[str] = []
+    for raw in sorted(set(paths)):
+        absolute = safe_project_path(root, raw)
+        if absolute is None:
+            errors.append(f"invalid production path: {raw}")
+            continue
+        if absolute.exists() and not absolute.is_file():
+            errors.append(f"production path must be a file or missing: {raw}")
+            continue
+        values[raw] = sha256_bytes(absolute.read_bytes()) if absolute.exists() else "<missing>"
+    return values, errors
+
+
+def test_paths(task: dict[str, Any]) -> list[str]:
+    return [item["path"] for item in task.get("implementation_tests", []) if isinstance(item, dict) and isinstance(item.get("path"), str)]
+
+
+def dirty_declared_production_paths(root: Path, paths: list[str]) -> list[str]:
+    """Reject evidence that starts after a declared source file was already edited.
+
+    A non-Git temporary project is acceptable for unit tests, but a real Git
+    worktree supplies independent evidence that the RED checkpoint preceded
+    production edits.
+    """
+    try:
+        completed = subprocess.run(["git", "status", "--porcelain=v1", "--", *paths], cwd=root, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
+    except OSError:
+        return []
+    if completed.returncode != 0:
+        return []
+    return [line[3:] for line in completed.stdout.splitlines() if len(line) > 3]
+
+
+def task_binding(root: Path, feature: str, task_id: str) -> tuple[dict[str, Any] | None, list[str]]:
+    validation = validate_bindings(root, feature)
+    if not validation.get("ok"):
+        return None, [str(item) for item in validation.get("errors", ["invalid test bindings"])]
+    bindings = read_json(root / ".planning" / "features" / feature / "test-bindings.json")
+    if bindings is None:
+        return None, ["missing test bindings"]
+    matches = [item for item in bindings.get("tasks", []) if isinstance(item, dict) and item.get("id") == task_id]
+    if len(matches) != 1:
+        return None, [f"task binding not found: {task_id}"]
+    task = matches[0]
+    if task.get("test_mode") != "tdd_required":
+        return None, [f"task {task_id} is not tdd_required"]
+    return task, []
+
+
+def evidence_path(root: Path, feature: str, task_id: str) -> Path:
+    return root / ".planning" / "test-runs" / feature / "tdd" / f"{task_id}.json"
+
+
+def command_hash(argv: list[str]) -> str:
+    return sha256_bytes(json.dumps(argv, ensure_ascii=False, separators=(",", ":")).encode("utf-8"))
+
+
+def response(ok: bool, **fields: Any) -> dict[str, Any]:
+    return {"ok": ok, **fields}
+
+
+def prepare(root: Path, feature: str, task_id: str, write: bool) -> dict[str, Any]:
+    task, errors = task_binding(root, feature, task_id)
+    if errors:
+        return response(False, feature=feature, task_id=task_id, errors=errors)
+    assert task is not None
+    snapshot, snapshot_errors = source_snapshot(root, list(task["production_paths"]))
+    tests_snapshot, test_snapshot_errors = source_snapshot(root, test_paths(task))
+    if snapshot_errors:
+        return response(False, feature=feature, task_id=task_id, errors=snapshot_errors)
+    if test_snapshot_errors:
+        return response(False, feature=feature, task_id=task_id, errors=test_snapshot_errors)
+    dirty = dirty_declared_production_paths(root, list(task["production_paths"]))
+    if dirty:
+        return response(False, feature=feature, task_id=task_id, errors=[f"declared production paths already changed before TDD preparation: {', '.join(dirty)}"])
+    destination = evidence_path(root, feature, task_id)
+    existing = read_json(destination)
+    if existing is not None:
+        return response(False, feature=feature, task_id=task_id, errors=["TDD evidence is already prepared; use a new task binding to restart"])
+    record = {
+        "schema_version": 1,
+        "origin": "core_tdd_evidence",
+        "feature": feature,
+        "task_id": task_id,
+        "tc_refs": task["tc_refs"],
+        "prepared_at": utc_now(),
+        "prepared_source_snapshot": snapshot,
+        "prepared_test_snapshot": tests_snapshot,
+        "stages": {},
+    }
+    if write:
+        write_json(destination, record)
+    return response(True, feature=feature, task_id=task_id, action="prepare", path=str(destination.relative_to(root)), record=record)
+
+
+def record_stage(root: Path, feature: str, task_id: str, stage: str, write: bool) -> dict[str, Any]:
+    task, errors = task_binding(root, feature, task_id)
+    if errors:
+        return response(False, feature=feature, task_id=task_id, stage=stage, errors=errors)
+    assert task is not None
+    destination = evidence_path(root, feature, task_id)
+    record = read_json(destination)
+    if record is None:
+        return response(False, feature=feature, task_id=task_id, stage=stage, errors=["TDD evidence must be prepared before RED"])
+    if record.get("feature") != feature or record.get("task_id") != task_id or not isinstance(record.get("stages"), dict):
+        return response(False, feature=feature, task_id=task_id, stage=stage, errors=["invalid existing TDD evidence record"])
+    stages = record["stages"]
+    if stage in stages:
+        return response(False, feature=feature, task_id=task_id, stage=stage, errors=[f"stage already recorded: {stage}"])
+    if stage == "green" and stages.get("red", {}).get("status") != "passed":
+        return response(False, feature=feature, task_id=task_id, stage=stage, errors=["GREEN requires a passed RED record"])
+    if stage == "regression" and stages.get("green", {}).get("status") != "passed":
+        return response(False, feature=feature, task_id=task_id, stage=stage, errors=["REGRESSION requires a passed GREEN record"])
+
+    snapshot, snapshot_errors = source_snapshot(root, list(task["production_paths"]))
+    tests_snapshot, test_snapshot_errors = source_snapshot(root, test_paths(task))
+    if snapshot_errors:
+        return response(False, feature=feature, task_id=task_id, stage=stage, errors=snapshot_errors)
+    if test_snapshot_errors:
+        return response(False, feature=feature, task_id=task_id, stage=stage, errors=test_snapshot_errors)
+    prepared_snapshot = record.get("prepared_source_snapshot")
+    if not isinstance(prepared_snapshot, dict):
+        return response(False, feature=feature, task_id=task_id, stage=stage, errors=["prepared source snapshot is missing"])
+    if stage == "red" and snapshot != prepared_snapshot:
+        return response(False, feature=feature, task_id=task_id, stage=stage, errors=["production paths changed before RED; task is no longer eligible for TDD evidence"])
+    if stage == "red" and tests_snapshot == record.get("prepared_test_snapshot"):
+        return response(False, feature=feature, task_id=task_id, stage=stage, errors=["test paths did not change before RED"])
+    if stage == "green" and snapshot == prepared_snapshot:
+        return response(False, feature=feature, task_id=task_id, stage=stage, errors=["production paths did not change after RED"])
+
+    tdd = task["tdd"]
+    stage_spec = tdd[stage]
+    argv = stage_spec["argv"]
+    command_error = validate_test_command(root, argv)
+    if command_error:
+        return response(False, feature=feature, task_id=task_id, stage=stage, errors=[command_error])
+    if stage == "green" and command_hash(argv) != stages["red"].get("command_hash"):
+        return response(False, feature=feature, task_id=task_id, stage=stage, errors=["GREEN command does not match the recorded RED test target"])
+    started_at = utc_now()
+    try:
+        completed = subprocess.run(argv, cwd=root, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=120, check=False)
+        exit_code = completed.returncode
+        output = f"{completed.stdout}\n{completed.stderr}"
+    except subprocess.TimeoutExpired as error:
+        exit_code = 124
+        output = f"command timed out: {error}"
+    except OSError as error:
+        exit_code = 127
+        output = f"command could not start: {error}"
+    expected_failure = stage_spec.get("expected_failure") if isinstance(stage_spec, dict) else None
+    passed = (exit_code != 0 and isinstance(expected_failure, str) and expected_failure in output) if stage == "red" else exit_code == 0
+    stage_record = {
+        "status": "passed" if passed else "failed",
+        "stage": stage,
+        "argv": argv,
+        "command_hash": command_hash(argv),
+        "started_at": started_at,
+        "finished_at": utc_now(),
+        "exit_code": exit_code,
+        "output_sha256": sha256_bytes(output.encode("utf-8", errors="replace")),
+        "source_snapshot": snapshot,
+        "test_snapshot": tests_snapshot,
+        "tc_refs": task["tc_refs"],
+    }
+    if stage == "red":
+        stage_record["expected_failure"] = expected_failure
+    stages[stage] = stage_record
+    if write:
+        write_json(destination, record)
+    failures = [] if passed else (["RED did not fail with its declared expected_failure"] if stage == "red" else [f"{stage.upper()} command failed with exit code {exit_code}"])
+    return response(passed, feature=feature, task_id=task_id, stage=stage, path=str(destination.relative_to(root)), stage_record=stage_record, errors=failures)
+
+
+def validate_feature(root: Path, feature: str) -> dict[str, Any]:
+    binding_result = validate_bindings(root, feature)
+    errors = [str(item) for item in binding_result.get("errors", [])]
+    if errors:
+        return response(False, feature=feature, errors=errors)
+    bindings = read_json(root / ".planning" / "features" / feature / "test-bindings.json")
+    assert bindings is not None
+    checked: list[str] = []
+    for task in bindings.get("tasks", []):
+        if not isinstance(task, dict) or task.get("test_mode") != "tdd_required":
+            continue
+        task_id = task.get("id")
+        if not isinstance(task_id, str):
+            errors.append("invalid TDD task id in test bindings")
+            continue
+        checked.append(task_id)
+        record = read_json(evidence_path(root, feature, task_id))
+        if record is None:
+            errors.append(f"missing TDD evidence: {task_id}")
+            continue
+        if record.get("origin") != "core_tdd_evidence" or record.get("feature") != feature or record.get("task_id") != task_id:
+            errors.append(f"invalid TDD evidence identity: {task_id}")
+            continue
+        if not isinstance(record.get("prepared_source_snapshot"), dict):
+            errors.append(f"missing prepared source snapshot: {task_id}")
+        if not isinstance(record.get("prepared_test_snapshot"), dict):
+            errors.append(f"missing prepared test snapshot: {task_id}")
+        stages = record.get("stages") if isinstance(record.get("stages"), dict) else {}
+        for stage in STAGES:
+            evidence = stages.get(stage)
+            if not isinstance(evidence, dict) or evidence.get("status") != "passed":
+                errors.append(f"missing passed {stage.upper()} evidence: {task_id}")
+                continue
+            expected_hash = command_hash(task["tdd"][stage]["argv"])
+            if evidence.get("command_hash") != expected_hash:
+                errors.append(f"{stage.upper()} command does not match frozen binding: {task_id}")
+        red = stages.get("red") if isinstance(stages.get("red"), dict) else {}
+        green = stages.get("green") if isinstance(stages.get("green"), dict) else {}
+        if red and green and red.get("command_hash") != green.get("command_hash"):
+            errors.append(f"RED/GREEN command mismatch in evidence: {task_id}")
+        if red and record.get("prepared_source_snapshot") != red.get("source_snapshot"):
+            errors.append(f"RED source snapshot differs from prepared snapshot: {task_id}")
+        if red and record.get("prepared_test_snapshot") == red.get("test_snapshot"):
+            errors.append(f"RED test snapshot did not change after preparation: {task_id}")
+        if green and record.get("prepared_source_snapshot") == green.get("source_snapshot"):
+            errors.append(f"GREEN source snapshot did not change after RED: {task_id}")
+    return response(not errors, feature=feature, task_ids=checked, errors=errors)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("action", choices=("prepare", "record", "inspect", "validate"))
+    parser.add_argument("--feature", required=True)
+    parser.add_argument("--task-id")
+    parser.add_argument("--stage", choices=STAGES)
+    parser.add_argument("--write", action="store_true")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+    if not FEATURE_RE.fullmatch(args.feature):
+        result = response(False, errors=["invalid feature"])
+    elif args.action == "validate":
+        result = validate_feature(Path.cwd().resolve(), args.feature)
+    elif not args.task_id or "/" in args.task_id or "\\" in args.task_id:
+        result = response(False, errors=["invalid task_id"])
+    elif args.action == "inspect":
+        record = read_json(evidence_path(Path.cwd().resolve(), args.feature, args.task_id))
+        result = response(record is not None, record=record, errors=[] if record else ["TDD evidence not found"])
+    elif not args.write:
+        result = response(False, errors=["--write is required for prepare and record"])
+    elif args.action == "prepare":
+        result = prepare(Path.cwd().resolve(), args.feature, args.task_id, True)
+    elif not args.stage:
+        result = response(False, errors=["--stage is required for record"])
+    else:
+        result = record_stage(Path.cwd().resolve(), args.feature, args.task_id, args.stage, True)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/test_command_policy.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Allow only initialized, non-shell test runner argv commands."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def runner_marker(argv: list[str]) -> str | None:
+    if not argv:
+        return None
+    executable = Path(argv[0]).name
+    if executable in {"pytest"}:
+        return "pytest"
+    if executable.startswith("python") and len(argv) >= 3 and argv[1:3] == ["-m", "pytest"]:
+        return "pytest"
+    if executable.startswith("python") and len(argv) >= 3 and argv[1:3] == ["-m", "unittest"]:
+        return "unittest"
+    if executable == "bun" and len(argv) >= 2 and argv[1] == "test":
+        return "bun test"
+    if executable == "npm" and len(argv) >= 2 and argv[1] in {"test", "run"}:
+        return "npm"
+    if executable == "pnpm" and len(argv) >= 2 and argv[1] in {"test", "run"}:
+        return "pnpm"
+    if executable == "yarn" and len(argv) >= 2 and argv[1] in {"test", "run"}:
+        return "yarn"
+    if executable == "go" and len(argv) >= 2 and argv[1] == "test":
+        return "go test"
+    if executable == "newman" and len(argv) >= 2 and argv[1] == "run":
+        return "newman"
+    if executable == "playwright" and len(argv) >= 2 and argv[1] == "test":
+        return "playwright"
+    if executable == "npx" and len(argv) >= 3 and argv[1:3] == ["playwright", "test"]:
+        return "playwright"
+    if executable == "vitest" and len(argv) >= 2 and argv[1] in {"run", "related"}:
+        return "vitest"
+    return None
+
+
+def validate_test_command(root: Path, argv: Any) -> str | None:
+    if not isinstance(argv, list) or not argv or not all(isinstance(token, str) and token and "\x00" not in token for token in argv):
+        return "test command must be a non-empty argv array"
+    marker = runner_marker(argv)
+    if marker is None:
+        return "test command runner is not in the Core allowlist"
+    toolchain = root / ".planning" / "toolchain.md"
+    if not toolchain.is_file():
+        return "initialized .planning/toolchain.md is required before Core can execute a test command"
+    content = toolchain.read_text(encoding="utf-8").lower()
+    aliases = {"pytest": ("pytest",), "unittest": ("unittest",), "bun test": ("bun test",), "npm": ("npm",), "pnpm": ("pnpm",), "yarn": ("yarn",), "go test": ("go test",), "newman": ("newman",), "playwright": ("playwright",), "vitest": ("vitest",)}
+    if not any(alias in content for alias in aliases[marker]):
+        return f"test runner '{marker}' was not discovered in .planning/toolchain.md"
+    return None

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/test_task_binding_check.py

@@ -0,0 +1,254 @@
+#!/usr/bin/env python3
+"""Fail-closed validation of implementation-task to acceptance-TC bindings.
+
+The change plan is drafted *before* CP-3 freezes its TC candidates.  Treating
+that draft as if it already pointed at a frozen view creates a circular gate:
+the plan cannot reach the checkpoint which is responsible for freezing it.
+
+This checker therefore has two explicit stages:
+
+* ``candidate`` validates the complete draft binding against the current,
+  unfrozen suite.  It is the gate for the change-plan step.
+* ``frozen`` validates the same binding against the Core-owned CP-3 freeze
+  attestation and the resulting frozen suite.  It is the gate before TDD or
+  acceptance execution may claim the binding is usable.
+
+The binding keeps its candidate-view pin; the freeze attestation joins that
+immutable draft to the post-freeze view without asking a Skill to rewrite a
+file after the user's approval.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+
+FEATURE_RE = re.compile(r"^[^/\\\x00-\x1f\x7f]+$")
+MODES = {"tdd_required", "contract_first", "integration_only", "manual_justified"}
+
+
+def read_json(path: Path, errors: list[str], label: str) -> dict[str, Any] | None:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        errors.append(f"missing {label}: {path.as_posix()}")
+        return None
+    except json.JSONDecodeError as error:
+        errors.append(f"invalid {label}: {error.msg}")
+        return None
+    if not isinstance(value, dict):
+        errors.append(f"invalid {label}: root must be an object")
+        return None
+    return value
+
+
+def file_fingerprint(path: Path) -> str | None:
+    try:
+        return hashlib.sha256(path.read_bytes()).hexdigest()
+    except OSError:
+        return None
+
+
+def valid_argv(value: Any) -> bool:
+    return isinstance(value, list) and bool(value) and all(isinstance(token, str) and token and "\x00" not in token for token in value)
+
+
+def test_case_ids(suite: dict[str, Any]) -> set[str]:
+    nodes = suite.get("nodes")
+    if not isinstance(nodes, list):
+        return set()
+    return {
+        node["id"]
+        for node in nodes
+        if isinstance(node, dict) and node.get("kind") == "test_case" and isinstance(node.get("id"), str)
+    }
+
+
+def view_pin(suite: dict[str, Any]) -> dict[str, Any]:
+    view_meta = suite.get("view_meta") if isinstance(suite.get("view_meta"), dict) else {}
+    return {"graph_revision": suite.get("graph_revision"), "fingerprint": view_meta.get("fingerprint")}
+
+
+def freeze_attestation_path(root: Path, feature: str) -> Path:
+    return root / ".planning" / "features" / feature / "test-suite-freeze.json"
+
+
+def validated_attestation(
+    root: Path,
+    feature: str,
+    suite: dict[str, Any],
+    binding_path: Path,
+    binding_pin: dict[str, Any],
+    tc_ids: set[str],
+    errors: list[str],
+) -> None:
+    attestation = read_json(freeze_attestation_path(root, feature), errors, "TC suite freeze attestation")
+    if attestation is None:
+        return
+    if attestation.get("schema_version") != 1:
+        errors.append("TC suite freeze attestation schema_version must be 1")
+    if attestation.get("origin") != "core_acceptance_test_suite_freeze":
+        errors.append("TC suite freeze attestation origin is invalid")
+    if attestation.get("feature") != feature:
+        errors.append("TC suite freeze attestation feature does not match requested feature")
+    if attestation.get("candidate_test_suite") != binding_pin:
+        errors.append("TC suite freeze attestation does not match the binding candidate suite")
+    if attestation.get("frozen_test_suite") != view_pin(suite):
+        errors.append("TC suite freeze attestation does not match the current frozen TC suite")
+    if attestation.get("test_binding_sha256") != file_fingerprint(binding_path):
+        errors.append("test bindings changed after CP-3 freeze")
+    frozen_ids = attestation.get("frozen_case_ids")
+    if not isinstance(frozen_ids, list) or set(frozen_ids) != tc_ids or not all(isinstance(value, str) for value in frozen_ids):
+        errors.append("TC suite freeze attestation does not cover exactly the frozen TC cases")
+
+
+def validate(root: Path, feature: str, stage: str = "frozen") -> dict[str, Any]:
+    errors: list[str] = []
+    suite_path = root / ".planning" / "requirements" / feature / "tests.json"
+    binding_path = root / ".planning" / "features" / feature / "test-bindings.json"
+    suite = read_json(suite_path, errors, "TC suite")
+    bindings = read_json(binding_path, errors, "test bindings")
+    if suite is None or bindings is None:
+        return {"ok": False, "errors": errors}
+
+    tc_ids = test_case_ids(suite)
+    if not tc_ids:
+        errors.append("TC suite contains no test_case nodes")
+    else:
+        non_confirmed = sorted(
+            node.get("id", "<unknown>")
+            for node in suite.get("nodes", [])
+            if isinstance(node, dict) and node.get("kind") == "test_case" and node.get("status") != "confirmed"
+        )
+        confirmed = sorted(tc_ids - set(non_confirmed))
+        if stage == "candidate":
+            if confirmed:
+                errors.append(f"TC candidate suite already contains frozen cases: {', '.join(confirmed)}")
+            if suite.get("frozen") is True:
+                errors.append("TC candidate suite is marked frozen")
+        else:
+            if non_confirmed:
+                errors.append(f"TC suite is not frozen: {', '.join(non_confirmed)}")
+            if suite.get("frozen") is not True:
+                errors.append("TC suite is not marked frozen and fresh")
+    if bindings.get("schema_version") != 2:
+        errors.append("test bindings schema_version must be 2")
+    if bindings.get("origin") != "devflow_change_plan":
+        errors.append("test bindings origin must be devflow_change_plan")
+    if bindings.get("feature") != feature:
+        errors.append("test bindings feature does not match requested feature")
+
+    pin = bindings.get("candidate_test_suite")
+    # schema_version=1 shipped only in the unfinished local implementation.
+    # Reject it deliberately rather than treating an ambiguous pre-freeze pin
+    # as frozen evidence.
+    if not isinstance(pin, dict):
+        errors.append("candidate_test_suite pin is required")
+    else:
+        if stage == "candidate" and pin != view_pin(suite):
+            errors.append("candidate_test_suite does not match current TC candidate suite")
+
+    tasks = bindings.get("tasks")
+    if not isinstance(tasks, list) or not tasks:
+        errors.append("tasks must be a non-empty array")
+        tasks = []
+    task_ids: set[str] = set()
+    covered: set[str] = set()
+    for index, task in enumerate(tasks):
+        label = f"tasks[{index}]"
+        if not isinstance(task, dict):
+            errors.append(f"{label} must be an object")
+            continue
+        task_id = task.get("id")
+        if not isinstance(task_id, str) or not task_id:
+            errors.append(f"{label}.id is required")
+        elif task_id in task_ids:
+            errors.append(f"duplicate task id: {task_id}")
+        else:
+            task_ids.add(task_id)
+        mode = task.get("test_mode")
+        if mode not in MODES:
+            errors.append(f"{label}: invalid test_mode")
+        refs = task.get("tc_refs")
+        if not isinstance(refs, list) or not refs or not all(isinstance(ref, str) and ref for ref in refs):
+            errors.append(f"{label}: tc_refs must be a non-empty string array")
+            refs = []
+        for ref in refs:
+            if ref not in tc_ids:
+                errors.append(f"{label}: unknown TC reference {ref}")
+            else:
+                covered.add(ref)
+        tests = task.get("implementation_tests")
+        if not isinstance(tests, list) or not tests:
+            errors.append(f"{label}: implementation_tests must be a non-empty array")
+        elif not all(isinstance(item, dict) and isinstance(item.get("path"), str) and item["path"] for item in tests):
+            errors.append(f"{label}: implementation_tests entries require path")
+
+        if mode == "tdd_required":
+            tdd = task.get("tdd")
+            if not isinstance(tdd, dict):
+                errors.append(f"{label}: tdd is required")
+                continue
+            for tdd_stage in ("red", "green", "regression"):
+                evidence = tdd.get(tdd_stage)
+                if not isinstance(evidence, dict):
+                    errors.append(f"{label}: missing tdd.{tdd_stage}")
+                    continue
+                if not valid_argv(evidence.get("argv")):
+                    errors.append(f"{label}: tdd.{tdd_stage}.argv must be a non-empty argv array")
+            red = tdd.get("red")
+            if not isinstance(red, dict) or not isinstance(red.get("expected_failure"), str) or not red["expected_failure"].strip():
+                errors.append(f"{label}: tdd.red.expected_failure is required")
+            green = tdd.get("green")
+            if isinstance(red, dict) and isinstance(green, dict) and valid_argv(red.get("argv")) and valid_argv(green.get("argv")) and red["argv"] != green["argv"]:
+                errors.append(f"{label}: tdd.red and tdd.green must use the same test target")
+            production_paths = task.get("production_paths")
+            if not isinstance(production_paths, list) or not production_paths or not all(isinstance(item, str) and item and not item.startswith(("/", "\\")) and ".." not in item.split("/") for item in production_paths):
+                errors.append(f"{label}: tdd_required production_paths must be a non-empty project-relative path array")
+        elif mode in MODES:
+            reason = task.get("non_tdd_reason")
+            if not isinstance(reason, str) or not reason.strip():
+                errors.append(f"{label}: non_tdd_reason is required for {mode}")
+            if mode == "manual_justified" and (not isinstance(task.get("owner"), str) or not task["owner"].strip()):
+                errors.append(f"{label}: manual_justified requires owner")
+
+    suite_label = "candidate" if stage == "candidate" else "frozen"
+    for tc_id in sorted(tc_ids - covered):
+        errors.append(f"uncovered {suite_label} TC: {tc_id}")
+
+    if stage == "frozen" and isinstance(pin, dict):
+        validated_attestation(root, feature, suite, binding_path, pin, tc_ids, errors)
+    return {
+        "ok": not errors,
+        "feature": feature,
+        "stage": stage,
+        "covered_tc_ids": sorted(covered),
+        "tc_ids": sorted(tc_ids),
+        "candidate_test_suite": pin if isinstance(pin, dict) else None,
+        "binding_sha256": file_fingerprint(binding_path),
+        "errors": errors,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--feature", required=True)
+    # ``recovery`` is Core-only: it lets advance_state repair an interrupted
+    # CP-3 after it can independently prove every TC was frozen by that exact
+    # checkpoint.  It deliberately cannot be selected by plugin tools.
+    parser.add_argument("--stage", choices=("candidate", "frozen", "recovery"), default="frozen")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+    if not FEATURE_RE.fullmatch(args.feature):
+        print(json.dumps({"ok": False, "errors": ["invalid feature"]}, ensure_ascii=False))
+        return 0
+    print(json.dumps(validate(Path.cwd().resolve(), args.feature, args.stage), ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())