phase-loop-runtime 0.7.2__tar.gz → 0.7.4__tar.gz

{phase_loop_runtime-0.7.2 → phase_loop_runtime-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.7.2
+Version: 0.7.4
 Summary: Harness-neutral phase-loop orchestration runtime and CLI
 Author: ViperJuice
 License-Expression: Apache-2.0

{phase_loop_runtime-0.7.2 → phase_loop_runtime-0.7.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phase-loop-runtime"  # PyPI dist name; NOT "agent-harness" (an unrelated third-party PyPI project)
-version = "0.7.2"
+version = "0.7.4"
 description = "Harness-neutral phase-loop orchestration runtime and CLI"
 readme = "README.md"
 requires-python = ">=3.10"

{phase_loop_runtime-0.7.2 → phase_loop_runtime-0.7.4}/src/phase_loop_runtime/__init__.py

@@ -18,4 +18,4 @@ __all__ = [
     "state_ops",
 ]
 
-__version__ = "0.7.2"
+__version__ = "0.7.4"

{phase_loop_runtime-0.7.2 → phase_loop_runtime-0.7.4}/src/phase_loop_runtime/cli.py

@@ -18,6 +18,7 @@ from .consiliency_scaffold import ScaffoldError, scaffold
 from .docs_freshness import scan_docs_freshness
 from .discovery import AmbiguousRoadmapError, find_plan_artifact, phase_source_bundle_diagnostic, resolve_repo, resolve_suite_command, select_roadmap
 from .events import append_event, read_events
+from .roadmap_authority import RoadmapAuthorityError, assert_roadmap_authorized
 from .git_topology import collect_git_topology
 from .handoff import handoff_metadata, write_tui_handoff
 from .install_status import build_install_status
@@ -859,6 +860,9 @@ def main(argv: list[str] | None = None) -> int:
             file=sys.stderr,
         )
         return 2
+    except RoadmapAuthorityError as exc:
+        print(f"phase-loop {command}: roadmap authority refusal — {exc}", file=sys.stderr)
+        return 2
 
 
 def _resolve_run_closeout_mode(args: argparse.Namespace, command: str) -> str:
@@ -1046,6 +1050,7 @@ def _main(parser: argparse.ArgumentParser, args: argparse.Namespace, command: st
             _warn_roadmap_validation(select_roadmap(repo, args.roadmap))
         return _evidence_audit_command(repo=repo, args=args, as_json=as_json)
     if command in {"run", "resume", "dry-run"} and bool(getattr(args, "reset_capability", False)):
+        assert_roadmap_authorized(repo, args.roadmap)
         clear_degradation(repo)
 
     if command == "execute":
@@ -1137,6 +1142,7 @@ def _main(parser: argparse.ArgumentParser, args: argparse.Namespace, command: st
                 )
         return 0
     if command == "migrate-handoffs":
+        assert_roadmap_authorized(repo, args.roadmap)
         records = migrate_handoffs(repo, apply=bool(getattr(args, "apply", False)))
         if as_json:
             print(records_to_json(records))
@@ -1145,8 +1151,10 @@ def _main(parser: argparse.ArgumentParser, args: argparse.Namespace, command: st
                 print(f"{record.status}\t{record.action}\t{record.skill_name}\t{record.source}\t{record.target}")
         return 1 if any(record.action == "blocked" for record in records) else 0
     if command == "migrate-events":
+        assert_roadmap_authorized(repo, args.roadmap)
         return _migrate_events_command(repo=repo, dry_run=bool(args.dry_run), backup_suffix=args.backup_suffix)
     if command == "archive-state":
+        assert_roadmap_authorized(repo, args.roadmap)
         print(render_archive_result(
             archive_state(repo, reason=getattr(args, "reason", None), dry_run=bool(getattr(args, "dry_run", False))),
             as_json=as_json,

{phase_loop_runtime-0.7.2 → phase_loop_runtime-0.7.4}/src/phase_loop_runtime/discovery.py

@@ -39,6 +39,7 @@ from .models import (
 )
 from .pipeline_adapter.flag import reconcile_git_reality_enabled
 from .provenance import phase_sha256, roadmap_sha256
+from .roadmap_authority import active_authorized_roadmap, assert_roadmap_authorized
 from .runtime_paths import phase_loop_state_read_file
 
 
@@ -413,28 +414,33 @@ def select_roadmap(repo: Path, explicit: str | Path | None = None) -> Path:
         path = Path(explicit).expanduser()
         if not path.is_absolute():
             path = repo / path
+        authorized = assert_roadmap_authorized(repo, path)
         if not path.exists():
             raise FileNotFoundError(f"roadmap not found: {path}")
-        return path.resolve()
+        return authorized
+
+    authority_roadmap = active_authorized_roadmap(repo)
+    if authority_roadmap is not None:
+        return authority_roadmap
 
     state_roadmap = active_state_roadmap(repo)
     if state_roadmap is not None:
-        return state_roadmap
+        return assert_roadmap_authorized(repo, state_roadmap)
 
     manifest_roadmap = manifest_backed_roadmap(repo)
     if manifest_roadmap is not None:
-        return manifest_roadmap
+        return assert_roadmap_authorized(repo, manifest_roadmap)
 
     handoff = latest_handoff_roadmap(repo_identity(repo), "codex-phase-roadmap-builder")
     if handoff is not None:
-        return handoff
+        return assert_roadmap_authorized(repo, handoff)
 
     candidates = sorted((repo / "specs").glob("phase-plans-v*.md"))
     if not candidates:
         raise FileNotFoundError("no specs/phase-plans-v*.md roadmap found")
     if len(candidates) != 1:
         raise AmbiguousRoadmapError([c.resolve() for c in candidates])
-    return candidates[0].resolve()
+    return assert_roadmap_authorized(repo, candidates[0])
 
 
 def active_state_roadmap(repo: Path) -> Path | None:

{phase_loop_runtime-0.7.2 → phase_loop_runtime-0.7.4}/src/phase_loop_runtime/events.py

@@ -8,6 +8,7 @@ from pathlib import Path
 from .closeout import phase_loop_closeout_diagnostic
 from .git_topology import attach_git_topology, collect_git_topology
 from .models import LoopEvent, WorkUnitEventMetadata
+from .roadmap_authority import assert_roadmap_authorized
 from .runtime_paths import ensure_phase_loop_excluded, phase_loop_event_file, phase_loop_event_read_files
 
 
@@ -20,16 +21,17 @@ def event_read_paths(repo: Path) -> tuple[Path, ...]:
 
 
 def append_event(repo: Path, event: LoopEvent) -> None:
-    ensure_phase_loop_excluded(repo)
     event = _event_with_closeout_metadata(event)
     event = attach_git_topology(repo, event)
-    path = event_path(repo)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    _append_jsonl(path, event.to_json())
+    append_payload(
+        repo,
+        event.to_json(),
+        roadmap=event.roadmap,
+    )
 
 
 def append_work_unit_event(repo: Path, event: WorkUnitEventMetadata, *, roadmap: Path | None = None) -> None:
-    ensure_phase_loop_excluded(repo)
+    authorized_roadmap = assert_roadmap_authorized(repo, roadmap)
     payload = event.to_json()
     closeout = _extract_work_unit_closeout(payload)
     if closeout is not None:
@@ -37,7 +39,7 @@ def append_work_unit_event(repo: Path, event: WorkUnitEventMetadata, *, roadmap:
     payload.update(
         {
             "repo": str(repo),
-            "roadmap": str(roadmap or ""),
+            "roadmap": str(roadmap or authorized_roadmap or ""),
             "phase": event.identity.phase,
             "action": "work_unit",
             "status": event.status,
@@ -46,6 +48,17 @@ def append_work_unit_event(repo: Path, event: WorkUnitEventMetadata, *, roadmap:
             "git_topology": collect_git_topology(repo),
         }
     )
+    append_payload(repo, payload, roadmap=roadmap or authorized_roadmap)
+
+
+def append_payload(
+    repo: Path,
+    payload: dict,
+    *,
+    roadmap: str | Path | None,
+) -> None:
+    assert_roadmap_authorized(repo, roadmap)
+    ensure_phase_loop_excluded(repo)
     path = event_path(repo)
     path.parent.mkdir(parents=True, exist_ok=True)
     _append_jsonl(path, payload)

{phase_loop_runtime-0.7.2 → phase_loop_runtime-0.7.4}/src/phase_loop_runtime/panel_invoker.py

@@ -1235,6 +1235,91 @@ def _run_leg_with_liveness(
                 pass
 
 
+# #188 — de-animation of the Claude TUI's cosmetic status line. While the model
+# call is in flight the TUI repaints an animated "✻ Herding… (Ns · esc to
+# interrupt)" line ~1x/sec (rotating whimsical verb + a per-second elapsed
+# counter). Those repaints are PTY output but NOT reviewer progress: a leg wedged
+# in ``ep_poll`` waiting on a stream that never completes keeps animating that
+# line forever. Treating any PTY byte as a heartbeat (the pre-#188 behavior) let
+# a wedged Fable leg hang ~17 min with ~2s CPU and no output. So for the TUI path
+# the kill clock is reset ONLY by GENUINE reviewer progress — output-file growth,
+# transcript growth, or SUBSTANTIVE novel de-animated terminal text — never by raw
+# PTY churn and never by incidental CPU (a Node CLI trickles libuv/GC CPU while
+# blocked, which would defeat a CPU heartbeat here just as the animation defeats a
+# byte heartbeat). This is exactly #188's "separate process-alive from
+# reviewer-heartbeat freshness"; the codex/grok/gemini ``_run_leg_with_liveness``
+# path keeps its stdout/stderr + CPU heartbeat (load-bearing there) untouched.
+_ANSI_CSI_RE = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]")
+_ANSI_OSC_RE = re.compile(r"\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)")
+_TUI_DIGIT_RUN_RE = re.compile(r"\d+")
+_TUI_NON_TOKEN_RE = re.compile(r"[^0-9a-zA-Z#]+")
+# A normalized visible line must be at least this long to count as substantive
+# novelty — filters out short glyph/one-word blips while any real review sentence
+# (or streamed token run) clears it easily.
+_TUI_PROGRESS_MIN_CHARS = 8
+
+
+def _normalize_tui_line(line: str) -> str:
+    """Collapse a rendered terminal line to a spinner/timer-invariant token string.
+
+    Digit runs → ``#`` (kills the per-second elapsed counter) and every non-alnum
+    glyph/punctuation is dropped (kills the rotating spinner glyph + box drawing),
+    so the animated status line maps to a FINITE set of normalized strings while
+    genuinely-streamed review text keeps introducing novel ones.
+    """
+    line = _TUI_DIGIT_RUN_RE.sub("#", line)
+    line = _TUI_NON_TOKEN_RE.sub(" ", line)
+    return " ".join(line.split()).strip().lower()
+
+
+def _tui_chunk_has_novel_content(chunk: bytes, seen: set[str]) -> bool:
+    """True iff a PTY chunk carries SUBSTANTIVE new (non-cosmetic) terminal text.
+
+    Strips ANSI escapes, splits on newline AND carriage-return (spinner overwrite),
+    normalizes each visible line, and reports whether any sufficiently-long line
+    has not been seen before. ``seen`` accumulates for the session (bounded by real
+    novelty — a wedge's animation vocabulary is finite, so it saturates and stops
+    resetting the kill clock).
+    """
+    text = chunk.decode("utf-8", errors="replace")
+    text = _ANSI_OSC_RE.sub("", text)
+    text = _ANSI_CSI_RE.sub("", text)
+    novel = False
+    for raw in re.split(r"[\r\n]+", text):
+        norm = _normalize_tui_line(raw)
+        if len(norm) >= _TUI_PROGRESS_MIN_CHARS and norm not in seen:
+            seen.add(norm)
+            novel = True
+    return novel
+
+
+# A single ``os.read(8192)`` can split a novel review line across two chunks; each
+# fragment normalizes differently (or collides with a seen/too-short form), so the
+# whole-line progress signal is lost. Carry the trailing PARTIAL line (bytes after
+# the last newline/CR) forward and prepend it to the next chunk, so novelty is only
+# ever evaluated on COMPLETE lines. Bounded so an unterminated over-long run (a rare
+# no-newline stream) is flushed rather than growing the buffer without limit.
+_TUI_CARRY_MAX_BYTES = 1 << 16  # 64 KiB
+
+
+def _tui_take_complete_lines(carry: bytearray, chunk: bytes) -> bytes:
+    """Append ``chunk`` to ``carry`` and return the bytes up to the last line
+    terminator (complete lines, safe to scan for novelty), retaining the trailing
+    partial line in ``carry`` for the next read. Carried at the RAW byte level so a
+    straddling ANSI escape (never containing \\n/\\r) also reassembles intact."""
+    carry.extend(chunk)
+    last = max(carry.rfind(b"\n"), carry.rfind(b"\r"))
+    if last < 0:
+        if len(carry) >= _TUI_CARRY_MAX_BYTES:
+            complete = bytes(carry)
+            carry.clear()
+            return complete
+        return b""
+    complete = bytes(carry[: last + 1])
+    del carry[: last + 1]
+    return complete
+
+
 def _run_claude_tui_session(
     *,
     command: Sequence[str],
@@ -1266,8 +1351,14 @@ def _run_claude_tui_session(
     next_transcript_check = start_monotonic + _CLAUDE_TUI_TRANSCRIPT_INTERVAL_S
     transcript_salvage = ""
     last_heartbeat = start_monotonic
-    last_cpu_sample = start_monotonic
-    last_ticks = 0
+    # #188: GENUINE-progress heartbeat state. The kill clock (``last_heartbeat``)
+    # is reset ONLY by reviewer progress — never by cosmetic PTY animation or
+    # incidental CPU. ``seen_tui_lines`` accumulates de-animated visible lines so a
+    # wedged TUI's finite animation vocabulary saturates and stops resetting it.
+    seen_tui_lines: set[str] = set()
+    tui_carry = bytearray()  # #188 CR: trailing partial line held across os.read boundaries
+    last_review_len = 0
+    last_transcript_len = 0
     try:
         master_fd, slave_fd = pty.openpty()
         try:
@@ -1293,7 +1384,6 @@ def _run_claude_tui_session(
             os.close(master_fd)
         return 1, "", f"claude_tui_launch_error:{type(exc).__name__}"
 
-    last_ticks = group_cpu_ticks(proc.pid)
     try:
         while time.monotonic() < deadline:
             if master_fd is not None:
@@ -1305,7 +1395,17 @@ def _run_claude_tui_session(
                         chunk = b""
                     if chunk:
                         terminal_bytes.extend(chunk)
-                        last_heartbeat = time.monotonic()  # PTY output = liveness
+                        # #188: a raw PTY chunk is a heartbeat ONLY if it carries
+                        # SUBSTANTIVE novel text. The TUI's animated "thinking"
+                        # status line (rotating verb + per-second timer) repaints
+                        # forever while wedged in ep_poll; de-animation maps it to
+                        # already-seen lines so it never resets the kill clock.
+                        # #188 CR: carry the trailing partial line across read
+                        # boundaries so a novel line split by ``os.read`` is scanned
+                        # WHOLE (only complete lines are evaluated).
+                        complete = _tui_take_complete_lines(tui_carry, chunk)
+                        if complete and _tui_chunk_has_novel_content(complete, seen_tui_lines):
+                            last_heartbeat = time.monotonic()
                     else:
                         # #48: PTY EOF — the child CLI and ALL its descendants closed
                         # the slave side, so no further output can arrive. Without this
@@ -1341,11 +1441,20 @@ def _run_claude_tui_session(
                 except OSError:
                     return 1, "", "claude_tui_submit_failed"
             review_text = _read_review_output(output_file)
+            # #188: canonical review OUTPUT growing is unambiguous reviewer progress.
+            if len(review_text) > last_review_len:
+                last_review_len = len(review_text)
+                last_heartbeat = now
             if _completion_ok(review_text, mode):
                 return 0, review_text, "claude_tui_file_output"
             if now >= next_transcript_check:
                 next_transcript_check = now + _CLAUDE_TUI_TRANSCRIPT_INTERVAL_S
                 transcript_text = _latest_claude_transcript_text(str(cwd), since=start_wall)
+                # #188: the session transcript growing (tool calls, streamed
+                # messages) is genuine progress even before a file verdict lands.
+                if len(transcript_text) > last_transcript_len:
+                    last_transcript_len = len(transcript_text)
+                    last_heartbeat = now
                 if _completion_ok(transcript_text, mode):
                     transcript_salvage = transcript_text
             if proc.poll() is not None:
@@ -1355,14 +1464,13 @@ def _run_claude_tui_session(
                     return 0, review_text, "claude_tui_file_output"
                 detail = "claude_tui_missing_canonical_output"
                 return proc.returncode or 1, review_text or transcript_text, detail
-            # secondary CPU heartbeat (never a kill; only extends life) + stall reclaim.
-            if now - last_cpu_sample >= _LEG_LIVENESS_CPU_SAMPLE_S:
-                last_cpu_sample = now
-                ticks = group_cpu_ticks(proc.pid)
-                if ticks > last_ticks:
-                    last_heartbeat = now
-                last_ticks = ticks
-            # stall: PTY silent AND CPU-flat past the threshold while still running. The
+            # #188: NO CPU heartbeat on the TUI path. Unlike the print-mode legs, a
+            # Node CLI blocked in ep_poll still trickles libuv/GC CPU, so a CPU-advance
+            # reset would keep a genuinely-wedged TUI alive forever (the ~2s-CPU/17-min
+            # hang). Liveness here is reviewer progress ONLY (novel PTY text / output /
+            # transcript growth above) — "process-alive" is deliberately NOT "leg-alive".
+            #
+            # stall: no GENUINE progress for the threshold while still running. The
             # canonical verdict is the review FILE (checked above); nothing to nudge for a
             # wedged TUI, so fail closed (rc forced non-zero, like the #48/deadline paths).
             if now - last_heartbeat >= _LEG_STALL_THRESHOLD_S:
@@ -1729,7 +1837,15 @@ def _exec_claude_tui_leg(
         mode=mode,
         backstop_s=backstop_s,
     )
-    return _classify_leg(rc, review_text, log_text, mode), review_text or log_text
+    # #188: a heartbeat-reclaimed (genuinely wedged) TUI leg is a TYPED stalled leg,
+    # not a bare ERROR — surface it as DEGRADED so the panel summary names the
+    # liveness reclaim ("process alive but no reviewer heartbeat") while the three
+    # completed seats are preserved. A leg that produced a conforming verdict before
+    # the reclaim still classifies OK (unchanged).
+    status = _classify_leg(rc, review_text, log_text, mode)
+    if log_text == "claude_tui_stalled" and status != "OK":
+        return "DEGRADED", review_text or "claude_tui_stalled: no reviewer heartbeat (liveness reclaim)"
+    return status, review_text or log_text
 
 
 def _exec_claude_agent_view_attempt(

{phase_loop_runtime-0.7.2 → phase_loop_runtime-0.7.4}/src/phase_loop_runtime/pipeline_adapter/ratification.py

@@ -6,7 +6,7 @@ from pathlib import Path
 from typing import Any
 
 from ..git_topology import collect_git_topology
-from ..runtime_paths import ensure_phase_loop_excluded, phase_loop_event_file
+from ..events import append_payload
 from ..models import utc_now
 from .merge_policy import MergePolicy
 
@@ -21,12 +21,11 @@ def emit_ratification_passed(
     ratification_gate: str,
     merge_policy: MergePolicy,
     audit: dict[str, Any],
+    *,
+    roadmap_path: Path | None = None,
 ) -> None:
     repo = Path(repo_root)
     payload = _payload(repo, roadmap_version, phase_alias, ratification_gate, merge_policy, audit)
-    ensure_phase_loop_excluded(repo)
-    event_path = phase_loop_event_file(repo)
-    event_path.parent.mkdir(parents=True, exist_ok=True)
     event = {
         "timestamp": utc_now(),
         "repo": str(repo),
@@ -40,8 +39,11 @@ def emit_ratification_passed(
         "payload": payload,
         "git_topology": collect_git_topology(repo),
     }
-    with event_path.open("a", encoding="utf-8") as handle:
-        handle.write(json.dumps(event, sort_keys=True) + "\n")
+    append_payload(
+        repo,
+        event,
+        roadmap=roadmap_path or repo / "specs" / f"phase-plans-{roadmap_version}.md",
+    )
 
     trigger = repo / TRIGGER_PATH
     trigger.parent.mkdir(parents=True, exist_ok=True)

phase_loop_runtime-0.7.4/src/phase_loop_runtime/roadmap_authority.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import stat
+from pathlib import Path
+
+
+SCHEMA = "phase_loop_roadmap_authority.v1"
+REQUIRED_MARKER = "phase_loop_roadmap_authority_required.v1\n"
+LATCH_MARKER = "phase_loop_roadmap_authority_latched.v1\n"
+
+
+class RoadmapAuthorityError(RuntimeError):
+    pass
+
+
+def roadmap_authority_file(repo: Path) -> Path:
+    return _git_common_path(repo, "phase-loop-roadmap-authority.json")
+
+
+def roadmap_authority_required_file(repo: Path) -> Path:
+    return _git_common_path(repo, "phase-loop-roadmap-authority-required")
+
+
+def roadmap_authority_latch_file(repo: Path) -> Path:
+    return _git_common_path(repo, "phase-loop-roadmap-authority-latch")
+
+
+def roadmap_authority_worktree_latch_file(repo: Path) -> Path:
+    return repo.resolve() / ".phase-loop" / "roadmap-authority-latch"
+
+
+def _git_common_path(repo: Path, name: str) -> Path:
+    git_entry = repo.resolve() / ".git"
+    if git_entry.is_dir():
+        common = git_entry
+    elif git_entry.is_file():
+        try:
+            line = git_entry.read_text(encoding="utf-8").strip()
+            if not line.startswith("gitdir: "):
+                raise ValueError
+            git_dir = Path(line.removeprefix("gitdir: "))
+            git_dir = git_dir if git_dir.is_absolute() else (repo / git_dir).resolve()
+            commondir = git_dir / "commondir"
+            if commondir.exists():
+                common_value = commondir.read_text(encoding="utf-8").strip()
+                common_path = Path(common_value)
+                common = common_path if common_path.is_absolute() else (git_dir / common_path).resolve()
+            else:
+                common = git_dir
+        except (OSError, UnicodeDecodeError, ValueError) as error:
+            raise RoadmapAuthorityError("roadmap authority marker path unavailable") from error
+    else:
+        common = git_entry
+    return common / name
+
+
+def active_authorized_roadmap(repo: Path) -> Path | None:
+    return assert_roadmap_authorized(repo, None)
+
+
+def assert_roadmap_authorized(
+    repo: Path,
+    roadmap: str | Path | None,
+) -> Path | None:
+    root = repo.resolve()
+    authority_path = roadmap_authority_file(root)
+    if not authority_path.exists():
+        _require_authority_not_removed(root)
+        return _resolve_roadmap(root, roadmap) if roadmap is not None and str(roadmap).strip() else None
+    _require_authority_installed(root, authority_path)
+    authority = _read_authority(authority_path)
+    if authority["status"] != "active":
+        raise RoadmapAuthorityError("roadmap authority is blocked")
+    active = _bound_path(root, authority["active_roadmap"])
+    retired = {_bound_path(root, item["path"]): item for item in authority["retired_roadmaps"]}
+    for path, item in retired.items():
+        blob = _bound_common_blob(authority_path.parent, item["common_blob"])
+        _require_control_mode(blob, 0o400)
+        if not blob.is_file() or _sha256(blob) != item["sha256"]:
+            raise RoadmapAuthorityError(f"retired roadmap digest mismatch: {path}")
+    target = active if roadmap is None or str(roadmap).strip() == "" else _resolve_roadmap(root, roadmap)
+    if target in retired:
+        raise RoadmapAuthorityError(f"roadmap retired: {target}")
+    if target != active:
+        raise RoadmapAuthorityError(f"roadmap is not active: {target}")
+    if active.is_file():
+        if _sha256(active) != authority["active_roadmap_sha256"]:
+            raise RoadmapAuthorityError(f"roadmap authority digest mismatch: {active}")
+    else:
+        raise RoadmapAuthorityError(f"roadmap authority digest mismatch: {active}")
+    return target
+
+
+def _read_authority(path: Path) -> dict:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise RoadmapAuthorityError(f"invalid roadmap authority: {path}") from error
+    if not isinstance(value, dict) or set(value) != {
+        "schema",
+        "status",
+        "active_roadmap",
+        "active_roadmap_sha256",
+        "retired_roadmaps",
+    }:
+        raise RoadmapAuthorityError(f"invalid roadmap authority schema: {path}")
+    if value["schema"] != SCHEMA or value["status"] not in {"blocked", "active"} or not _digest(value["active_roadmap_sha256"]):
+        raise RoadmapAuthorityError(f"invalid roadmap authority binding: {path}")
+    retired = value["retired_roadmaps"]
+    if not isinstance(retired, list):
+        raise RoadmapAuthorityError(f"invalid retired roadmap set: {path}")
+    seen: set[str] = set()
+    for item in retired:
+        if not isinstance(item, dict) or set(item) != {"path", "sha256", "common_blob"}:
+            raise RoadmapAuthorityError(f"invalid retired roadmap binding: {path}")
+        if not isinstance(item["path"], str) or item["path"] in seen or not _digest(item["sha256"]) or not isinstance(item["common_blob"], str) or not item["common_blob"]:
+            raise RoadmapAuthorityError(f"invalid retired roadmap binding: {path}")
+        seen.add(item["path"])
+    return value
+
+
+def _require_authority_not_removed(repo: Path) -> None:
+    marker = roadmap_authority_required_file(repo)
+    latch = roadmap_authority_latch_file(repo)
+    worktree_latch = roadmap_authority_worktree_latch_file(repo)
+    if not marker.exists() and not latch.exists() and not worktree_latch.exists():
+        return
+    if worktree_latch.exists():
+        _read_control_file(worktree_latch, LATCH_MARKER, 0o400)
+    if latch.exists():
+        _read_control_file(latch, LATCH_MARKER, 0o400)
+    if marker.exists():
+        _read_control_file(marker, REQUIRED_MARKER, 0o400)
+    raise RoadmapAuthorityError("required roadmap authority is missing")
+
+
+def _require_authority_installed(repo: Path, authority: Path) -> None:
+    _require_control_mode(authority, 0o600)
+    _read_control_file(roadmap_authority_worktree_latch_file(repo), LATCH_MARKER, 0o400)
+    _read_control_file(roadmap_authority_required_file(repo), REQUIRED_MARKER, 0o400)
+    _read_control_file(roadmap_authority_latch_file(repo), LATCH_MARKER, 0o400)
+
+
+def _read_control_file(path: Path, expected: str, mode: int) -> None:
+    try:
+        value = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as error:
+        raise RoadmapAuthorityError("invalid roadmap authority required marker") from error
+    if value != expected:
+        raise RoadmapAuthorityError("invalid roadmap authority required marker")
+    _require_control_mode(path, mode)
+
+
+def _require_control_mode(path: Path, mode: int) -> None:
+    try:
+        metadata = path.stat()
+        common_owner = path.parent.stat().st_uid
+    except OSError as error:
+        raise RoadmapAuthorityError("invalid roadmap authority control file") from error
+    if os.name == "nt":
+        return
+    if metadata.st_uid != common_owner or stat.S_IMODE(metadata.st_mode) != mode or metadata.st_uid != os.geteuid():
+        raise RoadmapAuthorityError("invalid roadmap authority control file")
+
+
+def _resolve_roadmap(repo: Path, roadmap: str | Path | None) -> Path:
+    if roadmap is None or str(roadmap).strip() == "":
+        raise RoadmapAuthorityError("roadmap authority requires a roadmap path")
+    path = Path(roadmap).expanduser()
+    return (path if path.is_absolute() else repo / path).resolve()
+
+
+def _bound_common_blob(common: Path, value: str) -> Path:
+    path = Path(value)
+    if path.is_absolute():
+        raise RoadmapAuthorityError("retired roadmap blob escapes git common directory")
+    resolved = (common / path).resolve()
+    try:
+        resolved.relative_to(common.resolve())
+    except ValueError as error:
+        raise RoadmapAuthorityError("retired roadmap blob escapes git common directory") from error
+    return resolved
+
+
+def _bound_path(repo: Path, value: object) -> Path:
+    if not isinstance(value, str) or not value or Path(value).is_absolute():
+        raise RoadmapAuthorityError("roadmap authority paths must be repository-relative")
+    path = (repo / value).resolve()
+    try:
+        path.relative_to(repo)
+    except ValueError as error:
+        raise RoadmapAuthorityError("roadmap authority path escapes repository") from error
+    return path
+
+
+def _sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _digest(value: object) -> bool:
+    return isinstance(value, str) and len(value) == 64 and all(character in "0123456789abcdef" for character in value)