@ikon85/agent-workflow-kit 0.36.5 → 0.38.0

package/scripts/test_wrapup_land.py

@@ -0,0 +1,428 @@
+#!/usr/bin/env python3
+"""Focused contracts for wrapup's bounded PR-check merge gate."""
+
+import importlib.util
+import io
+import json
+import subprocess
+import unittest
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+WRAPUP = REPO / "scripts/wrapup-land.py"
+
+
+def load_wrapup():
+    spec = importlib.util.spec_from_file_location("wrapup_land_check_gate", WRAPUP)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def completed(payload, returncode=0, stderr=""):
+    return subprocess.CompletedProcess([], returncode, json.dumps(payload), stderr)
+
+
+def pr_snapshot(**overrides):
+    snapshot = {
+        "state": "OPEN",
+        "mergeable": "MERGEABLE",
+        "mergeStateStatus": "CLEAN",
+        "statusCheckRollup": [],
+        "baseRefName": "main",
+    }
+    snapshot.update(overrides)
+    return snapshot
+
+
+def gate_runner(snapshots, required_checks):
+    snapshots = iter(snapshots)
+    required_checks = iter(required_checks)
+
+    def runner(cmd, **_kwargs):
+        if cmd[:3] == ["gh", "pr", "view"]:
+            return completed(next(snapshots))
+        if cmd[:3] == ["gh", "pr", "checks"]:
+            checks = next(required_checks)
+            return completed(checks, returncode=1 if any(
+                check.get("state") == "FAILURE" for check in checks
+            ) else 0)
+        raise AssertionError(f"unexpected command: {cmd}")
+
+    return runner
+
+
+class FakeClock:
+    def __init__(self):
+        self.now = 0.0
+
+    def monotonic(self):
+        return self.now
+
+    def sleep(self, seconds):
+        self.now += seconds
+
+
+class WrapupCheckGateContract(unittest.TestCase):
+    def setUp(self):
+        self.wrapup = load_wrapup()
+
+    def test_required_check_names_come_from_active_base_branch_rules(self):
+        commands = []
+
+        def runner(cmd, **_kwargs):
+            commands.append(cmd)
+            if cmd[:3] == ["gh", "repo", "view"]:
+                return completed({"nameWithOwner": "acme/repo"})
+            if cmd[:2] == ["gh", "api"]:
+                return completed([
+                    {"type": "pull_request"},
+                    {
+                        "type": "required_status_checks",
+                        "parameters": {
+                            "required_status_checks": [
+                                {"context": "test", "integration_id": 1},
+                                {"context": "lint", "integration_id": 1},
+                            ],
+                        },
+                    },
+                ])
+            raise AssertionError(f"unexpected command: {cmd}")
+
+        self.assertEqual(
+            self.wrapup._configured_required_check_names(
+                pr_snapshot(baseRefName="release/next"), runner
+            ),
+            {"test", "lint"},
+        )
+        self.assertIn(
+            ["gh", "api", "repos/acme/repo/rules/branches/release%2Fnext"],
+            commands,
+        )
+
+    def test_pending_checks_are_visible_then_green_checks_proceed(self):
+        snapshots = iter([
+            pr_snapshot(mergeable="UNKNOWN", mergeStateStatus="BLOCKED"),
+            pr_snapshot(),
+        ])
+        checks = iter([
+            [{"name": "test", "state": "PENDING", "link": "https://example.test"}],
+            [{"name": "test", "state": "SUCCESS", "link": "https://example.test"}],
+        ])
+        calls = []
+
+        def runner(cmd, **_kwargs):
+            calls.append(cmd)
+            if cmd[:3] == ["gh", "pr", "view"]:
+                return completed(next(snapshots))
+            if cmd[:3] == ["gh", "pr", "checks"]:
+                return completed(next(checks))
+            raise AssertionError(f"unexpected command: {cmd}")
+
+        clock = FakeClock()
+        progress = io.StringIO()
+        already_merged = self.wrapup.wait_for_merge_gate(
+            "42",
+            timeout_seconds=30,
+            poll_interval=5,
+            command_runner=runner,
+            clock=clock.monotonic,
+            sleeper=clock.sleep,
+            progress_stream=progress,
+            configured_required_names={"test"},
+        )
+
+        self.assertFalse(already_merged)
+        self.assertEqual(len(calls), 4)
+        self.assertIn("waiting for PR #42 checks", progress.getvalue())
+        self.assertIn("test", progress.getvalue())
+
+    def test_explicit_null_conclusion_waits_even_with_green_legacy_state(self):
+        checks = [{
+            "name": "test",
+            "status": "COMPLETED",
+            "conclusion": None,
+            "state": "SUCCESS",
+        }]
+
+        self.assertEqual(self.wrapup.pending_checks(checks), checks)
+
+    def test_terminal_red_check_stops_before_merge_and_names_check(self):
+        snapshot = pr_snapshot(mergeStateStatus="BLOCKED")
+        checks = [[{
+            "name": "test",
+            "state": "FAILURE",
+            "link": "https://example.test",
+        }]]
+
+        with self.assertRaises(self.wrapup.Stop) as stopped:
+            self.wrapup.wait_for_merge_gate(
+                "42",
+                command_runner=gate_runner([snapshot], checks),
+                configured_required_names={"test"},
+            )
+
+        self.assertEqual(stopped.exception.step, "0c merge-gate")
+        self.assertIn("test", stopped.exception.detail)
+        self.assertNotIn("infrastructure failure", stopped.exception.detail)
+
+    def test_timeout_names_pending_checks_and_elapsed_time(self):
+        snapshot = pr_snapshot(mergeable="UNKNOWN", mergeStateStatus="BLOCKED")
+        checks = [
+            {"name": "test", "state": "QUEUED"},
+            {"name": "lint", "state": "PENDING"},
+        ]
+        clock = FakeClock()
+
+        with self.assertRaises(self.wrapup.Stop) as stopped:
+            self.wrapup.wait_for_merge_gate(
+                "42",
+                timeout_seconds=10,
+                poll_interval=5,
+                command_runner=gate_runner(
+                    [snapshot, snapshot, snapshot],
+                    [checks, checks, checks],
+                ),
+                clock=clock.monotonic,
+                sleeper=clock.sleep,
+                progress_stream=io.StringIO(),
+                configured_required_names={"test", "lint"},
+            )
+
+        self.assertIn("wait budget exceeded", stopped.exception.reason)
+        self.assertIn("elapsed=10.0s", stopped.exception.detail)
+        self.assertIn("test", stopped.exception.detail)
+        self.assertIn("lint", stopped.exception.detail)
+
+    def test_already_merged_pr_bypasses_check_wait(self):
+        snapshot = pr_snapshot(
+            state="MERGED", mergeable="UNKNOWN", mergeStateStatus="UNKNOWN"
+        )
+        clock = FakeClock()
+        commands = []
+
+        def runner(cmd, **_kwargs):
+            commands.append(cmd)
+            return completed(snapshot)
+
+        already_merged = self.wrapup.wait_for_merge_gate(
+            "42",
+            command_runner=runner,
+            clock=clock.monotonic,
+            sleeper=clock.sleep,
+            progress_stream=io.StringIO(),
+            configured_required_names={"test"},
+        )
+
+        self.assertTrue(already_merged)
+        self.assertEqual(clock.now, 0)
+        self.assertEqual(len(commands), 1)
+
+    def test_optional_red_check_does_not_block_when_required_check_is_green(self):
+        snapshot = pr_snapshot(
+            mergeStateStatus="BLOCKED",
+            statusCheckRollup=[{
+                "name": "advisory-browser",
+                "status": "COMPLETED",
+                "conclusion": "FAILURE",
+            }],
+        )
+        runner = gate_runner([snapshot], [[{
+            "name": "test",
+            "state": "SUCCESS",
+            "link": "https://example.test",
+        }]])
+
+        self.assertFalse(self.wrapup.wait_for_merge_gate(
+            "42", command_runner=runner, configured_required_names={"test"}
+        ))
+
+    def test_fresh_pr_waits_until_required_checks_become_visible(self):
+        snapshots = [
+            pr_snapshot(mergeable="UNKNOWN", mergeStateStatus="BLOCKED"),
+            pr_snapshot(mergeable="UNKNOWN", mergeStateStatus="BLOCKED"),
+            pr_snapshot(),
+        ]
+        required = [
+            [],
+            [{"name": "test", "state": "PENDING"}],
+            [{"name": "test", "state": "SUCCESS"}],
+        ]
+        clock = FakeClock()
+        progress = io.StringIO()
+
+        self.assertFalse(self.wrapup.wait_for_merge_gate(
+            "42",
+            timeout_seconds=30,
+            poll_interval=5,
+            command_runner=gate_runner(snapshots, required),
+            clock=clock.monotonic,
+            sleeper=clock.sleep,
+            progress_stream=progress,
+            configured_required_names={"test"},
+        ))
+        self.assertIn("test (awaiting discovery)", progress.getvalue())
+        self.assertIn("test", progress.getvalue())
+
+    def test_visible_optional_check_cannot_mask_required_discovery(self):
+        snapshot = pr_snapshot(
+            mergeStateStatus="BLOCKED",
+            statusCheckRollup=[{
+                "name": "advisory-browser",
+                "status": "COMPLETED",
+                "conclusion": "FAILURE",
+            }],
+        )
+
+        clock = FakeClock()
+        with self.assertRaises(self.wrapup.Stop) as stopped:
+            self.wrapup.wait_for_merge_gate(
+                "42",
+                timeout_seconds=0,
+                command_runner=gate_runner([snapshot], [[]]),
+                clock=clock.monotonic,
+                sleeper=clock.sleep,
+                progress_stream=io.StringIO(),
+                configured_required_names={"test"},
+            )
+        self.assertIn("test (awaiting discovery)", stopped.exception.detail)
+
+    def test_zero_step_failed_job_is_named_as_infrastructure_failure(self):
+        snapshot = pr_snapshot(mergeStateStatus="BLOCKED")
+        check = {
+            "name": "test",
+            "state": "FAILURE",
+            "link": "https://github.com/acme/repo/actions/runs/123/job/456",
+        }
+        commands = []
+
+        def runner(cmd, **_kwargs):
+            commands.append(cmd)
+            if cmd[:3] == ["gh", "pr", "view"]:
+                return completed(snapshot)
+            if cmd[:3] == ["gh", "pr", "checks"]:
+                return completed([check], returncode=1)
+            if "--json" in cmd:
+                return completed({
+                    "jobs": [{
+                        "databaseId": 456,
+                        "name": "test",
+                        "conclusion": "failure",
+                        "steps": [],
+                    }],
+                })
+            return subprocess.CompletedProcess(
+                cmd, 1, "", "log unavailable"
+            )
+
+        with self.assertRaises(self.wrapup.Stop) as stopped:
+            self.wrapup.wait_for_merge_gate(
+                "42", command_runner=runner, configured_required_names={"test"}
+            )
+
+        self.assertIn("test", stopped.exception.detail)
+        self.assertIn("infrastructure failure", stopped.exception.detail)
+        self.assertIn(["gh", "run", "view", "123", "--json", "jobs"], commands)
+        self.assertEqual(
+            [cmd[:3] for cmd in commands].count(["gh", "run", "view"]), 1
+        )
+
+    def test_billing_annotation_is_sanitized_and_bounded(self):
+        noisy = (
+            "The job was not started because recent account payments have failed. "
+            + "TOKEN=secret "
+            + "x" * 1000
+        )
+        check = {
+            "name": "test",
+            "state": "FAILURE",
+            "link": "https://github.com/acme/repo/actions/runs/123/job/456",
+        }
+
+        def runner(cmd, **_kwargs):
+            if "--json" in cmd:
+                return completed({"jobs": [{
+                    "databaseId": 456,
+                    "name": "test",
+                    "conclusion": "failure",
+                    "steps": [{"name": "x"}],
+                }]})
+            self.assertIn("--job", cmd)
+            self.assertIn("456", cmd)
+            return subprocess.CompletedProcess(cmd, 0, noisy, "")
+
+        diagnosis = self.wrapup.infrastructure_failure_diagnosis(
+            check, command_runner=runner
+        )
+
+        self.assertIn("infrastructure failure", diagnosis)
+        self.assertLessEqual(len(diagnosis), self.wrapup.MAX_EXTERNAL_DETAIL)
+        self.assertNotIn("\n", diagnosis)
+
+    def test_mixed_run_does_not_misclassify_real_test_failure_as_infra(self):
+        check = {
+            "name": "test",
+            "state": "FAILURE",
+            "link": "https://github.com/acme/repo/actions/runs/123/job/456",
+        }
+        commands = []
+
+        def runner(cmd, **_kwargs):
+            commands.append(cmd)
+            if "--json" in cmd:
+                return completed({"jobs": [
+                    {
+                        "databaseId": 111,
+                        "name": "setup",
+                        "conclusion": "startup_failure",
+                        "steps": [],
+                    },
+                    {
+                        "databaseId": 456,
+                        "name": "test",
+                        "conclusion": "failure",
+                        "steps": [{"name": "Run tests", "conclusion": "failure"}],
+                    },
+                ]})
+            return subprocess.CompletedProcess(
+                cmd, 0, "AssertionError: expected green", ""
+            )
+
+        diagnosis = self.wrapup.infrastructure_failure_diagnosis(
+            check, command_runner=runner
+        )
+
+        self.assertEqual(diagnosis, "")
+        self.assertIn(
+            ["gh", "run", "view", "123", "--job", "456", "--log-failed"],
+            commands,
+        )
+
+    def test_check_without_unique_job_match_is_not_classified_from_run_logs(self):
+        check = {
+            "name": "test",
+            "state": "FAILURE",
+            "link": "https://github.com/acme/repo/actions/runs/123",
+        }
+        commands = []
+
+        def runner(cmd, **_kwargs):
+            commands.append(cmd)
+            if "--json" in cmd:
+                return completed({"jobs": [
+                    {"name": "test", "conclusion": "failure", "steps": []},
+                    {"name": "test", "conclusion": "failure", "steps": []},
+                ]})
+            raise AssertionError("aggregate run logs must not be inspected")
+
+        self.assertEqual(
+            self.wrapup.infrastructure_failure_diagnosis(
+                check, command_runner=runner
+            ),
+            "",
+        )
+        self.assertEqual(len(commands), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/workflow-advisories/core.py

@@ -261,11 +261,47 @@ def convention_freshness_decision(profile: dict, root: Path) -> Decision:
     )
 
 
-def migration_reminder_decision(profile: dict, payload: dict) -> Decision:
+def _migration_session_marker(profile: dict, payload: dict, root: Path) -> Path | None:
+    session_id = payload.get("session_id")
+    if not isinstance(session_id, str) or not session_id:
+        return None
+    state_dir = root / profile.get("baseline", {}).get(
+        "stateDir", ".claude/logs/advisory-state",
+    )
+    safe_session = re.sub(r"[^A-Za-z0-9._-]", "-", session_id)
+    return state_dir / f"{safe_session}.migration.hinted"
+
+
+def _unquoted_shell_text(command: str) -> str:
+    visible: list[str] = []
+    quote: str | None = None
+    escaped = False
+    for character in command:
+        if escaped:
+            visible.append(" " if quote else character)
+            escaped = False
+        elif character == "\\" and quote != "'":
+            visible.append(" ")
+            escaped = True
+        elif quote:
+            visible.append(" ")
+            if character == quote:
+                quote = None
+        elif character in {"'", '"', "`"}:
+            visible.append(" ")
+            quote = character
+        else:
+            visible.append(character)
+    return "".join(visible)
+
+
+def migration_reminder_decision(
+    profile: dict, payload: dict, root: Path,
+) -> Decision:
     config = profile.get("migration", {})
     if payload.get("tool_name") != "Bash":
         return Decision(None, "PostToolUse")
-    command = payload.get("tool_input", {}).get("command", "")
+    command = _unquoted_shell_text(payload.get("tool_input", {}).get("command", ""))
     if not any(
         re.search(pattern, command)
         for pattern in config.get("commandMatchers", [])
@@ -275,6 +311,12 @@ def migration_reminder_decision(profile: dict, payload: dict) -> Decision:
     refresh = config.get("refreshCommand", [])
     if not artifact or not refresh:
         return Decision(None, "PostToolUse")
+    marker = _migration_session_marker(profile, payload, root)
+    if marker and marker.exists():
+        return Decision(None, "PostToolUse")
+    if marker:
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        marker.write_text(f"{payload['session_id']}\n", encoding="utf-8")
     message = (
         f"Migration advisory: refresh {artifact} with `{' '.join(refresh)}` "
         "before treating the migration result as complete."

package/scripts/worktree-lifecycle/README.md

@@ -17,6 +17,17 @@ 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.
+- `wrapup.landingGeneratedArtifactPatterns`: an explicitly reviewed
+  consumer-owned allowlist for outputs created by the landing commands. It is
+  deletion authority, so setup never derives it from `.gitignore` alone and
+  update never installs a universal default.
+
+Profile globs use repository-relative POSIX semantics. `*` stays inside one
+path segment; `**` crosses `/`, and leading `**/` also matches the repository
+root. For example, `**/__pycache__/**` matches both root and nested caches,
+while `dist-kit/*` does not match `dist-kit/a/b`.
 
 Unknown or malformed events fail open without changing repository state.
 Security-sensitive, profile-matched edits and commands fail closed only when
@@ -35,10 +46,121 @@ 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.
+
+The generic setup route atomically records its ignored and complete
+untracked-file inventories in the linked worktree's Git metadata after its
+configured setup steps. The record is bound to the worktree path, branch, root
+device/inode, and setup HEAD, and carries a canonical digest. Existing
+worktrees can receive a conservative baseline only when they are the exact
+registered no-follow directory on an attached branch with a clean tracked
+worktree and index. Setup reuse defers that backfill, without blocking the
+existing worktree, while tracked work is dirty or landing-generated blockers
+are present. Landing classifies those blockers before writing any baseline;
+after they are moved, every remaining current ignored and untracked path is
+recorded as pre-existing and therefore protected. A corrupt baseline or an
+active landing attempt is never overwritten. The claim-bound session route
+below captures its stricter baseline before project setup so a failed setup has
+an exact recovery boundary.
+
+Before merge, the committed worktree profile may only nominate exact,
+identity-bound landing candidates; it authorizes no deletion. After merge and
+`fetch origin/main`, cleanup reloads the profile directly from canonical
+`origin/main`, requires its scratch and generator policies to equal the
+worktree candidate and the policy digest frozen at attempt start, and only then
+authorizes mutation. Every supplied generator-evidence path is independently
+checked against that canonical generator policy. A missing policy is distinct
+from an explicit empty policy. An unmerged or transient branch policy therefore
+cannot grant itself broader cleanup authority.
+
+The landing adapter may carry exact scratch evidence only for current ignored
+files that match the consumer-owned
+`wrapup.landingGeneratedArtifactPatterns` profile and were absent from that
+creation baseline. Missing, changed, or incoherent provenance stops landing
+cleanup. Initial/profile-matched files, unmatched files, symlinks, and writes
+after the landing evidence snapshot remain cleanup stops; deletion still uses
+the same descriptor-bound regular-file primitive and a second inventory check.
+Mutable session logs belong in explicit `scratchPatterns`, not in the landing
+generator allowlist: their identity is frozen at final cleanup assessment, so
+normal logging before teardown remains live while a later append or replacement
+still stops deletion.
+Landing-start blockers are classified before a journal is written, so moving a
+protected blocker permits a clean next attempt. An explicit relinquish archives
+either a started or frozen attempt, including drifted evidence, without
+deleting or claiming any file; the next preflight treats every current file as
+pre-existing. Exact unchanged frozen evidence remains directly resumable.
+
+`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.
+
+## Session-owned teardown
+
+`session.py` is the narrower orchestration route. It binds one receipt in the
+Git common directory to the active `wave-active/<anchor>` annotated claim:
+
+```sh
+python3 scripts/worktree-lifecycle/session.py begin --anchor <n> --owner <run> --base <wave-head>
+python3 scripts/worktree-lifecycle/session.py create --anchor <n> --owner <run> --base <current-wave-head> <issue> <slug> <type>
+python3 scripts/worktree-lifecycle/session.py recover --anchor <n> --owner <run> --branch <exact-branch>
+python3 scripts/worktree-lifecycle/session.py seal --anchor <n> --owner <run>
+python3 scripts/worktree-lifecycle/session.py inspect --anchor <n> --owner <run> --main origin/main
+python3 scripts/worktree-lifecycle/session.py teardown --anchor <n> --owner <run> --main origin/main
+```
+
+Only `create` can add an inventory row, and it refuses any branch or path that
+already existed. It journals a provisional exact row before `git worktree add`,
+then captures the shared artifact baseline before project setup and promotes
+the row only after setup succeeds. Session inspection
+therefore accepts generated scratch only when the exact path matches the
+profile and is absent from the creation baseline; missing, changed, or
+incoherent provenance stops. `seal` records the final exact branch OIDs.
+Inspection reports ancestry, one-to-one stable patch equivalence, unique
+content, and ambiguity separately. Empty commits, non-ancestry merge commits,
+duplicate patch IDs, open or unreadable PR evidence, dirt, protected names,
+stale registrations, recreated removed targets, and identity drift stop the
+whole teardown before mutation.
+
+If setup fails, the provisional row becomes `recovery-pending`. Automatic and
+explicit `recover` use the same bounded route: active claim and receipt,
+protected name, PR state, exact ref OID, registration/root identity, and the
+creation baseline are revalidated. A branch-only remainder is compare-deleted
+only at its provisional OID. A registered worktree whose add succeeded before
+root journaling is adopted only when its Git registration/backlink, branch,
+OID, and exact-clean inventory all match.
+
+For failed project setup, exact index/worktree diff hashes and paths are frozen
+without storing diff content. Exact regular-file or no-follow symlink identity
+is frozen for every setup-created untracked path. Recovery revalidates that
+evidence, restores only the frozen tracked paths to the creation OID, and
+unlinks only matching untracked identities; later foreign files,
+modifications, or replacements stop without losing receipt ownership. If
+identity capture cannot finish, the receipt retains only a bounded failure
+class and can retry from the unchanged inventory or an exact-clean worktree.
+Raw command, exception, stdout, and stderr text is never retained or archived.
+Recovery uses ordinary worktree removal and compare-deletes the exact ref.
+
+Teardown re-runs that complete assessment, archives every recovery OID in the
+receipt before its first mutation, and revalidates canonical main, the active
+claim and receipt, profile protection, PR state, branch OID, worktree
+registration/root identity, dirt, and the exact scratch inventory immediately
+before each target mutation. After ordinary worktree removal it rechecks the
+ref-side gates, then compare-deletes only the recorded local refs with
+`git update-ref -d <ref> <expected-oid>`. A concurrent ref move therefore
+survives, while a partial run keeps its recovery OIDs and can resume. Generic
+cleanup and sweep never consume this ownership route and never infer authority
+over a foreign 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/capabilities.json

@@ -39,7 +39,15 @@
     {
       "historicalPath": "scripts/cleanup-worktrees.sh",
       "artifact": "scripts/worktree-lifecycle/cleanup.py",
-      "primitives": ["profile", "git-facts", "cleanup-safety"]
+      "supportingArtifacts": ["scripts/worktree-lifecycle/session.py"],
+      "primitives": [
+        "profile",
+        "git-facts",
+        "cleanup-safety",
+        "claim-bound-session-receipt",
+        "patch-equivalence",
+        "compare-and-delete"
+      ]
     }
   ]
 }