@opengsd/gsd-path 1.5.0 → 1.6.0

package/skills/gsd-path-research/scripts/pipeline_git.py

@@ -2,8 +2,9 @@
 # gsd-path project runtime
 """Deterministic GSD Path branch names and pipeline commit messages.
 
-Bound work lives on `gsd-path/M00N` for that milestone. The required remote
-default `main` stays a separate trunk. Ship merges the bound branch onto main;
+Bound work lives on `gsd-path/M00N` for that milestone. The remote default
+that STATE.md records (`main` when unrecorded) stays a separate trunk. Ship
+merges the bound branch onto it;
 the next milestone binds a new unused `gsd-path/M00N` and retires the
 integrated previous branch, locally and on origin.
 """
@@ -98,7 +99,8 @@ def ship_subject(archive_name: str) -> str:
 
 
 def integrate_subject(archive_name: str, default_branch: str) -> str:
-    if not default_branch or default_branch.startswith("origin/"):
+    # The bare name, under the rule that records it; `origin/trunk` is a legal bare name.
+    if not _common.valid_default_branch(default_branch):
         raise PipelineGitError(f"default branch is invalid: {default_branch}")
     number = milestone_number(archive_name)
     return (
@@ -363,7 +365,7 @@ def _remote_branch_exists(repo: Path, branch: str) -> bool:
     return _remote_ref_sha(repo, f"refs/heads/{branch}") is not None
 
 
-def _pull_request_tag_fields(repo: Path, ref: str) -> dict[str, str]:
+def _milestone_tag_fields(repo: Path, ref: str) -> dict[str, str]:
     tag_type = _run_git(repo, "cat-file", "-t", ref, check=False)
     if tag_type.returncode != 0 or tag_type.stdout.strip() != "tag":
         return {}
@@ -373,7 +375,7 @@ def _pull_request_tag_fields(repo: Path, ref: str) -> dict[str, str]:
         match = re.fullmatch(r"(Mode|Pull-Request|Ship|Landing): (.+)", line)
         if match:
             if match.group(1) in fields:
-                raise PipelineGitError("pull-request milestone tag repeats metadata")
+                raise PipelineGitError("milestone tag repeats metadata")
             fields[match.group(1)] = match.group(2)
     return fields
 
@@ -404,7 +406,15 @@ def _validated_shipped_state(repo: Path) -> dict[str, object]:
     return state
 
 
-def _require_pull_request_integration_proof(
+# Metadata a published milestone tag must carry, per integration mode, before
+# bind-next accepts a previous bound branch that the forge deleted on merge.
+TAG_PROOF_FIELDS = {
+    "pull-request": {"Mode", "Pull-Request", "Ship", "Landing"},
+    "external-landing": {"Mode", "Ship", "Landing"},
+}
+
+
+def _require_tag_integration_proof(
     repo: Path,
     ship: str,
     base: str,
@@ -415,8 +425,11 @@ def _require_pull_request_integration_proof(
         raise PipelineGitError("bind-next requires shipped/done state")
     if state.get("branch") != previous_branch:
         raise PipelineGitError("shipped state does not name the previous branch")
-    if state.get("integration") != "pull-request":
-        raise PipelineGitError("shipped integration mode is not pull-request")
+    mode = state.get("integration")
+    if mode not in TAG_PROOF_FIELDS:
+        raise PipelineGitError(
+            "shipped integration mode is not pull-request or external-landing"
+        )
     archive = state.get("archive")
     if not isinstance(archive, str):
         raise PipelineGitError("shipped state does not name an archive")
@@ -427,24 +440,23 @@ def _require_pull_request_integration_proof(
     ):
         raise PipelineGitError("shipped archive does not match the previous branch")
     ref = f"refs/tags/milestone/{match.group(1)}"
-    fields = _pull_request_tag_fields(repo, ref)
-    if set(fields) != {"Mode", "Pull-Request", "Ship", "Landing"}:
-        raise PipelineGitError("pull-request integration proof is incomplete")
-    if fields["Mode"] != "pull-request" or fields["Ship"] != ship:
-        raise PipelineGitError("pull-request integration proof does not match shipped state")
-    pull_request = fields["Pull-Request"]
-    if re.fullmatch(
+    fields = _milestone_tag_fields(repo, ref)
+    if set(fields) != TAG_PROOF_FIELDS[mode]:
+        raise PipelineGitError(f"{mode} integration proof is incomplete")
+    if fields["Mode"] != mode or fields["Ship"] != ship:
+        raise PipelineGitError(f"{mode} integration proof does not match shipped state")
+    if mode == "pull-request" and re.fullmatch(
         r"https://github\.com/[^/]+/[^/]+/pull/[1-9][0-9]*",
-        pull_request,
+        fields["Pull-Request"],
     ) is None:
         raise PipelineGitError("pull-request integration proof has an invalid PR URL")
     landing = fields["Landing"]
     if re.fullmatch(r"[0-9a-f]{40}", landing) is None:
-        raise PipelineGitError("pull-request integration proof has an invalid landing")
+        raise PipelineGitError(f"{mode} integration proof has an invalid landing")
     local_object = _run_git(repo, "rev-parse", ref).stdout.strip()
     local_target = _run_git(repo, "rev-parse", f"{ref}^{{commit}}").stdout.strip()
     if local_target != landing:
-        raise PipelineGitError("pull-request integration tag does not point at landing")
+        raise PipelineGitError(f"{mode} integration tag does not point at landing")
     remote = _run_git(
         repo,
         "ls-remote",
@@ -456,14 +468,14 @@ def _require_pull_request_integration_proof(
         check=False,
     )
     if remote.returncode != 0:
-        raise PipelineGitError("pull-request integration tag is not published")
+        raise PipelineGitError(f"{mode} integration tag is not published")
     rows = dict(
         line.split("\t", 1)[::-1]
         for line in remote.stdout.splitlines()
         if "\t" in line
     )
     if rows != {ref: local_object, f"{ref}^{{}}": landing}:
-        raise PipelineGitError("published pull-request integration tag differs")
+        raise PipelineGitError(f"published {mode} integration tag differs")
     parents = _run_git(
         repo,
         "rev-list",
@@ -473,11 +485,11 @@ def _require_pull_request_integration_proof(
         landing,
     ).stdout.split()
     if len(parents) != 3 or parents[2] != ship:
-        raise PipelineGitError("pull-request integration proof has invalid merge topology")
+        raise PipelineGitError(f"{mode} integration proof has invalid merge topology")
     first_parent = _run_git(repo, "rev-list", "--first-parent", base).stdout.splitlines()
     if landing not in first_parent:
         raise PipelineGitError(
-            "pull-request integration landing is not on main first-parent history"
+            f"{mode} integration landing is not on the default branch first-parent history"
         )
     return landing
 
@@ -533,6 +545,34 @@ def _write_bind_next_journal(path: Path, value: dict[str, object]) -> None:
             temporary.unlink()
 
 
+def _require_state_remote_default(repo: Path, remote_default: str) -> str:
+    """Return the default branch STATE.md records; `remote_default` must name it.
+
+    No STATE.md yet (bind-initial before initialize) or no field means main.
+    An unreadable STATE.md also means main, as before the field existed: the
+    callers that need a valid state check it themselves.
+    """
+    if __package__:
+        from . import pipeline_state
+    else:
+        try:
+            import pipeline_state
+        except ImportError:  # pragma: no cover - package import used by tests
+            from scripts import pipeline_state
+
+    default_name, unreadable = "main", ""
+    if (repo / ".project" / "STATE.md").exists():
+        try:
+            default_name = pipeline_state.load_state(repo)[0].default_branch
+        except (OSError, pipeline_state.PipelineStateError) as error:
+            unreadable = f" (STATE.md is unreadable: {error})"
+    if remote_default != f"origin/{default_name}":
+        raise PipelineGitError(
+            f"remote default must be origin/{default_name}, got {remote_default}{unreadable}"
+        )
+    return default_name
+
+
 def _initial_binding_snapshot(repo: Path) -> Optional[tuple]:
     """Admit only clean work or the validated, untracked initializer state."""
     dirty = _run_git(repo, "status", "--porcelain=v1", "-z", "--untracked-files=all").stdout
@@ -579,8 +619,7 @@ def bind_initial_milestone_branch(
     resolved = _require_worktree_root(repo)
     if not is_bound_branch(branch):
         raise PipelineGitError(f"invalid bound branch: {branch}")
-    if remote_default != "origin/main":
-        raise PipelineGitError(f"remote default must be origin/main, got {remote_default}")
+    default_name = _require_state_remote_default(resolved, remote_default)
 
     default_sha = _run_git(
         resolved,
@@ -600,7 +639,7 @@ def bind_initial_milestone_branch(
         raise PipelineGitError(
             f"validated base is stale: {base_sha} != {remote_default} {default_sha}"
         )
-    remote_sha = _remote_ref_sha(resolved, "refs/heads/main")
+    remote_sha = _remote_ref_sha(resolved, f"refs/heads/{default_name}")
     if remote_sha != default_sha:
         raise PipelineGitError(
             f"fetched {remote_default} is stale relative to origin"
@@ -742,8 +781,7 @@ def bind_next_milestone_branch(
         raise PipelineGitError(f"invalid previous bound branch: {previous_branch}")
     if milestone_number(branch) <= milestone_number(previous_branch):
         raise PipelineGitError(f"next branch {branch} must follow {previous_branch}")
-    if remote_default != "origin/main":
-        raise PipelineGitError(f"remote default must be origin/main, got {remote_default}")
+    default_name = _require_state_remote_default(repo, remote_default)
 
     default_sha = _run_git(
         repo,
@@ -763,7 +801,7 @@ def bind_next_milestone_branch(
         raise PipelineGitError(
             f"validated base is stale: {base_sha} != {remote_default} {default_sha}"
         )
-    live_default_sha = _remote_ref_sha(repo, "refs/heads/main")
+    live_default_sha = _remote_ref_sha(repo, f"refs/heads/{default_name}")
     if live_default_sha != default_sha:
         raise PipelineGitError(f"fetched {remote_default} is stale relative to origin")
     ship_sha = _run_git(
@@ -821,7 +859,7 @@ def bind_next_milestone_branch(
         detail = landing_integrated.stderr.strip() or landing_integrated.stdout.strip()
         raise PipelineGitError(f"could not verify integrated branch: {detail}")
     if allow_remote_absent:
-        proven_landing = _require_pull_request_integration_proof(
+        proven_landing = _require_tag_integration_proof(
             repo,
             ship_sha,
             base_sha,
@@ -829,7 +867,7 @@ def bind_next_milestone_branch(
         )
         if proven_landing != landing_sha:
             raise PipelineGitError(
-                "validated landing does not match pull-request integration proof"
+                "validated landing does not match the milestone tag integration proof"
             )
 
     symbolic_branch = _run_git(

package/skills/gsd-path-research/scripts/pipeline_state.py

@@ -173,9 +173,14 @@ class PipelineState:
     integration_default: str
     integration: str
     integration_source: str
+    default_branch: str = "main"
 
     def json(self) -> dict[str, Optional[str]]:
-        return asdict(self)
+        # ponytail: default_branch stays out of this payload; guard_hook, install
+        # and the daemon probe accept only the closed STATE_FIELDS set.
+        payload = asdict(self)
+        del payload["default_branch"]
+        return payload
 
 
 @dataclass(frozen=True)
@@ -290,7 +295,7 @@ def _bound_branch_number(value: str) -> Optional[int]:
 def _state_from_text(text: str, label: str = "STATE.md") -> PipelineState:
     values = _parse_frontmatter(text, label)
     missing = [field for field in LEGACY_STATE_FIELDS if field not in values]
-    extra = sorted(set(values) - set(STATE_FIELDS))
+    extra = sorted(set(values) - set(STATE_FIELDS) - {"default_branch"})
     if missing:
         raise PipelineStateError(f"{label} is missing fields: {', '.join(missing)}")
     if extra:
@@ -322,6 +327,7 @@ def _state_from_text(text: str, label: str = "STATE.md") -> PipelineState:
         integration_default=integration_default,
         integration=integration,
         integration_source=integration_source,
+        default_branch=values.get("default_branch", "main"),
     )
     _validate_state_values(state, label)
     return state
@@ -355,6 +361,10 @@ def _validate_state_values(state: PipelineState, label: str) -> None:
         raise PipelineStateError(
             f"{label} default-sourced integration must match integration_default"
         )
+    if not _common.valid_default_branch(state.default_branch):
+        raise PipelineStateError(
+            f"{label} has invalid default_branch: {state.default_branch}"
+        )
     if state.branch is not None and _bound_branch_number(state.branch) is None:
         raise PipelineStateError(f"{label} has invalid branch: {state.branch}")
     archive_match = ARCHIVE_RE.fullmatch(state.archive or "")
@@ -416,6 +426,7 @@ def validate_state(repo: Path, project_dir: str = ".project") -> dict[str, objec
         "status": "valid",
         "path": str(path),
         "state": state.json(),
+        "default_branch": state.default_branch,
     }
 
 
@@ -698,8 +709,10 @@ def status_state(repo: Path, project_dir: str = ".project") -> dict[str, object]
         if branch
         else None
     )
+    # The key keeps its name for status consumers; the ref follows STATE.
+    default_branch = load_state(resolved, project_dir)[0].default_branch
     origin_main = (
-        _optional_rev(resolved, "refs/remotes/origin/main") if has_git else None
+        _optional_rev(resolved, f"refs/remotes/origin/{default_branch}") if has_git else None
     )
     pending, pending_error = _pending_answers(resolved)
     lookahead = resolved / ".project" / "next"
@@ -722,6 +735,7 @@ def status_state(repo: Path, project_dir: str = ".project") -> dict[str, object]
         "advance": False,
         "completion": completion,
         "state": state,
+        "default_branch": default_branch,
         "route": route,
         "path": str(_track_root(resolved, project_dir) / "STATE.md"),
         "git": {
@@ -881,7 +895,12 @@ def _route_result(
         route["phase"] = phase
     if mode is not None:
         route["mode"] = mode
-    return {"schema": ROUTE_SCHEMA, "state": state.json(), "route": route}
+    return {
+        "schema": ROUTE_SCHEMA,
+        "state": state.json(),
+        "default_branch": state.default_branch,
+        "route": route,
+    }
 
 
 def _legacy_bind_next_landing(repo: Path, state: PipelineState) -> str:
@@ -1009,7 +1028,7 @@ def _bind_next_journal_recovery(
         raise PipelineStateError("bind-next journal landing does not contain ship")
     if not _is_ancestor(repo, landing, base):
         raise PipelineStateError("bind-next journal landing is not an ancestor of base")
-    if transaction["remote_default"] != "origin/main":
+    if transaction["remote_default"] != f"origin/{state.default_branch}":
         raise PipelineStateError("bind-next journal has invalid remote default")
     if stage not in {"prepared", "switched", "retired"}:
         raise PipelineStateError("bind-next journal has invalid stage")
@@ -1758,7 +1777,10 @@ def transition_state(
     if unsupported:
         raise PipelineStateError(f"unsupported state fields: {', '.join(sorted(unsupported))}")
     if not changes:
-        raise PipelineStateError("transition requires at least one changed field")
+        raise PipelineStateError(
+            "transition requires at least one changed field; "
+            "to record only a Log event, pass --set-status with the current status"
+        )
     required_expected = {"phase", "status", "branch", "archive"} | set(changes)
     missing_expected = sorted(required_expected - set(expected))
     if missing_expected:

package/skills/gsd-path-research/scripts/promote_lookahead.py

@@ -198,10 +198,10 @@ def select_fetched_base(
     use_lookahead: bool,
 ) -> dict:
     root = repo.resolve()
-    if not re.fullmatch(r"origin/[A-Za-z0-9][A-Za-z0-9._/-]*", remote_default):
+    if not remote_default.startswith("origin/") or not _common.valid_default_branch(
+        remote_default.removeprefix("origin/")
+    ):
         raise LookaheadError("remote default must be an origin branch")
-    if ".." in remote_default or "//" in remote_default:
-        raise LookaheadError("remote default is invalid")
     resolved = subprocess.run(
         ["git", "-C", str(root), "rev-parse", "--verify", f"{remote_default}^{{commit}}"],
         capture_output=True,

package/skills/gsd-path-research/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-research/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-research/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-roadmap/SKILL.md

@@ -27,7 +27,8 @@ return to `$gsd-path` for ownership checking. Legal entry is
 yet, `roadmap/active|blocked`, or a
 milestone-boundary re-slice: `inspect/active` or `define/active` with no
 approved INTENT.md for the next milestone and a user request to re-scope the
-remaining `pending` entries,
+remaining `pending` entries or, at `define/active` only, to change the scope
+of the `active` entry,
 or `roadmap/active` with STATE.milestone null and an `abandoned` entry in
 ROADMAP.md (the post-abandon re-slice the build orchestrator hands off).
 Enter from `decide/done` only with `pipeline_state.py transition`, exact
@@ -35,6 +36,8 @@ expected phase/status/milestone/branch/archive fields, event `roadmap started`,
 and `--set-phase roadmap --set-status active`; never edit STATE directly. In a
 milestone-boundary re-slice, preserve the entering `inspect/active` or
 `define/active` state throughout the re-slice.
+A `define/active` state that the router reports in `corrections` mode already
+has an approved INTENT.md; it blocks.
 Any later phase blocks; mid-milestone
 re-scope is never legal — finish or ship the active milestone first. A
 `decide/done` state with ROADMAP.md already present is milestone-scope decide;
@@ -71,8 +74,11 @@ precondition fails.
    give `.project/ROADMAP.before-reslice.md` with the instruction to preserve
    `shipped` entries byte-for-byte except Status/Archive/Integrated fields and
    to never modify `abandoned` entries at all. For a milestone-boundary
-   re-slice, also preserve the existing `active` entry byte-for-byte; only
-   `pending` entries are in scope.
+   re-slice entered at `inspect/active`, also preserve the existing `active`
+   entry byte-for-byte; only `pending` entries are in scope. Entered at
+   `define/active`, the `active` entry may also change as the user ruled, but
+   its heading (id and slug) and its Status, Depends on, Archive, and
+   Integrated fields stay unchanged.
    The output is exactly `.project/ROADMAP.md` — no other location is
    canonical.
 3. Gate ROADMAP.md:
@@ -96,8 +102,11 @@ precondition fails.
    - On a re-slice, `shipped` entries differ from
      `.project/ROADMAP.before-reslice.md` only in Status/Archive/Integrated;
      `abandoned` entries are byte-for-byte identical.
-   - On a milestone-boundary re-slice, the prior `active` entry is byte-for-byte
-     identical to `.project/ROADMAP.before-reslice.md`.
+   - On a milestone-boundary re-slice entered at `inspect/active`, the prior
+     `active` entry is byte-for-byte identical to
+     `.project/ROADMAP.before-reslice.md`. Entered at `define/active`, it
+     stays the only `active` entry and keeps its heading and its Status,
+     Depends on, Archive, and Integrated fields.
 4. Redispatch one complete corrected brief under logical task name `roadmap`,
    following the runtime dispatch contract and including all gate failures.
    Allow one revision round. If it still fails, keep the entering
@@ -160,7 +169,8 @@ precondition fails.
 
    The helper owns roadmap selection, expected state, baseline cleanup and
    the approval checkpoint. It journals before mutation, retains the baseline
-   bytes for recovery, and refuses changes to settled or active entries.
+   bytes for recovery, and refuses changes to settled entries and every
+   `active` entry change that step 2 does not permit.
    A milestone-boundary re-slice retains Inspect or Define; a post-abandon
    re-slice enters Inspect. Require its typed result to report `status:
    approved`, the requested kind, milestone and returned commit. After an

package/skills/gsd-path-roadmap/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

package/skills/gsd-path-roadmap/references/runtime-selection.md

@@ -20,6 +20,15 @@ references to bundled copies of those helpers. Other skill helpers, templates,
 and role briefs remain in the installed skill bundle. Pass `-B` to Python helper
 invocations so execution does not create bytecode in the runtime store.
 
+The selected runtime is authoritative for each helper in its `manifest.json`;
+this includes `review_findings.py` and `task_context.py`. A selected runtime
+that was published before a helper became a runtime file does not list that
+helper: run the bundled copy until the project runtime is upgraded.
+`dispatch_driver.py` and `workflow_run.py` always run from the installed skill
+bundle, because they read role briefs and templates from it; a skill update
+replaces them, a runtime upgrade does not. The driver reloads the helper modules
+that it imports from the selected runtime.
+
 With no declaration, retain the legacy helper lookup. An existing
 `.gsd-path/runtime/` requires the explicit `--runtime-migrate --project PATH`
 operation before adopting external storage; review the resulting Git diff.