@opengsd/gsd-path 1.5.0 → 1.6.0

package/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/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/scripts/pipeline_undo.py

@@ -22,6 +22,7 @@ from datetime import date
 # Runtime helpers must not modify their immutable installation.
 sys.dont_write_bytecode = True
 import tempfile
+import traceback
 from pathlib import Path, PurePosixPath
 from typing import Optional, Sequence
 
@@ -53,7 +54,7 @@ def _load_pipeline_modules():
     try:
         from scripts import archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint
         return archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint
-    except ModuleNotFoundError as error:
+    except ImportError as error:  # a foreign `scripts` package
         if error.name not in {
             "scripts",
             "scripts.archive_milestone",
@@ -63,6 +64,13 @@ def _load_pipeline_modules():
             "scripts.state_checkpoint",
         }:
             raise
+        # A plain ImportError raised while a `scripts` module loaded is not a
+        # foreign package. A missing module falls back, as before.
+        if not isinstance(error, ModuleNotFoundError) and any(
+            frame.f_globals.get("__name__", "").startswith("scripts.")
+            for frame, _ in traceback.walk_tb(error.__traceback__)
+        ):
+            raise
         shared = Path(__file__).resolve().parents[2] / "gsd-path" / "scripts"
         sys.path.insert(0, str(shared))
         import archive_milestone
@@ -772,14 +780,15 @@ def _member_undo_parent(repo: Path, member: str, landing: str) -> str:
     bound = entry["branch"]
     if _run_git(checkout, "rev-parse", f"refs/heads/{bound}").stdout.strip() != landing:
         raise UndoError(f"member {member} {bound} moved past this landing")
-    _require_member_unpublished(checkout, member, landing, bound)
+    _require_member_unpublished(repo, checkout, member, landing, bound)
     return _run_git(checkout, "rev-parse", f"{landing}^").stdout.strip()
 
 
-def _require_member_unpublished(checkout: Path, member: str, landing: str, bound: str) -> None:
-    for ref, where in (("refs/remotes/origin/main", "origin/main"), (f"refs/remotes/origin/{bound}", f"origin/{bound}")):
+def _require_member_unpublished(repo: Path, checkout: Path, member: str, landing: str, bound: str) -> None:
+    for branch in (isolation.member_default_branch(repo, member), bound):
+        ref = f"refs/remotes/origin/{branch}"
         if _run_git(checkout, "merge-base", "--is-ancestor", landing, ref, check=False).returncode == 0:
-            raise UndoError(f"member {member} landing is already on {where}")
+            raise UndoError(f"member {member} landing is already on origin/{branch}")
 
 
 def _require_no_member_landing_journal(repo: Path) -> None:
@@ -794,7 +803,7 @@ def _undo_member_landing(repo: Path, transaction: dict[str, object]) -> None:
     checkout, _, entry = isolation._member_context(repo, member)
     tip = _run_git(checkout, "rev-parse", f"refs/heads/{entry['branch']}").stdout.strip()
     if tip == transaction["member_parent"]:
-        _require_member_unpublished(checkout, member, str(transaction["landing"]), entry["branch"])
+        _require_member_unpublished(repo, checkout, member, str(transaction["landing"]), entry["branch"])
         return
     if tip != transaction["landing"]:
         raise UndoError(f"member {member} bound branch moved during undo")
@@ -861,7 +870,7 @@ def classify_undo(repo: Path) -> dict[str, object]:
             [f"an in-progress helper journal exists ({names}); resume that transaction first"]
         )
     if git.get("ancestor_of_origin_main"):
-        return _blocked(["HEAD is an ancestor of origin/main; undo would rewrite shipped history"])
+        return _blocked(["HEAD is an ancestor of the origin default branch; undo would rewrite shipped history"])
 
     product = _product_dirty(dirty)
     if product:
@@ -1081,7 +1090,7 @@ def _require_unpublished_reset(repo: Path, expected_branch: str) -> None:
     if git.get("published"):
         raise UndoError("HEAD became published on its recorded remote branch")
     if git.get("ancestor_of_origin_main"):
-        raise UndoError("HEAD became published through origin/main")
+        raise UndoError("HEAD became published through the origin default branch")
 
 
 def _remove_untracked_tree(repo: Path, relative: str) -> None:

package/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,