@opengsd/gsd-path 1.4.0 → 1.6.0

package/skills/path/scripts/review_findings.py

@@ -8,20 +8,29 @@ canonical review files, and every skeptic file for this wave. It groups
 blocking findings by canonical criterion locator (`t001_ac2`, `sc3`,
 `t001_files`, `t001_interface_contract`), collapses true duplicate
 observations, selects the groups that need a skeptic, carries refutations
-forward across cycles, batches fix-task groups by disjoint file scope, keeps
-structural blockers out of skeptic accounting, and reports whether the cycle
-cap is reached. It never decides the wave verdict.
+forward across cycles, batches fix-task groups by repo and disjoint file
+scope, keeps structural blockers out of skeptic accounting, and reports
+whether the cycle cap is reached. It never decides the wave verdict.
 """
 
 from __future__ import annotations
 
 import argparse
+import functools
 import json
 import re
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from pathlib import Path
 from typing import Dict, List, Optional, Sequence
 
+try:
+    from . import _common
+except ImportError:  # installed standalone helper
+    import _common
+
 DEFAULT_PROJECT_DIR = ".project"
 DEFAULT_MAX_REVIEW_CYCLES = 3
 CONFIG_KEYS = ("max_review_cycles", "wave_budget", "review_panel", "finding_skeptics")
@@ -143,15 +152,25 @@ def _frontmatter_list(frontmatter: str, key: str) -> List[str]:
 
 
 def _numbered_items(section: Optional[str]) -> List[str]:
-    items: List[str] = []
+    """Numbered criteria; each also carries its text without sub-bullet markers (issue #392)."""
     if section is None:
-        return items
+        return []
+    bare = _numbered_texts(_common.without_sub_bullet_markers(section))
+    return [_common.Criterion(text, other) for text, other in zip(_numbered_texts(section), bare)]
+
+
+def _numbered_texts(section: str) -> List[str]:
+    items: List[str] = []
+    open_item = False
     for line in _strip_comments(section).splitlines():
         match = NUMBERED_ITEM.match(line.strip())
         if match:
             items.append(_normalize(match.group(2)))
-        elif items and line.startswith("   ") and line.strip():
+            open_item = True
+        elif open_item and line[:1].isspace() and line.strip():
             items[-1] = _normalize(items[-1] + " " + line.strip())
+        elif line.strip():
+            open_item = False
     return items
 
 
@@ -183,9 +202,11 @@ def load_wave_tasks(project: Path, wave: int) -> Dict[str, dict]:
         if not task_wave or int(task_wave.group(1)) != wave:
             continue
         body = parts[2]
+        member = re.search(r"(?m)^repo:[ \t]*(?P<name>[^\s#]+)", frontmatter)
         tasks[named.group("id")] = {
             "id": named.group("id"),
             "path": str(path),
+            "repo": member.group("name").strip("\"'") if member else None,  # None is the coordinator
             "files": _frontmatter_list(frontmatter, "files"),
             "acceptance": _numbered_items(_section(body, "Acceptance criteria")),
             "interface": [
@@ -270,17 +291,20 @@ def parse_lens(text: str, lens: str, tasks: Dict[str, dict]) -> dict:
                 continue
             zones[zone].append(line)
         for observation in _fail_items(zones["criteria"]):
-            criterion = _criterion_of(observation)
-            locator = None
-            if criterion in task["acceptance"]:
-                locator = f"{task_id.lower()}_ac{task['acceptance'].index(criterion) + 1}"
-            elif criterion in task["interface"]:
-                locator = f"{task_id.lower()}_interface_contract"
-            if locator is None:
+            # Issue #392: match as the wave gate does, then report the task's own text.
+            criteria = task["acceptance"] + task["interface"]
+            quoted = _common.quoted_criterion(observation, criteria)
+            if quoted is None:
                 problems.append(
-                    f"{lens} lens {task_id} finding names no task criterion: {criterion}"
+                    f"{lens} lens {task_id} finding names no task criterion: "
+                    f"{_criterion_of(observation)}"
                 )
                 continue
+            criterion = criteria[quoted[0]]
+            if quoted[0] < len(task["acceptance"]):
+                locator = f"{task_id.lower()}_ac{quoted[0] + 1}"
+            else:
+                locator = f"{task_id.lower()}_interface_contract"
             findings.append(
                 {"locator": locator, "criterion": criterion, "task": task_id,
                  "lens": lens, "observation": observation}
@@ -433,21 +457,27 @@ def _earlier_lens_locators(project: Path, wave: int, cycle: int, depth: str, tas
 
 
 def _fix_batches(groups: Sequence[dict], tasks: Dict[str, dict]) -> List[dict]:
-    """One batch per disjoint file scope: groups whose task files overlap share a batch."""
+    """One batch per repo and disjoint file scope: groups whose task files overlap in one repo share a batch.
+
+    A member batch names its `repo`; a coordinator batch has no such key.
+    """
 
     batches: List[dict] = []
     for group in groups:
-        files = sorted({path for task_id in group["tasks"] for path in tasks.get(task_id, {}).get("files", [])})
-        merged = {"locators": [group["locator"]], "files": files}
-        keep: List[dict] = []
-        for batch in batches:
-            if set(batch["files"]) & set(files):
-                merged["locators"] = batch["locators"] + merged["locators"]
-                merged["files"] = sorted(set(batch["files"]) | set(merged["files"]))
-            else:
-                keep.append(batch)
-        keep.append(merged)
-        batches = keep
+        owners = [tasks.get(task_id, {}) for task_id in group["tasks"]]
+        for repo in sorted({task.get("repo") or "" for task in owners}) or [""]:
+            files = sorted({path for task in owners if (task.get("repo") or "") == repo
+                            for path in task.get("files", [])})
+            merged = {"locators": [group["locator"]], "files": files, **({"repo": repo} if repo else {})}
+            keep: List[dict] = []
+            for batch in batches:
+                if batch.get("repo") == merged.get("repo") and _common.overlapping_paths(batch["files"], files):
+                    merged["locators"] = batch["locators"] + merged["locators"]
+                    merged["files"] = sorted(set(batch["files"]) | set(merged["files"]))
+                else:
+                    keep.append(batch)
+            keep.append(merged)
+            batches = keep
     return batches
 
 
@@ -604,7 +634,7 @@ def repair_evidence(repo: Path, project_dir: str, wave: int, cycle: int, task_id
         )["tasks"][0]
         if proof["verdict"] != "recovered":
             raise ReviewFindingsError("repair requires a proven landing")
-        base, commit = proof["base"], proof["commit"]
+        base = proof["base"]  # in the coordinator, where the source review is
         findings = _section(text, "Review findings") or ""
         headings = list(re.finditer(r"(?m)^### ([a-z0-9_]+)\s*$", findings))
         locators = [heading.group(1) for heading in headings]
@@ -613,10 +643,28 @@ def repair_evidence(repo: Path, project_dir: str, wave: int, cycle: int, task_id
         source = compute(repo, project_dir, wave, cycle)
         if source["structural_blockers"]:
             raise ReviewFindingsError("source findings have structural blockers")
+        member = fields.get("repo")  # a finding in two repos has one batch per repo with the same locators
         batches = [batch for batch in source["fix_batches"]
-                   if set(batch["locators"]) == set(locators)]
+                   if batch.get("repo") == member and set(batch["locators"]) == set(locators)]
         if len(batches) != 1:
             raise ReviewFindingsError("repair must carry one eligible source finding batch")
+        # A member task's product is in the member repository: its commits, its bound branch, its Verify rows.
+        where, tip = repo, []  # the coordinator product is judged in the working tree
+        if member:
+            where, _, lock = isolation._member_context(repo, member)
+            tip = [f"refs/heads/{lock['branch']}"]
+
+        def entry(landing: dict, path: Path, paths: List[str]) -> dict:
+            """A proven landing as the receipt shows it; a member landing adds its commits in the member."""
+            item = {"task": landing["task_id"], "base": landing["base"], "commit": landing["commit"], "files": paths}
+            if member:
+                item.update(member_base=isolation.task_frontmatter(_read(path, "task"))[0]["member_base"],
+                            member_commit=landing["landing"])
+            return item
+
+        def at(item: dict, point: str = "commit") -> str:
+            return item.get(f"member_{point}", item[point])
+
         groups = [group for group in source["groups"] if group["locator"] in locators]
         for index, heading in enumerate(headings):
             end = headings[index + 1].start() if index + 1 < len(headings) else len(findings)
@@ -627,22 +675,101 @@ def repair_evidence(repo: Path, project_dir: str, wave: int, cycle: int, task_id
                 raise ReviewFindingsError("repair does not carry the exact criterion and observations")
         frontmatter = text.split("---", 2)[1]
         files = _frontmatter_list(frontmatter, "files")
-        originals = sorted({task for group in groups for task in group["tasks"]})
+        sources = load_wave_tasks(project, wave)
+        originals = sorted({task for group in groups for task in group["tasks"] if sources[task]["repo"] == member})
+        # A repair names the files it needs. They can be fewer than the batch files, and a plan repair
+        # can add a fix site that the source tasks did not declare.
         if (task_id in originals or not set(originals) <= set(_frontmatter_list(frontmatter, "deps"))
-                or set(files) != set(batches[0]["files"])):
+                or not files):
             raise ReviewFindingsError("repair dependencies/files do not match its source batch")
-        sources = load_wave_tasks(project, wave)
+        repair = {"task_file": repair_path.relative_to(repo).as_posix(), **entry(proof, repair_path, files),
+                  **({"member": member} if member else {})}
+
+        def differ(start: str, end: List[str], paths: List[str]) -> bool:
+            return bool(isolation.run_git(where, "diff", "--quiet", start, *end, "--", *paths).returncode)
+
+        def before(start: str, end: str) -> bool:
+            return not isolation.run_git(where, "merge-base", "--is-ancestor", start, end).returncode
+
+        @functools.lru_cache(maxsize=None)
+        def linked() -> tuple:
+            """Landed repairs of the same findings that `deps` join to this repair, in landing order.
+
+            A linked task is done, is in the same repo, carries a finding of this repair in its
+            `## Review findings`, and depends on this repair or on a linked task, or the reverse.
+            """
+            tasks, carried = {task_id: (repair_path, fields)}, {}
+            for path in (project / "tasks").glob("T*-*.md"):
+                other = _read(path, "task")
+                other_fields = isolation.task_frontmatter(other)[0] or {}
+                tasks[str(other_fields.get("id"))] = (path, other_fields)
+                blocks = re.split(r"(?m)^### ([a-z0-9_]+)\s*$", _section(other, "Review findings") or "")
+                carried[str(other_fields.get("id"))] = {
+                    (locator, _normalize(line)) for locator, block in zip(blocks[1::2], blocks[2::2])
+                    for line in re.findall(r"(?m)^Criterion:(.*)$", block)}
+
+            def traced(finding: tuple, seen: frozenset = frozenset()) -> set:
+                """The finding as it started: its locator and criterion in the review of the source tasks.
+
+                A finding on an acceptance criterion of a fix task (`fix-tasks` copies the carried criteria
+                there) is the finding with the same criterion that this fix task carries. Two findings with
+                the same criterion text and other locators stay two findings.
+                """
+                owner = re.fullmatch(r"t(\d{3})_ac\d+", finding[0])
+                sources = () if not owner else {
+                    item for item in carried.get(f"T{owner.group(1)}", ()) if item[1] == finding[1]} - seen
+                return {origin for item in sources for origin in traced(item, seen | {finding})} or {finding}
+
+            def origins(other: str) -> set:
+                return {origin for finding in carried.get(other, ()) for origin in traced(finding)}
+
+            repairs = {other: task for other, task in tasks.items() if other == task_id or (
+                task[1].get("status") == "done" and task[1].get("repo") == member
+                and origins(task_id) & origins(other))}
+            joined, more = set(), {task_id}
+            while more:
+                joined |= more
+                more = {other for other, (_, other_fields) in repairs.items() if other not in joined and (
+                    joined & set(other_fields.get("deps") or [])
+                    or any(other in (repairs[item][1].get("deps") or []) for item in joined))}
+            others = sorted(joined - {task_id})
+            proofs = isolation.verify_landed_task_files(
+                repo, [repairs[other][0] for other in others], f"{project_dir}/tasks", head)["tasks"] if others else []
+            links = []
+            for landing in proofs:
+                path, other_fields = repairs[landing["task_id"]]
+                if landing["verdict"] == "recovered":
+                    links.append({"task_file": path.relative_to(repo).as_posix(),
+                                  **entry(landing, path, list(other_fields.get("files") or []))})
+            return tuple(sorted(links, key=lambda link: int(isolation.git_output(where, "rev-list", "--count", at(link)))))
+
+        def linked_changes(start: str, end: List[str], paths: List[str]) -> Optional[List[dict]]:
+            """The linked repairs whose landings are every change to `paths` from `start` to `end`, else None."""
+            if not differ(start, end, paths):
+                return []
+            links = [link for link in linked()
+                     if before(start, f"{at(link)}^") and (not end or before(at(link), end[0]))]
+            for link in links:
+                if differ(start, [f"{at(link)}^"], paths):
+                    return None
+                start = at(link)
+            return None if differ(start, end, paths) else links
+
         original_paths = [Path(sources[task]["path"]) for task in originals]
         original_proofs = isolation.verify_landed_task_files(
             repo, original_paths, f"{project_dir}/tasks", head
         )["tasks"]
-        for original in original_proofs:
-            original_id = original["task_id"]
-            if (original["verdict"] != "recovered"
-                    or isolation.run_git(repo, "merge-base", "--is-ancestor", original["commit"], base).returncode
-                    or isolation.run_git(repo, "diff", "--quiet", original["commit"], base,
-                                         "--", *sources[original_id]["files"]).returncode):
+        landed, earlier = [], set()
+        for landing in original_proofs:
+            links = None
+            if landing["verdict"] == "recovered":
+                original = entry(landing, Path(sources[landing["task_id"]]["path"]), sources[landing["task_id"]]["files"])
+                if before(at(original), at(repair, "base")):
+                    links = linked_changes(at(original), [at(repair, "base")], original["files"])
+            if links is None:
                 raise ReviewFindingsError("repair base contains unlinked changes to original product")
+            landed.append(original)
+            earlier.update(link["task"] for link in links)
         source_paths = list(review_paths(project, wave, cycle, source["depth"]).values())
         source_paths.extend(Path(group["skeptic"]["path"]) for group in groups if group["skeptic"])
         for path in set(source_paths):
@@ -650,19 +777,28 @@ def repair_evidence(repo: Path, project_dir: str, wave: int, cycle: int, task_id
             at_base = isolation.run_git(repo, "show", f"{base}:{relative}")
             if at_base.returncode or at_base.stdout != _read(path, "source review"):
                 raise ReviewFindingsError("source review must be unchanged and precede the repair")
-        verification = build_state.verify_lookup(str(repo), _common.task_verify_command(text), commit)
+        # A later linked repair supersedes this one: the last one is the product at the tip, and its
+        # landing and its Verify are the evidence. The reviewer applies every patch of the chain, so the
+        # files of every later linked repair must also change only through the landings of the chain.
+        later = linked_changes(at(repair), tip, files)
+        chain_files = sorted({*files, *(path for link in later or [] for path in link["files"])})
+        last = later[-1] if later else repair
+        verification = build_state.verify_lookup(
+            str(repo), _common.task_verify_command(_read(repo / last["task_file"], "repair task")), at(last), member)
         if not verification["reuse"]:
             raise ReviewFindingsError("repair has no reusable passing Verify at its landing")
-        if isolation.run_git(repo, "diff", "--quiet", commit, "--", *files).returncode:
+        if later is None or (later and linked_changes(at(repair), tip, chain_files) is None):
             raise ReviewFindingsError("product changed after the repair landing")
+        # A parallel landing can have a parent that is newer than the repair base. The reviewer builds the
+        # product from the base, so no other landing between the two can change a file of the chain.
+        if differ(at(repair, "base"), [f"{at(repair)}^"], chain_files):
+            raise ReviewFindingsError("product changed between the repair base and the repair landing")
         return {
             "status": "ok", "command": "repair-evidence", "head": head,
             "source": {"wave": wave, "cycle": cycle}, "groups": groups,
-            "originals": [{"task": item["task_id"], "base": item["base"],
-                           "commit": item["commit"], "files": sources[item["task_id"]]["files"]}
-                          for item in original_proofs],
-            "repair": {"task": task_id, "task_file": repair_path.relative_to(repo).as_posix(),
-                       "base": base, "commit": commit, "files": files},
+            "originals": landed, "repair": repair,
+            **({"earlier_repairs": [link for link in linked() if link["task"] in earlier]} if earlier else {}),
+            **({"later_repairs": later, "chain_files": chain_files} if later else {}),
             "verification": verification,
             "verdict": "evidence-ready; reviewer judges the original unchanged criteria",
         }

package/skills/path/scripts/roadmap.py

@@ -252,7 +252,12 @@ def activate_milestone(text: str, milestone: str) -> str:
     return "".join(lines)
 
 
-def reslice(before: str, candidate: str, phase: str, selected: str) -> str:
+def _entry_identity(block: dict) -> tuple:
+    """Heading, Status, Depends on, Archive and Integrated of one entry."""
+    return block["id"], block["title"], {name: value for name, (_, value) in block["fields"].items()}
+
+
+def reslice(before: str, candidate: str, phase: str, selected: str, amend_active: bool = False) -> str:
     old_blocks = roadmap_blocks(before)
     before_lines = before.splitlines(keepends=True)
     candidate_lines = candidate.splitlines(keepends=True)
@@ -264,6 +269,9 @@ def reslice(before: str, candidate: str, phase: str, selected: str) -> str:
         new = milestone_block(candidate, slug)
         if status == "shipped":
             changed = roadmap_contract(before, slug) != roadmap_contract(candidate, slug)
+        elif status == "active" and amend_active:
+            # Intent is not approved: the scope may change, the identity may not.
+            changed = _entry_identity(block) != _entry_identity(new)
         else:
             changed = before_lines[block["start"]:block["end"]] != candidate_lines[new["start"]:new["end"]]
         if changed:

package/skills/path/scripts/state_checkpoint.py

@@ -18,14 +18,14 @@ from pathlib import Path, PurePosixPath
 from typing import Mapping, Optional, Sequence
 
 if __package__:
-    from .isolation import IsolationError, checkpoint as isolation_checkpoint, require_commit, require_full_sha, PROJECT_ENTRIES
+    from .isolation import IsolationError, checkpoint as isolation_checkpoint, PROJECT_ENTRIES
 else:
     try:
-        from isolation import IsolationError, checkpoint as isolation_checkpoint, require_commit, require_full_sha, PROJECT_ENTRIES
+        from isolation import IsolationError, checkpoint as isolation_checkpoint, PROJECT_ENTRIES
     except ModuleNotFoundError as error:  # pragma: no cover - package imports used by tests
         if error.name != "isolation":
             raise
-        from scripts.isolation import IsolationError, checkpoint as isolation_checkpoint, require_commit, require_full_sha, PROJECT_ENTRIES
+        from scripts.isolation import IsolationError, checkpoint as isolation_checkpoint, PROJECT_ENTRIES
 
 
 if __package__:
@@ -164,9 +164,16 @@ def _approval_details(
     raise PipelineStateError(f"unsupported approval kind: {kind}")
 
 
-def _reslice_roadmap(before: str, candidate: str, state: PipelineState, selected: str) -> str:
+def _reslice_roadmap(
+    repo: Path, before: str, candidate: str, state: PipelineState, state_text: str, selected: str,
+) -> str:
+    # Define may amend its active entry until intent approval. A return to
+    # define after that approval always leaves an active recovery record.
+    amend_active = state.phase == "define" and not (
+        pipeline_state._build_recovery().context(repo, state_text) or {}
+    ).get("active")
     try:
-        return roadmap.reslice(before, candidate, state.phase, selected)
+        return roadmap.reslice(before, candidate, state.phase, selected, amend_active)
     except roadmap.RoadmapError as error:
         raise PipelineStateError(str(error)) from error
 
@@ -223,6 +230,10 @@ def _approval_journal(repo: Path, journal: Mapping[str, object]) -> dict[str, ob
         expected_keys.add("baseline_before")
         if not isinstance(journal.get("baseline_before"), str):
             raise PipelineStateError("checkpoint journal has an invalid re-slice baseline")
+    if "recovery_reviews" in journal:
+        expected_keys.add("recovery_reviews")
+        if journal.get("kind") != "plan" or not isinstance(journal["recovery_reviews"], dict):
+            raise PipelineStateError("checkpoint journal has an invalid recovery review report")
     if set(journal) != expected_keys:
         raise PipelineStateError("checkpoint journal has invalid fields")
     if journal.get("schema") != CHECKPOINT_SCHEMA or journal.get("repo") != str(repo):
@@ -307,7 +318,8 @@ def _approval_journal(repo: Path, journal: Mapping[str, object]) -> dict[str, ob
         if journal["roadmap_path"] != ".project/ROADMAP.md":
             raise PipelineStateError("checkpoint journal has an invalid ROADMAP path")
         expected_roadmap = _reslice_roadmap(
-            str(journal["baseline_before"]), str(journal["roadmap_before"]), before, str(selected),
+            repo, str(journal["baseline_before"]), str(journal["roadmap_before"]), before,
+            str(journal["state_before"]), str(selected),
         ) if journal["kind"] == "roadmap-reslice" else _activate_roadmap_milestone(
             str(journal["roadmap_before"]),
             str(selected),
@@ -423,7 +435,7 @@ def _resume_checkpoint_locked(
         raise PipelineStateError("approval checkpoint returned the wrong commit")
     _unlink_checkpoint_journal(journal_path)
     state = pipeline_state._state_from_text(str(transaction["state_after"]))
-    return {
+    approved: dict[str, object] = {
         "schema": CHECKPOINT_SCHEMA,
         "status": "approved",
         "kind": transaction["kind"],
@@ -432,6 +444,9 @@ def _resume_checkpoint_locked(
         "paths": committed.get("paths"),
         "state": state.json(),
     }
+    if "recovery_reviews" in transaction:
+        approved["recovery_reviews"] = transaction["recovery_reviews"]
+    return approved
 
 
 def _validate_plan_briefs(repo: Path, kind: str, project_dir: str) -> None:
@@ -444,14 +459,14 @@ def _validate_plan_briefs(repo: Path, kind: str, project_dir: str) -> None:
         # Pre-Git approval defers base-dependent checks to build.
         return
     if __package__:
-        from .check_task_briefs import BriefError, _member_bases, validate_task_briefs
+        from .check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
     else:
         try:
-            from check_task_briefs import BriefError, _member_bases, validate_task_briefs
+            from check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
         except ModuleNotFoundError as error:  # pragma: no cover - package imports
             if error.name != "check_task_briefs":
                 raise
-            from scripts.check_task_briefs import BriefError, _member_bases, validate_task_briefs
+            from scripts.check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
     if __package__:
         from . import check_handoffs
     else:
@@ -462,28 +477,10 @@ def _validate_plan_briefs(repo: Path, kind: str, project_dir: str) -> None:
                 raise
             from scripts import check_handoffs
     try:
-        tasks, dependency_files = check_handoffs.plan_brief_inputs(repo, project_dir)
-        landed_bases = {}
         member_base = _member_bases(repo)
-        for task_id, text in tasks.items():
-            if check_handoffs._task_scalar(text, task_id, "status") != "done":
-                continue
-            agent = check_handoffs._task_scalar(text, task_id, "agent")
-            if agent in {"", "null"}:
-                raise BriefError(f"{task_id} landed task has no recorded agent")
-            member = check_handoffs._strict_frontmatter(text, task_id).get("repo")
-            base_repo = repo
-            if member is not None:
-                located = member_base(member) if isinstance(member, str) and member else None
-                if located is None:
-                    raise BriefError(f"repo: names no member in MEMBERS.md: {member}")
-                base_repo = located[0]
-            recorded_base = check_handoffs._task_scalar(text, task_id, "base")
-            try:
-                landed_bases[task_id] = require_commit(base_repo, require_full_sha(recorded_base))
-            except IsolationError as error:
-                raise BriefError(f"{task_id} landed task has invalid historical base: {error}") from error
-            dependency_files[task_id] = set()
+        tasks, dependency_files, landed_bases = plan_validation_bases(
+            repo, project_dir, member_base, initial=True
+        )
         validate_task_briefs(
             repo, head.stdout.strip(), f"{project_dir}/tasks",
             dependency_files=dependency_files, landed_bases=landed_bases,
@@ -581,7 +578,10 @@ def checkpoint_approval(
             f"{expected_head}^{{commit}}",
         ).stdout.strip()
         if resolved_head != expected_head:
-            raise PipelineStateError("expected-head must be an exact full commit SHA")
+            raise PipelineStateError(
+                "expected-head must be an exact full commit SHA; "
+                "resolve a ref or a short SHA with git rev-parse first"
+            )
         if pipeline_state._run_git(resolved, "rev-parse", "HEAD").stdout.strip() != expected_head:
             raise PipelineStateError("approval must start at expected-head")
         active_state, _, _ = pipeline_state.load_state(resolved)
@@ -596,8 +596,9 @@ def checkpoint_approval(
         state, state_before, state_path = pipeline_state.load_state(resolved, project_dir)
         changes, event, subject, body = _approval_details(kind, state, selected_milestone)
         _validate_plan_briefs(resolved, kind, project_dir)
+        recovery_reviews = None
         if kind == "plan" and project_dir == ".project":
-            pipeline_state._build_recovery().restore_unchanged_reviews(resolved)
+            recovery_reviews = pipeline_state._build_recovery().restore_unchanged_reviews(resolved)
         expected = {
             "phase": state.phase,
             "status": state.status,
@@ -629,7 +630,7 @@ def checkpoint_approval(
             if kind == "roadmap-reslice":
                 baseline_before = pipeline_state._read_real_file(project / "ROADMAP.before-reslice.md", "re-slice baseline")
             roadmap_after = _reslice_roadmap(
-                baseline_before, roadmap_before, state, selected_milestone,
+                resolved, baseline_before, roadmap_before, state, state_before, selected_milestone,
             ) if kind == "roadmap-reslice" else _activate_roadmap_milestone(
                 roadmap_before,
                 selected_milestone,
@@ -659,6 +660,8 @@ def checkpoint_approval(
         }
         if baseline_before is not None:
             journal["baseline_before"] = baseline_before
+        if recovery_reviews is not None:
+            journal["recovery_reviews"] = recovery_reviews
         pipeline_state._write_json(journal_path, journal)
         return _resume_checkpoint_locked(resolved, project, journal_path, journal)
 
@@ -740,8 +743,8 @@ def defer_approval(
             if kind == "roadmap-reslice":
                 baseline = project / "ROADMAP.before-reslice.md"
                 roadmap_after = _reslice_roadmap(
-                    pipeline_state._read_real_file(baseline, "re-slice baseline"),
-                    roadmap_before, state, selected_milestone,
+                    resolved, pipeline_state._read_real_file(baseline, "re-slice baseline"),
+                    roadmap_before, state, state_before, selected_milestone,
                 )
             else:
                 roadmap_after = _activate_roadmap_milestone(roadmap_before, selected_milestone)

package/skills/path/scripts/state_promote.py

@@ -377,17 +377,22 @@ def _prepare_promotion(
     head = pipeline_state._run_git(repo, "rev-parse", "HEAD").stdout.strip()
     if head != base:
         raise PipelineStateError(f"promotion must start at base SHA: {head} != {base}")
-    remote = pipeline_state._run_git(repo, "rev-parse", "--verify", "origin/main^{commit}").stdout.strip()
+    active_state, active_text, _ = pipeline_state.load_state(repo)
+    remote_default = f"origin/{active_state.default_branch}"
+    remote = pipeline_state._run_git(
+        repo, "rev-parse", "--verify", f"{remote_default}^{{commit}}"
+    ).stdout.strip()
     if remote != base:
         raise PipelineStateError(
-            f"base SHA is not current origin/main: {base} != {remote}"
+            f"base SHA is not current {remote_default}: {base} != {remote}"
         )
     if not pipeline_state._is_ancestor(repo, landing, base):
-        raise PipelineStateError("landing is not an ancestor of the current main base")
+        raise PipelineStateError(
+            f"landing is not an ancestor of the current {active_state.default_branch} base"
+        )
     if pipeline_state._run_git(repo, "status", "--porcelain", "--untracked-files=all").stdout:
         raise PipelineStateError("promotion must start from a clean worktree")
 
-    active_state, active_text, _ = pipeline_state.load_state(repo)
     if active_state.phase != "shipped" or active_state.status != "done":
         raise PipelineStateError("promotion requires active STATE shipped/done")
     if active_state.milestone is None:
@@ -456,6 +461,12 @@ def _prepare_promotion(
         raise PipelineStateError(
             "lookahead integration_default does not match the active project"
         )
+    if next_state.default_branch != active_state.default_branch:
+        raise PipelineStateError(
+            "lookahead default_branch does not match the active project: copy "
+            f"`default_branch: {active_state.default_branch}` from .project/STATE.md "
+            "into .project/next/STATE.md"
+        )
     if next_state.milestone != milestone:
         raise PipelineStateError(
             f"requested milestone {milestone} != next STATE milestone {next_state.milestone}"

package/skills/path/scripts/status_runtime.py

@@ -6,6 +6,7 @@ import hashlib
 import errno
 import json
 import os
+import stat
 import subprocess
 import sys
 import time
@@ -151,7 +152,17 @@ def validate_runtime(data: dict) -> Path:
             path = root / name
             if path.is_symlink() or hashlib.sha256(path.read_bytes()).hexdigest() != expected:
                 raise ValueError(f"runtime file changed: {name}")
-        if set(p.name for p in root.iterdir()) != set(files) | {"manifest.json"}:
+        runtime_entries = set()
+        for path in root.iterdir():
+            if path.name == "__pycache__":
+                if not stat.S_ISDIR(path.lstat().st_mode):
+                    raise ValueError("unexpected runtime files")
+                for cached in path.iterdir():
+                    if cached.suffix != ".pyc" or not stat.S_ISREG(cached.lstat().st_mode):
+                        raise ValueError("unexpected runtime files")
+                continue
+            runtime_entries.add(path.name)
+        if runtime_entries != set(files) | {"manifest.json"}:
             raise ValueError("unexpected runtime files")
     except (OSError, ValueError, TypeError) as error:
         raise ValueError(hint + f" ({error})") from error
@@ -167,8 +178,13 @@ def run_guard(repo: Path, name: str) -> None:
     root = resolve_runtime(repo)
     sys.dont_write_bytecode = True
     sys.path.insert(0, str(root))
-    code = compile((root / name).read_bytes(), str(root / name), "exec")
-    exec(code, {"__name__": "__main__", "__file__": str(repo / ".gsd-path" / name)})
+    previous_pycache_prefix = sys.pycache_prefix
+    sys.pycache_prefix = str(root / "manifest.json")
+    try:
+        code = compile((root / name).read_bytes(), str(root / name), "exec")
+        exec(code, {"__name__": "__main__", "__file__": str(repo / ".gsd-path" / name)})
+    finally:
+        sys.pycache_prefix = previous_pycache_prefix
 
 
 def launch(repo: Path) -> int:
@@ -179,7 +195,9 @@ def launch(repo: Path) -> int:
         except (OSError, ValueError) as error:
             print(str(error), file=sys.stderr)
             return 2
-        return subprocess.call([sys.executable, "-B", str(runtime), "status", "--repo", str(repo)],
+        return subprocess.call([sys.executable, "-B", "-X",
+                                f"pycache_prefix={runtime.parent / 'manifest.json'}",
+                                str(runtime), "status", "--repo", str(repo)],
                                env={**os.environ, "GIT_OPTIONAL_LOCKS": "0"})
     runtime = parent / "runtime" / "pipeline_state.py"
     lock = repo / ".gsd-path-install-lock"