pirl-framework-cli 0.0.0-stage → 1.0.0

package/bundled-framework/files/.agents/evals/tests/test_validate_layer_artifact.py

@@ -0,0 +1,214 @@
+"""Check the public Plan/Review handoff and the role catalog, not per-line editorial rules."""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+EVALS = Path(__file__).resolve().parents[1]
+REPO = EVALS.parents[1]
+sys.path.insert(0, str(EVALS))
+from layer_record import LAYER_USAGES  # noqa: E402
+from validate_layer_artifact import CATALOG, _scalar, load_roles  # noqa: E402
+
+ROLES = """### Role catalog
+
+| ID | Expertise | Used in |
+| --- | --- | --- |
+| `business-analyst` | Business logic | plan, review |
+| `code-analyst` | Flow tracing | plan, verify, review |
+| `backend-developer` | Writes source | implement |
+| `code-reviewer` | Challenges the diff | verify, review |
+| `process-auditor` | Self-evaluation | audit |
+
+### Other section
+"""
+PLAN = """---
+schema: pirl-plan/v1
+content_language: en
+plan_set: request_20260909-090000
+task_id: T01
+title: Short API task
+layer: implement
+status: planned
+depends_on: []
+created_at: "2026-09-09T09:00:00+07:00"
+target_repo: .
+source_request: Review API DTO ownership
+planning_roles: [code-analyst]
+implementation_roles: [backend-developer]
+verification_roles: [code-reviewer]
+---
+# API task
+## What to do
+API DTO HTTP response contract.
+## How to do it
+Read the input and return the requested result.
+## Participating roles
+Use the roles assigned above.
+## Required quality gates
+The caller receives the requested data.
+"""
+REVIEW = """---
+schema: pirl-review/v1
+content_language: en
+plan_file: "request_20260909-090000/task.md"
+task_id: T01
+review_round: 1
+prior_review: null
+review_roles: [code-analyst, code-reviewer, business-analyst]
+repair_roles: []
+business_verdict: PASS
+verdict: PASS
+status: completed
+reviewed_at: "2026-09-09T10:00:00+07:00"
+---
+## Business
+The selected result satisfies the request.
+## Evaluations
+Roles and supporting sources were reviewed.
+"""
+
+
+class HandoffIOTests(unittest.TestCase):
+    def setUp(self):
+        temporary = tempfile.TemporaryDirectory()
+        self.addCleanup(temporary.cleanup)
+        self.root = Path(temporary.name)
+        (self.root / CATALOG).parent.mkdir(parents=True)
+        (self.root / CATALOG).write_text(ROLES, encoding="utf-8")
+        # With no location named by the user, Plan packages and reports sit under the Hub root.
+        self.plan = self.root / "request_20260909-090000/task.md"
+        self.plan.parent.mkdir(parents=True)
+        self.plan.write_text(PLAN, encoding="utf-8")
+
+    def check(self, kind, path):
+        result = subprocess.run(
+            [sys.executable, "-X", "utf8", "-B", str(EVALS / "validate_layer_artifact.py"),
+             "--root", str(self.root), "--kind", kind, "--path", str(path)],
+            capture_output=True, text=True, encoding="utf-8",
+        )
+        return result.returncode, json.loads(result.stdout)
+
+    def write_plan(self, text):
+        self.plan.write_text(text, encoding="utf-8")
+        return self.check("plan", self.plan)
+
+    def test_plan_and_review_accept_complete_handoffs_without_scoring_prose(self):
+        code, result = self.check("plan", self.plan)
+        self.assertEqual(code, 0, result)
+        report = self.root / "request_20260909-090000/t01-api/round-01.md"
+        report.parent.mkdir(parents=True)
+        report.write_text(REVIEW, encoding="utf-8")
+        code, result = self.check("review", report)
+        self.assertEqual(code, 0, result)
+        for invalid in (
+            REVIEW.replace("task.md", "missing.md"),
+            REVIEW.replace("review_round: 1", "review_round: 2"),
+            REVIEW.replace("verdict: PASS\nstatus", "verdict: FAIL\nstatus"),
+            REVIEW.replace("review_roles: [code-analyst, code-reviewer, business-analyst]", "review_roles: [backend-developer]"),
+            REVIEW.replace("repair_roles: []", "repair_roles: [business-analyst]"),
+        ):
+            with self.subTest(invalid=invalid):
+                report.write_text(invalid, encoding="utf-8")
+                code, result = self.check("review", report)
+                self.assertNotEqual(code, 0)
+                self.assertFalse(result["passed"])
+
+    def test_plan_roles_come_from_the_catalog_and_verifier_differs_from_implementation_role(self):
+        for invalid, field in (
+            (PLAN.replace("verification_roles: [code-reviewer]", "verification_roles: []"), "verification_roles"),
+            (PLAN.replace("verification_roles: [code-reviewer]", "verification_roles: [unknown-role]"), "verification_roles"),
+            (PLAN.replace("verification_roles: [code-reviewer]", "verification_roles: [business-analyst]"), "verification_roles"),
+            (PLAN.replace("implementation_roles: [backend-developer]", "implementation_roles: [code-reviewer]"), "implementation_roles"),
+            (PLAN.replace("verification_roles: [code-reviewer]", "verification_roles: [process-auditor]"), "verification_roles"),
+            (PLAN.replace("planning_roles: [code-analyst]", "planning_roles: [backend-developer]"), "planning_roles"),
+        ):
+            with self.subTest(field=field, invalid=invalid):
+                code, result = self.write_plan(invalid)
+                self.assertNotEqual(code, 0)
+                self.assertTrue(any(field in error for error in result["errors"]), result)
+
+    def test_quoted_values_keep_windows_backslashes(self):
+        # target_repo is usually an absolute path; on Windows it holds backslashes that are not escapes.
+        self.assertEqual(_scalar('"D:\\new-app\\shop"', "plan", 1), "D:\\new-app\\shop")
+        self.assertEqual(_scalar('"C:\\Users\\dev"', "plan", 1), "C:\\Users\\dev")
+        self.assertEqual(_scalar("'it''s'", "plan", 1), "it's")
+        self.assertEqual(_scalar('"say \\"hi\\""', "plan", 1), 'say "hi"')
+
+    def test_target_repo_must_be_an_existing_directory(self):
+        outside = tempfile.TemporaryDirectory()
+        self.addCleanup(outside.cleanup)
+        (self.root / "shop-web").mkdir()
+        for target in ("shop-web", outside.name):
+            with self.subTest(target=target):
+                self.assertEqual(self.write_plan(PLAN.replace("target_repo: .", f'target_repo: "{target}"'))[0], 0)
+        code, result = self.write_plan(PLAN.replace("target_repo: .", 'target_repo: "missing-repo"'))
+        self.assertNotEqual(code, 0)
+        self.assertTrue(any("target_repo" in error for error in result["errors"]), result)
+
+    def test_status_beyond_planned_requires_a_matching_implementation_record(self):
+        implemented = PLAN.replace("status: planned", "status: implemented")
+        self.assertNotEqual(self.write_plan(implemented)[0], 0)
+        record = '\n## Implementation Record\n- status: implemented\n- updated_at: "2026-09-09T11:00:00+07:00"\n'
+        self.assertEqual(self.write_plan(implemented + record)[0], 0)
+        self.assertNotEqual(self.write_plan(implemented + record.replace("status: implemented", "status: failed"))[0], 0)
+
+    def test_invalid_dependencies_and_metadata_return_errors_for_file_and_package(self):
+        for invalid in ("depends_on: [[]]", "depends_on: [T99]", "depends_on: [T01]"):
+            self.plan.write_text(PLAN.replace("depends_on: []", invalid), encoding="utf-8")
+            for path in (self.plan, self.plan.parent):
+                with self.subTest(invalid=invalid, path=path):
+                    code, result = self.check("plan", path)
+                    self.assertNotEqual(code, 0)
+                    self.assertTrue(result["errors"])
+        self.assertNotEqual(self.write_plan(PLAN.replace("2026-09-09T09", "2026-99-99T09"))[0], 0)
+
+    def test_timestamps_accept_any_utc_offset_but_require_one(self):
+        for offset in ("+00:00", "-05:00", "+09:30"):
+            with self.subTest(offset=offset):
+                self.assertEqual(self.write_plan(PLAN.replace("T09:00:00+07:00", f"T09:00:00{offset}"))[0], 0)
+        code, result = self.write_plan(PLAN.replace("T09:00:00+07:00", "T09:00:00"))
+        self.assertNotEqual(code, 0)
+        self.assertTrue(any("UTC offset" in error for error in result["errors"]), result)
+
+
+class RoleCatalogTests(unittest.TestCase):
+    """Layer role tables must use IDs that the role catalog registers for that layer."""
+
+    # A table row starts with the role ID, plain or linked to its role file.
+    ROW = re.compile(r"(?m)^\| (?:\[`([a-z0-9-]+)`\]\(([^)]+)\)|`([a-z0-9-]+)`) \|")
+
+    def test_layer_role_tables_match_the_agents_catalog(self):
+        catalog = load_roles(REPO)
+        for layer, usages in LAYER_USAGES.items():
+            path = REPO / f".agents/instructions/{layer}.instructions.md"
+            section = re.search(rf"(?ms)^## AI Agent roles at the {layer.capitalize()} layer\s*$(.*?)(?=^## )", path.read_text(encoding="utf-8"))
+            self.assertIsNotNone(section, layer)
+            rows = self.ROW.findall(section.group(1))
+            self.assertTrue(rows, layer)
+            for linked, target, plain in rows:
+                role = linked or plain
+                with self.subTest(layer=layer, role=role):
+                    self.assertIn(role, catalog)
+                    self.assertTrue(catalog[role] & usages, f"{role} is not registered for {layer}")
+                    if target:
+                        self.assertEqual((path.parent / target).resolve(), (REPO / f".agents/roles/{role}.role.md").resolve())
+
+    def test_every_catalog_role_has_exactly_one_role_file(self):
+        catalog = load_roles(REPO)
+        files = {p.name.removesuffix(".role.md"): p for p in (REPO / ".agents/roles").glob("*.role.md")}
+        self.assertEqual(set(files), set(catalog))
+        for role, path in files.items():
+            with self.subTest(role=role):
+                header = path.read_text(encoding="utf-8").split("---")[1]
+                self.assertIn(f"id: .agents/roles/{role}\n", header)
+                self.assertRegex(header, r"(?m)^version: \d+\.\d+\.\d+$")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/bundled-framework/files/.agents/evals/validate_layer_artifact.py

@@ -0,0 +1,415 @@
+#!/usr/bin/env python3
+"""Check Plan/Review handoff inputs and references, without grading their prose."""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import re
+from collections import deque
+from datetime import datetime
+from pathlib import Path, PureWindowsPath
+from typing import Any
+
+PLAN_SCHEMA = "pirl-plan/v1"
+REVIEW_SCHEMA = "pirl-review/v1"
+PLAN_HEADINGS = ("What to do", "How to do it", "Participating roles", "Required quality gates")
+REVIEW_HEADINGS = ("Business", "Evaluations")
+# Value lists owned here and imported by layer_record.py, so the two tools cannot drift apart.
+IMPLEMENT_STATUSES = ("implemented", "awaiting_confirmation", "blocked", "failed")
+PLAN_STATUSES = ("planned", *IMPLEMENT_STATUSES)
+REVIEW_STATUSES = ("completed", "blocked")
+VERDICTS = ("PASS", "FAIL", "BLOCKED")
+TASK_PATTERN = re.compile(r"T\d{2,}")
+ROLE_USAGES = ("plan", "implement", "verify", "review", "audit")
+CATALOG = ".agents/instructions/standalone-and-maintenance.instructions.md"
+ROLE_SECTION = re.compile(r"(?ms)^### Role catalog\s*$(.*?)(?=^#{1,3} |\Z)")
+ROLE_ROW = re.compile(r"^\|\s*`([a-z0-9]+(?:-[a-z0-9]+)*)`\s*\|(.*)\|\s*$")
+
+
+class LayerArtifactError(ValueError):
+    pass
+
+
+# ---------- constrained YAML subset (frontmatter) ----------
+
+
+def _scalar(raw: str, source: str, number: int) -> Any:
+    value = raw.strip()
+    if not value:
+        raise LayerArtifactError(f"{source}:{number}: expected a scalar value")
+    lowered = value.lower()
+    if lowered in ("true", "false"):
+        return lowered == "true"
+    if lowered in ("null", "~"):
+        return None
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "'\"":
+        # A quoted string is taken as written: Windows paths such as "D:\new-app" keep their backslashes.
+        # Only an escaped quote or backslash in double quotes, and a doubled quote in single quotes, are decoded.
+        inner = value[1:-1]
+        if value[0] == "'":
+            return inner.replace("''", "'")
+        return re.sub(r'\\(["\\])', r"\1", inner)
+    if value.startswith(("[", "{", "'", '"')):
+        try:
+            return ast.literal_eval(value)
+        except (SyntaxError, ValueError) as exc:
+            if value.startswith("[") and value.endswith("]"):
+                inner = value[1:-1].strip()
+                parts = [part.strip() for part in inner.split(",")] if inner else []
+                if all(parts):
+                    return [_scalar(part, source, number) for part in parts]
+            raise LayerArtifactError(f"{source}:{number}: invalid quoted or inline value: {value}") from exc
+    try:
+        return int(value)
+    except ValueError:
+        return value
+
+
+def parse_yaml_subset(text: str, source: str) -> dict[str, Any]:
+    """Parse mappings, scalar lists and inline scalar collections; reject anything else."""
+
+    tokens: list[tuple[int, str, int]] = []
+    for number, raw_line in enumerate(text.splitlines(), 1):
+        if not raw_line.strip() or raw_line.lstrip().startswith("#"):
+            continue
+        lead = raw_line[: len(raw_line) - len(raw_line.lstrip())]
+        if "\t" in lead:
+            raise LayerArtifactError(f"{source}:{number}: tabs are not valid indentation")
+        indent = len(raw_line) - len(raw_line.lstrip(" "))
+        if indent % 2:
+            raise LayerArtifactError(f"{source}:{number}: indentation must use two spaces")
+        tokens.append((indent, raw_line.strip(), number))
+    if not tokens:
+        return {}
+    if tokens[0][0] != 0:
+        raise LayerArtifactError(f"{source}:{tokens[0][2]}: top-level key must be unindented")
+
+    def block(index: int, indent: int) -> tuple[Any, int]:
+        if index >= len(tokens) or tokens[index][0] != indent:
+            line = tokens[index][2] if index < len(tokens) else len(text.splitlines())
+            raise LayerArtifactError(f"{source}:{line}: malformed indentation")
+        is_list = tokens[index][1].startswith("- ")
+        container: Any = [] if is_list else {}
+        while index < len(tokens):
+            current, content, number = tokens[index]
+            if current < indent:
+                break
+            if current > indent:
+                raise LayerArtifactError(f"{source}:{number}: unexpected indentation")
+            if is_list:
+                if not content.startswith("- "):
+                    raise LayerArtifactError(f"{source}:{number}: mixed list and mapping block")
+                item = content[2:].strip()
+                if not item or (":" in item and not item.startswith(("'", '"'))):
+                    raise LayerArtifactError(f"{source}:{number}: only scalar list items are supported")
+                container.append(_scalar(item, source, number))
+                index += 1
+                continue
+            if content.startswith("- ") or ":" not in content:
+                raise LayerArtifactError(f"{source}:{number}: expected a mapping entry")
+            key, raw_value = content.split(":", 1)
+            key = key.strip()
+            if not key:
+                raise LayerArtifactError(f"{source}:{number}: mapping key is empty")
+            if key in container:
+                raise LayerArtifactError(f"{source}:{number}: duplicate key {key!r}")
+            raw_value = raw_value.strip()
+            index += 1
+            if raw_value:
+                container[key] = _scalar(raw_value, source, number)
+            elif index < len(tokens) and tokens[index][0] > indent:
+                if tokens[index][0] != indent + 2:
+                    raise LayerArtifactError(f"{source}:{tokens[index][2]}: nested blocks must indent two spaces")
+                container[key], index = block(index, indent + 2)
+            else:
+                container[key] = {}
+        return container, index
+
+    parsed, end = block(0, 0)
+    if end != len(tokens) or not isinstance(parsed, dict):
+        raise LayerArtifactError(f"{source}: root must be a mapping")
+    return parsed
+
+
+def read_frontmatter(path: Path) -> tuple[dict[str, Any], str]:
+    """Return the parsed frontmatter and the body of a Plan/Review Markdown file."""
+
+    return _frontmatter_and_body(path)
+
+
+def _frontmatter_and_body(path: Path) -> tuple[dict[str, Any], str]:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+        if not lines or lines[0].strip() != "---":
+            raise LayerArtifactError("missing frontmatter")
+        end = next(i for i in range(1, len(lines)) if lines[i].strip() == "---")
+        return parse_yaml_subset("\n".join(lines[1:end]), path.as_posix()), "\n".join(lines[end + 1:])
+    except (OSError, UnicodeError, StopIteration, RecursionError) as exc:
+        raise LayerArtifactError(f"{path}: cannot read metadata: {exc}") from exc
+
+
+# ---------- role catalog ----------
+
+
+def load_roles(root: Path) -> dict[str, set[str]]:
+    """Return role ID -> usages from the role catalog table (CATALOG, section "Role catalog")."""
+
+    try:
+        text = (root / CATALOG).read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise LayerArtifactError(f"{CATALOG}: cannot read role catalog: {exc}") from exc
+    section = ROLE_SECTION.search(text)
+    if section is None:
+        raise LayerArtifactError(f"{CATALOG}: missing '### Role catalog' section")
+    roles: dict[str, set[str]] = {}
+    for line in section.group(1).splitlines():
+        row = ROLE_ROW.match(line.strip())
+        if row is None:
+            continue
+        usages = {item.strip() for item in row.group(2).rsplit("|", 1)[-1].split(",") if item.strip()}
+        if not usages or not usages <= set(ROLE_USAGES):
+            raise LayerArtifactError(f"{CATALOG}: role {row.group(1)} has invalid usage {sorted(usages)}")
+        roles[row.group(1)] = usages
+    if not roles:
+        raise LayerArtifactError(f"{CATALOG}: role catalog has no roles")
+    return roles
+
+
+def resolve_path(value: Any, root: Path) -> Path:
+    """Resolve a path written in a Plan, report or record: relative to the Hub root, or absolute."""
+
+    if not isinstance(value, str) or not value.strip():
+        raise LayerArtifactError("expected a path relative to the Hub root or an absolute path")
+    path = Path(value.strip())
+    return (path if path.is_absolute() or PureWindowsPath(value.strip()).drive else root / path).resolve()
+
+
+# ---------- field helpers ----------
+
+
+def _timestamp(value: Any, label: str, errors: list[str]) -> None:
+    try:
+        parsed = datetime.fromisoformat(value) if isinstance(value, str) else None
+        if parsed is None or parsed.utcoffset() is None:
+            raise ValueError("expected ISO-8601 with a UTC offset, for example +07:00")
+    except ValueError as exc:
+        errors.append(f"{label}: invalid timestamp ({exc})")
+
+
+def _strings(value: Any, label: str, errors: list[str], required: bool = False) -> list[str]:
+    if not isinstance(value, list) or not all(isinstance(x, str) and x.strip() for x in value):
+        errors.append(f"{label}: expected an array of non-empty strings")
+        return []
+    if required and not value:
+        errors.append(f"{label}: at least one entry is required")
+    if len(set(value)) != len(value):
+        errors.append(f"{label}: duplicate entries")
+    return value
+
+
+def _roles(
+    value: Any,
+    label: str,
+    usage: str,
+    catalog: dict[str, set[str]],
+    errors: list[str],
+    required: bool,
+) -> list[str]:
+    names = _strings(value, label, errors, required)
+    for name in names:
+        if name not in catalog:
+            errors.append(f"{label}: unknown role {name}")
+        elif usage not in catalog[name]:
+            errors.append(f"{label}: role {name} is not registered for {usage}")
+    return names
+
+
+def _reference_path(value: Any, root: Path, label: str) -> Path:
+    path = resolve_path(value, root)
+    if not path.is_file():
+        raise LayerArtifactError(f"{label}: {value} is not an existing file")
+    return path
+
+
+def _basic(path: Path, root: Path, kind: str) -> tuple[list[str], dict[str, Any], str]:
+    errors: list[str] = []
+    try:
+        if path.suffix != ".md":
+            raise LayerArtifactError("expected a Markdown file")
+        metadata, body = _frontmatter_and_body(path)
+    except LayerArtifactError as exc:
+        return [str(exc)], {}, ""
+    expected = PLAN_SCHEMA if kind == "plan" else REVIEW_SCHEMA
+    if metadata.get("schema") != expected:
+        errors.append(f"schema must be {expected}")
+    task = metadata.get("task_id")
+    if not isinstance(task, str) or not TASK_PATTERN.fullmatch(task):
+        errors.append("task_id must identify a task, for example T01")
+    if metadata.get("content_language") != "en":
+        errors.append("content_language must be en")
+    for heading in PLAN_HEADINGS if kind == "plan" else REVIEW_HEADINGS:
+        if not re.search(rf"(?m)^## {re.escape(heading)}\s*$", body):
+            errors.append(f"missing handoff section: {heading}")
+    _timestamp(metadata.get("created_at" if kind == "plan" else "reviewed_at"), "timestamp", errors)
+    return errors, metadata, body
+
+
+# ---------- Plan ----------
+
+
+def _plan_file(path: Path, root: Path) -> tuple[list[str], dict[str, Any]]:
+    errors, metadata, body = _basic(path, root, "plan")
+    if not metadata:
+        return errors, metadata
+    for key in ("plan_set", "title", "target_repo", "source_request"):
+        if not isinstance(metadata.get(key), str) or not metadata[key].strip():
+            errors.append(f"{key}: non-empty text is required")
+    if metadata.get("plan_set") != path.parent.name:
+        errors.append("plan_set must identify the containing package")
+    if metadata.get("layer") != "implement" or metadata.get("status") not in PLAN_STATUSES:
+        errors.append("invalid Plan layer/status")
+    # The target repository is any existing directory the user named (AGENTS.md, Target repository).
+    target = metadata.get("target_repo")
+    if isinstance(target, str) and target.strip() and not resolve_path(target, root).is_dir():
+        errors.append(f"target_repo: {target} is not an existing directory (relative to the Hub root or absolute)")
+    try:
+        catalog = load_roles(root)
+    except LayerArtifactError as exc:
+        errors.append(str(exc))
+    else:
+        _roles(metadata.get("planning_roles"), "planning_roles", "plan", catalog, errors, True)
+        implementers = _roles(metadata.get("implementation_roles"), "implementation_roles", "implement", catalog, errors, True)
+        verifiers = _roles(metadata.get("verification_roles"), "verification_roles", "verify", catalog, errors, True)
+        if set(implementers) & set(verifiers):
+            errors.append("verification_roles: a role cannot verify its own implementation")
+    deps = _strings(metadata.get("depends_on"), "depends_on", errors)
+    if any(not TASK_PATTERN.fullmatch(dep) for dep in deps):
+        errors.append("depends_on: each entry must be a task ID")
+    if metadata.get("status") != "planned":
+        record = re.search(r"(?ms)^## Implementation Record\s*\n(.*)", body)
+        if record is None:
+            errors.append("missing Implementation Record")
+        else:
+            fields = dict(re.findall(r"(?m)^- ([A-Za-z_]+):\s*(.*)$", record[1]))
+            if fields.get("status") != metadata.get("status"):
+                errors.append("Implementation Record status differs from Plan status")
+            _timestamp(fields.get("updated_at", "").strip('"'), "updated_at", errors)
+    return errors, metadata
+
+
+def _dependencies(records: list[tuple[Path, dict[str, Any]]]) -> list[str]:
+    errors: list[str] = []
+    tasks: dict[str, list[str]] = {}
+    for path, data in records:
+        task = data.get("task_id")
+        if not isinstance(task, str) or not TASK_PATTERN.fullmatch(task):
+            errors.append(f"{path}: invalid task_id")
+            continue
+        if task in tasks:
+            errors.append(f"duplicate task_id: {task}")
+        deps = _strings(data.get("depends_on"), f"{path}: depends_on", errors)
+        tasks[task] = [dep for dep in deps if TASK_PATTERN.fullmatch(dep)]
+        if len(tasks[task]) != len(deps):
+            errors.append(f"{path}: invalid dependency ID")
+    indegree = {task: 0 for task in tasks}
+    children: dict[str, list[str]] = {task: [] for task in tasks}
+    for task, deps in tasks.items():
+        for dep in deps:
+            if dep not in tasks:
+                errors.append(f"{task}: dependency {dep} is not in this package")
+            else:
+                children[dep].append(task)
+                indegree[task] += 1
+    ready = deque(task for task, count in indegree.items() if count == 0)
+    visited = 0
+    while ready:
+        task = ready.popleft()
+        visited += 1
+        for child in children[task]:
+            indegree[child] -= 1
+            if indegree[child] == 0:
+                ready.append(child)
+    if visited != len(tasks):
+        errors.append("dependency cycle in this package")
+    return errors
+
+
+def validate_plan_path(path: Path, root: Path) -> list[str]:
+    path, root = path.resolve(), root.resolve()
+    if not path.exists():
+        return ["expected an existing Plan file or package directory"]
+    package = path.parent if path.is_file() else path
+    selected = [path] if path.is_file() else sorted(path.glob("*.md"))
+    if not selected:
+        return ["Plan package has no Markdown files"]
+    errors: list[str] = []
+    records = []
+    for item in sorted(package.glob("*.md")):
+        try:
+            records.append((item, _frontmatter_and_body(item)[0]))
+        except LayerArtifactError as exc:
+            errors.append(str(exc))
+    errors.extend(_dependencies(records))
+    for item in selected:
+        errors.extend(f"{item}: {error}" for error in _plan_file(item, root)[0])
+    return errors
+
+
+# ---------- Review ----------
+
+
+def validate_review_file(path: Path, root: Path) -> list[str]:
+    root, path = root.resolve(), path.resolve()
+    errors, metadata, _ = _basic(path, root, "review")
+    if not metadata:
+        return errors
+    if metadata.get("status") not in REVIEW_STATUSES:
+        errors.append("status must be completed or blocked")
+    if metadata.get("business_verdict") not in VERDICTS or metadata.get("verdict") != metadata.get("business_verdict"):
+        errors.append("verdict must match business_verdict: PASS, FAIL or BLOCKED")
+    round_number = metadata.get("review_round")
+    if type(round_number) is not int or round_number < 1:
+        errors.append("review_round must be a positive integer")
+    try:
+        plan = _reference_path(metadata.get("plan_file"), root, "plan_file")
+        plan_metadata, _ = _frontmatter_and_body(plan)
+        if plan_metadata.get("schema") != PLAN_SCHEMA or plan_metadata.get("task_id") != metadata.get("task_id"):
+            errors.append("plan_file does not identify the reviewed Plan/task")
+        prior = metadata.get("prior_review")
+        if prior is not None:
+            previous, _ = _frontmatter_and_body(_reference_path(prior, root, "prior_review"))
+            same_plan = resolve_path(previous.get("plan_file"), root) == plan if previous.get("plan_file") else False
+            if not same_plan or previous.get("task_id") != metadata.get("task_id"):
+                errors.append("prior_review belongs to another Plan/task")
+            if type(round_number) is int and previous.get("review_round") != round_number - 1:
+                errors.append("prior_review must identify the preceding round")
+        elif type(round_number) is int and round_number > 1:
+            errors.append("prior_review is required after round 1")
+        catalog = load_roles(root)
+        _roles(metadata.get("review_roles"), "review_roles", "review", catalog, errors, True)
+        _roles(metadata.get("repair_roles"), "repair_roles", "implement", catalog, errors, False)
+    except (OSError, UnicodeError, LayerArtifactError, RecursionError) as exc:
+        errors.append(str(exc))
+    return errors
+
+
+def repository_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--kind", choices=("plan", "review"), required=True)
+    parser.add_argument("--path", type=Path, required=True)
+    parser.add_argument("--root", type=Path, default=repository_root())
+    args = parser.parse_args()
+    validator = validate_plan_path if args.kind == "plan" else validate_review_file
+    errors = validator(args.path, args.root)
+    print(json.dumps({"passed": not errors, "kind": args.kind, "path": args.path.as_posix(), "errors": errors}, ensure_ascii=False, indent=2))
+    return 0 if not errors else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())