@opengsd/gsd-path 1.4.0 → 1.6.0

package/skills/path/scripts/loop_run.py

@@ -514,16 +514,28 @@ def run_shell(command: str, timeout: float) -> tuple[Optional[int], str]:
     """Run one spec command; a hung command counts as failed (exit None).
 
     POSIX runs /bin/sh as shell=True did; Windows runs Git for Windows bash, not
-    cmd.exe. A timeout kills the whole process group, so a grandchild cannot
-    keep the output pipes open.
+    cmd.exe. A timeout kills the whole process group when possible; if output
+    pipes stay open, drain them with a short grace timeout and then close them.
     """
     argv = _common.bash_argv(command) if os.name == "nt" else ["/bin/sh", "-c", command]
     process = _common.popen_group(argv, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    stdout = b""
+    stderr = b""
     try:
         stdout, stderr = process.communicate(timeout=timeout)
-    except subprocess.TimeoutExpired:
+    except subprocess.TimeoutExpired as expired:
         _common.kill_tree(process)
-        stdout, stderr = process.communicate()
+        try:
+            stdout, stderr = process.communicate(timeout=5)
+        except subprocess.TimeoutExpired as drained:
+            stdout = drained.stdout or expired.stdout or b""
+            stderr = drained.stderr or expired.stderr or b""
+            if process.stdout:
+                process.stdout.close()
+            if process.stderr:
+                process.stderr.close()
+            process.kill()
+            process.wait(timeout=5)
         output = stdout.decode("utf-8", errors="replace") + stderr.decode("utf-8", errors="replace")
         return None, f"{output}\ntimed out at the admitted wall-clock deadline"
     return process.returncode, (stdout + stderr).decode("utf-8", errors="replace")

package/skills/path/scripts/members.py

@@ -35,6 +35,8 @@ MARKER_SCHEMA = "gsd-path/member/v1"
 MARKER_KEYS = {"schema", "coordinator", "project", "name"}
 NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
 FIELDS = ("Checkout", "Remote", "Integration")
+# Optional: `add` records it one time; a row without it means main.
+DEFAULT_BRANCH_FIELD = "Default branch"
 INTEGRATIONS = ("default", "direct", "pull-request")
 GITHUB_REMOTE_RE = re.compile(
     r"(?:https://github\.com/|git@github\.com:|ssh://git@github\.com/)([^/\s]+)/([^/\s]+)"
@@ -221,9 +223,10 @@ def read_members(coordinator: Path) -> list[dict[str, str]]:
         if not line.strip():
             continue
         key, separator, value = line.partition(":")
-        if not separator or key not in FIELDS or key.lower() in current:
+        field = key.lower().replace(" ", "_")
+        if not separator or key not in (*FIELDS, DEFAULT_BRANCH_FIELD) or field in current:
             raise MembersError(f"MEMBERS.md line {number}: unexpected line {line!r}")
-        current[key.lower()] = value.strip()
+        current[field] = value.strip()
     if not preamble or preamble[0] != "# Members":
         raise MembersError("MEMBERS.md format error: expected # Members")
     rest = preamble[1:]
@@ -247,16 +250,37 @@ def read_members(coordinator: Path) -> list[dict[str, str]]:
             )
         if not Path(member["checkout"]).is_absolute():
             raise MembersError(f"MEMBERS.md member {member['name']} Checkout must be absolute")
+        if not _common.valid_default_branch(default_branch(member)):
+            raise MembersError(
+                f"MEMBERS.md member {member['name']} has invalid Default branch: {member['default_branch']}"
+            )
     return members
 
 
+def default_branch(member: dict[str, str]) -> str:
+    """The default branch a MEMBERS.md row records; a row without the field means main."""
+    return member.get("default_branch", "main")
+
+
+def member_default_branch(coordinator: Path, name: str) -> str:
+    """The default branch MEMBERS.md records for the member `name`."""
+    for member in read_members(coordinator):
+        if member["name"] == name:
+            return default_branch(member)
+    raise MembersError(f"member {name} is not in MEMBERS.md")
+
+
 def check_member(
     coordinator: Path,
     coordinator_name: str,
     checkout: Path,
-    recorded_remote: Optional[str] = None,
-) -> str:
-    """Refuse a checkout that cannot join; return its origin URL."""
+    recorded: Optional[dict[str, str]] = None,
+    refuse_reserved_refs: bool = True,
+) -> tuple[str, str]:
+    """Refuse a checkout that cannot join; return its origin URL and default branch.
+
+    `recorded` is the member's MEMBERS.md row. Without it (`add`), the default
+    branch is the local origin/HEAD, read this one time; an unset ref means main."""
     if checkout.is_symlink() or not checkout.is_dir():
         raise MembersError(f"member checkout is not a real directory: {checkout}")
     checkout = checkout.resolve()
@@ -278,12 +302,21 @@ def check_member(
     remote = _git(checkout, "config", "--get", "remote.origin.url")
     if not GITHUB_REMOTE_RE.fullmatch(remote):
         raise MembersError(f"member requires a GitHub.com origin: {remote}")
-    if recorded_remote is not None and remote != recorded_remote:
-        raise MembersError(f"member origin changed: {recorded_remote} -> {remote}")
-    default = _common.run_git(checkout, "symbolic-ref", "--short", "refs/remotes/origin/HEAD")
-    if default.returncode != 0 or default.stdout.strip() != "origin/main":
-        raise MembersError(f"member remote default must be main: {checkout}")
-    require_origin_main(checkout)
+    if recorded is not None and remote != recorded["remote"]:
+        raise MembersError(f"member origin changed: {recorded['remote']} -> {remote}")
+    live = _common.origin_default_branch(checkout)
+    default = live if recorded is None else default_branch(recorded)
+    if live != default:
+        raise MembersError(
+            f"member remote default must be {default}, got {live}: {checkout}; "
+            "run `git remote set-head origin --auto` when the local origin/HEAD is stale"
+        )
+    if not _common.valid_default_branch(default):
+        raise MembersError(
+            f"member default branch {default!r} cannot be recorded in MEMBERS.md: it is a "
+            "GSD Path reserved name or it has a character that the file cannot hold"
+        )
+    require_origin_branch(checkout, default)
     member_state = checkout / ".project" / "STATE.md"
     if member_state.exists() or member_state.is_symlink():
         if member_state.is_symlink() or not member_state.is_file():
@@ -294,14 +327,15 @@ def check_member(
             raise MembersError(f"member STATE.md is unreadable: {error}") from error
         if state.milestone is not None and (state.phase, state.status) != ("shipped", "done"):
             raise MembersError(f"member has an active milestone: {state.milestone}")
-    prefixes = member_ref_prefixes(coordinator_name) + tuple(
-        "refs/remotes/origin/" + branch.format(coordinator_name) for branch in MEMBER_BRANCH_FORMATS
-    )
-    refs = _git(checkout, "for-each-ref", "--format=%(refname)").splitlines()
-    colliding = [ref for ref in refs if ref.startswith(prefixes)]
-    if colliding:
-        raise MembersError("member refs collide with coordinator names: " + ", ".join(colliding))
-    return remote
+    if refuse_reserved_refs:
+        prefixes = member_ref_prefixes(coordinator_name) + tuple(
+            "refs/remotes/origin/" + branch.format(coordinator_name) for branch in MEMBER_BRANCH_FORMATS
+        )
+        refs = _git(checkout, "for-each-ref", "--format=%(refname)").splitlines()
+        colliding = [ref for ref in refs if ref.startswith(prefixes)]
+        if colliding:
+            raise MembersError("member refs collide with coordinator names: " + ", ".join(colliding))
+    return remote, default
 
 
 MEMBER_CLOSE_SCHEMA = "gsd-path/member-close/v1"
@@ -336,12 +370,14 @@ def write_member_close(common: Path, archive_name: str, rows: list[dict]) -> Non
     _common.atomic_write(path, json.dumps({"schema": MEMBER_CLOSE_SCHEMA, "members": rows}, indent=2) + "\n")
 
 
-def require_origin_main(checkout: Path) -> None:
+def require_origin_branch(checkout: Path, branch: str) -> str:
+    """The commit of the member's fetched default branch `branch`."""
     baseline = _common.run_git(
-        checkout, "rev-parse", "--verify", "--quiet", "refs/remotes/origin/main^{commit}"
+        checkout, "rev-parse", "--verify", "--quiet", f"refs/remotes/origin/{branch}^{{commit}}"
     )
     if baseline.returncode != 0:
-        raise MembersError("member requires refs/remotes/origin/main; run git fetch origin")
+        raise MembersError(f"member requires refs/remotes/origin/{branch}; run git fetch origin")
+    return baseline.stdout.strip()
 
 
 def member_ref_prefixes(project: str) -> tuple[str, ...]:
@@ -403,7 +439,8 @@ def _task_members(coordinator: Path) -> set[str]:
 
 def lock_build_members(coordinator: Path) -> Optional[list[dict[str, str]]]:
     """At build start, lock the members tasks name (MEMBERS.md order) and create
-    each member's bound branch at its origin/main. None when no task names a member."""
+    each member's bound branch at its recorded default branch on origin. None when
+    no task names a member."""
     root, state = _coordinator(coordinator)
     named = _task_members(root)
     lock_path = root / LOCK_PATH
@@ -442,8 +479,8 @@ def lock_build_members(coordinator: Path) -> Optional[list[dict[str, str]]]:
         remote = _git(checkout, "config", "--get", "remote.origin.url")
         if remote != member["remote"]:
             raise MembersError(f"member origin changed: {member['remote']} -> {remote}")
-        require_origin_main(checkout)
-        base = _git(checkout, "rev-parse", "refs/remotes/origin/main^{commit}")
+        default = default_branch(member)
+        base = require_origin_branch(checkout, default)
         existing = _common.run_git(checkout, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}")
         if existing.returncode == 0:
             tip = existing.stdout.strip()
@@ -456,7 +493,7 @@ def lock_build_members(coordinator: Path) -> Optional[list[dict[str, str]]]:
             elif _common.run_git(checkout, "merge-base", "--is-ancestor", tip, base).returncode == 0:
                 base = tip
             else:
-                raise MembersError(f"member {member['name']} branch {branch} has commits not on origin/main")
+                raise MembersError(f"member {member['name']} branch {branch} has commits not on origin/{default}")
         else:
             missing.append((checkout, base))
         entries.append({"name": member["name"], "branch": branch, "base": base})
@@ -473,6 +510,8 @@ def render(members: Sequence[dict[str, str]]) -> str:
         f"Checkout: {member['checkout']}\n"
         f"Remote: {member['remote']}\n"
         f"Integration: {member['integration']}\n"
+        # A row that never had the field keeps none, so old rows are not rewritten.
+        + (f"{DEFAULT_BRANCH_FIELD}: {member['default_branch']}\n" if "default_branch" in member else "")
         for member in members
     ]
     return "\n".join([HEADER, *sections])
@@ -486,7 +525,7 @@ def add_member(repo: Path, name: str, checkout: Path, integration: str) -> list[
         raise MembersError(f"invalid member name: {name!r}")
     members = read_members(root)
     resolved = checkout.resolve()
-    remote = check_member(root, state.project, checkout)
+    remote, default = check_member(root, state.project, checkout)
     common = Path(_git(resolved, "rev-parse", "--path-format=absolute", "--git-common-dir")).resolve()
     identity = _remote_identity(remote)
     for member in members:
@@ -497,7 +536,8 @@ def add_member(repo: Path, name: str, checkout: Path, integration: str) -> list[
             raise MembersError(f"member already recorded: {member['name']}")
     _refuse_foreign_marker(resolved, root, state.project, name)
     members.append(
-        {"name": name, "checkout": str(resolved), "remote": remote, "integration": integration}
+        {"name": name, "checkout": str(resolved), "remote": remote, "integration": integration,
+         "default_branch": default}
     )
     _write_marker(resolved, root, state.project, name)
     _common.atomic_write(root / ".project" / MEMBERS_FILE, render(members))
@@ -558,8 +598,9 @@ def create_member(repo: Path, name: str, checkout: Path, integration: str, githu
         _common.atomic_write(journal, json.dumps(recorded, indent=2, sort_keys=True) + "\n")
     listed = [member for member in read_members(root) if member["name"] == name]
     if listed:
-        if (len(listed) != 1 or listed[0] != {"name": name, "checkout": str(resolved), "remote": url,
-                                            "integration": integration}
+        if (len(listed) != 1 or {**listed[0], "default_branch": default_branch(listed[0])} != {
+                    "name": name, "checkout": str(resolved), "remote": url,
+                    "integration": integration, "default_branch": "main"}
                 or member_role(resolved) != {"coordinator": root, "project": state.project, "name": name}):
             raise MembersError(f"member already recorded with a different checkout or marker: {name}")
         journal.unlink()
@@ -608,6 +649,10 @@ def create_member(repo: Path, name: str, checkout: Path, integration: str, githu
         cloned = _common.run_git(resolved.parent, "clone", "-q", url, str(resolved))
         if cloned.returncode != 0:
             raise MembersError(f"could not clone {url}: {(cloned.stderr or cloned.stdout).strip()}")
+    # ponytail: --create stays main-only, because a new repository uses main;
+    # `add` joins an existing repository with any default branch.
+    if _common.origin_default_branch(resolved) != "main":
+        raise MembersError(f"member remote default must be main: {resolved}")
     recorded["step"] = "join"
     _common.atomic_write(journal, json.dumps(recorded, indent=2, sort_keys=True) + "\n")
     joined = add_member(root, name, resolved, integration)
@@ -620,7 +665,7 @@ def validate_members(repo: Path) -> list[dict[str, str]]:
     members = read_members(root)
     for member in members:
         checkout = Path(member["checkout"])
-        check_member(root, state.project, checkout, member["remote"])
+        check_member(root, state.project, checkout, member, refuse_reserved_refs=False)
         try:
             role = member_role(checkout)
         except MembersError as error:
@@ -639,7 +684,7 @@ def repair_members(repo: Path) -> list[dict[str, str]]:
     members = read_members(root)
     for member in members:
         checkout = Path(member["checkout"])
-        check_member(root, state.project, checkout, member["remote"])
+        check_member(root, state.project, checkout, member, refuse_reserved_refs=False)
         _refuse_foreign_marker(checkout.resolve(), root, state.project, member["name"])
     for member in members:
         checkout = Path(member["checkout"]).resolve()

package/skills/path/scripts/model_policy.py

@@ -202,7 +202,11 @@ def native_record(args):
         identity = {'repo': str(args.repo.resolve()), 'project_dir': args.project_dir,
                     'scope': args.scope, 'assignment': args.assignment, 'role': args.role}
         if data is not None and data.get('identity') != identity:
-            raise PolicyError('record belongs to another assignment or milestone/track/cycle')
+            recorded = data.get('identity')
+            recorded = recorded if isinstance(recorded, dict) else {}
+            differing = ', '.join(f'{field}: {value}, record has {recorded.get(field)}'
+                                  for field, value in identity.items() if recorded.get(field) != value)
+            raise PolicyError(f'record belongs to another assignment or milestone/track/cycle ({differing})')
         if args.action == 'release':
             if data is None or not args.terminal_result:
                 raise PolicyError('release requires an existing record and terminal-result evidence')

package/skills/path/scripts/path_config.py

@@ -13,7 +13,7 @@ sys.dont_write_bytecode = True
 ROLES = ('coder', 'reviewer', 'review_panel', 'skeptic', 'inspect_codebase',
          'inspect_docs', 'docs_audit', 'research', 'decide', 'roadmap', 'plan', 'plan_patch')
 HOSTS = ('codex', 'claude', 'grok', 'opencode', 'copilot', 'qwen', 'antigravity',
-         'cursor', 'zed', 'kiro', 'kimi')
+         'cursor', 'zed', 'kiro', 'kimi', 'muse')
 
 
 def sibling(name):
@@ -73,8 +73,8 @@ def validate_value(key, value):
     if not isinstance(value, str) or not value or value != value.strip():
         raise ValueError(f'{key} requires a nonempty string')
     if key == 'integration':
-        if value not in ('direct', 'pull-request'):
-            raise ValueError('integration must be direct or pull-request')
+        if value not in ('direct', 'pull-request', 'external-landing'):
+            raise ValueError('integration must be direct, pull-request, or external-landing')
     elif key == 'review_panel':
         if any(char.isspace() for char in value):
             raise ValueError('use off, detected, or comma-separated families without spaces')

package/skills/path/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 (
@@ -146,6 +148,29 @@ def ship_commit_body(archive_path: str, reviewed_head: str, members: Sequence[di
     )
 
 
+_TRAILER_LINE = re.compile(r"^[A-Za-z-]+:\s")
+
+
+def ship_body_matches(body: str, expected_body: str) -> bool:
+    """True when body equals the contract or adds only optional git trailers after it."""
+    normalized = body.rstrip("\n")
+    expected = expected_body.rstrip("\n")
+    if normalized == expected:
+        return True
+    prefix = expected + "\n"
+    if not normalized.startswith(prefix):
+        return False
+    remainder = normalized[len(prefix):]
+    if not remainder:
+        return True
+    for line in remainder.splitlines():
+        if not line.strip():
+            return False
+        if not _TRAILER_LINE.match(line):
+            return False
+    return True
+
+
 def integrate_commit_body(
     archive_path: str,
     ship_commit: str,
@@ -270,22 +295,50 @@ def _symbolic_branch(repo: Path) -> str:
     return result.stdout.strip()
 
 
-def _branch_worktrees(repo: Path) -> dict[str, Path]:
-    """Return every checked-out local branch from Git's worktree registry."""
-    output = _run_git(repo, "worktree", "list", "--porcelain", "-z").stdout
+def worktree_list_porcelain(repo: Path) -> tuple[str, bool]:
+    """Return worktree list output and whether it is NUL-separated."""
+    result = _run_git(repo, "worktree", "list", "--porcelain", "-z", check=False)
+    if result.returncode == 0:
+        return result.stdout, True
+    result = _run_git(repo, "worktree", "list", "--porcelain", check=False)
+    if result.returncode != 0:
+        message = (result.stderr or result.stdout).strip() or "could not list worktrees"
+        raise PipelineGitError(message)
+    return result.stdout, False
+
+
+def branch_worktrees_from_porcelain(output: str, *, nul_separated: bool) -> dict[str, Path]:
     worktrees: dict[str, Path] = {}
-    current_path: Optional[Path] = None
-    for field in output.split("\0"):
-        if field.startswith("worktree "):
-            current_path = Path(field.removeprefix("worktree ")).resolve()
-        elif field.startswith("branch ") and current_path is not None:
-            ref = field.removeprefix("branch ")
-            prefix = "refs/heads/"
-            if ref.startswith(prefix):
-                worktrees[ref.removeprefix(prefix)] = current_path
+    if nul_separated:
+        current_path: Optional[Path] = None
+        for field in output.split("\0"):
+            if not field:
+                continue
+            if field.startswith("worktree "):
+                current_path = Path(field.removeprefix("worktree ")).resolve()
+            elif field.startswith("branch ") and current_path is not None:
+                ref = field.removeprefix("branch ")
+                prefix = "refs/heads/"
+                if ref.startswith(prefix):
+                    worktrees[ref.removeprefix(prefix)] = current_path
+        return worktrees
+    for block in output.strip().split("\n\n"):
+        fields = block.splitlines()
+        if not fields or not fields[0].startswith("worktree "):
+            continue
+        current_path = Path(fields[0].removeprefix("worktree ")).resolve()
+        for line in fields[1:]:
+            if line.startswith("branch refs/heads/"):
+                worktrees[line.removeprefix("branch refs/heads/")] = current_path
     return worktrees
 
 
+def _branch_worktrees(repo: Path) -> dict[str, Path]:
+    """Return every checked-out local branch from Git's worktree registry."""
+    output, nul_separated = worktree_list_porcelain(repo)
+    return branch_worktrees_from_porcelain(output, nul_separated=nul_separated)
+
+
 def _remote_ref_sha(repo: Path, ref: str) -> Optional[str]:
     if not _origin_remote_exists(repo):
         raise PipelineGitError("origin remote is not configured")
@@ -312,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 {}
@@ -322,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
 
@@ -353,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,
@@ -364,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")
@@ -376,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",
@@ -405,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",
@@ -422,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
 
@@ -482,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
@@ -528,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,
@@ -549,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"
@@ -691,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,
@@ -712,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(
@@ -770,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,
@@ -778,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(