@ikon85/agent-workflow-kit 0.21.0 → 0.22.0

package/.agents/skills/setup-workflow/SKILL.md

@@ -26,6 +26,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `## Agent skills` + `## Prod` in CLAUDE.md **and** AGENTS.md | one-line pointers + deploy target (Sections C/G + Write) |
 | `.github/workflows/agent-workflow-kit-update.yml` | optional tested Kit update pull request for GitHub consumers (Section A2) |
 | `docs/agents/census.md` | optional-census choice, paths, state, and safe disable contract seeded from [census.md](./census.md) (Section A3) |
+| `docs/agents/workflow-capabilities.json` | consumer-owned capability profile, including optional Worktree Lifecycle activation (Section A4) |
 
 ## Idempotency contract — read before writing anything
 
@@ -56,6 +57,7 @@ Read the current state; don't assume. For every target file, read its first line
 - `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/` — domain-doc layout.
 - `docs/agents/`, `docs/agents/skills/`, `docs/conventions/` — prior output of this skill.
 - `docs/agents/census.md`, `.census/profile.json`, `.census/active.json` — an existing census choice or consumer-owned census to adopt.
+- `docs/agents/workflow-capabilities.json`, `.claude/settings.json` — an existing Worktree Lifecycle choice/profile and hook wiring to adopt.
 - `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
 
 ### 2. Section A — Issue tracker
@@ -135,6 +137,34 @@ activate without rerunning setup. Disable enforcement first, but retain every
 consumer-owned profile, scanner, test, and active snapshot unless the user
 separately approves deletion. Repeated runs are no-ops after reconciliation.
 
+### 2c. Section A4 — Optional Worktree Lifecycle
+
+> Worktree Lifecycle is one consumer capability for isolated setup, shared
+> branch/worktree facts, enforcement, handoff, and safe cleanup. The profile is
+> tracked and consumer-owned; hook wiring activates only after an explicit yes.
+
+Read [worktree-lifecycle.md](./worktree-lifecycle.md) in full. Reconcile the
+complete `yes / later / no / existing / disable` matrix from its structured
+contract. If no choice exists, ask: *"Should setup activate the portable
+Worktree Lifecycle for this repository?"* Offer exactly **Yes**, **Later**, and
+**No**.
+
+- **Yes** — create or deepen only the `worktreeLifecycle` section in
+  `docs/agents/workflow-capabilities.json`, preserve every other section and
+  unknown key, and reconcile only the exact kit-owned hook commands listed in
+  the seed.
+- **Later / No** — record the choice in the tracked profile without installing
+  hook wiring. Ordinary reruns do not ask again.
+- **Existing** — adopt the current section and wiring without normalizing
+  consumer-owned values.
+- **Disable** — remove only the exact kit-owned hook commands first, then set
+  `enabled: false`; retain the profile, setup policy, and unknown keys.
+
+The default setup entry is
+`python3 scripts/worktree-lifecycle/setup.py`; a proven consumer-native helper
+may remain the configured `setupEntry` for parity. The handoff advisory always
+reads that configured entry and never hardcodes a project script.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
@@ -220,6 +250,12 @@ pre-existing consumer-owned census file. `yes`, `later`, `no`, and an adopted
 existing census are terminal for ordinary setup reruns. Only an explicit user
 request changes a recorded choice.
 
+For `docs/agents/workflow-capabilities.json`, reconcile only the selected
+capability section. Never replace the whole file: Project Release, Memory
+Lifecycle, Worktree Lifecycle, future sections, and unknown consumer keys share
+this profile. Apply the Worktree Lifecycle transition and hook ownership rules
+from [worktree-lifecycle.md](./worktree-lifecycle.md) transactionally.
+
 For the **`## Workflow`**, **`## Agent skills`**, and **`## Prod`** blocks, reconcile per section in **both** CLAUDE.md and AGENTS.md that exist:
 
 - If **both** files exist → write/update the block in **both** (keep them coherent — Codex is a first-class surface).

package/.agents/skills/setup-workflow/worktree-lifecycle.md

@@ -0,0 +1,81 @@
+# Worktree Lifecycle setup contract
+
+Worktree Lifecycle is one opt-in capability backed by the consumer-owned
+`docs/agents/workflow-capabilities.json` profile. Enabling it activates the
+portable setup entry, shared branch/worktree facts, thin hook adapters, handoff
+advisory, and safe cleanup policy as one unit.
+
+## Choice matrix
+
+| State | Setup action |
+|---|---|
+| `missing` | Ask `yes / later / no`; do not infer or write before the answer. |
+| `yes` | Reconcile the enabled profile and exact kit-owned hook commands. |
+| `later` | Record the retryable deferral; do not activate hooks. |
+| `no` | Record the opt-out; do not activate hooks. |
+| `existing` | Adopt the consumer profile byte-safely and preserve unknown keys. |
+| `disable` | Remove only kit-owned hook wiring, then set `enabled: false`; retain the profile and unknown keys. |
+
+```json worktree-lifecycle-setup-effects
+[
+  {
+    "state": "missing",
+    "choice": null,
+    "operations": []
+  },
+  {
+    "state": "yes",
+    "choice": "yes",
+    "operations": [
+      "record-choice",
+      "reconcile-profile-enabled",
+      "reconcile-hook-wiring"
+    ]
+  },
+  {
+    "state": "later",
+    "choice": "later",
+    "operations": [
+      "record-choice"
+    ]
+  },
+  {
+    "state": "no",
+    "choice": "no",
+    "operations": [
+      "record-choice"
+    ]
+  },
+  {
+    "state": "existing",
+    "choice": "yes",
+    "operations": [
+      "adopt-existing"
+    ]
+  },
+  {
+    "state": "disable",
+    "choice": "yes",
+    "operations": [
+      "remove-hook-wiring",
+      "update-profile-disabled"
+    ]
+  }
+]
+```
+
+## Hook ownership
+
+The exact kit-owned commands are:
+
+- SessionStart: `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/branch-context.py"`
+- UserPromptSubmit: `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/slice-handoff-hint.py"`
+- PostToolUse on Bash: `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/branch-watch.py"`
+- PreToolUse on Edit/Write/MultiEdit:
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-worktree.py"`
+- PreToolUse on Bash:
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-worktree-cwd.py"` and
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-worktree-discipline.py"`
+
+Preserve unrelated settings, hook groups, profile sections, and unknown keys.
+Repeated reconciliation with the same choice is byte-identical.

package/.claude/hooks/slice-handoff-hint.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+"""UserPromptSubmit adapter for configured Worktree Lifecycle handoffs."""
+
+import json
+import sys
+from pathlib import Path
+
+from _hook_utils import hook_event_output, load_worktree_lifecycle_core
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+        core = load_worktree_lifecycle_core()
+        profile = core.load_profile(Path("docs/agents/workflow-capabilities.json"))
+        decision = core.evaluate(profile, core.collect_facts(Path.cwd()), "handoff", payload)
+    except Exception:
+        return 0
+    if decision.action == "emit":
+        print(json.dumps(hook_event_output(decision.event_name, decision.message)))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.claude/skills/setup-workflow/SKILL.md

@@ -26,6 +26,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `## Agent skills` + `## Prod` in CLAUDE.md **and** AGENTS.md | one-line pointers + deploy target (Sections C/G + Write) |
 | `.github/workflows/agent-workflow-kit-update.yml` | optional tested Kit update pull request for GitHub consumers (Section A2) |
 | `docs/agents/census.md` | optional-census choice, paths, state, and safe disable contract seeded from [census.md](./census.md) (Section A3) |
+| `docs/agents/workflow-capabilities.json` | consumer-owned capability profile, including optional Worktree Lifecycle activation (Section A4) |
 
 ## Idempotency contract — read before writing anything
 
@@ -56,6 +57,7 @@ Read the current state; don't assume. For every target file, read its first line
 - `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/` — domain-doc layout.
 - `docs/agents/`, `docs/agents/skills/`, `docs/conventions/` — prior output of this skill.
 - `docs/agents/census.md`, `.census/profile.json`, `.census/active.json` — an existing census choice or consumer-owned census to adopt.
+- `docs/agents/workflow-capabilities.json`, `.claude/settings.json` — an existing Worktree Lifecycle choice/profile and hook wiring to adopt.
 - `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
 
 ### 2. Section A — Issue tracker
@@ -135,6 +137,34 @@ activate without rerunning setup. Disable enforcement first, but retain every
 consumer-owned profile, scanner, test, and active snapshot unless the user
 separately approves deletion. Repeated runs are no-ops after reconciliation.
 
+### 2c. Section A4 — Optional Worktree Lifecycle
+
+> Worktree Lifecycle is one consumer capability for isolated setup, shared
+> branch/worktree facts, enforcement, handoff, and safe cleanup. The profile is
+> tracked and consumer-owned; hook wiring activates only after an explicit yes.
+
+Read [worktree-lifecycle.md](./worktree-lifecycle.md) in full. Reconcile the
+complete `yes / later / no / existing / disable` matrix from its structured
+contract. If no choice exists, ask: *"Should setup activate the portable
+Worktree Lifecycle for this repository?"* Offer exactly **Yes**, **Later**, and
+**No**.
+
+- **Yes** — create or deepen only the `worktreeLifecycle` section in
+  `docs/agents/workflow-capabilities.json`, preserve every other section and
+  unknown key, and reconcile only the exact kit-owned hook commands listed in
+  the seed.
+- **Later / No** — record the choice in the tracked profile without installing
+  hook wiring. Ordinary reruns do not ask again.
+- **Existing** — adopt the current section and wiring without normalizing
+  consumer-owned values.
+- **Disable** — remove only the exact kit-owned hook commands first, then set
+  `enabled: false`; retain the profile, setup policy, and unknown keys.
+
+The default setup entry is
+`python3 scripts/worktree-lifecycle/setup.py`; a proven consumer-native helper
+may remain the configured `setupEntry` for parity. The handoff advisory always
+reads that configured entry and never hardcodes a project script.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
@@ -220,6 +250,12 @@ pre-existing consumer-owned census file. `yes`, `later`, `no`, and an adopted
 existing census are terminal for ordinary setup reruns. Only an explicit user
 request changes a recorded choice.
 
+For `docs/agents/workflow-capabilities.json`, reconcile only the selected
+capability section. Never replace the whole file: Project Release, Memory
+Lifecycle, Worktree Lifecycle, future sections, and unknown consumer keys share
+this profile. Apply the Worktree Lifecycle transition and hook ownership rules
+from [worktree-lifecycle.md](./worktree-lifecycle.md) transactionally.
+
 For the **`## Workflow`**, **`## Agent skills`**, and **`## Prod`** blocks, reconcile per section in **both** CLAUDE.md and AGENTS.md that exist:
 
 - If **both** files exist → write/update the block in **both** (keep them coherent — Codex is a first-class surface).

package/.claude/skills/setup-workflow/worktree-lifecycle.md

@@ -0,0 +1,81 @@
+# Worktree Lifecycle setup contract
+
+Worktree Lifecycle is one opt-in capability backed by the consumer-owned
+`docs/agents/workflow-capabilities.json` profile. Enabling it activates the
+portable setup entry, shared branch/worktree facts, thin hook adapters, handoff
+advisory, and safe cleanup policy as one unit.
+
+## Choice matrix
+
+| State | Setup action |
+|---|---|
+| `missing` | Ask `yes / later / no`; do not infer or write before the answer. |
+| `yes` | Reconcile the enabled profile and exact kit-owned hook commands. |
+| `later` | Record the retryable deferral; do not activate hooks. |
+| `no` | Record the opt-out; do not activate hooks. |
+| `existing` | Adopt the consumer profile byte-safely and preserve unknown keys. |
+| `disable` | Remove only kit-owned hook wiring, then set `enabled: false`; retain the profile and unknown keys. |
+
+```json worktree-lifecycle-setup-effects
+[
+  {
+    "state": "missing",
+    "choice": null,
+    "operations": []
+  },
+  {
+    "state": "yes",
+    "choice": "yes",
+    "operations": [
+      "record-choice",
+      "reconcile-profile-enabled",
+      "reconcile-hook-wiring"
+    ]
+  },
+  {
+    "state": "later",
+    "choice": "later",
+    "operations": [
+      "record-choice"
+    ]
+  },
+  {
+    "state": "no",
+    "choice": "no",
+    "operations": [
+      "record-choice"
+    ]
+  },
+  {
+    "state": "existing",
+    "choice": "yes",
+    "operations": [
+      "adopt-existing"
+    ]
+  },
+  {
+    "state": "disable",
+    "choice": "yes",
+    "operations": [
+      "remove-hook-wiring",
+      "update-profile-disabled"
+    ]
+  }
+]
+```
+
+## Hook ownership
+
+The exact kit-owned commands are:
+
+- SessionStart: `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/branch-context.py"`
+- UserPromptSubmit: `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/slice-handoff-hint.py"`
+- PostToolUse on Bash: `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/branch-watch.py"`
+- PreToolUse on Edit/Write/MultiEdit:
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-worktree.py"`
+- PreToolUse on Bash:
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-worktree-cwd.py"` and
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-worktree-discipline.py"`
+
+Preserve unrelated settings, hook groups, profile sections, and unknown keys.
+Repeated reconciliation with the same choice is byte-identical.

package/README.md

@@ -332,6 +332,19 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.22.0
+
+- added: `.agents/skills/setup-workflow/worktree-lifecycle.md`
+- added: `.claude/hooks/slice-handoff-hint.py`
+- added: `.claude/skills/setup-workflow/worktree-lifecycle.md`
+- added: `scripts/worktree-lifecycle/cleanup.py`
+- changed: `.agents/skills/setup-workflow/SKILL.md`
+- changed: `.claude/skills/setup-workflow/SKILL.md`
+- changed: `scripts/worktree-lifecycle/README.md`
+- changed: `scripts/worktree-lifecycle/capabilities.json`
+- changed: `scripts/worktree-lifecycle/core.py`
+- changed: `scripts/wrapup-land.py`
+
 ### 0.21.0
 
 - added: `.agents/skills/project-release/SKILL.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.21.0",
+  "kitVersion": "0.22.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -573,7 +573,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "91ba30cc08206204c83d189274579471366221ccfe8f2abdf36957ad85ae136b",
+      "sha256": "a1145034dbc334fb388be27dfb77cf1d93f3cefc6f760d5f4fa5d3ee98050dff",
       "mode": 420,
       "origin": "kit"
     },
@@ -622,6 +622,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".agents/skills/setup-workflow/worktree-lifecycle.md",
+      "kind": "skill",
+      "ownerSkill": "setup-workflow",
+      "surface": "codex",
+      "sha256": "5e0914874f0b9f940205fbcfcfbba87d0c2df8f31db104d2c5328a0d20c80616",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".agents/skills/spec-self-critique/scenarios.md",
       "kind": "skill",
@@ -921,6 +930,13 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": ".claude/hooks/slice-handoff-hint.py",
+      "kind": "hook",
+      "sha256": "664ca09a7e86c267ce7d49bf6b2529ebb9e75a4fd3443548f36f6eb9d4665abf",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": ".claude/hooks/sync-board-status.py",
       "kind": "hook",
@@ -1626,7 +1642,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "91ba30cc08206204c83d189274579471366221ccfe8f2abdf36957ad85ae136b",
+      "sha256": "a1145034dbc334fb388be27dfb77cf1d93f3cefc6f760d5f4fa5d3ee98050dff",
       "mode": 420,
       "origin": "kit"
     },
@@ -1675,6 +1691,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/setup-workflow/worktree-lifecycle.md",
+      "kind": "skill",
+      "ownerSkill": "setup-workflow",
+      "surface": "claude",
+      "sha256": "5e0914874f0b9f940205fbcfcfbba87d0c2df8f31db104d2c5328a0d20c80616",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/spec-self-critique/scenarios.md",
       "kind": "skill",
@@ -2151,14 +2176,21 @@
     {
       "path": "scripts/worktree-lifecycle/capabilities.json",
       "kind": "doc",
-      "sha256": "3e51acaf2a8ac3ace0a400e23a30732ff0c3e9b4864f763c7abf82019605f309",
+      "sha256": "e80501bd86bbdb0ba296fc6b172442d8ad128f43e571777698657491279e4305",
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "scripts/worktree-lifecycle/cleanup.py",
+      "kind": "script",
+      "sha256": "370af8840732db3b6ba39b4825686f3980f69f612038123bc86b2c68921f02ca",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": "scripts/worktree-lifecycle/core.py",
       "kind": "script",
-      "sha256": "36848a16ed7eaed1f731399efd2caf5771c9c5b48331771d6aedcbad2156e62a",
+      "sha256": "d54c4d663c234b7d2e607b99f6090b46104c21ba4326ef03bcb65de39d1cce19",
       "mode": 420,
       "origin": "kit"
     },
@@ -2172,7 +2204,7 @@
     {
       "path": "scripts/worktree-lifecycle/README.md",
       "kind": "doc",
-      "sha256": "59b78826308404497545b0a0ba57ff50f4618be2f6838f64e6a8c18bce83ea7f",
+      "sha256": "5dba0332253c37162ad1b2f1b7bf504a23af85bf297fdaa8920036f610ff754a",
       "mode": 420,
       "origin": "kit"
     },
@@ -2186,7 +2218,7 @@
     {
       "path": "scripts/wrapup-land.py",
       "kind": "script",
-      "sha256": "24ce9373c464cc8363c53b0c690c3231cbf11362e6e08336e0e97663579d1f19",
+      "sha256": "ee1f567e7be4f7baae222ed3974d39e5efee93edb2a663cacc8e18b567fa837e",
       "mode": 493,
       "origin": "kit"
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {

package/scripts/test_worktree_wrapup_contract.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Wrapup must reuse the shipped Worktree Lifecycle cleanup assessment."""
+
+import importlib.util
+import tempfile
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+REPO = Path(__file__).resolve().parent.parent
+WRAPUP = REPO / "scripts/wrapup-land.py"
+
+
+def load_wrapup():
+    spec = importlib.util.spec_from_file_location("wrapup_land_worktree_contract", WRAPUP)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class WorktreeCleanupContract(unittest.TestCase):
+    def test_active_profile_delegates_removal_safety_to_shared_assessment(self):
+        wrapup = load_wrapup()
+        calls = []
+
+        class FakeCore:
+            @staticmethod
+            def load_profile(path):
+                calls.append(("profile", path))
+                return {"enabled": True}
+
+            @staticmethod
+            def cleanup_assessment(profile, main, target, merge_target=None):
+                calls.append(("assessment", main, target, merge_target))
+                return SimpleNamespace(reasons=("dirty worktree",), assumptions="reviewed")
+
+        with tempfile.TemporaryDirectory() as tmp:
+            main = Path(tmp)
+            profile = main / "docs/agents/workflow-capabilities.json"
+            profile.parent.mkdir(parents=True)
+            profile.write_text('{"worktreeLifecycle":{"enabled":true}}\n')
+            with patch.object(wrapup, "load_worktree_cleanup_core", return_value=FakeCore):
+                with self.assertRaises(wrapup.Stop) as stopped:
+                    wrapup.ensure_worktree_removable(str(main / "wt"), str(main))
+
+        self.assertIn("shared cleanup guard", stopped.exception.reason)
+        self.assertEqual(calls[1][-1], "origin/main")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/worktree-lifecycle/README.md

@@ -31,6 +31,14 @@ the core proves the target is unsafe.
 | `enforce-worktree.py` | PreToolUse | blocks tracked main-checkout edits and cross-worktree leaks |
 | `enforce-worktree-cwd.py` | PreToolUse | blocks verification or Git mutation in the wrong checkout |
 | `enforce-worktree-discipline.py` | PreToolUse | routes issue-branch creation through the configured setup entry |
+| `slice-handoff-hint.py` | UserPromptSubmit | names the configured setup entry for a defined slice |
+
+## 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.
 
 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

@@ -3,34 +3,42 @@
   "capabilities": [
     {
       "historicalPath": "scripts/setup-worktree.sh",
+      "artifact": "scripts/worktree-lifecycle/setup.py",
       "primitives": ["profile", "git-facts", "transactional-setup"]
     },
     {
       "historicalPath": ".claude/hooks/branch-context.py",
+      "artifact": ".claude/hooks/branch-context.py",
       "primitives": ["profile", "git-facts", "hook-event-output"]
     },
     {
       "historicalPath": ".claude/hooks/branch-watch.py",
+      "artifact": ".claude/hooks/branch-watch.py",
       "primitives": ["profile", "git-facts", "hook-event-output"]
     },
     {
       "historicalPath": ".claude/hooks/enforce-worktree.py",
+      "artifact": ".claude/hooks/enforce-worktree.py",
       "primitives": ["profile", "git-facts", "worktree-decision"]
     },
     {
       "historicalPath": ".claude/hooks/enforce-worktree-cwd.py",
+      "artifact": ".claude/hooks/enforce-worktree-cwd.py",
       "primitives": ["profile", "git-facts", "worktree-decision"]
     },
     {
       "historicalPath": ".claude/hooks/enforce-worktree-discipline.py",
+      "artifact": ".claude/hooks/enforce-worktree-discipline.py",
       "primitives": ["profile", "git-facts", "worktree-decision"]
     },
     {
       "historicalPath": ".claude/hooks/slice-handoff-hint.py",
+      "artifact": ".claude/hooks/slice-handoff-hint.py",
       "primitives": ["profile", "git-facts", "hook-event-output"]
     },
     {
       "historicalPath": "scripts/cleanup-worktrees.sh",
+      "artifact": "scripts/worktree-lifecycle/cleanup.py",
       "primitives": ["profile", "git-facts", "cleanup-safety"]
     }
   ]

package/scripts/worktree-lifecycle/cleanup.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Preview or safely remove a profile-governed linked worktree."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from core import LifecycleError, cleanup_assessment, 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")
+    return parser.parse_args()
+
+
+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))
+    report = {
+        "worktree": str(assessment.worktree),
+        "branch": assessment.branch,
+        "removable": assessment.removable,
+        "reasons": list(assessment.reasons),
+        "assumptions": assessment.assumptions,
+        "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)
+    run(["git", "branch", "-d", assessment.branch], cwd=main)
+    report["removed"] = True
+    return report
+
+
+def main() -> int:
+    try:
+        print(json.dumps(execute(parse_args()), ensure_ascii=False, indent=2))
+        return 0
+    except LifecycleError as error:
+        print(f"STOP: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/worktree-lifecycle/core.py

@@ -38,6 +38,18 @@ class Decision:
     event_name: str = ""
 
 
+@dataclass(frozen=True)
+class CleanupAssessment:
+    worktree: Path
+    branch: str
+    assumptions: str
+    reasons: tuple[str, ...]
+
+    @property
+    def removable(self) -> bool:
+        return not self.reasons
+
+
 def collect_facts(cwd: Path) -> RepoFacts:
     root = Path(run(["git", "rev-parse", "--show-toplevel"], cwd=cwd).stdout.strip()).resolve()
     main = main_worktree(root)
@@ -104,6 +116,50 @@ def is_tracked(root: Path, relative: str) -> bool:
     return result.returncode == 0
 
 
+def cleanup_assessment(
+    profile: WorktreeProfile,
+    main: Path,
+    target: Path,
+    merge_target: str | None = None,
+) -> CleanupAssessment:
+    worktree = target.resolve()
+    reasons = []
+    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"],
+        cwd=main,
+        check=False,
+    ).stdout
+    if status.strip():
+        reasons.append("dirty worktree")
+    if branch and branch not in profile.protected_branches:
+        main_branch = merge_target or run(
+            ["git", "-C", str(main), "branch", "--show-current"],
+            cwd=main,
+            check=False,
+        ).stdout.strip()
+        merged = run(
+            ["git", "merge-base", "--is-ancestor", branch, main_branch],
+            cwd=main,
+            check=False,
+        )
+        if merged.returncode != 0:
+            reasons.append(f"unmerged branch: {branch}")
+    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))
+
+
 def edit_decision(
     profile: WorktreeProfile,
     facts: RepoFacts,
@@ -196,6 +252,28 @@ def branch_create_decision(
     return Decision("allow")
 
 
+def handoff_decision(
+    profile: WorktreeProfile,
+    facts: RepoFacts,
+    payload: dict[str, Any],
+) -> Decision:
+    prompt = str(payload.get("prompt") or "")
+    pattern = re.compile(
+        rf"{re.escape(profile.setup_entry)}\s+(\d+)\s+(\S+)"
+    )
+    match = pattern.search(prompt)
+    if match is None or not facts.is_main_worktree:
+        return Decision("skip")
+    issue, slug = match.groups()
+    command = f"{profile.setup_entry} {issue} {slug}"
+    return Decision(
+        "emit",
+        f"Defined slice detected: create its isolated worktree first with `{command}`, "
+        "then perform repository reads from that worktree.",
+        "UserPromptSubmit",
+    )
+
+
 def evaluate(
     profile: WorktreeProfile,
     facts: RepoFacts,
@@ -216,4 +294,6 @@ def evaluate(
         return command_decision(profile, facts, payload)
     if event == "branch-create":
         return branch_create_decision(profile, facts, payload)
+    if event == "handoff":
+        return handoff_decision(profile, facts, payload)
     return Decision("skip")

package/scripts/wrapup-land.py

@@ -20,6 +20,7 @@ no --no-verify; the caller diagnoses.
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import json
 import os
 import re
@@ -90,6 +91,44 @@ def load_profile() -> dict:
         return {}
 
 
+def load_worktree_cleanup_core():
+    path = Path(__file__).resolve().parent / "worktree-lifecycle" / "core.py"
+    module_dir = str(path.parent)
+    if module_dir not in sys.path:
+        sys.path.insert(0, module_dir)
+    spec = importlib.util.spec_from_file_location("_wrapup_worktree_lifecycle", path)
+    if spec is None or spec.loader is None:
+        raise Stop("cleanup", f"cannot load shared cleanup core from {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def ensure_worktree_removable(wt: str, main_tree: str):
+    profile_path = Path(main_tree) / "docs/agents/workflow-capabilities.json"
+    if not profile_path.is_file():
+        return None
+    core = load_worktree_cleanup_core()
+    try:
+        profile = core.load_profile(profile_path)
+        assessment = core.cleanup_assessment(
+            profile,
+            Path(main_tree),
+            Path(wt),
+            merge_target="origin/main",
+        )
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+    if assessment.reasons:
+        raise Stop(
+            "cleanup",
+            "shared cleanup guard refused worktree removal",
+            "; ".join(assessment.reasons),
+        )
+    return assessment
+
+
 # ---------- drift log (ANNAHMEN.md) ----------
 
 def parse_annahmen(text: str, default_section: str) -> tuple[list[dict], list[str]]:
@@ -428,6 +467,12 @@ def cmd_land(args) -> dict:
 
     # Step 2 — kill the worktree's dev server, then Step 4 — teardown
     if wt_exists:
+        git(["fetch", "origin", "main"], cwd=main_tree, check=True)
+        cleanup = ensure_worktree_removable(wt, main_tree)
+        report["cleanup_guard"] = {
+            "active": cleanup is not None,
+            "assumptions_read": bool(cleanup and cleanup.assumptions),
+        }
         report["killed_processes"] = kill_worktree_processes(wt)
         p = git(["worktree", "remove", wt], cwd=main_tree)
         if p.returncode != 0:

package/src/lib/bundle.mjs

@@ -74,6 +74,7 @@ export const HELPER_FILES = [
   { path: 'scripts/worktree-lifecycle/core.py', kind: 'script', mode: 0o644 },
   { path: 'scripts/worktree-lifecycle/profile.py', kind: 'script', mode: 0o644 },
   { path: 'scripts/worktree-lifecycle/setup.py', kind: 'script', mode: 0o755 },
+  { path: 'scripts/worktree-lifecycle/cleanup.py', kind: 'script', mode: 0o755 },
   { path: 'scripts/worktree-lifecycle/capabilities.json', kind: 'doc', mode: 0o644 },
   { path: 'scripts/worktree-lifecycle/README.md', kind: 'doc', mode: 0o644 },
   // Shared hook utility imported by the shipped hooks (drift-guard,
@@ -87,6 +88,7 @@ export const HELPER_FILES = [
   { path: '.claude/hooks/enforce-worktree.py', kind: 'hook', mode: 0o755 },
   { path: '.claude/hooks/enforce-worktree-cwd.py', kind: 'hook', mode: 0o755 },
   { path: '.claude/hooks/enforce-worktree-discipline.py', kind: 'hook', mode: 0o755 },
+  { path: '.claude/hooks/slice-handoff-hint.py', kind: 'hook', mode: 0o755 },
   { path: '.claude/hooks/drift-guard.py', kind: 'hook', mode: 0o755 },
   // SessionStart skill-freshness drift-hint (audit-skills names it). For each
   // <skill>/SOURCES.txt it flags sources newer in git than the SKILL.md. Imports