@ikon85/agent-workflow-kit 0.27.0 → 0.28.0

package/scripts/test_board_sync.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""Behavior tests for bounded board operations; the fake seam never calls GitHub."""
+
+from __future__ import annotations
+
+import io
+import json
+import subprocess
+import unittest
+from contextlib import redirect_stderr, redirect_stdout
+from unittest.mock import patch
+
+import importlib.util
+from pathlib import Path
+
+
+SPEC = importlib.util.spec_from_file_location(
+    "board_sync_operations_test", Path(__file__).with_name("board-sync.py"))
+bs = importlib.util.module_from_spec(SPEC)
+assert SPEC.loader is not None
+SPEC.loader.exec_module(bs)
+
+
+class FakeGh:
+    def __init__(self, responses=None, failures=None):
+        self.responses = responses or {}
+        self.failures = failures or {}
+        self.calls = []
+
+    def __call__(self, args):
+        self.calls.append(args)
+        joined = " ".join(args)
+        for needle, body in self.failures.items():
+            if needle in joined:
+                error = bs.GhError("injected failure")
+                error.stdout = body
+                raise error
+        for needle, body in self.responses.items():
+            if needle in joined:
+                return body
+        return ""
+
+
+def run(fake, argv):
+    old = bs._gh
+    bs._gh = fake
+    out = io.StringIO()
+    try:
+        with redirect_stdout(out):
+            code = bs.main(argv)
+    finally:
+        bs._gh = old
+    return code, out.getvalue()
+
+
+class BoundedCalls(unittest.TestCase):
+    def test_full_board_and_ordinary_calls_have_distinct_clear_timeouts(self):
+        with patch.object(bs.subprocess, "run", side_effect=subprocess.TimeoutExpired("gh", 1)) as call:
+            with self.assertRaisesRegex(bs.GhError, "15s"):
+                bs._gh(["issue", "view", "1"])
+            self.assertEqual(call.call_args.kwargs["timeout"], 15)
+            with self.assertRaisesRegex(bs.GhError, "60s"):
+                bs._gh(["project", "item-list", "3"])
+            self.assertEqual(call.call_args.kwargs["timeout"], 60)
+
+    def test_partial_create_prints_issue_and_replay_safe_repair(self):
+        fake = FakeGh(
+            {"issue list": "[]", "issue create": "https://github.com/x/y/issues/17\n"},
+            {"project item-add": ""},
+        )
+        with patch.object(bs, "REPO", "x/y"):
+            with self.subTest("created issue remains visible"):
+                from tempfile import NamedTemporaryFile
+                with NamedTemporaryFile("w") as body:
+                    body.write("<!-- program-leaf-source: p/1 -->\n")
+                    body.flush()
+                    code, out = run(fake, ["create", "--title", "S", "--body-file", body.name])
+        self.assertEqual(code, 1)
+        self.assertIn("#17 https://github.com/x/y/issues/17", out)
+        self.assertIn("board-sync.py add --issue 17", out)
+        self.assertIn("idempotent", out)
+
+
+class WaveLookup(unittest.TestCase):
+    def test_search_finds_next_wave_without_full_scan(self):
+        fake = FakeGh({"search/issues": json.dumps({"items": [
+            {"title": f"{bs.WAVE_TITLE_PREFIX} 7 — Anchor"},
+            {"title": f"{bs.WAVE_TITLE_PREFIX} 8 / Slice 1 — Leaf"},
+        ]})})
+        code, out = run(fake, ["next-wave"])
+        self.assertEqual((code, out.strip()), (0, "9"))
+        self.assertFalse(any("item-list" in " ".join(c) for c in fake.calls))
+
+    def test_empty_search_falls_back_and_scan_skips_search(self):
+        fake = FakeGh({"search/issues": '{"items":[]}', "item-list": '{"items":[{"wave":4}]}'})
+        with redirect_stderr(io.StringIO()):
+            self.assertEqual(run(fake, ["next-wave"])[1].strip(), "5")
+        scan = FakeGh({"item-list": '{"items":[{"wave":9}]}'})
+        self.assertEqual(run(scan, ["next-wave", "--scan"])[1].strip(), "10")
+        self.assertFalse(any("search/issues" in " ".join(c) for c in scan.calls))
+
+    def test_promotion_refuses_foreign_anchor_but_allows_same_issue(self):
+        foreign = {"items": [{"number": 22, "title": f"{bs.WAVE_TITLE_PREFIX} 7 — Other"}]}
+        message = bs.wave_collision_guard(foreign, 7, 21)
+        self.assertIn("#22", message)
+        self.assertIn("next-wave", message)
+        self.assertIsNone(bs.wave_collision_guard(foreign, 7, 22))
+        leaf = {"items": [{"number": 23, "title": f"{bs.WAVE_TITLE_PREFIX} 7 / Slice 1 — X"}]}
+        self.assertIsNone(bs.wave_collision_guard(leaf, 7, 21))
+
+    def test_promote_collision_fails_before_any_write(self):
+        fake = FakeGh({
+            "--json labels": "",
+            "--json body": "Draft PRD\n",
+            "graphql": '{"data":{"repository":{"issue":{"projectItems":{"nodes":[]}}}}}',
+            "search/issues": json.dumps({"items": [
+                {"number": 22, "title": f"{bs.WAVE_TITLE_PREFIX} 7 — Other"},
+            ]}),
+        })
+        error = io.StringIO()
+        with redirect_stderr(error):
+            code, _ = run(fake, ["promote", "--issue", "21", "--wave", "7"])
+        self.assertEqual(code, 1)
+        self.assertIn("#22", error.getvalue())
+        self.assertFalse(any(c[:2] == ["issue", "edit"] for c in fake.calls))
+
+
+class TargetedLookup(unittest.TestCase):
+    @staticmethod
+    def payload(project):
+        return {"data": {"repository": {"issue": {"projectItems": {"nodes": [{
+            "id": "PVTI_x", "project": {"id": project}, "fieldValues": {"nodes": [
+                {"number": 7, "field": {"id": bs.WAVE_FIELD_ID}},
+                {"name": "Spec", "field": {"id": bs.STATUS_FIELD_ID}},
+            ]},
+        }]}}}}}
+
+    def test_item_of_returns_configured_fields(self):
+        fake = FakeGh({"graphql": json.dumps(self.payload(bs.PROJECT_NODE_ID))})
+        code, out = run(fake, ["item-of", "--issue", "21"])
+        self.assertEqual(code, 0)
+        self.assertEqual(json.loads(out), {"itemId": "PVTI_x", "wave": 7,
+                                           "status": "Spec", "cluster": None})
+
+    def test_item_of_fails_clearly_when_absent(self):
+        payload = {"data": {"repository": {"issue": {"projectItems": {"nodes": []}}}}}
+        code, out = run(FakeGh({"graphql": json.dumps(payload)}),
+                        ["item-of", "--issue", "99"])
+        self.assertEqual((code, out.strip()), (1, "NOT-ON-BOARD"))
+
+
+class ArchiveDone(unittest.TestCase):
+    def item_payload(self, count=1):
+        items = [{"id": f"D{i}", "status": bs.STATUS_ROLES["done"]} for i in range(count)]
+        items += [{"id": "OPEN", "status": bs.STATUS_ROLES["inProgress"]},
+                  {"id": "OLD", "status": bs.STATUS_ROLES["done"], "archived": True}]
+        return json.dumps({"items": items, "totalCount": len(items)})
+
+    def test_archive_defaults_to_dry_run_and_selects_only_active_done(self):
+        fake = FakeGh({"item-list": self.item_payload()})
+        code, out = run(fake, ["archive-done"])
+        self.assertEqual(code, 0)
+        self.assertIn("D0", out)
+        self.assertNotIn("OPEN", out)
+        self.assertNotIn("OLD", out)
+        self.assertFalse(any("archiveProjectV2Item" in " ".join(c) for c in fake.calls))
+
+    def test_apply_batches_at_thirty(self):
+        class BatchGh(FakeGh):
+            def __call__(self, args):
+                self.calls.append(args)
+                if "item-list" in args:
+                    return self.responses["item-list"]
+                count = " ".join(args).count("archiveProjectV2Item")
+                return json.dumps({"data": {f"a{i}": {"item": {"id": f"x{i}"}}
+                                             for i in range(count)}})
+        fake = BatchGh({"item-list": self.item_payload(31)})
+        code, out = run(fake, ["archive-done", "--apply"])
+        self.assertEqual(code, 0)
+        self.assertIn("31 of 31", out)
+        calls = [c for c in fake.calls if "archiveProjectV2Item" in " ".join(c)]
+        self.assertEqual([" ".join(c).count("archiveProjectV2Item") for c in calls], [30, 1])
+
+    def test_truncated_input_refuses_without_mutation(self):
+        fake = FakeGh({"item-list": '{"items":[{"id":"D","status":"Done"}],"totalCount":2}'})
+        err = io.StringIO()
+        with redirect_stderr(err):
+            code, _ = run(fake, ["archive-done", "--apply"])
+        self.assertEqual(code, 1)
+        self.assertIn("partial archive", err.getvalue())
+        self.assertFalse(any("archiveProjectV2Item" in " ".join(c) for c in fake.calls))
+
+    def test_apply_reports_partial_failure_and_empty_replay_is_idempotent(self):
+        body = json.dumps({"data": {"a0": {"item": {"id": "D0"}}, "a1": None},
+                           "errors": [{"path": ["a1"], "message": "already archived"}]})
+        fake = FakeGh({"item-list": self.item_payload(2)}, {"archiveProjectV2Item": body})
+        code, out = run(fake, ["archive-done", "--apply"])
+        self.assertEqual(code, 1)
+        self.assertIn("1 of 2", out)
+        self.assertIn("D1: already archived", out)
+        empty = FakeGh({"item-list": json.dumps({"items": [], "totalCount": 0})})
+        code, out = run(empty, ["archive-done", "--apply"])
+        self.assertEqual(code, 0)
+        self.assertIn("nothing to archive", out)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/scripts/test_census_backstop.py

@@ -4,6 +4,7 @@ import os
 import subprocess
 import sys
 import tempfile
+import time
 import unittest
 from pathlib import Path
 from unittest.mock import patch
@@ -45,6 +46,35 @@ class CensusBackstopTest(unittest.TestCase):
             json.dumps(fresh) + "\n", encoding="utf-8"
         )
 
+    def test_census_bridge_uses_production_scale_budgets_and_clamps_proofs(self):
+        temporary, root = self.make_repo()
+        self.addCleanup(temporary.cleanup)
+        self.enable(root)
+        calls = []
+
+        def complete_scan(*args, **kwargs):
+            calls.append(kwargs)
+            return subprocess.CompletedProcess(
+                args=args[0], returncode=0,
+                stdout=json.dumps({"state": "bootstrap"}), stderr="",
+            )
+
+        with patch.object(DRIFT_GUARD.subprocess, "run", side_effect=complete_scan):
+            DRIFT_GUARD.scan_census_status(root)
+            DRIFT_GUARD.scan_census_status(root, proof_timeout_ms=10**9)
+
+        default_input = json.loads(calls[0]["input"])
+        clamped_input = json.loads(calls[1]["input"])
+        self.assertEqual(calls[0]["timeout"], 30)
+        self.assertEqual(default_input["proofTimeoutMs"], 12_000)
+        self.assertGreater(clamped_input["proofTimeoutMs"], 0)
+        self.assertLess(clamped_input["proofTimeoutMs"], calls[1]["timeout"] * 1_000)
+
+        for invalid in (False, 1.5, "12000"):
+            with self.subTest(invalid=invalid):
+                with self.assertRaisesRegex(ValueError, "proof timeout must be an integer"):
+                    DRIFT_GUARD.scan_census_status(root, proof_timeout_ms=invalid)
+
     def test_missing_disabled_bootstrap_and_offline_are_visible_but_fail_open(self):
         temporary, root = self.make_repo()
         self.addCleanup(temporary.cleanup)
@@ -322,15 +352,14 @@ class CensusBackstopTest(unittest.TestCase):
                          ("refresh_required", True))
         self.assertIn("proof:src", failed_test["reasons"])
 
-    def test_activated_census_blocks_when_local_proof_times_out(self):
+    def test_production_scale_proof_completes_and_hung_proofs_stay_bounded(self):
         temporary, root = self.make_repo()
         self.addCleanup(temporary.cleanup)
         module = root / "scanner.mjs"
         test = root / "scanner.test.mjs"
         module.write_text("export function scanLocal() { return ['src']; }\n", encoding="utf-8")
         test.write_text(
-            "import { test } from 'node:test'; "
-            "test('hang', async () => new Promise(resolve => setTimeout(resolve, 250)));\n",
+            "import { test } from 'node:test'; test('proof', () => {});\n",
             encoding="utf-8",
         )
         subprocess.run(["git", "add", "scanner.mjs", "scanner.test.mjs"], cwd=root, check=True)
@@ -341,11 +370,32 @@ class CensusBackstopTest(unittest.TestCase):
         self.enable(root, local_scanners=[scanner])
         self.activate_current(root)
 
+        module.write_text(
+            "export async function scanLocal() { "
+            "await new Promise(resolve => setTimeout(resolve, 5200)); return ['src']; }\n",
+            encoding="utf-8",
+        )
+        valid_started = time.monotonic()
+        valid = DRIFT_GUARD.evaluate_census(root)
+        valid_elapsed = time.monotonic() - valid_started
+        self.assertEqual((valid["state"], valid["block_handoff"]), ("current", False))
+        self.assertGreater(valid_elapsed, 5)
+        self.assertLess(valid_elapsed, DRIFT_GUARD.CENSUS_BRIDGE_TIMEOUT_SECONDS)
+
+        test.write_text(
+            "import { test } from 'node:test'; "
+            "test('hang', async () => new Promise(resolve => setTimeout(resolve, 250)));\n",
+            encoding="utf-8",
+        )
+        module.write_text("export function scanLocal() { return ['src']; }\n", encoding="utf-8")
+        timeout_started = time.monotonic()
         result = DRIFT_GUARD.evaluate_census(root, proof_timeout_ms=25)
+        timeout_elapsed = time.monotonic() - timeout_started
 
         self.assertEqual((result["state"], result["block_handoff"]),
                          ("refresh_required", True))
         self.assertIn("proof:src", result["reasons"])
+        self.assertLess(timeout_elapsed, 2)
 
         test.write_text("import { test } from 'node:test'; test('proof', () => {});\n",
                         encoding="utf-8")
@@ -353,10 +403,13 @@ class CensusBackstopTest(unittest.TestCase):
             "export async function scanLocal() { return new Promise(() => {}); }\n",
             encoding="utf-8",
         )
+        scanner_timeout_started = time.monotonic()
         scanner_timeout = DRIFT_GUARD.evaluate_census(root, proof_timeout_ms=25)
+        scanner_timeout_elapsed = time.monotonic() - scanner_timeout_started
         self.assertEqual((scanner_timeout["state"], scanner_timeout["block_handoff"]),
                          ("refresh_required", True))
         self.assertIn("proof:src", scanner_timeout["reasons"])
+        self.assertLess(scanner_timeout_elapsed, 2)
 
     def test_activated_census_fails_closed_when_bridge_is_unavailable(self):
         temporary, root = self.make_repo()

package/scripts/test_orchestrate_wave_contract.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Reference-free behavioral contract for the portable orchestrate-wave skill.
+
+The parity table names outcomes, not the consumer that first proved them.  That
+keeps the regression test useful in every repository that installs the kit.
+
+Run: python3 scripts/test_orchestrate_wave_contract.py
+"""
+
+import re
+import unittest
+from pathlib import Path
+
+
+REPO = Path(__file__).resolve().parent.parent
+CLAUDE_SKILL = REPO / ".claude/skills/orchestrate-wave/SKILL.md"
+CODEX_SKILL = REPO / ".agents/skills/orchestrate-wave/SKILL.md"
+CLAUDE_BUILDER = (
+    REPO / ".claude/skills/orchestrate-wave/references/builder-contract.md"
+)
+CODEX_BUILDER = (
+    REPO / ".agents/skills/orchestrate-wave/references/builder-contract.md"
+)
+
+
+# Outcome -> fragments whose conjunction proves that portable behavior.
+BEHAVIORAL_PARITY = {
+    "collision-safe claim": (
+        "wave-active/<anchor>",
+        "ahead",
+        "uncommitted changes",
+        "LOCAL annotated tag",
+        "never push",
+    ),
+    "owner-safe abort cleanup": (
+        "this run planted",
+        "On ANY wave STOP/abort",
+        "Never delete a claim marker observed during a preflight collision",
+    ),
+    "dependency-aware retirement": (
+        "topological",
+        "internal import graph",
+        "ONE atomic slice",
+        "cycle",
+    ),
+    "safe stacked landing": (
+        "Do NOT rely on auto-retarget",
+        "FRESH PR",
+        "merge order",
+        "manual gate",
+    ),
+    "completion propagation": (
+        "Closing Conditions",
+        "completion status",
+        "native parent",
+        "Program-PRD",
+        "program sync",
+    ),
+}
+
+
+def markdown_body(text: str) -> str:
+    """Ignore frontmatter representation differences between adapters."""
+    if not text.startswith("---\n"):
+        return text
+    return text.split("\n---\n", 1)[1]
+
+
+class OrchestrateWaveContract(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.skill = CLAUDE_SKILL.read_text(encoding="utf-8")
+        cls.builder = CLAUDE_BUILDER.read_text(encoding="utf-8")
+
+    def test_reference_free_behavioral_parity_table(self):
+        prose = " ".join(self.skill.split())
+        for outcome, fragments in BEHAVIORAL_PARITY.items():
+            with self.subTest(outcome=outcome):
+                for fragment in fragments:
+                    self.assertIn(" ".join(fragment.split()), prose)
+
+        self.assertNotRegex(self.skill, re.compile(r"/home/|#[0-9]{3,}"))
+
+    def test_builder_commands_finish_in_the_foreground(self):
+        prose = " ".join(self.builder.split())
+        for fragment in (
+            "IN THE FOREGROUND",
+            "never background a test/gate command",
+            "completed command results",
+            "exit status",
+        ):
+            self.assertIn(" ".join(fragment.split()), prose)
+
+    def test_current_portable_contracts_survive_the_port(self):
+        for fragment in (
+            "project layer",
+            "Native blocking edges are the frontier authority",
+            "AFK heartbeat",
+            "Re-run your project's full CI/verify gate CENTRALLY yourself",
+            "already authenticated",
+        ):
+            self.assertIn(fragment, self.skill)
+
+    def test_claude_and_codex_surfaces_match(self):
+        self.assertEqual(
+            markdown_body(self.skill),
+            markdown_body(CODEX_SKILL.read_text(encoding="utf-8")),
+        )
+        self.assertEqual(
+            self.builder,
+            CODEX_BUILDER.read_text(encoding="utf-8"),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/test_pr_body_check.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""Behavior tests for the PR-body convention guard."""
+import importlib.util
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from unittest import mock
+from pathlib import Path
+from types import SimpleNamespace
+
+PROFILE_PATH = Path(__file__).parent.parent / "docs/agents/board-sync.md"
+TEST_ENV = os.environ.copy()
+TEST_ENV["BOARD_SYNC_PROFILE"] = str(PROFILE_PATH)
+_PREVIOUS_PROFILE = os.environ.get("BOARD_SYNC_PROFILE")
+os.environ["BOARD_SYNC_PROFILE"] = str(PROFILE_PATH)
+
+_SPEC = importlib.util.spec_from_file_location(
+    "pr_body_check", Path(__file__).parent / "pr-body-check.py")
+pbc = importlib.util.module_from_spec(_SPEC)
+_SPEC.loader.exec_module(pbc)
+if _PREVIOUS_PROFILE is None:
+    os.environ.pop("BOARD_SYNC_PROFILE", None)
+else:
+    os.environ["BOARD_SYNC_PROFILE"] = _PREVIOUS_PROFILE
+import pr_body_e2e as e2e  # noqa: E402
+
+SCRIPT_PATH = Path(__file__).parent / "pr-body-check.py"
+
+RETRO = "**Retro:** skipped — focused guard change"
+VALID_LEAF_BODY = f"closes #149\n{RETRO}"
+
+
+class E2eNaBodyEvidence(unittest.TestCase):
+    def test_no_trailer_and_no_evidence_is_green(self):
+        self.assertEqual(pbc.check_pr_body(VALID_LEAF_BODY, 149, None), [])
+
+    def test_no_trailer_with_evidence_is_green(self):
+        body = VALID_LEAF_BODY + "\nE2E: n/a — harmless extra context"
+        self.assertEqual(pbc.check_pr_body(body, 149, None), [])
+
+    def test_valid_trailer_without_body_evidence_is_actionable(self):
+        violations = pbc.check_pr_body(
+            VALID_LEAF_BODY,
+            149,
+            None,
+            has_e2e_na_trailer=True,
+        )
+        self.assertTrue(any("E2E: n/a" in violation for violation in violations))
+
+    def test_valid_trailer_with_non_empty_evidence_is_green(self):
+        body = VALID_LEAF_BODY + "\nE2E: n/a — backend-only change"
+        self.assertEqual(
+            pbc.check_pr_body(body, 149, None, has_e2e_na_trailer=True), []
+        )
+
+    def test_valid_trailer_with_empty_evidence_is_actionable(self):
+        body = VALID_LEAF_BODY + "\nE2E: n/a —   "
+        violations = pbc.check_pr_body(
+            body, 149, None, has_e2e_na_trailer=True
+        )
+        self.assertTrue(any("E2E: n/a" in violation for violation in violations))
+
+
+class ExistingBodyRules(unittest.TestCase):
+    def test_anchor_slice_still_accepts_part_of_and_leaf_close(self):
+        body = f"Part of #130\ncloses #149\n{RETRO}"
+        self.assertEqual(pbc.check_pr_body(body, 149, 130), [])
+
+    def test_anchor_slice_still_rejects_close_on_anchor(self):
+        body = f"Part of #130\ncloses #130\n{RETRO}"
+        self.assertTrue(any("130" in item for item in pbc.check_pr_body(body, 149, 130)))
+
+    def test_leaf_still_requires_active_close(self):
+        body = f"`closes #149`\n{RETRO}"
+        self.assertTrue(any("closes #149" in item for item in pbc.check_pr_body(body, 149, None)))
+
+    def test_retro_line_still_required(self):
+        self.assertTrue(any("Retro" in item for item in pbc.check_pr_body("closes #149", 149, None)))
+
+    def test_wave_pr_still_requires_part_of_without_closing_anchor(self):
+        body = f"Part of #130\ncloses #149\n{RETRO}"
+        self.assertEqual(pbc.check_pr_body(body, 130, None, is_anchor=True), [])
+
+
+class ImmutableRangeTrailer(unittest.TestCase):
+    def test_two_commit_range_finds_one_valid_trailer(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            repo = Path(temp_dir)
+            subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
+            subprocess.run(
+                ["git", "config", "user.email", "tests@example.invalid"],
+                cwd=repo,
+                check=True,
+            )
+            subprocess.run(
+                ["git", "config", "user.name", "Test User"], cwd=repo, check=True
+            )
+            (repo / "change.txt").write_text("base\n", encoding="utf-8")
+            subprocess.run(["git", "add", "change.txt"], cwd=repo, check=True)
+            subprocess.run(["git", "commit", "-qm", "base"], cwd=repo, check=True)
+            base = subprocess.check_output(
+                ["git", "rev-parse", "HEAD"], cwd=repo, text=True
+            ).strip()
+            (repo / "change.txt").write_text("head\n", encoding="utf-8")
+            subprocess.run(["git", "add", "change.txt"], cwd=repo, check=True)
+            subprocess.run(
+                [
+                    "git",
+                    "commit",
+                    "-qm",
+                    "head\n\nE2E-NA: backend-only change",
+                ],
+                cwd=repo,
+                check=True,
+            )
+            head = subprocess.check_output(
+                ["git", "rev-parse", "HEAD"], cwd=repo, text=True
+            ).strip()
+
+            self.assertTrue(e2e.fetch_has_e2e_na_trailer(base, head, cwd=repo))
+
+    def test_unreadable_range_fails_open(self):
+        self.assertFalse(e2e.fetch_has_e2e_na_trailer("missing-base", "missing-head"))
+
+    def test_empty_or_multiple_trailers_are_not_a_single_valid_trailer(self):
+        with mock.patch.object(
+            e2e, "_collect_e2e_na_trailers", side_effect=[[""], ["one", "two"]]
+        ):
+            self.assertFalse(e2e.fetch_has_e2e_na_trailer("base", "head"))
+            self.assertFalse(e2e.fetch_has_e2e_na_trailer("base", "head"))
+
+    def test_pr_range_reads_immutable_base_and_head_oids(self):
+        payload = '{"baseRefOid":"base-sha","headRefOid":"head-sha"}'
+        with mock.patch.object(e2e, "_run", return_value=(0, payload)):
+            self.assertEqual(e2e.fetch_pr_range("feat/149-guard"), ("base-sha", "head-sha"))
+
+    def test_checker_defaults_to_pr_range_when_no_overrides_are_given(self):
+        args = SimpleNamespace(base_sha=None, head_sha=None)
+        with (
+            mock.patch.object(pbc, "fetch_pr_range", return_value=("base", "head")) as get_range,
+            mock.patch.object(pbc, "fetch_has_e2e_na_trailer", return_value=True) as has_trailer,
+        ):
+            self.assertTrue(pbc.resolve_has_e2e_na(args, "feat/149-guard"))
+        get_range.assert_called_once_with("feat/149-guard")
+        has_trailer.assert_called_once_with("base", "head")
+
+    def test_unavailable_or_invalid_pr_range_fails_open(self):
+        with mock.patch.object(e2e, "_run", side_effect=[(1, ""), (0, "not-json")]):
+            self.assertEqual(e2e.fetch_pr_range("missing"), (None, None))
+            self.assertEqual(e2e.fetch_pr_range("invalid"), (None, None))
+
+    def test_explicit_range_requires_then_accepts_body_evidence(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            repo = Path(temp_dir)
+            subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
+            subprocess.run(
+                ["git", "config", "user.email", "tests@example.invalid"],
+                cwd=repo,
+                check=True,
+            )
+            subprocess.run(
+                ["git", "config", "user.name", "Test User"], cwd=repo, check=True
+            )
+            (repo / "change.txt").write_text("base\n", encoding="utf-8")
+            subprocess.run(["git", "add", "change.txt"], cwd=repo, check=True)
+            subprocess.run(["git", "commit", "-qm", "base"], cwd=repo, check=True)
+            base = subprocess.check_output(
+                ["git", "rev-parse", "HEAD"], cwd=repo, text=True
+            ).strip()
+            (repo / "change.txt").write_text("head\n", encoding="utf-8")
+            subprocess.run(["git", "add", "change.txt"], cwd=repo, check=True)
+            subprocess.run(
+                ["git", "commit", "-qm", "head\n\nE2E-NA: backend-only change"],
+                cwd=repo,
+                check=True,
+            )
+            head = subprocess.check_output(
+                ["git", "rev-parse", "HEAD"], cwd=repo, text=True
+            ).strip()
+            body_path = repo / "body.md"
+            base_body = f"Part of #130\ncloses #149\n{RETRO}"
+            command = [
+                sys.executable,
+                str(SCRIPT_PATH),
+                "--issue",
+                "149",
+                "--parent",
+                "130",
+                "--body-file",
+                str(body_path),
+                "--base-sha",
+                base,
+                "--head-sha",
+                head,
+            ]
+
+            body_path.write_text(base_body, encoding="utf-8")
+            missing = subprocess.run(
+                command, cwd=repo, capture_output=True, text=True, env=TEST_ENV
+            )
+            self.assertEqual(missing.returncode, 1, missing.stdout + missing.stderr)
+            self.assertIn("E2E: n/a", missing.stdout)
+
+            body_path.write_text(
+                base_body + "\nE2E: n/a — backend-only change\n", encoding="utf-8"
+            )
+            matching = subprocess.run(
+                command, cwd=repo, capture_output=True, text=True, env=TEST_ENV
+            )
+            self.assertEqual(matching.returncode, 0, matching.stdout + matching.stderr)
+
+
+class ExistingExitCodes(unittest.TestCase):
+    def test_no_issue_is_still_exit_two(self):
+        result = subprocess.run(
+            [sys.executable, str(SCRIPT_PATH), "--branch", "main"],
+            capture_output=True,
+            text=True,
+            env=TEST_ENV,
+        )
+        self.assertEqual(result.returncode, 2, result.stdout + result.stderr)
+
+    def test_unreadable_body_file_is_still_exit_two(self):
+        result = subprocess.run(
+            [
+                sys.executable,
+                str(SCRIPT_PATH),
+                "--issue",
+                "149",
+                "--parent",
+                "130",
+                "--body-file",
+                "/definitely/missing/body.md",
+            ],
+            capture_output=True,
+            text=True,
+            env=TEST_ENV,
+        )
+        self.assertEqual(result.returncode, 2, result.stdout + result.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()