@opengsd/gsd-path 1.3.1 → 1.5.0

package/skills/gsd-path-roadmap/scripts/integration.py

@@ -9,26 +9,12 @@ sys.dont_write_bytecode = True
 
 import json
 import re
+import contextlib
 from pathlib import Path, PurePosixPath
 from typing import Optional
 
-try:
-    from pipeline_git import (
-        bound_branch_name,
-        default_branch_name,
-        integrate_commit_body,
-        integrate_subject,
-        is_bound_branch,
-        milestone_id,
-        milestone_number,
-        ship_subject,
-    )
-    from pipeline_state import PipelineState
-    from isolation import publication_base
-    import _common
-    import worktree_paths
-except ImportError:  # pragma: no cover - package import used by tests
-    from scripts.pipeline_git import (
+if __package__:
+    from .pipeline_git import (
         bound_branch_name,
         default_branch_name,
         integrate_commit_body,
@@ -38,10 +24,41 @@ except ImportError:  # pragma: no cover - package import used by tests
         milestone_number,
         ship_subject,
     )
-    from scripts.pipeline_state import PipelineState
-    from scripts.isolation import publication_base
-    from scripts import _common
-    from scripts import worktree_paths
+    from .pipeline_state import PipelineState
+    from .isolation import publication_base
+    from . import _common
+    from . import worktree_paths
+else:
+    try:
+        from pipeline_git import (
+            bound_branch_name,
+            default_branch_name,
+            integrate_commit_body,
+            integrate_subject,
+            is_bound_branch,
+            milestone_id,
+            milestone_number,
+            ship_subject,
+        )
+        from pipeline_state import PipelineState
+        from isolation import publication_base
+        import _common
+        import worktree_paths
+    except ImportError:  # pragma: no cover - package import used by tests
+        from scripts.pipeline_git import (
+            bound_branch_name,
+            default_branch_name,
+            integrate_commit_body,
+            integrate_subject,
+            is_bound_branch,
+            milestone_id,
+            milestone_number,
+            ship_subject,
+        )
+        from scripts.pipeline_state import PipelineState
+        from scripts.isolation import publication_base
+        from scripts import _common
+        from scripts import worktree_paths
 
 
 if __package__:
@@ -541,8 +558,8 @@ def ensure_integration_tag(
 
 def github_repository(project: Path) -> str:
     remote = archive_milestone.require_git_success(
-        run_git(project, "remote", "get-url", "origin"),
-        "resolve origin URL",
+        run_git(project, "config", "--get", "remote.origin.url"),
+        "read configured origin URL",
     )
     patterns = (
         r"https://github\.com/([^/]+/[^/]+?)(?:\.git)?$",
@@ -701,8 +718,9 @@ def update_pull_request_body(
     archive_path: str,
     ship_commit: str,
     branch: str,
+    expected_body: Optional[str] = None,
 ) -> dict:
-    expected = pull_request_body(archive_path, ship_commit, branch)
+    expected = expected_body if expected_body is not None else pull_request_body(archive_path, ship_commit, branch)
     current = pull.get("body")
     if isinstance(current, str) and current.rstrip().endswith(PR_CREDIT_LINE):
         return pull
@@ -780,6 +798,36 @@ def pull_request_tag_metadata(project: Path, tag_ref: str) -> dict[str, str]:
     return fields
 
 
+def external_landing_tag_message(
+    archive_name: str, ship_commit: str, landing: str
+) -> str:
+    return (
+        f"milestone {archive_name}\n\n"
+        "Mode: external-landing\n"
+        f"Ship: {ship_commit}\n"
+        f"Landing: {landing}"
+    )
+
+
+def external_landing_tag_metadata(project: Path, tag_ref: str) -> dict[str, str]:
+    message = archive_milestone.require_git_success(
+        run_git(project, "for-each-ref", "--format=%(contents)", tag_ref),
+        "inspect external-landing milestone tag",
+    )
+    fields: dict[str, str] = {}
+    for line in message.splitlines():
+        match = re.fullmatch(r"(Mode|Ship|Landing): (.+)", line)
+        if match:
+            if match.group(1) in fields:
+                raise ArchiveError("external-landing milestone tag repeats metadata")
+            fields[match.group(1)] = match.group(2)
+    if set(fields) != {"Mode", "Ship", "Landing"}:
+        raise ArchiveError("external-landing milestone tag is missing metadata")
+    if fields["Mode"] != "external-landing":
+        raise ArchiveError("external-landing milestone tag has the wrong mode")
+    return fields
+
+
 def require_pull_request_merge(
     project: Path,
     merge_commit: str,
@@ -1004,6 +1052,78 @@ def integrate_pull_request(
     return validate_integrated(project, archive_milestone.milestone_slug(state))
 
 
+def integrate_external_landing(
+    project: Path,
+    state: PipelineState,
+    archive_path: str,
+    archive_name: str,
+    ship_commit: str,
+    remote_default: str,
+    default_name: str,
+    bound_branch: str,
+) -> dict:
+    if state.branch is None:
+        raise ArchiveError("external-landing integration requires a bound branch")
+    publishable_bound_branch(project, bound_branch, ship_commit)
+    contains_ship = run_git(
+        project, "merge-base", "--is-ancestor", ship_commit, remote_default
+    )
+    if contains_ship.returncode == 1:
+        publish_bound_branch(project, bound_branch, ship_commit)
+        return {
+            "status": "awaiting-merge",
+            "mode": "external-landing",
+            "archive": archive_path,
+            "commit": ship_commit,
+        }
+    if contains_ship.returncode != 0:
+        archive_milestone.require_git_success(
+            contains_ship, "inspect ship ancestry on the remote default"
+        )
+        raise AssertionError("unreachable")
+
+    merge_commit = find_integrate_commit(
+        project, remote_default, archive_name, ship_commit
+    )
+    require_generated_integration_commit(
+        project,
+        merge_commit,
+        archive_path,
+        archive_name,
+        ship_commit,
+        default_name,
+        bound_branch,
+    )
+    tag_name = f"milestone/{archive_name}"
+    message = external_landing_tag_message(archive_name, ship_commit, merge_commit)
+    tag_object, tag_published = ensure_integration_tag(
+        project,
+        tag_name,
+        merge_commit,
+        message,
+    )
+    if not tag_published:
+        archive_milestone.require_git_success(
+            run_git(
+                project,
+                "push",
+                "origin",
+                f"refs/tags/{tag_name}:refs/tags/{tag_name}",
+            ),
+            "push milestone tag",
+        )
+        archive_milestone.require_git_success(
+            run_git(
+                project,
+                "update-ref",
+                f"refs/remotes/origin/tags/{tag_name}",
+                tag_object,
+            ),
+            "refresh local milestone-tag ref",
+        )
+    return validate_integrated(project, archive_milestone.milestone_slug(state))
+
+
 def integrate(repo: Path, slug: str) -> dict:
     project = repo.resolve()
     active_root = archive_milestone.require_project_layout(project)
@@ -1053,6 +1173,17 @@ def integrate(repo: Path, slug: str) -> dict:
             archive_name,
             ship_commit,
         )
+    if state.integration == "external-landing":
+        return integrate_external_landing(
+            project,
+            state,
+            archive_path,
+            archive_name,
+            ship_commit,
+            remote_default,
+            default_name,
+            bound_branch,
+        )
     publishable_bound_branch(project, bound_branch, ship_commit)
     integration_branch, worktree = integration_names(project, archive_name, pin=True)
     interrupted_worktree = registered_worktree(project, integration_branch)
@@ -1328,6 +1459,32 @@ def validate_integrated(
                 merge_commit,
             ),
         )
+    elif state.integration == "external-landing":
+        merge_commit = find_integrate_commit(
+            project, remote_default, archive_name, ship_commit
+        )
+        archive_milestone.require_canonical_commit_body(
+            project,
+            merge_commit,
+            integrate_subject(archive_name, default_name),
+            integrate_commit_body(configured, ship_commit, default_name, bound_branch),
+            "integration",
+        )
+        require_pull_request_merge(project, merge_commit, ship_commit, remote_default)
+        if run_git(project, "rev-parse", "--verify", "--quiet", tag_ref).returncode != 0:
+            raise ArchiveError(f"missing milestone tag: {tag_name}")
+        metadata = external_landing_tag_metadata(project, tag_ref)
+        if metadata["Ship"] != ship_commit:
+            raise ArchiveError("external-landing milestone tag names the wrong ship commit")
+        if metadata["Landing"] != merge_commit:
+            raise ArchiveError("external-landing milestone tag names the wrong landing")
+        require_annotated_tag(
+            project,
+            tag_ref,
+            merge_commit,
+            f"milestone tag {tag_name}",
+            external_landing_tag_message(archive_name, ship_commit, merge_commit),
+        )
     else:
         merge_commit = find_integrate_commit(
             project, remote_default, archive_name, ship_commit
@@ -1364,7 +1521,8 @@ def validate_integrated(
         ship_commit,
         tag_name,
         merge_commit,
-        allow_missing_bound=state.integration == "pull-request" or (historical and has_origin),
+        allow_missing_bound=state.integration in ("pull-request", "external-landing")
+        or (historical and has_origin),
         retired=historical,
     )
 
@@ -1394,6 +1552,12 @@ def validate_integrated(
                 raise ArchiveError(f"published {ref} differs from local integration evidence")
     if pull_request is not None:
         result["pull_request"] = pull_request
+    for row in shipped.get("members", []):
+        proven = validate_member_integrated(project, row["name"], configured, row["reviewed_head"], refresh=refresh)
+        if (proven["merge"], proven["tag"]) != (row["merge"], row["tag"]):
+            raise ArchiveError(f"member {row['name']} integration differs from the ship commit")
+    if "members" in shipped:
+        result["members"] = shipped["members"]
     return result
 
 
@@ -1457,3 +1621,394 @@ def require_published_integration(
         raise ArchiveError(
             f"published milestone tag {tag_name} does not point at the integration merge"
         )
+
+
+def _member_names(coordinator: Path, member: str, archive_path: str) -> tuple[Path, str, str, str, str]:
+    """A member's checkout, coordinator project, bound branch, merge subject, and tag."""
+    try:
+        import isolation
+    except ImportError:  # pragma: no cover - package import used by tests
+        from scripts import isolation
+    try:
+        checkout, project = isolation.member_checkout(coordinator.resolve(), member)
+    except isolation.IsolationError as error:
+        raise ArchiveError(str(error)) from error
+    archive_name = PurePosixPath(archive_path).name
+    identifier = milestone_id(milestone_number(archive_name))
+    bound = f"gsd-path/{project}-{identifier}"
+    subject = f"integrate: {project} {identifier} — merge {bound} into main"
+    return checkout, project, bound, subject, f"milestone/{project}-{archive_name}"
+
+
+def _member_merge_body(archive_path: str, member: str, reviewed_head: str) -> str:
+    return f"Archive: {archive_path}\nMember: {member}\nReviewed-HEAD: {reviewed_head}"
+
+
+def member_pull_request_tag_message(tag_name: str, pull_request: str, reviewed_head: str, landing: str) -> str:
+    return (f"milestone {tag_name.removeprefix('milestone/')}\n\nMode: pull-request\n"
+            f"Pull-Request: {pull_request}\nReviewed-HEAD: {reviewed_head}\nLanding: {landing}")
+
+
+def member_pull_request_tag_metadata(contents: str) -> dict[str, str]:
+    fields: dict[str, str] = {}
+    for line in contents.splitlines():
+        match = re.fullmatch(r"(Mode|Pull-Request|Reviewed-HEAD|Landing): (.+)", line)
+        if match:
+            if match.group(1) in fields:
+                raise ArchiveError("pull-request member tag repeats metadata")
+            fields[match.group(1)] = match.group(2)
+    if set(fields) != {"Mode", "Pull-Request", "Reviewed-HEAD", "Landing"}:
+        raise ArchiveError("pull-request member tag is missing metadata")
+    if fields["Mode"] != "pull-request":
+        raise ArchiveError("pull-request member tag has the wrong mode")
+    return fields
+
+
+def _find_member_merge(checkout: Path, subject: str, body: str, reviewed_head: str) -> Optional[str]:
+    """The member merge in origin/main's first-parent history, if published."""
+    log = archive_milestone.require_git_success(
+        run_git(checkout, "log", "--first-parent", "--format=%H%x00%s", "origin/main"),
+        "inspect member origin/main first-parent history",
+    )
+    matches = [commit for commit, _, text in (line.partition("\x00") for line in log.splitlines())
+               if text == subject]
+    if len(matches) > 1:
+        raise ArchiveError(f"multiple member merges named {subject!r} on origin/main")
+    if not matches:
+        return None
+    _require_member_merge(checkout, matches[0], subject, body, reviewed_head)
+    return matches[0]
+
+
+def _require_member_merge(checkout: Path, commit: str, subject: str, body: str, reviewed_head: str) -> str:
+    """Check a canonical member merge; return its first parent."""
+    archive_milestone.require_canonical_commit_body(checkout, commit, subject, body, "member integration")
+    parents = archive_milestone.require_git_success(
+        run_git(checkout, "rev-list", "--parents", "-n", "1", commit), "inspect member merge parents"
+    ).split()
+    if len(parents) != 3 or parents[2] != reviewed_head:
+        raise ArchiveError("member merge second parent is not the member reviewed HEAD")
+    return parents[1]
+
+
+def _create_member_merge(checkout: Path, project: str, archive_path: str, subject: str, body: str,
+                         reviewed_head: str, origin_main: str) -> str:
+    identifier = milestone_id(milestone_number(PurePosixPath(archive_path).name))
+    branch = f"gsd-path-integrate/{project}-{identifier}"
+    try:
+        worktree = worktree_paths.worktree_path(checkout, "integrate", f"{project}-{identifier}", pin=True)
+    except (ValueError, OSError) as error:
+        raise ArchiveError(str(error)) from error
+    interrupted = registered_worktree(checkout, branch)
+    if interrupted is not None and optional_ref(interrupted, "MERGE_HEAD") is not None:
+        archive_milestone.require_git_success(run_git(interrupted, "merge", "--abort"),
+                                              "abort interrupted member merge")
+    remove_registered_worktree(checkout, branch, worktree)
+    tip = optional_ref(checkout, f"refs/heads/{branch}")
+    if tip is not None:
+        base_tip = run_git(checkout, "merge-base", "--is-ancestor", tip, origin_main)
+        if base_tip.returncode != 0:
+            if base_tip.returncode != 1:
+                archive_milestone.require_git_success(base_tip, "inspect interrupted member integration base")
+            if _require_member_merge(checkout, tip, subject, body, reviewed_head) == origin_main:
+                return tip
+        delete_integration_branch(checkout, branch, tip)
+    archive_milestone.require_git_success(
+        run_git(checkout, "worktree", "add", "--quiet", "-b", branch, str(worktree), origin_main),
+        "create member integration worktree",
+    )
+    merged = run_git(worktree, "merge", "--no-ff", "-m", subject, "-m", body, reviewed_head)
+    if merged.returncode != 0:
+        conflicts = run_git(worktree, "diff", "--name-only", "--diff-filter=U").stdout.split()
+        if optional_ref(worktree, "MERGE_HEAD") is not None:
+            run_git(worktree, "merge", "--abort")
+        remove_registered_worktree(checkout, branch, worktree)
+        delete_integration_branch(checkout, branch, origin_main)
+        raise ArchiveError("member integration merge failed; Git aborted it without resolving files: "
+                           + (", ".join(conflicts) or (merged.stderr or merged.stdout).strip()))
+    merge = archive_milestone.require_git_success(run_git(worktree, "rev-parse", "HEAD"), "resolve member merge")
+    if _require_member_merge(worktree, merge, subject, body, reviewed_head) != origin_main:
+        raise ArchiveError("member merge first parent is not origin/main")
+    remove_registered_worktree(checkout, branch, worktree)
+    return merge
+
+
+def _push_member_ref(checkout: Path, project: str, source: str, ref: str, sha: str, lease: Optional[str]) -> None:
+    """Authorize `ref` at `sha` for the member pre-push hook, then publish it."""
+    try:
+        import members
+    except ImportError:  # pragma: no cover - package import used by tests
+        from scripts import members
+    members.authorize_push(checkout, project, ref, sha)
+    arguments = ["push"] + ([f"--force-with-lease={ref}:{lease}"] if lease is not None else [])
+    archive_milestone.require_git_success(
+        run_git(checkout, *arguments, "origin", f"{source}:{ref}"), f"publish member {ref}"
+    )
+
+
+def _publish_member_bound(checkout: Path, project: str, member: str, bound: str, reviewed_head: str) -> None:
+    bound_ref = f"refs/heads/{bound}"
+    remote_bound = live_remote_ref(checkout, bound_ref)
+    if remote_bound is None:
+        _push_member_ref(checkout, project, reviewed_head, bound_ref, reviewed_head, "")
+    elif remote_bound != reviewed_head:
+        raise ArchiveError(f"member {member} origin/{bound} moved: {remote_bound}")
+
+
+def _require_member_close(checkout: Path, member: str, bound: str, reviewed_head: str) -> None:
+    if optional_ref(checkout, f"refs/heads/{bound}") != reviewed_head:
+        raise ArchiveError(f"member {member} {bound} is not at its reviewed HEAD {reviewed_head}")
+    if default_branch_name(refresh_origin(checkout)["remote_default"]) != "main":
+        raise ArchiveError(f"member {member} remote default must be main")
+
+
+def integrate_member(coordinator: Path, member: str, archive_path: str, reviewed_head: str) -> dict:
+    """Direct-mode member close: publish the bound branch, merge it into main, then tag."""
+    checkout, project, bound, subject, tag_name = _member_names(coordinator, member, archive_path)
+    body = _member_merge_body(archive_path, member, reviewed_head)
+    _require_member_close(checkout, member, bound, reviewed_head)
+    merge = _find_member_merge(checkout, subject, body, reviewed_head)
+    if merge is None:
+        origin_main = archive_milestone.require_git_success(
+            run_git(checkout, "rev-parse", "origin/main"), "resolve member origin/main")
+        ancestry = run_git(checkout, "merge-base", "--is-ancestor", reviewed_head, origin_main)
+        if ancestry.returncode == 0:
+            raise ArchiveError("member reviewed HEAD reached origin/main outside Path; user-approved recovery required")
+        if ancestry.returncode != 1:
+            archive_milestone.require_git_success(ancestry, "inspect member reviewed HEAD ancestry")
+        merge = _create_member_merge(checkout, project, archive_path, subject, body, reviewed_head, origin_main)
+    # Publish in order: bound branch, main, tag; a rerun publishes only what is missing.
+    _publish_member_bound(checkout, project, member, bound, reviewed_head)
+    if run_git(checkout, "merge-base", "--is-ancestor", merge, "origin/main").returncode != 0:
+        _push_member_ref(checkout, project, merge, "refs/heads/main", merge, None)
+        archive_milestone.require_git_success(
+            run_git(checkout, "update-ref", "refs/remotes/origin/main", merge), "refresh member origin/main")
+    tag_object, tag_published = ensure_integration_tag(checkout, tag_name, merge)
+    if not tag_published:
+        _push_member_ref(checkout, project, f"refs/tags/{tag_name}", f"refs/tags/{tag_name}", tag_object, None)
+        archive_milestone.require_git_success(
+            run_git(checkout, "update-ref", f"refs/remotes/origin/tags/{tag_name}", tag_object),
+            "refresh member milestone-tag ref")
+    identifier = milestone_id(milestone_number(PurePosixPath(archive_path).name))
+    delete_integration_branch(checkout, f"gsd-path-integrate/{project}-{identifier}", merge)
+    return validate_member_integrated(coordinator, member, archive_path, reviewed_head)
+
+
+def integrate_member_pull_request(coordinator: Path, member: str, archive_path: str, reviewed_head: str) -> dict:
+    """Pull-request member close: open one PR for the bound branch; after a human merge, tag it."""
+    checkout, project, bound, subject, tag_name = _member_names(coordinator, member, archive_path)
+    body = _member_merge_body(archive_path, member, reviewed_head)
+    _require_member_close(checkout, member, bound, reviewed_head)
+    require_github_authentication()
+    repository = github_repository(checkout)
+    pull = find_pull_request(repository, bound, reviewed_head)
+    if pull is None or pull["merged_at"] is None:
+        if pull is not None and pull["state"] != "open":
+            raise ArchiveError(f"member {member} pull request was closed without merging")
+        _publish_member_bound(checkout, project, member, bound, reviewed_head)
+        if pull is None:
+            pull = require_pull_request_shape(github_api_json(
+                f"repos/{repository}/pulls", "--method", "POST", "-f", f"title={subject}",
+                "-f", f"head={bound}", "-f", "base=main", "-f", f"body={body}\n\n---\n{PR_CREDIT_LINE}"))
+            require_pull_request_identity(repository, pull, bound, reviewed_head)
+        else:
+            pull = update_pull_request_body(
+                repository, pull, archive_path, reviewed_head, bound,
+                f"{body}\n\n---\n{PR_CREDIT_LINE}",
+            )
+        require_pull_request_merge_provenance(repository, pull["number"])
+        return {"status": "awaiting-merge", "mode": "pull-request", "member": member,
+                "pull_request": pull["html_url"]}
+    merge = pull["merge_commit_sha"]
+    if pull["state"] != "closed" or not isinstance(merge, str):
+        raise ArchiveError(f"member {member} pull request merge metadata is invalid")
+    require_pull_request_merge_provenance(repository, pull["number"], merge)
+    refresh_origin(checkout)
+    require_pull_request_merge(checkout, merge, reviewed_head, "origin/main")
+    pull = update_pull_request_body(
+        repository, pull, archive_path, reviewed_head, bound,
+        f"{body}\n\n---\n{PR_CREDIT_LINE}",
+    )
+    message = member_pull_request_tag_message(tag_name, pull["html_url"], reviewed_head, merge)
+    tag_object, tag_published = ensure_integration_tag(checkout, tag_name, merge, message)
+    if not tag_published:
+        _push_member_ref(checkout, project, f"refs/tags/{tag_name}", f"refs/tags/{tag_name}", tag_object, None)
+        archive_milestone.require_git_success(
+            run_git(checkout, "update-ref", f"refs/remotes/origin/tags/{tag_name}", tag_object),
+            "refresh member milestone-tag ref")
+    return validate_member_integrated(coordinator, member, archive_path, reviewed_head)
+
+
+def validate_member_integrated(
+    coordinator: Path, member: str, archive_path: str, reviewed_head: str, *, refresh: bool = True
+) -> dict:
+    """Prove the member merge is on origin/main and its published tag points at it."""
+    checkout, _, bound, subject, tag_name = _member_names(coordinator, member, archive_path)
+    tracking = f"refs/remotes/origin/tags/{tag_name}"
+    if refresh:
+        refresh_origin(checkout)
+        published = live_remote_ref(checkout, f"refs/tags/{tag_name}")
+    else:
+        published = optional_ref(checkout, tracking)
+    contents = ""
+    if refresh and published is not None:
+        archive_milestone.require_git_success(
+            run_git(checkout, "update-ref", tracking, published), "refresh member milestone-tag ref")
+    if published is not None:
+        contents = run_git(checkout, "for-each-ref", "--format=%(contents)", tracking).stdout
+    if "Mode: pull-request" in contents.splitlines():
+        metadata = member_pull_request_tag_metadata(contents)
+        if metadata["Reviewed-HEAD"] != reviewed_head:
+            raise ArchiveError(f"member {member} tag {tag_name} names a different reviewed HEAD")
+        merge = archive_milestone.require_git_success(
+            run_git(checkout, "rev-parse", f"{tracking}^{{commit}}"), "resolve member tag target")
+        if metadata["Landing"] != merge:
+            raise ArchiveError(f"member {member} tag {tag_name} names a different landing")
+        require_github_authentication()
+        repository = github_repository(checkout)
+        pull = find_pull_request(repository, bound, reviewed_head)
+        if pull is None:
+            raise ArchiveError(f"member {member} GitHub pull request is missing")
+        if pull["html_url"] != metadata["Pull-Request"]:
+            raise ArchiveError(f"member {member} tag {tag_name} names the wrong pull request")
+        if (pull["state"] != "closed" or pull["merged_at"] is None
+                or pull["merge_commit_sha"] != merge):
+            raise ArchiveError(f"member {member} GitHub pull request is not merged at the tagged landing")
+        require_pull_request_merge_provenance(repository, pull["number"], merge)
+        require_pull_request_merge(checkout, merge, reviewed_head, "origin/main")
+        require_annotated_tag(
+            checkout, tracking, merge, f"member tag {tag_name}",
+            member_pull_request_tag_message(tag_name, pull["html_url"], reviewed_head, merge),
+        )
+    else:
+        merge = _find_member_merge(checkout, subject, _member_merge_body(archive_path, member, reviewed_head),
+                                   reviewed_head)
+        if merge is None:
+            raise ArchiveError(f"member {member} has no {subject!r} merge on origin/main")
+        if published is None:
+            raise ArchiveError(f"member {member} tag {tag_name} is not published")
+        require_annotated_tag(checkout, tracking, merge, f"member tag {tag_name}")
+    return {"member": member, "merge": merge, "tag": tag_name, "tag_object": published}
+
+
+def retire_member(coordinator: Path, member: str, archive_path: str, reviewed_head: str,
+                  merge: str, tag: str) -> dict:
+    """After integration, delete a member's bound branch everywhere and clear its authorizations."""
+    try:
+        import members
+    except ImportError:  # pragma: no cover - package import used by tests
+        from scripts import members
+    checkout, project, bound, _, tag_name = _member_names(coordinator, member, archive_path)
+    proven = validate_member_integrated(coordinator, member, archive_path, reviewed_head)
+    if (proven["merge"], proven["tag"]) != (merge, tag):
+        raise ArchiveError(f"member {member} integration differs from the ship commit")
+    bound_ref = f"refs/heads/{bound}"
+    local = optional_ref(checkout, bound_ref)
+    if local is not None and local != reviewed_head:
+        raise ArchiveError(f"member {member} {bound} moved: {local}")
+    holder = registered_worktree(checkout, bound)
+    if holder is not None:
+        try:
+            expected = worktree_paths.worktree_path(
+                checkout, "bound", bound.removeprefix("gsd-path/")
+            ).resolve()
+        except (ValueError, OSError) as error:
+            raise ArchiveError(str(error)) from error
+        if holder != expected:
+            raise ArchiveError(f"member {member} bound checkout is outside Path's workspace: {holder}")
+        status = archive_milestone.require_git_success(
+            run_git(holder, "status", "--porcelain", "--untracked-files=all"),
+            "inspect member bound checkout",
+        )
+        if status:
+            raise ArchiveError(f"member {member} bound checkout is not clean: {holder}")
+    remote = live_remote_ref(checkout, bound_ref)
+    if remote is not None:
+        if remote != reviewed_head:
+            raise ArchiveError(f"member {member} origin/{bound} moved: {remote}")
+        members.authorize_delete(checkout, project, bound_ref, reviewed_head)
+        archive_milestone.require_git_success(
+            run_git(checkout, "push", f"--force-with-lease={bound_ref}:{reviewed_head}", "origin", "--delete", bound),
+            f"delete member origin/{bound}")
+    if holder is not None:
+        archive_milestone.require_git_success(run_git(checkout, "worktree", "remove", str(holder)),
+                                              "remove member bound checkout")
+    if local is not None:
+        archive_milestone.require_git_success(run_git(checkout, "update-ref", "-d", bound_ref, reviewed_head),
+                                              "delete member bound branch")
+    run_git(checkout, "update-ref", "-d", f"refs/remotes/origin/{bound}")
+    for kind, ref in (("push", bound_ref), ("push", "refs/heads/main"), ("push", f"refs/tags/{tag_name}"),
+                      ("delete", bound_ref)):
+        members.clear_authorization(checkout, project, kind, ref)
+    # The last sidecar retires here at milestone end; isolation's retires also
+    # release the pin whenever the workspace is idle, so a new root can apply.
+    with contextlib.suppress(ValueError, OSError):
+        worktree_paths.release_workspace(checkout)
+    return {"member": member, "retired": bound}
+
+
+def close_members(repo: Path) -> dict:
+    """Close each locked member in lock order before the coordinator ship commit; resumable."""
+    try:
+        import check_handoffs
+        import members
+        from pipeline_git import ship_commit_body
+    except ImportError:  # pragma: no cover - package import used by tests
+        from scripts import check_handoffs, members
+        from scripts.pipeline_git import ship_commit_body
+    project = repo.resolve()
+    state, _, _ = archive_milestone.strict_state(project)
+    if (state.phase, state.status) != ("ship", "active") or state.archive is None:
+        raise ArchiveError("close-members requires ship/active with a prepared archive")
+    archive = project / state.archive
+    final_text = (archive / "review" / "FINAL.md").read_text(encoding="utf-8")
+    reviewed = check_handoffs._reviewed_head(final_text, "FINAL.md")
+    lock = archive / "build" / "members.json"
+    locked = json.loads(lock.read_text(encoding="utf-8"))["members"] if lock.is_file() else []
+    try:
+        heads = check_handoffs.member_reviewed_heads(final_text, "FINAL.md")
+    except check_handoffs.HandoffError as error:
+        raise ArchiveError(str(error)) from error
+    if sorted(heads) != sorted(entry["name"] for entry in locked):
+        raise ArchiveError("FINAL.md Member reviewed HEAD lines must name each locked member")
+    common = Path(archive_milestone.require_git_success(
+        run_git(project, "rev-parse", "--path-format=absolute", "--git-common-dir"), "resolve Git common dir"))
+    archive_name = PurePosixPath(state.archive).name
+    try:
+        modes = {item["name"]: item["integration"] for item in members.read_members(project)} if locked else {}
+        rows = {row["name"]: row for row in members.read_member_close(common, archive_name)}
+    except members.MembersError as error:
+        raise ArchiveError(str(error)) from error
+    def save() -> None:
+        members.write_member_close(common, archive_name, [rows[item["name"]] for item in locked if item["name"] in rows])
+
+    closed = []
+    for entry in locked:
+        name = entry["name"]
+        mode = modes.get(name, "default")
+        mode = state.integration if mode == "default" else mode
+        row = rows.get(name) or {"name": name, "mode": mode, "reviewed_head": heads[name],
+                                 "status": "pending", "merge": None, "tag": None}
+        if row["reviewed_head"] != heads[name] or row["mode"] != mode:
+            raise ArchiveError(f"member-close journal for {name} differs from FINAL.md or MEMBERS.md")
+        if row["status"] == "integrated":
+            result = validate_member_integrated(project, name, state.archive, heads[name])
+            if (result["merge"], result["tag"]) != (row["merge"], row["tag"]):
+                raise ArchiveError(f"member {name} integration differs from its member-close journal")
+            closed.append(row)
+            continue
+        # Journal pending before the member moves; a later member waits for this one.
+        rows[name] = row
+        save()
+        if mode == "direct":
+            result = integrate_member(project, name, state.archive, heads[name])
+        else:
+            result = integrate_member_pull_request(project, name, state.archive, heads[name])
+        if result.get("status") == "awaiting-merge":
+            row["pull_request"] = result["pull_request"]
+            save()
+            return {"status": "awaiting-merge", "member": name, "pull_request": result["pull_request"]}
+        row.update(status="integrated", merge=result["merge"], tag=result["tag"])
+        save()
+        closed.append(row)
+    return {"status": "integrated", "members": closed, "body": ship_commit_body(state.archive, reviewed, closed)}