@opengsd/gsd-path 1.3.1 → 1.4.0

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

@@ -14,12 +14,16 @@ from datetime import date
 from pathlib import Path, PurePosixPath
 from typing import Optional, Sequence
 
-try:
-    from pipeline_state import PipelineState
-    import _common
-except ImportError:  # pragma: no cover - package import used by tests
-    from scripts.pipeline_state import PipelineState
-    from scripts import _common
+if __package__:
+    from .pipeline_state import PipelineState
+    from . import _common
+else:
+    try:
+        from pipeline_state import PipelineState
+        import _common
+    except ImportError:  # pragma: no cover - package import used by tests
+        from scripts.pipeline_state import PipelineState
+        from scripts import _common
 
 
 atomic_replace = _common.atomic_replace
@@ -105,7 +109,7 @@ def validate_discussion_directory(
 ) -> None:
     if directory.is_symlink() or not directory.is_dir():
         raise ArchiveError("discussion archive must be a real directory")
-    entries = sorted(path.name for path in directory.iterdir())
+    entries = sorted(path.name for path in directory.iterdir() if not _common.is_ignored_junk(path))
     if entries != sorted(DISCUSSION_FILES):
         raise ArchiveError("discussion archive must contain exactly DIALOGUE.md and ANSWERS.md")
     dialogue, answers = (directory / name for name in DISCUSSION_FILES)
@@ -490,10 +494,13 @@ def archived_intent_criteria(archive: Path) -> dict[int, str]:
     if not archive_milestone.is_real_file(intent):
         raise ArchiveError("archived intent must be a real INTENT.md file")
     text = HTML_COMMENT_PATTERN.sub("", intent.read_text(encoding="utf-8"))
-    try:
-        import check_handoffs
-    except ImportError:
-        from scripts import check_handoffs
+    if __package__:
+        from . import check_handoffs
+    else:
+        try:
+            import check_handoffs
+        except ImportError:
+            from scripts import check_handoffs
     try:
         criteria = check_handoffs._success_criteria(text)
     except check_handoffs.HandoffError as error:
@@ -502,10 +509,13 @@ def archived_intent_criteria(archive: Path) -> dict[int, str]:
 
 
 def parse_final_review(archive: Path) -> tuple:
-    try:
-        import check_handoffs
-    except ImportError:  # pragma: no cover - package import used by tests
-        from scripts import check_handoffs
+    if __package__:
+        from . import check_handoffs
+    else:
+        try:
+            import check_handoffs
+        except ImportError:  # pragma: no cover - package import used by tests
+            from scripts import check_handoffs
 
     final = archive / "review" / "FINAL.md"
     if not archive_milestone.is_real_file(final):
@@ -597,8 +607,29 @@ def parse_final_review(archive: Path) -> tuple:
     return reviewed_head.lower(), criteria
 
 
+def _member_heads(text: str, source: str) -> dict:
+    if __package__:
+        from . import check_handoffs
+    else:
+        try:
+            import check_handoffs
+        except ImportError:  # pragma: no cover - package import used by tests
+            from scripts import check_handoffs
+    try:
+        return check_handoffs.member_reviewed_heads(text, source)
+    except check_handoffs.HandoffError as error:
+        raise ArchiveError(str(error)) from error
+
+
 def validate_gap_reviews(archive: Path, reviewed_head: str) -> None:
     review = archive / "review"
+    member_heads = _member_heads((review / "FINAL.md").read_text(encoding="utf-8"), "FINAL.md")
+    lock = archive / "build" / "members.json"
+    locked = [item["name"] for item in json.loads(lock.read_text(encoding="utf-8"))["members"]] if lock.is_file() else []
+    if sorted(member_heads) != sorted(locked):
+        raise ArchiveError(
+            "FINAL.md Member reviewed HEAD lines must name each locked member: " + (", ".join(locked) or "none")
+        )
     candidates = sorted(path for path in review.iterdir() if path.name.startswith("final-gap-"))
     if not candidates:
         raise ArchiveError("final review requires at least one final-gap-N.md artifact")
@@ -626,6 +657,8 @@ def validate_gap_reviews(archive: Path, reviewed_head: str) -> None:
         gap_head = completed_field(lines, "Reviewed HEAD:", path.name).lower()
         if gap_head != reviewed_head:
             raise ArchiveError(f"{path.name} Reviewed HEAD does not match FINAL.md")
+        if _member_heads("\n".join(lines), path.name) != member_heads:
+            raise ArchiveError(f"{path.name} Member reviewed HEAD lines do not match FINAL.md")
         if completed_field(lines, "Gap verdict:", path.name) != "pass":
             raise ArchiveError(f"{path.name} gap review did not pass")
         risk = completed_field(lines, "Risk:", path.name)
@@ -655,10 +688,13 @@ def validate_gap_reviews(archive: Path, reviewed_head: str) -> None:
 
 
 def meaningful_review_evidence(lines: Sequence[str], marker: str, task_text: str = "") -> bool:
-    try:
-        from check_handoffs import task_review_observation
-    except ImportError:  # pragma: no cover - package import used by tests
-        from scripts.check_handoffs import task_review_observation
+    if __package__:
+        from .check_handoffs import task_review_observation
+    else:
+        try:
+            from check_handoffs import task_review_observation
+        except ImportError:  # pragma: no cover - package import used by tests
+            from scripts.check_handoffs import task_review_observation
 
     prefix = f"- {marker} "
     evidence = []
@@ -1071,8 +1107,17 @@ def archive_file_inventory(archive: Path) -> Sequence[str]:
     for path in archive.rglob("*"):
         if path.is_symlink():
             raise ArchiveError(f"archive contents must not be symlinks: {path}")
-        if path.is_file() and path.name != "MANIFEST.md":
-            contents.append(path.relative_to(archive).as_posix())
+        if not path.is_file() or path.name == "MANIFEST.md":
+            continue
+        relative = path.relative_to(archive)
+        if _common.is_ignored_junk(path):
+            if len(relative.parts) == 1:
+                continue
+            original = archive.parent.parent / relative
+            project = archive.parent.parent.parent
+            if run_git(project, "check-ignore", "-q", "--", original.relative_to(project).as_posix()).returncode == 0:
+                continue
+        contents.append(relative.as_posix())
     return sorted(contents)
 
 

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

@@ -12,23 +12,8 @@ import re
 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 +23,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 +557,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 +717,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
@@ -1394,6 +1411,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 +1480,390 @@ 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)
+    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)}