pirl-framework-cli 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,264 @@
+"""Check the record writer's public contract: accepted records, actionable rejections and stored lines."""
+from __future__ import annotations
+
+import copy
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from datetime import datetime
+from pathlib import Path
+
+EVALS = Path(__file__).resolve().parents[1]
+TOOL = EVALS / "layer_record.py"
+sys.path.insert(0, str(EVALS))
+from validate_layer_artifact import CATALOG  # noqa: E402
+
+ROLES = """### Role catalog
+
+| ID | Expertise | Used in |
+| --- | --- | --- |
+| `business-analyst` | Business logic | plan, review |
+| `code-analyst` | Flow tracing | plan, verify, review |
+| `backend-developer` | Non-UI code | implement |
+| `code-reviewer` | Challenges the diff | verify, review |
+| `process-auditor` | Self-evaluation | audit |
+
+### Other section
+"""
+# Records are stored as UTF-8 without escaping; this sample checks that non-ASCII text survives.
+NON_ASCII = "Không quét tài liệu ngoài đường dẫn Plan"
+REF = {"commit": "none", "files": {"AGENTS.md": "0123456789ab"}}
+IMPLEMENT = {
+    "layer": "implement",
+    "framework_ref": REF,
+    "task": {"plan_set": "sign-in_20261014-090000", "task_ids": ["T01"]},
+    "target_repo": ".",
+    "outcome": {"status": "implemented", "summary": "Added a check for expired OTP codes"},
+    "roles": [
+        {"role": "backend-developer", "mode": "agent", "assignment": "Fix OTP verification", "result": "PASS"},
+        {"role": "code-reviewer", "mode": "agent", "assignment": "Conclude QG-01", "result": "PASS"},
+    ],
+    "audit": {"role": "process-auditor", "mode": "agent", "result": "issues"},
+    "issues": [{
+        "id": "ISSUE-01", "issue_key": "skip-consistency-sweep", "role": "backend-developer", "record": None,
+        "cause": "instruction", "decision": "Did not sweep documentation outside the Plan paths",
+        "rule": ".agents/instructions/implement.instructions.md#implementing-and-repairing-per-review",
+        "evidence": "The API index still describes the old behavior", "prior_fix": None,
+    }],
+    "fixes": [{
+        "id": "FIX-01", "issues": ["ISSUE-01"], "status": "applied",
+        "files": [{"path": ".agents/instructions/implement.instructions.md", "section": "Implementing and repairing per Review"}],
+        "summary": "State that indexes and status tables must be swept", "checks": ["python -B -m unittest discover"],
+    }],
+    "evaluates": None,
+    "supersedes": None,
+}
+
+
+class LayerRecordTests(unittest.TestCase):
+    def setUp(self):
+        temporary = tempfile.TemporaryDirectory()
+        self.addCleanup(temporary.cleanup)
+        self.root = Path(temporary.name)
+        (self.root / "AGENTS.md").write_text("# Start here\n", encoding="utf-8")
+        (self.root / CATALOG).parent.mkdir(parents=True)
+        (self.root / CATALOG).write_text(ROLES, encoding="utf-8")
+        # Reports live wherever the user puts them; by default under the Hub root.
+        self.report = self.root / "sign-in_20261014-090000/t01-otp/round-01.md"
+        self.report.parent.mkdir(parents=True)
+        self.report.write_text("---\n---\n", encoding="utf-8")
+
+    def run_tool(self, *args, payload=None, raw=None):
+        stdin = raw if raw is not None else (json.dumps(payload, ensure_ascii=False).encode("utf-8") if payload is not None else b"")
+        result = subprocess.run([sys.executable, "-B", str(TOOL), "--root", str(self.root), *args], input=stdin, capture_output=True)
+        return result.returncode, json.loads(result.stdout.decode("utf-8"))
+
+    def append(self, payload):
+        return self.run_tool("append", payload=payload)
+
+    def stored(self):
+        return [json.loads(line) for path in sorted((self.root / ".agents/evals/records").glob("*/*.jsonl"))
+                for line in path.read_text(encoding="utf-8").splitlines()]
+
+    def test_append_stores_one_utf8_line_with_tool_fields(self):
+        payload = copy.deepcopy(IMPLEMENT)
+        payload["outcome"]["summary"] = NON_ASCII
+        code, result = self.append(payload)
+        self.assertEqual(code, 0, result)
+        self.assertTrue(result["record_id"].startswith("implement-") and result["record_id"].endswith("-T01"))
+        self.assertTrue(result["path"].startswith(".agents/evals/records/implement/"))
+        [record] = self.stored()
+        self.assertEqual(record["schema"], "pirl-record/v1")
+        self.assertEqual(record["outcome"]["summary"], NON_ASCII)
+        self.assertIsNotNone(datetime.fromisoformat(record["recorded_at"]).utcoffset())
+        code, again = self.append(IMPLEMENT)
+        self.assertEqual(code, 0, again)
+        self.assertNotEqual(again["record_id"], result["record_id"])
+
+    def test_input_file_with_bom_keeps_non_ascii_text(self):
+        payload = copy.deepcopy(IMPLEMENT)
+        payload["issues"][0]["decision"] = NON_ASCII
+        source = self.root / "record.json"
+        source.write_bytes(b"\xef\xbb\xbf" + json.dumps(payload, ensure_ascii=False).encode("utf-8"))
+        code, result = self.run_tool("append", "--input", str(source))
+        self.assertEqual(code, 0, result)
+        self.assertEqual(self.stored()[0]["issues"][0]["decision"], NON_ASCII)
+        code, result = self.run_tool("append", raw="not JSON".encode("utf-8"))
+        self.assertNotEqual(code, 0)
+
+    def test_rejections_name_the_broken_rule(self):
+        def variant(change):
+            data = copy.deepcopy(IMPLEMENT)
+            change(data)
+            return data
+
+        cases = {
+            "self-evaluation cannot apply": variant(lambda d: d["audit"].update(mode="self")),
+            "has no fix": variant(lambda d: d.update(fixes=[])),
+            "ineffective_fix must name an earlier fix": variant(lambda d: d["issues"][0].update(cause="ineffective_fix")),
+            "unknown role": variant(lambda d: d["roles"][0].update(role="implementer")),
+            "not registered for this layer": variant(lambda d: d["roles"][0].update(role="business-analyst")),
+            "did not take part": variant(lambda d: d["issues"][0].update(role="code-analyst")),
+            "set by the tool": variant(lambda d: d.update(record_id="x")),
+            "mode_self is only valid": variant(lambda d: d["fixes"][0].update(status="pending_user", reason="mode_self")),
+            "audit.result": variant(lambda d: d["audit"].update(result="clean")),
+        }
+        for message, payload in cases.items():
+            with self.subTest(message=message):
+                code, result = self.append(payload)
+                self.assertNotEqual(code, 0)
+                self.assertIn(message, " ".join(result["errors"]))
+        self.assertEqual(self.stored(), [])
+
+    def test_pending_fixes_follow_mode_and_safety(self):
+        self_run = copy.deepcopy(IMPLEMENT)
+        self_run["audit"]["mode"] = "self"
+        self_run["fixes"][0].update(status="pending_user", reason="mode_self")
+        self.assertEqual(self.append(self_run)[0], 0)
+        safety = copy.deepcopy(IMPLEMENT)
+        safety["fixes"][0].update(status="pending_user", reason="safety")
+        self.assertEqual(self.append(safety)[0], 0)
+        repository = copy.deepcopy(IMPLEMENT)
+        repository["issues"][0]["cause"] = "input"
+        repository["fixes"][0].update(status="pending_user", reason="repository",
+                                      files=[{"path": "sign-in_20261014-090000", "section": "Target repository context documentation"}])
+        self.assertEqual(self.append(repository)[0], 0)
+        unknown = copy.deepcopy(IMPLEMENT)
+        unknown["fixes"][0].update(status="pending_user", reason="later")
+        self.assertNotEqual(self.append(unknown)[0], 0)
+
+    def test_ineffective_fix_and_review_link_earlier_records(self):
+        _, first = self.append(IMPLEMENT)
+        repeat = copy.deepcopy(IMPLEMENT)
+        repeat["issues"][0].update(cause="ineffective_fix", prior_fix=f"{first['record_id']}#FIX-01")
+        code, second = self.append(repeat)
+        self.assertEqual(code, 0, second)
+        review = {
+            **copy.deepcopy(IMPLEMENT),
+            "layer": "review",
+            "task": {"plan_set": "sign-in_20261014-090000", "task_ids": ["T01"],
+                     "report_file": self.report.relative_to(self.root).as_posix()},
+            "outcome": {"status": "completed", "verdict": "FAIL", "summary": "FIND-01 expired OTP"},
+            "roles": [{"role": "code-reviewer", "mode": "agent", "assignment": "Challenge the diff", "result": "PASS"}],
+            "evaluates": second["record_id"],
+        }
+        review["issues"][0].update(role="code-reviewer", record=second["record_id"], cause="execution",
+                                   decision="Missed the expired OTP branch")
+        code, result = self.append(review)
+        self.assertEqual(code, 0, result)
+        absolute = copy.deepcopy(review)
+        absolute["task"]["report_file"] = str(self.report)
+        self.assertEqual(self.append(absolute)[0], 0)
+        missing = copy.deepcopy(review)
+        missing["evaluates"] = "implement-20000101-000000-T01"
+        self.assertNotEqual(self.append(missing)[0], 0)
+        found = self.run_tool("query", "--issue-key", "skip-consistency-sweep")[1]
+        self.assertEqual([r["layer"] for r in found], ["implement", "implement", "review", "review"])
+        self.assertEqual(found[0]["fixes"][0]["id"], "FIX-01")
+        self.assertEqual(len(self.run_tool("query", "--layer", "review", "--task", "T01")[1]), 2)
+
+    def test_check_resolves_references_by_time_not_by_layer_folder(self):
+        _, first = self.append(IMPLEMENT)
+        review = {
+            **copy.deepcopy(IMPLEMENT),
+            "layer": "review",
+            "task": {"plan_set": "sign-in_20261014-090000", "task_ids": ["T01"],
+                     "report_file": self.report.relative_to(self.root).as_posix()},
+            "outcome": {"status": "completed", "verdict": "FAIL", "summary": "FIND-01 expired OTP"},
+            "roles": [{"role": "code-reviewer", "mode": "agent", "assignment": "Challenge the diff", "result": "PASS"}],
+            "evaluates": first["record_id"],
+        }
+        review["issues"][0].update(role="code-reviewer", record=first["record_id"], cause="execution")
+        _, judged = self.append(review)
+        # The review folder sorts after the implement folder, yet this later implement record names the review's fix.
+        repeat = copy.deepcopy(IMPLEMENT)
+        repeat["issues"][0].update(cause="ineffective_fix", prior_fix=f"{judged['record_id']}#FIX-01")
+        code, second = self.append(repeat)
+        self.assertEqual(code, 0, second)
+        self.assertEqual(self.run_tool("check")[0], 0)
+        # A reference to a record written later than the referrer is still an error.
+        path = self.root / judged["path"]
+        text = path.read_text(encoding="utf-8")
+        later = text.replace('"recorded_at":"20', '"recorded_at":"29', 1)
+        self.assertNotEqual(later, text)
+        path.write_text(later, encoding="utf-8")
+        code, result = self.run_tool("check")
+        self.assertNotEqual(code, 0)
+        self.assertTrue(any("prior_fix" in error for error in result["errors"]), result)
+
+    def test_check_orders_records_by_instant_across_utc_offsets(self):
+        _, first = self.append(IMPLEMENT)
+        repeat = copy.deepcopy(IMPLEMENT)
+        repeat["issues"][0].update(cause="ineffective_fix", prior_fix=f"{first['record_id']}#FIX-01")
+        self.assertEqual(self.append(repeat)[0], 0)
+        path = self.root / first["path"]
+        lines = path.read_text(encoding="utf-8").splitlines()
+        # 10:00+07:00 is 03:00Z and comes before 04:00Z, although it sorts after "2026-10-14T04" as text.
+        stamps = ["2026-10-14T10:00:00+07:00", "2026-10-14T04:00:00+00:00"]
+        records = [json.loads(line) for line in lines]
+        for record, stamp in zip(records, stamps):
+            record["recorded_at"] = stamp
+        path.write_text("".join(json.dumps(r, ensure_ascii=False, separators=(",", ":")) + "\n" for r in records), encoding="utf-8")
+        self.assertEqual(self.run_tool("check")[0], 0)
+        records[0]["recorded_at"], records[1]["recorded_at"] = "2026-10-14T05:00:00+00:00", "2026-10-14T10:00:00+07:00"
+        path.write_text("".join(json.dumps(r, ensure_ascii=False, separators=(",", ":")) + "\n" for r in records), encoding="utf-8")
+        code, result = self.run_tool("check")
+        self.assertNotEqual(code, 0)
+        self.assertTrue(any("prior_fix" in error for error in result["errors"]), result)
+
+    def test_check_reads_stored_v1_lines_and_reports_corruption(self):
+        self.assertEqual(self.append(IMPLEMENT)[0], 0)
+        self.assertEqual(self.run_tool("check")[0], 0)
+        [path] = (self.root / ".agents/evals/records").glob("*/*.jsonl")
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write("{broken\n")
+        code, result = self.run_tool("check")
+        self.assertNotEqual(code, 0)
+        self.assertTrue(any("invalid JSON" in error for error in result["errors"]))
+        self.assertNotEqual(self.append(IMPLEMENT)[0], 0)
+
+    @unittest.skipUnless(shutil.which("git"), "git is required")
+    def test_start_pins_commit_and_changed_framework_files(self):
+        self.assertEqual(self.append(IMPLEMENT)[0], 0)
+        skill = self.root / ".skills/pirl-plan/SKILL.md"
+        skill.parent.mkdir(parents=True)
+        skill.write_text("---\nname: plan\n---\n", encoding="utf-8")
+        ref = self.run_tool("start")[1]["framework_ref"]
+        self.assertEqual(ref["commit"], "none")
+        # Skills are framework files; records are local output, not framework content.
+        self.assertEqual(sorted(ref["files"]), [CATALOG, ".skills/pirl-plan/SKILL.md", "AGENTS.md"])
+        git = ["git", "-C", str(self.root), "-c", "user.email=t@t", "-c", "user.name=t"]
+        subprocess.run([*git, "init", "-q"], check=True)
+        subprocess.run([*git, "add", "-A"], check=True)
+        subprocess.run([*git, "commit", "-qm", "init"], check=True)
+        (self.root / "AGENTS.md").write_text("# Start here\nchanged\n", encoding="utf-8")
+        ref = self.run_tool("start")[1]["framework_ref"]
+        self.assertRegex(ref["commit"], r"^[0-9a-f]{40}$")
+        self.assertEqual(list(ref["files"]), ["AGENTS.md"])
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,210 @@
+"""Check the layer skills as packages (frontmatter, resources, helper scripts) and the links between framework files."""
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+EVALS = Path(__file__).resolve().parents[1]
+REPO = EVALS.parents[1]
+SKILLS = REPO / ".skills"
+sys.path.insert(0, str(EVALS))
+from layer_record import FRAMEWORK_PATHS, LAYERS, NOT_FRAMEWORK, NOT_FRAMEWORK_TRACKED, RECORDS  # noqa: E402
+from validate_layer_artifact import CATALOG, parse_yaml_subset  # noqa: E402
+
+LINK = re.compile(r"\[[^\]]*\]\(([^)\s]+)\)")
+FENCE = re.compile(r"(?ms)^(`{3,})[^\n]*\n.*?^\1\s*$")
+
+
+def git(*args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(["git", "-C", str(REPO), "-c", "core.quotepath=off", *args], capture_output=True, text=True)
+
+
+def repository_files(pattern: str = "*") -> list[str]:
+    """Every file Git tracks or would track (ignored outputs excluded), so no hand-kept list decides what is checked."""
+
+    return sorted(set(git("ls-files", "--cached", "--others", "--exclude-standard", "--", pattern).stdout.splitlines()))
+
+
+HAS_GIT = shutil.which("git") is not None and git("rev-parse", "--git-dir").returncode == 0
+
+
+def anchors(path: Path) -> set[str]:
+    """GitHub heading anchors: lowercase, punctuation dropped, spaces turned into hyphens."""
+
+    text = FENCE.sub("", path.read_text(encoding="utf-8"))
+    return {re.sub(r"[^\w\- ]", "", heading.strip().lower()).replace(" ", "-")
+            for heading in re.findall(r"(?m)^#{1,6} (.+)$", text)}
+
+
+class SkillPackageTests(unittest.TestCase):
+    def test_each_layer_has_a_complete_skill(self):
+        for layer in LAYERS:
+            skill = SKILLS / f"pirl-{layer}"
+            with self.subTest(skill=layer):
+                text = (skill / "SKILL.md").read_text(encoding="utf-8")
+                header = text.split("---")[1]
+                meta = parse_yaml_subset(header, f"{skill.name}/SKILL.md")
+                self.assertEqual(meta.get("name"), skill.name)
+                self.assertTrue(isinstance(meta.get("description"), str) and 0 < len(meta["description"]) <= 1024)
+                self.assertEqual(meta.get("metadata", {}).get("layer"), layer)
+                self.assertRegex(str(meta.get("metadata", {}).get("version")), r"^\d+\.\d+\.\d+$")
+                self.assertTrue((REPO / f".agents/instructions/{layer}.instructions.md").is_file())
+                for folder in ("assets", "references", "scripts"):
+                    self.assertTrue([p for p in (skill / folder).glob("*") if p.is_file()], f"{skill.name}/{folder} is empty")
+                self.assertEqual(set(SKILLS.iterdir()), {SKILLS / f"pirl-{name}" for name in LAYERS})
+
+
+@unittest.skipUnless(HAS_GIT, "a git checkout is required")
+class FrameworkLinkTests(unittest.TestCase):
+    def test_relative_links_and_anchors_resolve(self):
+        for source in (REPO / name for name in repository_files("*.md")):
+            text = FENCE.sub("", source.read_text(encoding="utf-8"))
+            for target in LINK.findall(text):
+                if re.match(r"[a-z]+:", target):
+                    continue
+                file_part, _, anchor = target.partition("#")
+                resolved = (source.parent / file_part).resolve() if file_part else source
+                with self.subTest(source=source.relative_to(REPO).as_posix(), target=target):
+                    self.assertTrue(resolved.exists(), "link target does not exist")
+                    if anchor and resolved.suffix == ".md":
+                        self.assertIn(anchor, anchors(resolved))
+
+
+@unittest.skipUnless(HAS_GIT, "a git checkout is required")
+class PrivateOutputTests(unittest.TestCase):
+    """Plan packages, their reports and records describe the user's projects and must stay out of Git.
+
+    The paths come from the scripts and constants that produce them, so a change in how outputs are named is
+    checked against .gitignore instead of a hand-written sample that would keep passing.
+    """
+
+    def ignored(self, path):
+        return git("check-ignore", "--no-index", "-q", path).returncode == 0
+
+    def test_produced_outputs_are_ignored(self):
+        new_plan = SKILLS / "pirl-plan/scripts/new_plan.py"
+        new_review = SKILLS / "pirl-review/scripts/new_review.py"
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            produced = []
+            for extra in ([], ["--out-dir", "plans"]):
+                result = subprocess.run([sys.executable, "-X", "utf8", "-B", str(new_plan), "--root", str(root),
+                                         "--request-slug", "order-email", "--todo-slug", "send-email", *extra],
+                                        capture_output=True, text=True, encoding="utf-8")
+                plan = json.loads(result.stdout)
+                self.assertEqual(result.returncode, 0, plan)
+                result = subprocess.run([sys.executable, "-X", "utf8", "-B", str(new_review), "--root", str(root),
+                                         "--plan", plan["path"], "--todo-slug", "send-email", *extra],
+                                        capture_output=True, text=True, encoding="utf-8")
+                review = json.loads(result.stdout)
+                self.assertEqual(result.returncode, 0, review)
+                produced += [plan["path"], review["path"]]
+        produced.append(f"{RECORDS}/plan/2026-10-23.jsonl")
+        for path in produced:
+            with self.subTest(path=path):
+                self.assertTrue(self.ignored(path))
+
+    def test_no_tracked_file_is_ignored(self):
+        self.assertEqual(git("ls-files", "--cached", "--ignored", "--exclude-standard").stdout.splitlines(), [])
+
+    def test_every_tracked_file_is_classified(self):
+        def framework(path):
+            return any(path == base or path.startswith(base + "/") for base in FRAMEWORK_PATHS)
+
+        for path in repository_files():
+            if any(prefix in path for prefix in NOT_FRAMEWORK):
+                continue
+            with self.subTest(path=path):
+                self.assertTrue(framework(path) or path in NOT_FRAMEWORK_TRACKED,
+                                "add the path to FRAMEWORK_PATHS or NOT_FRAMEWORK_TRACKED in layer_record.py")
+
+
+class SkillScriptTests(unittest.TestCase):
+    """Run the helper scripts against a temporary Hub and check their output with the real validator."""
+
+    def setUp(self):
+        temporary = tempfile.TemporaryDirectory()
+        self.addCleanup(temporary.cleanup)
+        self.root = Path(temporary.name)
+        (self.root / CATALOG).parent.mkdir(parents=True)
+        shutil.copy(REPO / CATALOG, self.root / CATALOG)
+
+    def run_script(self, script, *args):
+        result = subprocess.run([sys.executable, "-X", "utf8", "-B", str(script), "--root", str(self.root), *args],
+                                capture_output=True, text=True, encoding="utf-8")
+        return result.returncode, json.loads(result.stdout)
+
+    def validate(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 new_plan(self, *args):
+        return self.run_script(SKILLS / "pirl-plan/scripts/new_plan.py", *args)
+
+    def fill_plan(self, path):
+        text = path.read_text(encoding="utf-8")
+        for placeholder, value in (("[<planning-role>]", "[code-analyst]"), ("[<implementation-role>]", "[backend-developer]"),
+                                   ("[<verification-role>]", "[code-reviewer]")):
+            text = text.replace(placeholder, value)
+        text = re.sub(r'(?m)^target_repo: ".*"$', 'target_repo: "."', text)
+        path.write_text(text, encoding="utf-8")
+
+    def test_plan_package_review_rounds_and_record_pass_the_validator(self):
+        code, first = self.new_plan("--request-slug", "order-email", "--todo-slug", "send-email")
+        self.assertEqual(code, 0, first)
+        self.assertEqual(first["task_id"], "T01")
+        self.assertRegex(first["path"], r"^order-email_\d{8}-\d{6}/01-plan-send-email-\d{8}-\d{6}\.md$")
+        code, second = self.new_plan("--plan-set", first["plan_set"], "--todo-slug", "log-email")
+        self.assertEqual(code, 0, second)
+        self.assertEqual(second["task_id"], "T02")
+        self.assertTrue(second["path"].endswith(first["plan_set"].split("_")[1] + ".md"))
+        self.assertNotEqual(self.new_plan("--request-slug", "Bad Slug", "--todo-slug", "x")[0], 0)
+        plan = self.root / first["path"]
+        for path in (plan, self.root / second["path"]):
+            self.fill_plan(path)
+        code, result = self.validate("plan", plan.parent)
+        self.assertEqual(code, 0, result)
+
+        review = SKILLS / "pirl-review/scripts/new_review.py"
+        code, round_one = self.run_script(review, "--plan", first["path"], "--todo-slug", "send-email")
+        self.assertEqual(code, 0, round_one)
+        self.assertEqual((round_one["review_round"], round_one["prior_review"]), (1, None))
+        self.assertTrue(round_one["path"].startswith(f"{first['plan_set']}/t01-send-email/round-01-review-send-email-"))
+        self.assertEqual(self.validate("review", self.root / round_one["path"])[0], 0)
+        code, round_two = self.run_script(review, "--plan", first["path"], "--todo-slug", "send-email")
+        self.assertEqual(code, 0, round_two)
+        self.assertEqual((round_two["review_round"], round_two["prior_review"]), (2, round_one["path"]))
+        code, result = self.validate("review", self.root / round_two["path"])
+        self.assertEqual(code, 0, result)
+
+        record = SKILLS / "pirl-implement/scripts/add_implementation_record.py"
+        self.assertEqual(self.run_script(record, "--plan", first["path"])[0], 0)
+        self.assertNotEqual(self.run_script(record, "--plan", first["path"])[0], 0)
+        text = plan.read_text(encoding="utf-8").replace("status: planned", "status: implemented", 1)
+        text = text.replace("- status: awaiting_confirmation | implemented | blocked | failed", "- status: implemented")
+        plan.write_text(text, encoding="utf-8")
+        code, result = self.validate("plan", plan)
+        self.assertEqual(code, 0, result)
+
+    def test_plan_and_layout_run_outside_the_default_location(self):
+        outside = tempfile.TemporaryDirectory()
+        self.addCleanup(outside.cleanup)
+        code, plan = self.new_plan("--request-slug", "cart", "--todo-slug", "badge", "--out-dir", outside.name)
+        self.assertEqual(code, 0, plan)
+        self.assertTrue(Path(plan["path"]).is_absolute() and Path(plan["path"]).is_file())
+        code, run = self.run_script(SKILLS / "pirl-implement/scripts/new_layout_run.py", "--plan", plan["path"])
+        self.assertEqual(code, 0, run)
+        self.assertRegex(run["path"], rf"^\.tmp/layout-snapshots/{plan['plan_set']}/T01/\d{{8}}-\d{{6}}$")
+        self.assertTrue((self.root / run["path"]).is_dir())
+
+
+if __name__ == "__main__":
+    unittest.main()