@opengsd/gsd-path 1.6.2 → 1.7.0

package/skills/gsd-path-docs-audit/scripts/archive_milestone.py

@@ -781,7 +781,14 @@ def validate_panel_skip_receipt(path: Path, expected_mode: str) -> None:
         not isinstance(item, dict)
         or set(item) != {"family", "reason"}
         or item["family"] not in KNOWN_FAMILIES
-        or item["reason"] not in {"parent family", "not advertised", "cap"}
+        # review_panel resolve writes every one of these reasons (#460);
+        # the receipt must validate whatever the helper can produce.
+        or item["reason"] not in {
+            "parent family",
+            "not advertised",
+            "cap",
+            "excluded reviewer family",
+        }
         for item in skipped
     ):
         raise ArchiveError(f"{path.name} has invalid skipped families")
@@ -1998,6 +2005,62 @@ def member_ship_rows(project: Path, archive: Path, ship_commit: str) -> list:
     return rows
 
 
+def tag_metadata_fields(project: Path, tag_ref: str) -> dict[str, str]:
+    """The Key: value fields of an annotated milestone tag's message."""
+    message = require_git_success(
+        run_git(project, "for-each-ref", "--format=%(contents)", tag_ref),
+        "inspect milestone tag",
+    )
+    fields: dict[str, str] = {}
+    for line in message.splitlines():
+        match = re.fullmatch(r"(Mode|Pull-Request|Ship|Landing): (.+)", line)
+        if match:
+            if match.group(1) in fields:
+                raise ArchiveError("milestone tag repeats metadata")
+            fields[match.group(1)] = match.group(2)
+    return fields
+
+
+def accept_rebased_ship(
+    project: Path, archive: Path, ship_commit: str, reviewed_head: str
+) -> Optional[str]:
+    """Accept the rebased ship copy a rebase merge landed, keyed by the milestone tag.
+
+    Historical validation only (issue #450): after a rebase merge the landed
+    ship copy's parent is never the reviewed HEAD, so the strict check cannot
+    pass over landed history. Acceptance requires the milestone tag to name
+    exactly this commit as its Landing, the original ship commit the tag
+    names to still resolve, the strict invariant re-proven against the
+    original ship's parent, and the rebase replay to hold. Returns the tag's
+    original Ship sha, or None when the landing is not a proven rebase: a
+    landing whose originals no longer resolve anywhere is refused, because
+    the per-task landing proofs elsewhere in validation pin the original
+    commits and a tag receipt alone cannot carry a full validation.
+    """
+    tag_ref = f"refs/tags/milestone/{archive.name}"
+    if run_git(project, "rev-parse", "--verify", "--quiet", tag_ref).returncode != 0:
+        return None
+    try:
+        fields = tag_metadata_fields(project, tag_ref)
+    except ArchiveError:
+        return None
+    if fields.get("Mode") != "pull-request":
+        return None
+    original = fields.get("Ship")
+    if not original or fields.get("Landing") != ship_commit:
+        return None
+    if run_git(project, "cat-file", "-e", f"{original}^{{commit}}").returncode != 0:
+        return None
+    original_parent = require_git_success(
+        run_git(project, "rev-parse", f"{original}^"), "resolve original ship parent"
+    )
+    if not reviewed_head_covers(project, reviewed_head, original_parent):
+        return None
+    if _common.rebase_landing_problem(project, original, ship_commit) is not None:
+        return None
+    return original
+
+
 def validate(repo: Path, *, historical: bool = False) -> dict:
     project, _, state, configured, archive, archived_files, reviewed_head = prepared_transaction(
         repo,
@@ -2093,11 +2156,17 @@ def validate(repo: Path, *, historical: bool = False) -> dict:
 
     members = member_ship_rows(project, archive, ship_commit)
     ship_parent = require_git_success(run_git(project, "rev-parse", f"{ship_commit}^"), "resolve ship parent")
+    rebased_ship: Optional[str] = None
     if not reviewed_head_covers(project, reviewed_head, ship_parent):
-        raise ArchiveError(
-            f"FINAL.md Reviewed HEAD {reviewed_head} does not match ship parent {ship_parent}; "
-            f"{_common.RUNTIME_PIN_ALLOWANCE}"
+        rebased_ship = (
+            accept_rebased_ship(project, archive, ship_commit, reviewed_head)
+            if historical else None
         )
+        if rebased_ship is None:
+            raise ArchiveError(
+                f"FINAL.md Reviewed HEAD {reviewed_head} does not match ship parent {ship_parent}; "
+                f"{_common.RUNTIME_PIN_ALLOWANCE}"
+            )
     require_canonical_commit_body(
         project,
         ship_commit,
@@ -2141,6 +2210,8 @@ def validate(repo: Path, *, historical: bool = False) -> dict:
         )
 
     result = {"archive": configured, "commit": ship_commit}
+    if rebased_ship is not None:
+        result["rebased_ship"] = rebased_ship
     if members:
         result["members"] = members
     return result
@@ -2178,6 +2249,15 @@ def parser() -> argparse.ArgumentParser:
     )
     validate_integrated_parser.add_argument("--repo", required=True, type=Path)
     validate_integrated_parser.add_argument("--slug", required=True)
+    validate_integrated_parser.add_argument(
+        "--historical",
+        action="store_true",
+        help=(
+            "validate from the landed default branch after the milestone closed "
+            "(the bound branch may be gone; a rebase-merged landing is proven "
+            "through the milestone tag)"
+        ),
+    )
 
     refresh_parser = subparsers.add_parser(
         "refresh-origin",
@@ -2190,6 +2270,17 @@ def parser() -> argparse.ArgumentParser:
         help="after preflight, integrate each locked member in lock order before the ship commit",
     )
     close_members_parser.add_argument("--repo", required=True, type=Path)
+    close_members_parser.add_argument(
+        "--adopt-landed-member",
+        action="append",
+        default=[],
+        metavar="MEMBER=SHA",
+        help=(
+            "user-approved recovery for a member whose reviewed HEAD already reached its "
+            "default branch outside Path; MEMBER=SHA names the live default-branch tip "
+            "to adopt as the landing"
+        ),
+    )
 
     integrate_parser = subparsers.add_parser(
         "integrate",
@@ -2197,6 +2288,16 @@ def parser() -> argparse.ArgumentParser:
     )
     integrate_parser.add_argument("--repo", required=True, type=Path)
     integrate_parser.add_argument("--slug", required=True)
+    integrate_parser.add_argument(
+        "--adopt-published-bound",
+        metavar="SHA",
+        help=(
+            "user-approved recovery when origin's bound branch is a strict ancestor "
+            "of the ship commit (a build task pushed it as a deploy pin, #464); "
+            "the 40-hex SHA must equal the live remote tip exactly; the publish "
+            "fast-forwards under the existing exact lease. Direct integration only"
+        ),
+    )
 
     abandon_parser = subparsers.add_parser(
         "abandon",
@@ -2225,13 +2326,34 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
         elif arguments.command == "abandon":
             result = abandon(arguments.repo, arguments.slug, arguments.reason)
         elif arguments.command == "validate-integrated":
-            result = integration.validate_integrated(arguments.repo, arguments.slug)
+            result = integration.validate_integrated(
+                arguments.repo, arguments.slug, historical=arguments.historical
+            )
         elif arguments.command == "refresh-origin":
             result = integration.refresh_origin(arguments.repo)
         elif arguments.command == "close-members":
-            result = integration.close_members(arguments.repo)
+            adopt: dict[str, str] = {}
+            for item in arguments.adopt_landed_member:
+                name, separator, sha = item.partition("=")
+                if not name or not separator or not re.fullmatch(r"[0-9a-f]{40}", sha):
+                    parser_error = (
+                        f"--adopt-landed-member expects MEMBER=SHA (40-hex), got {item!r}"
+                    )
+                    print(parser_error, file=sys.stderr)
+                    return 2
+                adopt[name] = sha
+            result = integration.close_members(arguments.repo, adopt=adopt or None)
         elif arguments.command == "integrate":
-            result = integration.integrate(arguments.repo, arguments.slug)
+            adopt_bound = arguments.adopt_published_bound
+            if adopt_bound is not None:
+                adopt_bound = adopt_bound.lower()
+            if adopt_bound is not None and not re.fullmatch(r"[0-9a-f]{40}", adopt_bound):
+                print(
+                    f"--adopt-published-bound expects a 40-hex SHA, got {adopt_bound!r}",
+                    file=sys.stderr,
+                )
+                return 2
+            result = integration.integrate(arguments.repo, arguments.slug, adopt_bound)
         else:
             result = validate(arguments.repo)
     except (ArchiveError, OSError) as error:

package/skills/gsd-path-docs-audit/scripts/build_recovery.py

@@ -144,7 +144,13 @@ def settled_tasks(repo: Path) -> dict[str, tuple[str, dict]]:
             raise state.PipelineStateError(f"invalid recovery task path: {path.name}")
         text = state._read_real_file(path, path.name)
         fields = task_fields(text, path.name)
-        if fields.get("status") not in {"pending", "done"}:
+        if fields.get("status") == "withdrawn":
+            # A cited tombstone is settled inventory; recovery skips it (#483).
+            if not state._common.withdrawn_citations(text):
+                raise state.PipelineStateError(
+                    f"withdrawn task lacks an owner citation: {path.name}"
+                )
+        elif fields.get("status") not in {"pending", "done"}:
             raise state.PipelineStateError(f"settle task ownership before recovery: {path.name}")
         if fields["status"] == "pending" and any(
             fields.get(key) != "null" for key in ("agent", "base", "worktree", "task_branch")
@@ -250,7 +256,24 @@ def validate_review_backup(repo: Path, recovery: dict, directory: Path) -> None:
               for path in directory.rglob("*")
               if path.is_file() and not state._common.is_ignored_junk(path)} if directory.exists() else {}
     if actual != expected:
-        raise state.PipelineStateError("review backup differs from the recovery base")
+        extra = sorted(set(actual) - set(expected))
+        changed = sorted(
+            name for name in set(actual) & set(expected) if actual[name] != expected[name]
+        )
+        missing = sorted(set(expected) - set(actual))
+        detail = ""
+        if extra:
+            detail += f" files in the review backup that the recovery base does not have: {', '.join(extra)}."
+        if changed:
+            detail += f" files differing from the recovery base: {', '.join(changed)}."
+        if missing:
+            detail += f" files at the recovery base missing from the review backup: {', '.join(missing)}."
+        raise state.PipelineStateError(
+            "review backup differs from the recovery base." + detail
+            + " prepare-build-recovery must run before re-planning touches any recovery"
+            " artifact; remove the extra files and restore the missing or changed ones"
+            " to the recovery base's content, then rerun prepare"
+        )
 
 
 def prepare(repo: Path) -> dict: