gitgrip 1.5.0__py3-none-any.whl

gr2/python_cli/project_review.py

@@ -0,0 +1,314 @@
+"""Minimal M1 project-tier composition over the existing review clone seam."""
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import re
+import tomllib
+from pathlib import Path
+from pathlib import PurePosixPath, PureWindowsPath
+from typing import Literal
+
+from gr2.prototypes import lane_workspace_prototype as lanes
+from . import grip, review, spec_apply
+from .gitops import git
+
+_SHA40 = re.compile(r"\A[0-9a-f]{40}\Z")
+
+
+@dataclasses.dataclass(frozen=True)
+class ProjectReviewPin:
+    key: str
+    repo: str
+    path: str
+    base: str
+    head: str
+
+
+@dataclasses.dataclass(frozen=True)
+class ProjectReviewSpec:
+    schema: str
+    grip_commit: str
+    pins: tuple[ProjectReviewPin, ...]
+
+
+@dataclasses.dataclass(frozen=True)
+class ProjectReviewFailure:
+    key: str
+    reason: str
+
+
+@dataclasses.dataclass(frozen=True)
+class ProjectReviewOutcome:
+    status: Literal["opened", "refused", "partial"]
+    grip_commit: str
+    observed: tuple[review.ReviewRecord, ...]
+    failures: tuple[ProjectReviewFailure, ...]
+    review_root: Path | None
+    current_lane_changed: bool
+
+
+def make_spec(
+    workspace: Path, pins: list[ProjectReviewPin], ranges: dict[str, str] | None = None,
+    committers: dict[str, str] | None = None,
+) -> ProjectReviewSpec:
+    ordered = tuple(sorted((_canonical_pin(pin) for pin in pins), key=lambda pin: pin.key))
+    if not ordered or len({pin.key for pin in ordered}) != len(ordered):
+        raise ValueError("project review pins must be non-empty with unique keys")
+    commit = grip.create_project_review_commit(
+        workspace, [{**dataclasses.asdict(pin), "repo": pin.repo} for pin in ordered],
+        ranges=ranges, committers=committers,
+    )
+    return ProjectReviewSpec("gr2-project-review/v1", commit, ordered)
+
+
+def pins_from_lane(workspace_root: Path, owner_unit: str, lane_name: str) -> list[ProjectReviewPin]:
+    """Build project-review pins for a materialized lane, reading each repo's base
+    from the RECORDED fork base (the fork-base ruling), never from HEAD^.
+
+    A review is measured from the point the lane forked from its integration
+    branch; that coordinate is recorded at lane create and read here through the
+    same resolver the workspace snapshot uses. A lane with no recorded fork base is
+    refused by that resolver (unknown, never HEAD^), so a review can never be bound
+    against a base the lane did not actually fork from.
+    """
+    from . import workspace_snapshot as ws_snap
+
+    rows = ws_snap.resolve_lane_repos(Path(workspace_root).resolve(), owner_unit, lane_name)
+    return [
+        ProjectReviewPin(key=r["key"], repo=r["remote"], path=r["path"], base=r["base"], head=r["commit"])
+        for r in rows
+    ]
+
+
+def _normalized_path(value: str) -> str:
+    path = PurePosixPath(value)
+    if not value or path.is_absolute() or ".." in path.parts or str(path) in {".", ""}:
+        raise ValueError(f"invalid project review path: {value!r}")
+    return path.as_posix()
+
+
+def _canonical_pin(pin: ProjectReviewPin) -> ProjectReviewPin:
+    if not pin.key or any(ch in pin.key for ch in "/\\") or not pin.repo or not _SHA40.match(pin.base) or not _SHA40.match(pin.head):
+        raise ValueError(f"invalid project review pin: {pin.key}")
+    return dataclasses.replace(pin, path=_normalized_path(pin.path))
+
+
+def _review_path_component(value: str, field: str) -> str:
+    """Validate names before they become a clone destination or lane path."""
+    if not value or value in {".", ".."}:
+        raise ValueError(f"invalid {field}: {value!r}")
+    windows = PureWindowsPath(value)
+    if (
+        "/" in value
+        or "\\" in value
+        or ":" in value
+        or windows.drive
+        or windows.root
+        or any(ord(char) < 0x20 or ord(char) == 0x7F for char in value)
+    ):
+        raise ValueError(f"invalid {field}: {value!r}")
+    return value
+
+
+def _canonical_repo_identity(value: str, *, allow_local: bool) -> str:
+    """Canonicalize a pin/spec identity without treating a clone path as truth.
+
+    Local paths are test-only transport. When one names a checkout, its origin
+    supplies the repository identity just as production HTTPS/SSH transport
+    does. A bare local path remains marked local for isolated fixtures.
+
+    ``allow_local`` is threaded to ``canonical_source_identity`` on EVERY path,
+    including the two ``local:`` sub-cases, so the literal ``local:`` prefix
+    cannot bypass the FILESYSTEM-identity refusal: with ``allow_local=False`` a
+    filesystem identity is refused with the same ``ReviewError`` as a bare
+    non-GitHub origin, because the refusal is delegated to
+    ``canonical_source_identity`` rather than re-implemented here. A ``local:``
+    checkout whose origin is a portable ``https://github.com/<owner>/<repo>``
+    still canonicalizes to that GitHub identity regardless of the flag — the
+    refusal is of a non-portable filesystem identity, not of the prefix itself.
+    """
+    if value.startswith("local:"):
+        local = Path(value.removeprefix("local:"))
+        origin = review.gitops.remote_origin_url(local) if local.is_dir() else None
+        if origin:
+            return review.canonical_source_identity(origin, allow_local=allow_local)
+        return review.canonical_source_identity(str(local), allow_local=allow_local)
+    return review.canonical_source_identity(value, allow_local=allow_local)
+
+
+def _validate_workspace_repository_boundary(
+    *, workspace: Path, pins: tuple[ProjectReviewPin, ...], sources: dict[str, tuple[Path, str]], allow_local: bool
+) -> ProjectReviewFailure | None:
+    """Bind every review pin and ephemeral source to the compiled workspace.
+
+    This is deliberately before pin-object checks, clone destinations, or lane
+    transition. A project review may only materialize repositories the compiled
+    workspace itself authorizes.
+    """
+    workspace_doc, failure = _load_workspace_boundary_doc(workspace)
+    if failure is not None:
+        return failure
+    entries: dict[str, str] = {}
+    for row in workspace_doc.get("repos", []):
+        if not isinstance(row, dict):
+            return ProjectReviewFailure("workspace_spec", "compiled workspace repo entry is not a mapping")
+        key = str(row.get("name", ""))
+        url = str(row.get("url", ""))
+        try:
+            entries[key] = _canonical_repo_identity(url, allow_local=allow_local)
+        except Exception as exc:
+            return ProjectReviewFailure("workspace_spec", f"invalid compiled repository {key!r}: {exc}")
+    for pin in pins:
+        expected = entries.get(pin.key)
+        if expected is None:
+            return ProjectReviewFailure(pin.key, f"unknown workspace repository key {pin.key!r}")
+        try:
+            pin_identity = _canonical_repo_identity(pin.repo, allow_local=allow_local)
+        except Exception as exc:
+            return ProjectReviewFailure(pin.key, f"invalid pin repository identity: {exc}")
+        if pin_identity != expected:
+            return ProjectReviewFailure(
+                pin.key,
+                f"workspace repository identity mismatch: pin {pin_identity!r}, compiled {expected!r}",
+            )
+        source_branch = sources.get(pin.key)
+        if source_branch is None:
+            continue
+        source, _branch = source_branch
+        origin = review.gitops.remote_origin_url(source)
+        if not origin:
+            return ProjectReviewFailure(pin.key, f"selected source {source} has no origin for identity validation")
+        try:
+            source_identity = _canonical_repo_identity(origin, allow_local=allow_local)
+        except Exception as exc:
+            return ProjectReviewFailure(pin.key, f"invalid selected source origin: {exc}")
+        if source_identity != pin_identity:
+            return ProjectReviewFailure(
+                pin.key,
+                f"selected source identity mismatch: source {source_identity!r}, pin {pin_identity!r}",
+            )
+    return None
+
+
+def _load_workspace_boundary_doc(workspace: Path) -> tuple[dict[str, object] | None, ProjectReviewFailure | None]:
+    """Keep absent and malformed authority in the review outcome channel."""
+    try:
+        return spec_apply.load_workspace_spec_doc(workspace), None
+    except (SystemExit, tomllib.TOMLDecodeError) as exc:
+        return None, ProjectReviewFailure("workspace_spec", str(exc))
+
+
+def _stamp_lane_kind(workspace: Path, owner_unit: str, lane_name: str, kind: str) -> None:
+    """Rewrite the lane's ``lane_kind`` in place. create_lane writes the default
+    ``materialized``; a review lane overrides it so require_current_lane reports the
+    review kind to every mutating verb."""
+    path = lanes.lane_file(workspace, owner_unit, lane_name)
+    text = path.read_text()
+    new = re.sub(r'(?m)^lane_kind\s*=\s*"[^"]*"\s*$', f'lane_kind = "{kind}"', text)
+    if 'lane_kind' not in new:
+        new = new.rstrip("\n") + f'\nlane_kind = "{kind}"\n'
+    path.write_text(new)
+
+
+def open_project_review(*, workspace: Path, owner_unit: str, lane_name: str, spec: ProjectReviewSpec, sources: dict[str, tuple[Path, str]], allow_local: bool = False, ephemeral: bool = False, materialize_heads: dict[str, str] | None = None) -> ProjectReviewOutcome:
+    """Preflight every immutable pin, then materialize all members before enter.
+
+    ``ephemeral`` materializes each member as a blobless+sparse review-ephemeral
+    lane from the persistent mirror (``sources[key]`` is the mirror), never through
+    the work-lane clone seam.
+
+    ``materialize_heads`` (key -> sha) OVERRIDES which head each member is
+    materialized at, WITHOUT changing what the gr commit is validated against. It is
+    the carried-range reconstruction case: the commit pins the original (pre-push)
+    head, but ``git am`` re-stamps the committer so the reconstructed head is a
+    DIFFERENT sha with the SAME tree; the commit-binding check stays on the pinned
+    head while materialization uses the reconstructed head that actually exists in
+    the topped-up mirror. Absent a key, the pinned head is used (the ordinary case)."""
+    materialize_heads = materialize_heads or {}
+    if spec.schema != "gr2-project-review/v1":
+        return ProjectReviewOutcome("refused", spec.grip_commit, (), (ProjectReviewFailure("spec", "unsupported schema"),), None, False)
+    try:
+        owner_unit = _review_path_component(owner_unit, "owner unit")
+        lane_name = _review_path_component(lane_name, "lane name")
+    except ValueError as exc:
+        return ProjectReviewOutcome("refused", spec.grip_commit, (), (ProjectReviewFailure("review_root", str(exc)),), None, False)
+    # A cross-repo project review requires a MATERIALIZED lane whose rows
+    # reconstruct together from carried ranges. A bound lane is a single-repo
+    # label on the author's own worktree — its bytes live in a tree the author
+    # keeps editing, so it cannot give the exact-reconstruction guarantee across
+    # rows. Refuse it here with a specific message rather than letting the later
+    # create_lane emit a generic "refusing to replace" (gr2-lane-author-shape
+    # ruling: bound lanes are single-repo `pr` only).
+    lane_path = lanes.lane_file(workspace, owner_unit, lane_name)
+    if lane_path.exists():
+        try:
+            existing_kind = tomllib.loads(lane_path.read_text()).get("lane_kind")
+        except (OSError, tomllib.TOMLDecodeError):
+            existing_kind = None
+        if existing_kind == "bound":
+            return ProjectReviewOutcome(
+                "refused", spec.grip_commit, (),
+                (ProjectReviewFailure(
+                    lane_name,
+                    f"lane {owner_unit}/{lane_name} is a BOUND single-repo lane; a project review "
+                    "requires a materialized lane whose rows reconstruct together. Use `gr2 pr` for "
+                    "this bound lane's single-repo review, or open the project review on a "
+                    "materialized lane.",
+                ),),
+                None, False,
+            )
+    try:
+        canonical_pins = tuple(_canonical_pin(pin) for pin in spec.pins)
+    except ValueError as exc:
+        return ProjectReviewOutcome("refused", spec.grip_commit, (), (ProjectReviewFailure("spec", str(exc)),), None, False)
+    decoded = grip.read_project_review_commit(workspace, spec.grip_commit)
+    if len(decoded) != len(canonical_pins):
+        return ProjectReviewOutcome("refused", spec.grip_commit, (), (ProjectReviewFailure("spec", "gr commit member count mismatch"),), None, False)
+    for row, pin in zip(decoded, canonical_pins):
+        for field, expected, observed in (("key", pin.key, row["key"]), ("repo", pin.repo, row["repo"]), ("path", pin.path, _normalized_path(row["path"])), ("base", pin.base, row["base"]), ("head", pin.head, row["head"])):
+            if expected != observed:
+                return ProjectReviewOutcome("refused", spec.grip_commit, (), (ProjectReviewFailure(pin.key, f"gr commit mismatch for {field}: expected {expected!r}, observed {observed!r}"),), None, False)
+    boundary_failure = _validate_workspace_repository_boundary(
+        workspace=workspace, pins=canonical_pins, sources=sources, allow_local=allow_local
+    )
+    if boundary_failure is not None:
+        return ProjectReviewOutcome("refused", spec.grip_commit, (), (boundary_failure,), None, False)
+    for pin in canonical_pins:
+        source_branch = sources.get(pin.key)
+        if source_branch is None:
+            return ProjectReviewOutcome("refused", spec.grip_commit, (), (ProjectReviewFailure(pin.key, "missing source transport"),), None, False)
+        source, _branch = source_branch
+        materialize_head = materialize_heads.get(pin.key, pin.head)
+        for label, sha in (("base", pin.base), ("head", materialize_head)):
+            if git(source, "cat-file", "-e", f"{sha}^{{commit}}").returncode != 0:
+                return ProjectReviewOutcome("refused", spec.grip_commit, (), (ProjectReviewFailure(pin.key, f"missing {label} pin {sha}"),), None, False)
+    review_root = workspace / "reviews" / owner_unit / lane_name
+    observed: list[review.ReviewRecord] = []
+    for pin in canonical_pins:
+        source, branch = sources[pin.key]
+        repo_name = Path(source).name.removesuffix(".git")
+        materialize_head = materialize_heads.get(pin.key, pin.head)
+        try:
+            record = review.open_review_lane(source_repo_root=source, review_branch=branch, expected_head_sha=materialize_head, base_sha=pin.base, lane_repo_root=review_root / "repos" / pin.key, workspace_root=workspace, allow_local=allow_local, ephemeral=ephemeral, repo_name=repo_name, echo=lambda _line: None)
+        except Exception as exc:
+            return ProjectReviewOutcome("partial", spec.grip_commit, tuple(observed), (ProjectReviewFailure(pin.key, str(exc)),), review_root, False)
+        observed.append(record)
+    try:
+        lanes.create_lane(argparse.Namespace(workspace_root=workspace, owner_unit=owner_unit, lane_name=lane_name, type="review", repos=",".join(pin.key for pin in canonical_pins), branch="main", source="project-review", default_commands=[]))
+        if ephemeral:
+            # Stamp the lane kind so every mutating verb (commit/push/bind) can
+            # refuse this lane naming the kind: a review lane never becomes a work lane.
+            _stamp_lane_kind(workspace, owner_unit, lane_name, "review-ephemeral")
+        lanes.enter_lane(argparse.Namespace(workspace_root=workspace, owner_unit=owner_unit, lane_name=lane_name, actor="project-review", notify_channel=False, recall=False))
+    except Exception as exc:
+        return ProjectReviewOutcome("partial", spec.grip_commit, tuple(observed), (ProjectReviewFailure("transition", str(exc)),), review_root, False)
+    return ProjectReviewOutcome("opened", spec.grip_commit, tuple(observed), (), review_root, True)
+
+
+def outcome_payload(outcome: ProjectReviewOutcome) -> dict[str, object]:
+    return {"status": outcome.status, "grip_commit": outcome.grip_commit,
+            "observed": [record.to_dict() for record in outcome.observed],
+            "failures": [dataclasses.asdict(failure) for failure in outcome.failures],
+            "review_root": str(outcome.review_root) if outcome.review_root else None,
+            "current_lane_changed": outcome.current_lane_changed}

gr2/python_cli/prune.py

@@ -0,0 +1,365 @@
+"""Native `prune` command for gr2.
+
+gr2 registers 44 verbs and `prune` was absent from all of them (measured
+2026-08-30): gr1 was the only surface with a branch-prune, so every lane gr2
+opens left a branch that only gr1 or a hand could remove. This is that verb.
+
+It is deliberately MORE correct than gr1's prune. gr1's `is_branch_merged`
+(src/git/branch.rs) uses `git branch --merged <target>`, which is CONTAINMENT
+alone -- it reports a branch merged only when its tip is an ancestor of the
+target. In our squash- and rebase-heavy history that misses most landed work
+(measured on Apollo's own desk 2026-09-06: feat/gr2-workspace-spec-regeneration
+and feat/pr-create-base each read NOT contained but ARE present in origin/dev by
+patch-id). Per claude.md's standing rule -- "containment answers 'is this commit
+OBJECT present'; nobody ever wants that answer" -- merged here is decided by
+PATCH-ID (`git cherry`, patch-id equivalence, catches plain/ff/rebase/cherry-pick
+merges) OR by the SQUASH TREE check (the branch's aggregate diff matching a single
+target commit's patch-id), never by containment alone.
+
+Single-repo by convention, like gr2's other top-level verbs (cwd or
+--repo-path). Dry-run by default; deletes only with --execute; never touches a
+remote ref; never deletes the current branch, the target, or `main`/`dev`.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+from dataclasses import dataclass
+
+from pathlib import Path
+
+from .gitops import git
+
+
+class PruneError(Exception):
+    pass
+
+
+# Never delete these, by name, in addition to the current branch and the target.
+_NAMED_PROTECTED = ("main", "dev")
+
+
+@dataclass(frozen=True)
+class MergedBranch:
+    """A local branch whose work is already in the target, with why."""
+
+    name: str
+    reason: str  # "patch-id" | "squash"
+    detail: str
+
+
+@dataclass
+class PruneReport:
+    target: str
+    target_source: str  # how the target was resolved, for the printout
+    merged: list[MergedBranch]
+    protected_skipped: list[str]
+    deleted: list[str]
+    failed: list[tuple[str, str]]  # (branch, error)
+    executed: bool
+
+
+def _short(ref: str) -> str:
+    """The short branch name for a possibly-qualified ref (origin/dev -> dev)."""
+    return ref.rsplit("/", 1)[-1]
+
+
+def _current_branch(repo: Path) -> str | None:
+    proc = git(repo, "branch", "--show-current")
+    if proc.returncode != 0:
+        raise PruneError(f"cannot read current branch in {repo}: {proc.stderr.strip()}")
+    name = proc.stdout.strip()
+    return name or None  # empty == detached HEAD
+
+
+def _local_branches(repo: Path) -> list[str]:
+    proc = git(repo, "for-each-ref", "--format=%(refname:short)", "refs/heads/")
+    if proc.returncode != 0:
+        raise PruneError(f"cannot list local branches in {repo}: {proc.stderr.strip()}")
+    return [line.strip() for line in proc.stdout.splitlines() if line.strip()]
+
+
+def _ref_exists(repo: Path, ref: str) -> bool:
+    return git(repo, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}").returncode == 0
+
+
+def resolve_target(
+    repo: Path,
+    target: str | None,
+    remote: str,
+    stored_target: str | None = None,
+) -> tuple[str, str]:
+    """Resolve the ref merged-ness is measured against.
+
+    Order: explicit ``--target``, then the gripspace's stored ``[settings].target``
+    (``stored_target``), then the integration branch ``<remote>/dev``, then the
+    remote's own default branch (``refs/remotes/<remote>/HEAD``), then
+    ``<remote>/main``. Returns ``(target_ref, how_it_was_resolved)``.
+
+    The stored target is the branch work in THIS gripspace actually merges into
+    (an epic branch, say, where ``dev`` is not the base). It is READ here, never
+    written -- ``gr target set`` is the only writer. A bare name (``epic/x``) is
+    mapped to ``<remote>/<name>`` because merged-ness is measured against a
+    remote-tracking ref. A stored target whose remote ref is ABSENT (a stale or
+    typo'd setting) is SKIPPED, not fatal: resolution falls through to ``dev`` and
+    the returned source names the skipped stored value, so a stranger reading the
+    report sees why ``dev`` was chosen. Skipping (rather than raising) keeps
+    deletion on the safe side -- a rotted setting never leaves branches
+    under-protected.
+
+    ``dev`` is tried BEFORE ``origin/HEAD`` on purpose: our integration branch is
+    ``dev``, but ``origin/HEAD`` points at ``main`` on a fresh clone, so resolving
+    HEAD first would silently measure prune against ``main`` and report dev-merged
+    branches as unmerged. An explicit ``--target`` that does not exist still
+    raises, because a wrong operator-named target makes every verdict wrong.
+    """
+    if target is not None:
+        if not _ref_exists(repo, target):
+            raise PruneError(f"target ref '{target}' does not exist in {repo}")
+        return target, "explicit --target"
+
+    stored_note: str | None = None
+    if stored_target:
+        stored_ref = (
+            stored_target
+            if stored_target.startswith(f"{remote}/")
+            else f"{remote}/{stored_target}"
+        )
+        if _ref_exists(repo, stored_ref):
+            return stored_ref, f"stored target ({stored_ref})"
+        stored_note = f"stored target '{stored_target}' skipped ({stored_ref} not found)"
+
+    def _with_note(source: str) -> str:
+        return f"{source}; {stored_note}" if stored_note else source
+
+    dev = f"{remote}/dev"
+    if _ref_exists(repo, dev):
+        return dev, _with_note(f"integration branch ({dev})")
+    head = git(repo, "symbolic-ref", "--quiet", f"refs/remotes/{remote}/HEAD")
+    if head.returncode == 0 and head.stdout.strip():
+        ref = _short_remote(head.stdout.strip(), remote)
+        if _ref_exists(repo, ref):
+            return ref, _with_note(f"{remote}/HEAD")
+    main = f"{remote}/main"
+    if _ref_exists(repo, main):
+        return main, _with_note(f"fallback ({main})")
+    msg = (
+        f"could not resolve a target in {repo}: no {remote}/dev, {remote}/HEAD, or "
+        f"{remote}/main. Pass --target explicitly."
+    )
+    if stored_note:
+        msg += f" ({stored_note})"
+    raise PruneError(msg)
+
+
+def _short_remote(symref: str, remote: str) -> str:
+    # refs/remotes/origin/dev -> origin/dev
+    prefix = "refs/remotes/"
+    return symref[len(prefix):] if symref.startswith(prefix) else symref
+
+
+def _patch_id(repo: Path, *diff_args: str) -> str | None:
+    """Stable patch-id of `git diff <diff_args>`; None if the diff is empty."""
+    diff = git(repo, "diff", *diff_args)
+    if diff.returncode != 0:
+        raise PruneError(f"git diff {' '.join(diff_args)} failed in {repo}: {diff.stderr.strip()}")
+    if not diff.stdout.strip():
+        return None
+    pid = subprocess.run(
+        ["git", "patch-id", "--stable"],
+        cwd=repo,
+        input=diff.stdout,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if pid.returncode != 0 or not pid.stdout.strip():
+        return None
+    return pid.stdout.split()[0]
+
+
+def _cherry_merged(repo: Path, target: str, branch: str) -> tuple[bool, int]:
+    """Patch-id equivalence via `git cherry`: no '+' line means every commit
+    unique to `branch` is already present in `target` by patch-id (covers
+    plain/fast-forward/rebase/cherry-pick merges, and the empty-ahead case)."""
+    proc = git(repo, "cherry", target, branch)
+    if proc.returncode != 0:
+        raise PruneError(
+            f"git cherry {target} {branch} failed in {repo}: {proc.stderr.strip()}"
+        )
+    plus = [ln for ln in proc.stdout.splitlines() if ln.startswith("+")]
+    return (len(plus) == 0, len(plus))
+
+
+# How many of target's first-parent commits (newest first) to scan for a squash
+# match before giving up. A squash-merge lands as ONE commit on the target's
+# first-parent mainline, so the scan is bounded to that line (not every commit
+# ever merged in). The cap is a safety valve against a pathologically old
+# merge-base: hitting it returns "not squash-merged" (the SAFE direction for a
+# deletion -- we never delete on an inconclusive check), and the caller can pass
+# --target closer if a branch diverged very long ago.
+_SQUASH_SCAN_CAP = 400
+
+
+def _target_squash_patch_ids(repo: Path, target: str) -> dict[str, str]:
+    """Map {commit patch-id -> sha} for target's newest first-parent commits.
+
+    Built ONCE per prune and shared across every branch, so squash detection is
+    O(cap) here plus O(1) per branch, not O(branches x cap). Squash-merge commits
+    land on the target's first-parent mainline, so that is the only line worth
+    scanning; the cap bounds a pathologically deep history and its miss is the
+    SAFE direction for a deletion (a branch squashed older than the window reads
+    as not-merged and is left alone)."""
+    rev = git(
+        repo,
+        "rev-list",
+        "--first-parent",
+        f"--max-count={_SQUASH_SCAN_CAP}",
+        target,
+    )
+    if rev.returncode != 0:
+        raise PruneError(
+            f"git rev-list --first-parent {target} failed in {repo}: {rev.stderr.strip()}"
+        )
+    ids: dict[str, str] = {}
+    for sha in (ln.strip() for ln in rev.stdout.splitlines() if ln.strip()):
+        # A root commit (no parent) or a shallow-clone boundary has no `<sha>^`;
+        # such a commit cannot be the squash of a feature branch, so skip it
+        # rather than error. This also keeps the verb usable inside a shallow
+        # review clone, where the oldest commits are grafted.
+        if not _ref_exists(repo, f"{sha}^"):
+            continue
+        pid = _patch_id(repo, f"{sha}^", sha)
+        if pid is not None:
+            ids.setdefault(pid, sha)
+    return ids
+
+
+def _squash_merged(
+    repo: Path, target: str, branch: str, target_ids: dict[str, str]
+) -> tuple[bool, str | None]:
+    """The branch's aggregate diff (merge-base..branch) has the same stable
+    patch-id as a single first-parent commit on `target` -- the squash case
+    `git cherry` cannot see, because a squash gives the combined change a new
+    commit whose per-commit patch-ids never match the branch's originals."""
+    mb = git(repo, "merge-base", target, branch)
+    if mb.returncode != 0 or not mb.stdout.strip():
+        return (False, None)
+    base = mb.stdout.strip()
+    aggregate = _patch_id(repo, base, branch)
+    if aggregate is None:
+        # No net contribution over the merge-base (empty-ahead branch is already
+        # handled by _cherry_merged).
+        return (False, None)
+    sha = target_ids.get(aggregate)
+    return (sha is not None, sha)
+
+
+def list_merged_branches(repo: Path, target: str) -> tuple[list[MergedBranch], list[str]]:
+    """Return (merged, protected_skipped) for `repo` measured against `target`.
+
+    Merged is decided by patch-id first, then the squash tree check -- never by
+    containment alone. Protected branches (current, the target's own short name,
+    `main`, `dev`) are never candidates and are returned so the caller can show
+    what was skipped and why.
+    """
+    repo = Path(repo).resolve()
+    protected = set(_NAMED_PROTECTED)
+    protected.add(_short(target))
+    current = _current_branch(repo)
+    if current is not None:
+        protected.add(current)
+
+    local = _local_branches(repo)
+    candidates = [b for b in local if b not in protected]
+    protected_skipped = [b for b in local if b in protected]
+    # Build target's first-parent squash-map ONCE, and only if a candidate that
+    # patch-id did not already resolve needs it -- most prunes never do.
+    target_ids: dict[str, str] | None = None
+
+    merged: list[MergedBranch] = []
+    for branch in candidates:
+        is_cherry, plus = _cherry_merged(repo, target, branch)
+        if is_cherry:
+            merged.append(
+                MergedBranch(branch, "patch-id", f"all commits present in {target} by patch-id (git cherry)")
+            )
+            continue
+        if target_ids is None:
+            target_ids = _target_squash_patch_ids(repo, target)
+        is_squash, sha = _squash_merged(repo, target, branch, target_ids)
+        if is_squash:
+            merged.append(
+                MergedBranch(
+                    branch,
+                    "squash",
+                    f"aggregate diff matches {target} commit {sha[:12]} by patch-id (squash-merged)",
+                )
+            )
+    return merged, protected_skipped
+
+
+def _delete_local_branch(repo: Path, branch: str) -> None:
+    # -D, not -d: we have already established the work is in the target by
+    # patch-id/tree, and git's own -d uses the same containment test we reject.
+    proc = git(repo, "branch", "-D", branch)
+    if proc.returncode != 0:
+        raise PruneError(proc.stderr.strip() or f"failed to delete {branch}")
+
+
+def prune(
+    repo: Path,
+    *,
+    target: str | None = None,
+    remote: str = "origin",
+    stored_target: str | None = None,
+    execute: bool = False,
+) -> PruneReport:
+    """List (and, with execute=True, delete) merged local branches in one repo."""
+    repo = Path(repo).resolve()
+    target_ref, source = resolve_target(repo, target, remote, stored_target)
+    merged, protected_skipped = list_merged_branches(repo, target_ref)
+
+    deleted: list[str] = []
+    failed: list[tuple[str, str]] = []
+    if execute:
+        for mb in merged:
+            try:
+                _delete_local_branch(repo, mb.name)
+                deleted.append(mb.name)
+            except PruneError as exc:
+                failed.append((mb.name, str(exc)))
+
+    return PruneReport(
+        target=target_ref,
+        target_source=source,
+        merged=merged,
+        protected_skipped=protected_skipped,
+        deleted=deleted,
+        failed=failed,
+        executed=execute,
+    )
+
+
+def render_report(report: PruneReport) -> str:
+    lines = [f"Target: {report.target}  ({report.target_source})"]
+    if not report.merged:
+        lines.append("No merged branches to prune.")
+        return "\n".join(lines)
+    verb = "Deleted" if report.executed else "Would delete"
+    for mb in report.merged:
+        marker = "  "
+        if report.executed:
+            if mb.name in report.deleted:
+                marker = "  ✓ "
+            elif any(mb.name == f for f, _ in report.failed):
+                marker = "  ✗ "
+        lines.append(f"{marker}{verb}: {mb.name}  [{mb.reason}] {mb.detail}")
+    for name, err in report.failed:
+        lines.append(f"  FAILED to delete {name}: {err}")
+    if not report.executed:
+        lines.append(f"\n{len(report.merged)} merged branch(es). Run with --execute to delete them.")
+    else:
+        lines.append(f"\nDeleted {len(report.deleted)} of {len(report.merged)} merged branch(es).")
+    return "\n".join(lines)