@opengsd/gsd-path 1.5.0 → 1.6.0

package/skills/gsd-path-build/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/gsd-path-build/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/gsd-path-build/scripts/state_checkpoint.py

@@ -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:
@@ -563,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)
@@ -578,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,
@@ -611,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,
@@ -641,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)
 
@@ -722,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/gsd-path-build/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/gsd-path-build/scripts/task_context.py

@@ -1,10 +1,12 @@
 #!/usr/bin/env python3
+# gsd-path project runtime
 """Render a read-only coder intent view from the approved task and intent."""
 
 import argparse
 import hashlib
 import re
 import sys
+sys.dont_write_bytecode = True
 from pathlib import Path
 
 try:

package/skills/gsd-path-build/scripts/workflow_run.py

@@ -210,8 +210,14 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
                         "--base", expected_head, "--task-id", task_id,
                         "--round-size", str(round_size))
             if task["mode"] == "serial":
+                name = f"task-{task_id.lower()}-verify"
+                stale = isolation.sidecar_root(repo, "verify", name)
+                if os.path.lexists(stale / ".git"):
+                    # An earlier prepare-task left this sidecar. Only one that is proven untouched is replaced.
+                    steps.append({"script": "isolation.py", "result": isolation.retire_stale_verify(
+                        repo, stale, isolation.verify_branch_name(name))})
                 step("isolation.py", "isolate-verify", "--repo", str(repo),
-                     "--base", expected_head, "--name", f"task-{task_id.lower()}-verify")
+                     "--base", expected_head, "--name", name)
         elif action == "build-evidence":
             proof = step("build_state.py", "verify-landed", *common, "--head", expected_head)
             # The landing proof has one canonical home; lean final-review reuse allows only this path.
@@ -278,7 +284,8 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
             if action == "approve-plan":
                 step("pipeline_state.py", "approve", *common, "--kind", "plan",
                      "--expected-head", expected_head)
-    except (StepFailed, OSError, subprocess.CalledProcessError, ValueError, KeyError, TypeError) as error:
+    except (StepFailed, isolation.IsolationError, OSError, subprocess.CalledProcessError,
+            ValueError, KeyError, TypeError) as error:
         return {"status": "blocked", "reason": str(error), "steps": steps,
                 "next": next_step}
     return {"status": "complete", "steps": steps, **outputs}

package/skills/gsd-path-build/templates/task.md

@@ -11,6 +11,7 @@ task_branch: null   # orchestrator-owned: gsd-path-task/<id> while parallel; nul
 # Optional explicit dispatch overrides: model: <advertised slug|inherit>
 # effort: <advertised effort|inherit>
 # repo: <member>    # multi-repo only: the MEMBERS.md member this task changes; omit for the coordinator
+# supersedes: [<task id>]  # only when INTENT requires it: earlier-wave tasks whose behavior this task replaces; retires their Verify
 files:              # every file this task may touch — dispatch checks overlap
   - <path>
 ---

package/skills/gsd-path-build/templates/wave-review.md

@@ -26,9 +26,17 @@ Tasks reviewed: <count>
 
 ## T001 — <title>: <pass | fail>
 
-<!-- Per task criterion: copy the full acceptance/interface criterion verbatim
-     before the em dash; join wrapped lines with spaces. An AC id or summary
-     alone cannot be matched by review_findings.py. -->
+<!-- Task sections go in task id order (T001 before T002), not in the order
+     of the PLAN.md wave table. The heading title is the exact `title:` of
+     the task file. An evidence line starts with `- ✅ ` (pass) or `- ❌ `
+     (fail). A section needs one or more lines with the marker of its own
+     verdict, so a failed task needs a `- ❌ ` criterion line.
+     Per task criterion: copy every word of the acceptance/interface
+     criterion before the em dash; join wrapped lines and sub-bullets with
+     spaces (the `- ` markers of sub-bullets are optional). An AC id or
+     summary alone cannot be matched by review_findings.py.
+     Write literal markup and code in backticks inside a sentence: text
+     such as <b> outside backticks reads as an unfilled placeholder. -->
 - ✅ <criterion> — <evidence: verify output / file:line checked>
 - ❌ <criterion> — found: <what exists instead, file:line>
   fix: <concrete direction a coder can execute without re-investigating>
@@ -47,13 +55,14 @@ Contract violations (blocking):
      wave, ending `: pass` or `: fail`. `scripts/check_handoffs.py wave
      --review <this file>` gates the SC id set and verdicts. Omit this
      section when no task in the wave owns an SC.
-     Copy the criterion text from INTENT.md `## Success criteria` exactly as
-     `_success_criteria` stores it: indented continuation lines join with a
-     single space and keep their leading `- ` markers; the gate compares
-     heading text with `_normalize_ws` only (no paraphrase or stripped
-     sub-bullets). -->
+     Copy every word of the criterion from INTENT.md `## Success criteria`:
+     join indented continuation lines and sub-bullets with a single space
+     (the `- ` markers of sub-bullets are optional). The gate compares every
+     other word: no paraphrase, no dropped sub-bullet.
+     Each SC block needs an evidence line with the marker of its own
+     verdict: `- ✅ ` (pass) or `- ❌ ` (fail). -->
 
-### SC1 — <criterion as stored by the gate>: <pass | fail>
+### SC1 — <criterion from INTENT.md>: <pass | fail>
 - ✅ <evidence: verify output / file:line checked>
 - ❌ <criterion> — found: <what exists instead, file:line>
   fix: <concrete direction a coder can execute without re-investigating>

package/skills/gsd-path-decide/references/operating-rules.md

@@ -38,8 +38,8 @@ bundles this file; spawned agents follow their role brief instead.
   the lookahead planning track for the next milestone; it follows the same
   marker rule, owns no task frontmatter, and never binds a branch.
 - STATE.integration_default is the project closeout choice and
-  STATE.integration is the current milestone choice. Both are `direct` or
-  `pull-request`; STATE.integration_source is `default` or `milestone` and
+  STATE.integration is the current milestone choice. Both are `direct`,
+  `pull-request`, or `external-landing`; STATE.integration_source is `default` or `milestone` and
   preserves explicit override provenance. Older v2 state defaults to `direct`,
   and modes may be changed only through `pipeline_state.py
   configure-integration` before build. A next milestone resets its current
@@ -82,7 +82,9 @@ bundles this file; spawned agents follow their role brief instead.
   `isolation.py attest` may stand in for it: one `.project/`-only commit that
   names the base, the attested HEAD, the declared files that changed, the
   task Verify recorded as passing at that HEAD, and the ruling verbatim.
-  `recover` reports it as `attested`, never as a proven landing.
+  `recover` reports it as `attested`, never as a proven landing. Attestation
+  matches the declared files literally: work that is only below a declared
+  directory can land but cannot be attested.
 - All pipeline work for a milestone lives on `gsd-path/M00N` (M001, M002,
   …) bound in STATE.branch. The next milestone binds a new unused
   `gsd-path/M00N` at the remote default after the previous ship integrates.
@@ -90,6 +92,12 @@ bundles this file; spawned agents follow their role brief instead.
   branch — either Path's direct merge or a Path-owned PR merged by the user.
   The bound branch never receives merges or back-merges and is never the
   GitHub default.
+- The default branch is the one that STATE `default_branch` records at
+  initialization; a STATE file without the field means `main`. `main` and
+  `origin/main` in these rules mean that branch. Never change the record and
+  never take the name from a later `origin/HEAD` lookup. For a member
+  repository, the branch is the one that its `.project/MEMBERS.md` section
+  records as `Default branch`; a section without the field means `main`.
 - After initialization writes STATE.md, and before entering the first pipeline
   phase in an existing Git repository, the router calls
   `scripts/pipeline_git.py bind-initial` with the selected M00N and exact