@ikon85/agent-workflow-kit 0.36.4 → 0.37.0

package/scripts/worktree-lifecycle/README.md

@@ -17,6 +17,8 @@ they do not carry a second branch regex, worktree traversal, or failure policy.
 - `setupEntry` and ordered `setupSteps`: the portable setup command and project
   setup sequence.
 - `riskyCommandPatterns`: commands that must target the active linked worktree.
+- `scratchPatterns`: consumer-owned glob patterns for untracked disposable
+  planning artefacts. No filename is assumed by Core.
 
 Unknown or malformed events fail open without changing repository state.
 Security-sensitive, profile-matched edits and commands fail closed only when
@@ -35,10 +37,22 @@ the core proves the target is unsafe.
 
 ## Cleanup
 
-`cleanup.py` previews by default. Removal refuses protected, dirty, or unmerged
-worktrees. The assessment reads `ANNAHMEN.md` before removal and returns its
-contents for propagation. `wrapup-land.py` invokes this same assessment after a
-merge and before killing processes or removing the worktree.
+`cleanup.py` previews by default. Removal refuses protected, tracked-dirty,
+non-scratch-dirty, open-PR, or unmerged worktrees. Profile-declared untracked
+scratch is named in the report but does not block removal. The assessment reads
+`ANNAHMEN.md` before removal and returns its contents for propagation.
+`wrapup-land.py` invokes this same assessment after a merge and before killing
+processes or removing the worktree.
+
+Explicit removal re-collects facts immediately before mutation, requires the
+same removable inventory, deletes only the exact contained regular scratch
+files from that inventory, and uses ordinary `git worktree remove`. It never
+bypasses Git's final concurrent-change check with force removal.
+
+`cleanup.py sweep` is the read-only inventory entrypoint. It accounts once for
+every linked worktree and local branch, reports issue/PR/merge/age/removal
+facts, and counts merged remote branches separately. It never removes a
+worktree or branch.
 
 Claude hook wiring and any Codex adaptation consume this same profile and core.
 An adapter may change only the surface event envelope; it must preserve the

package/scripts/worktree-lifecycle/cleanup.py

@@ -4,49 +4,216 @@
 from __future__ import annotations
 
 import argparse
+from contextlib import contextmanager
+from dataclasses import asdict, replace
 import json
+import os
+import stat
 import sys
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 
-from core import LifecycleError, cleanup_assessment, load_profile, main_worktree, run
+from core import (
+    LifecycleError,
+    classify_cleanup,
+    collect_cleanup_facts,
+    collect_sweep,
+    load_profile,
+    main_worktree,
+    run,
+)
 
 
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser()
     parser.add_argument("--profile", default="docs/agents/workflow-capabilities.json")
     parser.add_argument("--remove", action="store_true")
-    parser.add_argument("worktree")
+    parser.add_argument("--gh-command", default="gh")
+    parser.add_argument("worktree", nargs="?")
     return parser.parse_args()
 
 
+def parse_sweep_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="cleanup.py sweep")
+    parser.add_argument("--profile", default="docs/agents/workflow-capabilities.json")
+    parser.add_argument("--gh-command", default="gh")
+    return parser.parse_args(argv)
+
+
+def pr_state(gh_command: str, main: Path, branch: str) -> str:
+    remote = run(
+        ["git", "remote", "get-url", "origin"],
+        cwd=main,
+        check=False,
+    )
+    if remote.returncode != 0:
+        return "none"
+    result = run(
+        [
+            gh_command, "pr", "list", "--state", "all", "--head", branch,
+            "--json", "number,state,mergedAt",
+        ],
+        cwd=main,
+        check=False,
+    )
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout).strip()
+        raise LifecycleError(f"cannot determine PR state for {branch}: {detail}")
+    try:
+        prs = json.loads(result.stdout)
+    except json.JSONDecodeError as error:
+        raise LifecycleError(f"cannot determine PR state for {branch}: invalid gh output") from error
+    if any(str(pr.get("state", "")).upper() == "OPEN" for pr in prs):
+        return "open"
+    if any(pr.get("mergedAt") or str(pr.get("state", "")).upper() == "MERGED" for pr in prs):
+        return "merged"
+    return "none"
+
+
+def collect_assessment(profile, main: Path, worktree: Path, gh_command: str):
+    facts = collect_cleanup_facts(
+        main,
+        worktree,
+    )
+    state = pr_state(gh_command, main, facts.branch)
+    return classify_cleanup(profile, replace(facts, pr_state=state))
+
+
+@contextmanager
+def verified_worktree_root(root: Path, expected_device: int, expected_inode: int):
+    directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+    no_follow = getattr(os, "O_NOFOLLOW", 0)
+    descriptor = None
+    try:
+        descriptor = os.open(root, directory_flags | no_follow)
+        metadata = os.fstat(descriptor)
+        if (metadata.st_dev, metadata.st_ino) != (expected_device, expected_inode):
+            raise LifecycleError("worktree root changed before removal")
+        yield descriptor
+    except OSError as error:
+        raise LifecycleError("worktree root changed before removal") from error
+    finally:
+        if descriptor is not None:
+            os.close(descriptor)
+
+
+def remove_contained_regular(root_descriptor: int, relative: str) -> None:
+    path = PurePosixPath(relative)
+    if path.is_absolute() or not path.parts or any(part in {"", ".", ".."} for part in path.parts):
+        raise LifecycleError(f"unsafe scratch path: {relative}")
+    directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+    no_follow = getattr(os, "O_NOFOLLOW", 0)
+    descriptors = []
+    try:
+        current = root_descriptor
+        for component in path.parts[:-1]:
+            current = os.open(
+                component,
+                directory_flags | no_follow,
+                dir_fd=current,
+            )
+            descriptors.append(current)
+        metadata = os.stat(path.name, dir_fd=current, follow_symlinks=False)
+        if not stat.S_ISREG(metadata.st_mode):
+            raise LifecycleError(f"scratch path is not a regular file: {relative}")
+        os.unlink(path.name, dir_fd=current)
+    except OSError as error:
+        raise LifecycleError(f"scratch path changed before removal: {relative}") from error
+    finally:
+        for descriptor in reversed(descriptors):
+            os.close(descriptor)
+
+
 def execute(args: argparse.Namespace) -> dict:
     main = main_worktree(Path.cwd())
     profile_path = Path(args.profile)
     if not profile_path.is_absolute():
         profile_path = main / profile_path
     profile = load_profile(profile_path)
-    assessment = cleanup_assessment(profile, main, Path(args.worktree))
+    if not args.worktree:
+        raise LifecycleError("worktree is required")
+    worktree = Path(args.worktree)
+    assessment = collect_assessment(profile, main, worktree, args.gh_command)
     report = {
         "worktree": str(assessment.worktree),
         "branch": assessment.branch,
         "removable": assessment.removable,
         "reasons": list(assessment.reasons),
         "assumptions": assessment.assumptions,
+        "scratchFiles": list(assessment.scratch_files),
         "removed": False,
     }
     if not args.remove:
         return report
     if not assessment.removable:
         raise LifecycleError("; ".join(assessment.reasons))
-    run(["git", "worktree", "remove", str(assessment.worktree)], cwd=main)
+    latest = collect_assessment(profile, main, worktree, args.gh_command)
+    if not latest.removable:
+        raise LifecycleError(f"cleanup changed before removal: {'; '.join(latest.reasons)}")
+    if (
+        latest.branch != assessment.branch
+        or latest.scratch_files != assessment.scratch_files
+        or latest.assumptions != assessment.assumptions
+        or latest.root_device != assessment.root_device
+        or latest.root_inode != assessment.root_inode
+    ):
+        raise LifecycleError("cleanup changed before removal: inventory no longer matches preview")
+    with verified_worktree_root(
+        latest.worktree,
+        latest.root_device,
+        latest.root_inode,
+    ) as root_descriptor:
+        for scratch in latest.scratch_files:
+            remove_contained_regular(root_descriptor, scratch)
+    run(["git", "worktree", "remove", str(latest.worktree)], cwd=main)
     run(["git", "branch", "-d", assessment.branch], cwd=main)
     report["removed"] = True
     return report
 
 
+def sweep(args: argparse.Namespace) -> dict:
+    main = main_worktree(Path.cwd())
+    profile_path = Path(args.profile)
+    if not profile_path.is_absolute():
+        profile_path = main / profile_path
+    profile = load_profile(profile_path)
+    report = collect_sweep(
+        profile,
+        main,
+        lambda branch: pr_state(args.gh_command, main, branch),
+    )
+    payload = asdict(report)
+    return {
+        "mainBranch": payload["main_branch"],
+        "worktreeCount": payload["worktree_count"],
+        "localBranchCount": payload["local_branch_count"],
+        "mergedRemoteBranchCount": payload["merged_remote_branch_count"],
+        "rows": [
+            {
+                "kind": row["kind"],
+                "path": row["path"],
+                "branch": row["branch"],
+                "issue": row["issue"],
+                "prState": row["pr_state"],
+                "mergedIntoMain": row["merged_into_main"],
+                "lastCommitAgeSeconds": row["last_commit_age_seconds"],
+                "removable": row["removable"],
+                "reasons": list(row["reasons"]),
+                "verdictReason": row["verdict_reason"],
+                "scratchFiles": list(row["scratch_files"]),
+                "assumptions": row["assumptions"],
+            }
+            for row in payload["rows"]
+        ],
+    }
+
+
 def main() -> int:
     try:
-        print(json.dumps(execute(parse_args()), ensure_ascii=False, indent=2))
+        if len(sys.argv) > 1 and sys.argv[1] == "sweep":
+            result = sweep(parse_sweep_args(sys.argv[2:]))
+        else:
+            result = execute(parse_args())
+        print(json.dumps(result, ensure_ascii=False, indent=2))
         return 0
     except LifecycleError as error:
         print(f"STOP: {error}", file=sys.stderr)

package/scripts/worktree-lifecycle/core.py

@@ -3,9 +3,11 @@
 from __future__ import annotations
 
 import re
+from fnmatch import fnmatchcase
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any
+from time import time
+from typing import Any, Callable
 
 from profile import (
     LifecycleError,
@@ -44,12 +46,30 @@ class CleanupAssessment:
     branch: str
     assumptions: str
     reasons: tuple[str, ...]
+    root_device: int
+    root_inode: int
+    scratch_files: tuple[str, ...] = ()
 
     @property
     def removable(self) -> bool:
         return not self.reasons
 
 
+@dataclass(frozen=True)
+class CleanupFacts:
+    worktree: Path
+    branch: str
+    registered: bool
+    is_main: bool
+    tracked_files: tuple[str, ...]
+    untracked_files: tuple[str, ...]
+    merged: bool
+    pr_state: str
+    assumptions: str
+    root_device: int
+    root_inode: int
+
+
 def collect_facts(cwd: Path) -> RepoFacts:
     root = Path(run(["git", "rev-parse", "--show-toplevel"], cwd=cwd).stdout.strip()).resolve()
     main = main_worktree(root)
@@ -121,28 +141,60 @@ def cleanup_assessment(
     main: Path,
     target: Path,
     merge_target: str | None = None,
+    pr_state: str = "none",
 ) -> CleanupAssessment:
+    return classify_cleanup(
+        profile,
+        collect_cleanup_facts(
+            main,
+            target,
+            merge_target=merge_target,
+            pr_state=pr_state,
+        ),
+    )
+
+
+def collect_cleanup_facts(
+    main: Path,
+    target: Path,
+    *,
+    merge_target: str | None = None,
+    pr_state: str = "none",
+) -> CleanupFacts:
     worktree = target.resolve()
-    reasons = []
+    root_metadata = worktree.stat()
     branch = run(
         ["git", "-C", str(worktree), "branch", "--show-current"],
         cwd=main,
         check=False,
     ).stdout.strip()
-    if worktree not in registered_worktrees(main):
-        reasons.append("not a registered worktree")
-    if not branch:
-        reasons.append("detached or unreadable branch")
-    if branch in profile.protected_branches or worktree == main.resolve():
-        reasons.append(f"protected worktree branch: {branch or '<unknown>'}")
-    status = run(
-        ["git", "-C", str(worktree), "status", "--porcelain"],
+    tracked = set(run(
+        ["git", "-C", str(worktree), "diff", "--name-only"],
+        cwd=main,
+        check=False,
+    ).stdout.splitlines())
+    tracked.update(run(
+        ["git", "-C", str(worktree), "diff", "--cached", "--name-only"],
+        cwd=main,
+        check=False,
+    ).stdout.splitlines())
+    untracked = set(run(
+        ["git", "-C", str(worktree), "ls-files", "--others", "--exclude-standard"],
         cwd=main,
         check=False,
-    ).stdout
-    if status.strip():
-        reasons.append("dirty worktree")
-    if branch and branch not in profile.protected_branches:
+    ).stdout.splitlines())
+    untracked.update(run(
+        [
+            "git", "-C", str(worktree), "ls-files", "--others", "--ignored",
+            "--exclude-standard",
+        ],
+        cwd=main,
+        check=False,
+    ).stdout.splitlines())
+    # ANNAHMEN.md is governed separately: its bytes are returned before removal.
+    untracked.discard("ANNAHMEN.md")
+    merged = False
+    if branch:
         main_branch = merge_target or run(
             ["git", "-C", str(main), "branch", "--show-current"],
             cwd=main,
@@ -152,12 +204,273 @@ def cleanup_assessment(
             ["git", "merge-base", "--is-ancestor", branch, main_branch],
             cwd=main,
             check=False,
-        )
-        if merged.returncode != 0:
-            reasons.append(f"unmerged branch: {branch}")
+        ).returncode == 0
     assumptions_path = worktree / "ANNAHMEN.md"
     assumptions = assumptions_path.read_text(encoding="utf-8") if assumptions_path.is_file() else ""
-    return CleanupAssessment(worktree, branch, assumptions, tuple(reasons))
+    return CleanupFacts(
+        worktree=worktree,
+        branch=branch,
+        registered=worktree in registered_worktrees(main),
+        is_main=worktree == main.resolve(),
+        tracked_files=tuple(sorted(tracked)),
+        untracked_files=tuple(sorted(untracked)),
+        merged=merged,
+        pr_state=pr_state,
+        assumptions=assumptions,
+        root_device=root_metadata.st_dev,
+        root_inode=root_metadata.st_ino,
+    )
+
+
+def classify_cleanup(
+    profile: WorktreeProfile,
+    facts: CleanupFacts,
+) -> CleanupAssessment:
+    reasons = []
+    if not facts.registered:
+        reasons.append("not a registered worktree")
+    if not facts.branch:
+        reasons.append("detached or unreadable branch")
+    if facts.branch in profile.protected_branches or facts.is_main:
+        reasons.append(f"protected worktree branch: {facts.branch or '<unknown>'}")
+    scratch = sorted(
+        path for path in facts.untracked_files
+        if any(fnmatchcase(path, pattern) for pattern in profile.scratch_patterns)
+    )
+    non_scratch = sorted(set(facts.untracked_files).difference(scratch))
+    if facts.tracked_files:
+        reasons.append(
+            f"dirty worktree: tracked modifications: {', '.join(facts.tracked_files)}"
+        )
+    if non_scratch:
+        reasons.append(f"dirty worktree: untracked non-scratch: {', '.join(non_scratch)}")
+    if facts.pr_state == "open":
+        reasons.append("open PR")
+    if (
+        facts.branch
+        and facts.branch not in profile.protected_branches
+        and not facts.merged
+    ):
+        reasons.append(f"unmerged branch: {facts.branch}")
+    return CleanupAssessment(
+        facts.worktree,
+        facts.branch,
+        facts.assumptions,
+        tuple(reasons),
+        facts.root_device,
+        facts.root_inode,
+        tuple(scratch),
+    )
+
+
+@dataclass(frozen=True)
+class SweepRow:
+    kind: str
+    path: str | None
+    branch: str
+    issue: str | None
+    pr_state: str
+    merged_into_main: bool
+    last_commit_age_seconds: int
+    removable: bool
+    reasons: tuple[str, ...]
+    verdict_reason: str
+    scratch_files: tuple[str, ...] = ()
+    assumptions: str = ""
+
+
+@dataclass(frozen=True)
+class SweepReport:
+    main_branch: str
+    worktree_count: int
+    local_branch_count: int
+    merged_remote_branch_count: int
+    rows: tuple[SweepRow, ...]
+
+
+@dataclass(frozen=True)
+class SweepFactRow:
+    path: Path | None
+    branch: str
+    pr_state: str
+    merged_into_main: bool
+    last_commit_age_seconds: int
+    cleanup: CleanupFacts | None = None
+
+
+@dataclass(frozen=True)
+class SweepFacts:
+    main: Path
+    main_branch: str
+    worktree_count: int
+    local_branch_count: int
+    merged_remote_branch_count: int
+    rows: tuple[SweepFactRow, ...]
+
+
+def _worktree_branches(main: Path) -> tuple[dict[str, Path], tuple[Path, ...]]:
+    output = run(["git", "worktree", "list", "--porcelain"], cwd=main).stdout
+    linked: dict[str, Path] = {}
+    detached = []
+    path: Path | None = None
+    branch = ""
+    for line in [*output.splitlines(), ""]:
+        if line.startswith("worktree "):
+            path = Path(line.split(" ", 1)[1]).resolve()
+            branch = ""
+        elif line.startswith("branch refs/heads/"):
+            branch = line.removeprefix("branch refs/heads/")
+        elif not line and path is not None:
+            if branch:
+                linked[branch] = path
+            else:
+                detached.append(path)
+            path = None
+    return linked, tuple(detached)
+
+
+def collect_sweep_facts(
+    profile: WorktreeProfile,
+    main: Path,
+    pr_lookup: Callable[[str], str],
+    *,
+    now: int | None = None,
+) -> SweepFacts:
+    """Gather the complete read-only inventory without making removal decisions."""
+    main = main.resolve()
+    main_branch = run(
+        ["git", "-C", str(main), "branch", "--show-current"], cwd=main
+    ).stdout.strip()
+    linked, detached = _worktree_branches(main)
+    refs = run(
+        [
+            "git", "for-each-ref",
+            "--format=%(refname:short)\t%(committerdate:unix)",
+            "refs/heads/",
+        ],
+        cwd=main,
+    ).stdout.splitlines()
+    timestamp = int(time()) if now is None else now
+    rows: list[SweepFactRow] = []
+    for line in refs:
+        branch, commit_time = line.rsplit("\t", 1)
+        path = linked.get(branch)
+        pr_state = pr_lookup(branch)
+        merged = run(
+            ["git", "merge-base", "--is-ancestor", branch, main_branch],
+            cwd=main,
+            check=False,
+        ).returncode == 0
+        rows.append(SweepFactRow(
+            path=path,
+            branch=branch,
+            pr_state=pr_state,
+            merged_into_main=merged,
+            last_commit_age_seconds=max(0, timestamp - int(commit_time)),
+            cleanup=collect_cleanup_facts(
+                main,
+                path,
+                merge_target=main_branch,
+                pr_state=pr_state,
+            ) if path is not None else None,
+        ))
+    for path in detached:
+        commit_time = run(
+            ["git", "-C", str(path), "show", "-s", "--format=%ct", "HEAD"],
+            cwd=main,
+        ).stdout.strip()
+        rows.append(SweepFactRow(
+            path=path,
+            branch="",
+            pr_state="none",
+            merged_into_main=False,
+            last_commit_age_seconds=max(0, timestamp - int(commit_time)),
+        ))
+    remote_merged = run(
+        [
+            "git", "for-each-ref",
+            f"--merged={main_branch}",
+            "--format=%(refname:short)",
+            "refs/remotes/",
+        ],
+        cwd=main,
+        check=False,
+    ).stdout.splitlines()
+    return SweepFacts(
+        main=main,
+        main_branch=main_branch,
+        worktree_count=len(linked) + len(detached),
+        local_branch_count=len(refs),
+        merged_remote_branch_count=len([
+            branch for branch in remote_merged if branch and not branch.endswith("/HEAD")
+        ]),
+        rows=tuple(rows),
+    )
+
+
+def classify_sweep(profile: WorktreeProfile, facts: SweepFacts) -> SweepReport:
+    """Apply profile policy to already-collected inventory facts."""
+    rows = []
+    for fact in facts.rows:
+        if fact.cleanup is not None:
+            assessment = classify_cleanup(profile, fact.cleanup)
+            reasons = assessment.reasons
+            scratch = assessment.scratch_files
+            assumptions = assessment.assumptions
+        elif fact.path is not None:
+            reasons = ("detached or unreadable branch",)
+            scratch = ()
+            assumptions = ""
+        else:
+            reasons_list = []
+            if fact.branch in profile.protected_branches:
+                reasons_list.append(f"protected branch: {fact.branch}")
+            if fact.pr_state == "open":
+                reasons_list.append("open PR")
+            if not fact.merged_into_main:
+                reasons_list.append(f"unmerged branch: {fact.branch}")
+            reasons = tuple(reasons_list)
+            scratch = ()
+            assumptions = ""
+        rows.append(SweepRow(
+            kind="worktree" if fact.path is not None else "branch",
+            path=str(fact.path) if fact.path is not None else None,
+            branch=fact.branch,
+            issue=profile.issue_from_branch(fact.branch),
+            pr_state=fact.pr_state,
+            merged_into_main=fact.merged_into_main,
+            last_commit_age_seconds=fact.last_commit_age_seconds,
+            removable=not reasons,
+            reasons=reasons,
+            verdict_reason=(
+                "; ".join(reasons)
+                if reasons
+                else (
+                    f"merged into {facts.main_branch}; scratch-only: {', '.join(scratch)}"
+                    if scratch
+                    else f"merged into {facts.main_branch}; no blocking work"
+                )
+            ),
+            scratch_files=scratch,
+            assumptions=assumptions,
+        ))
+    return SweepReport(
+        main_branch=facts.main_branch,
+        worktree_count=facts.worktree_count,
+        local_branch_count=facts.local_branch_count,
+        merged_remote_branch_count=facts.merged_remote_branch_count,
+        rows=tuple(rows),
+    )
+
+
+def collect_sweep(
+    profile: WorktreeProfile,
+    main: Path,
+    pr_lookup: Callable[[str], str],
+    *,
+    now: int | None = None,
+) -> SweepReport:
+    return classify_sweep(profile, collect_sweep_facts(profile, main, pr_lookup, now=now))
 
 
 def edit_decision(

package/scripts/worktree-lifecycle/profile.py

@@ -25,6 +25,7 @@ class WorktreeProfile:
     branch_regex: str
     setup_entry: str
     risky_command_patterns: tuple[str, ...]
+    scratch_patterns: tuple[str, ...]
 
     def branch_name(self, issue: str, slug: str, branch_type: str) -> str:
         return _render(self.branch_template, issue, slug, branch_type)
@@ -74,6 +75,7 @@ def load_profile(path: Path) -> WorktreeProfile:
             r"\b(?:npm|pnpm|yarn)\s+(?:run\s+)?(?:test|typecheck|build)\b",
             r"\bgit\s+(?:commit|push)\b",
         )),
+        scratch_patterns=tuple(raw.get("scratchPatterns") or ()),
     )