@ikon85/agent-workflow-kit 0.20.0 → 0.22.0

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.20.0",
+  "kitVersion": "0.22.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -379,6 +379,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".agents/skills/project-release/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "project-release",
+      "surface": "codex",
+      "sha256": "5aa0b0827e8691334c30608df8506c756455ecebcc460efa140889297cf02ed5",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".agents/skills/prototype/LOGIC.md",
       "kind": "skill",
@@ -564,7 +573,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "91ba30cc08206204c83d189274579471366221ccfe8f2abdf36957ad85ae136b",
+      "sha256": "a1145034dbc334fb388be27dfb77cf1d93f3cefc6f760d5f4fa5d3ee98050dff",
       "mode": 420,
       "origin": "kit"
     },
@@ -609,7 +618,16 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "c522a7de1b8eaa827a72880651a94aca6d066687e8c21b789d9008e3321f7362",
+      "sha256": "bc4db6413135ad9056cc63691cb823a9b198ad47538f292b37fcbb915477a716",
+      "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"
     },
@@ -912,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",
@@ -1405,6 +1430,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/project-release/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "project-release",
+      "surface": "claude",
+      "sha256": "5aa0b0827e8691334c30608df8506c756455ecebcc460efa140889297cf02ed5",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/prototype/LOGIC.md",
       "kind": "skill",
@@ -1608,7 +1642,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "91ba30cc08206204c83d189274579471366221ccfe8f2abdf36957ad85ae136b",
+      "sha256": "a1145034dbc334fb388be27dfb77cf1d93f3cefc6f760d5f4fa5d3ee98050dff",
       "mode": 420,
       "origin": "kit"
     },
@@ -1653,7 +1687,16 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "c522a7de1b8eaa827a72880651a94aca6d066687e8c21b789d9008e3321f7362",
+      "sha256": "bc4db6413135ad9056cc63691cb823a9b198ad47538f292b37fcbb915477a716",
+      "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"
     },
@@ -2028,7 +2071,7 @@
     {
       "path": "scripts/kit-release.mjs",
       "kind": "script",
-      "sha256": "d3148aab63fa670c0a3407d2816d287b7cdeaa130588fb55b6075217da95d3d3",
+      "sha256": "3c86eb5fc4b2071b423d87f023ba4c3f778ffe716a2603dcecdbe4e83ec1b8df",
       "mode": 420,
       "origin": "kit"
     },
@@ -2102,6 +2145,13 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "scripts/project-release.mjs",
+      "kind": "script",
+      "sha256": "6c08cf16f97fdbc0172041c64109e859b1f073862e9f8edc2accbafd97b33843",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": "scripts/release-delta-guard.mjs",
       "kind": "script",
@@ -2126,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"
     },
@@ -2147,7 +2204,7 @@
     {
       "path": "scripts/worktree-lifecycle/README.md",
       "kind": "doc",
-      "sha256": "59b78826308404497545b0a0ba57ff50f4618be2f6838f64e6a8c18bce83ea7f",
+      "sha256": "5dba0332253c37162ad1b2f1b7bf504a23af85bf297fdaa8920036f610ff754a",
       "mode": 420,
       "origin": "kit"
     },
@@ -2161,10 +2218,17 @@
     {
       "path": "scripts/wrapup-land.py",
       "kind": "script",
-      "sha256": "24ce9373c464cc8363c53b0c690c3231cbf11362e6e08336e0e97663579d1f19",
+      "sha256": "ee1f567e7be4f7baae222ed3974d39e5efee93edb2a663cacc8e18b567fa837e",
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": "src/lib/release-apply.mjs",
+      "kind": "script",
+      "sha256": "d9b3bd07c88629c570d8a58f1d91d1cdac1457470cee973f99e186d9630efb03",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": "src/lib/release-preview.mjs",
       "kind": "script",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.20.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/kit-release.mjs

@@ -5,19 +5,15 @@ import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
+import { applyProjectRelease } from '../src/lib/release-apply.mjs';
+import { previewProjectRelease } from '../src/lib/release-preview.mjs';
+import { nextVersion } from '../src/lib/semver.mjs';
 import { buildKit } from './build-kit.mjs';
 import { checkReleaseDelta } from './release-delta-guard.mjs';
 
 const exec = promisify(execFile);
 
-export function nextVersion(version, bump) {
-  const parts = version.split('.').map(Number);
-  if (parts.length !== 3 || parts.some(Number.isNaN)) throw new Error(`invalid semver: ${version}`);
-  if (bump === 'major') return `${parts[0] + 1}.0.0`;
-  if (bump === 'minor') return `${parts[0]}.${parts[1] + 1}.0`;
-  if (bump === 'patch') return `${parts[0]}.${parts[1]}.${parts[2] + 1}`;
-  throw new Error(`invalid bump: ${bump}`);
-}
+export { nextVersion };
 
 function note(version, delta) {
   const lines = ['added', 'removed', 'changed'].flatMap((kind) =>
@@ -30,8 +26,17 @@ async function updateMetadata(repoRoot, targetVersion, delta) {
   const pkg = JSON.parse(await readFile(packagePath, 'utf8'));
   const resumed = pkg.version === targetVersion;
   if (!resumed) {
-    pkg.version = targetVersion;
-    await writeFile(packagePath, `${JSON.stringify(pkg, null, 2)}\n`);
+    const preview = await previewProjectRelease({
+      consumerRoot: repoRoot,
+      profile: { versionFiles: ['package.json'], tagPrefix: 'v' },
+      requestedVersion: targetVersion,
+      repositoryFacts: { dirtyPaths: [], existingTags: [] },
+    });
+    await applyProjectRelease({
+      consumerRoot: repoRoot,
+      preview,
+      confirmation: preview.confirmation,
+    });
   }
   const readmePath = join(repoRoot, 'README.md');
   const readme = await readFile(readmePath, 'utf8');

package/scripts/project-release.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { applyProjectRelease, assertSafeReleaseTargets } from '../src/lib/release-apply.mjs';
+import { loadProjectReleaseProfile, previewProjectRelease } from '../src/lib/release-preview.mjs';
+
+function gitOutput(consumerRoot, args) {
+  return execFileSync('git', args, { cwd: consumerRoot, encoding: 'utf8' });
+}
+
+export function readRepositoryFacts(consumerRoot, run = gitOutput) {
+  const records = run(
+    consumerRoot, ['status', '--porcelain=v1', '-z', '--untracked-files=all'],
+  ).split('\0').filter(Boolean);
+  const dirtyPaths = [];
+  for (let index = 0; index < records.length; index += 1) {
+    const record = records[index];
+    dirtyPaths.push(record.slice(3));
+    if (record[0] === 'R' || record[0] === 'C'
+        || record[1] === 'R' || record[1] === 'C') index += 1;
+  }
+  const existingTags = run(consumerRoot, ['tag', '--list'])
+    .split('\n').filter(Boolean);
+  return { dirtyPaths, existingTags };
+}
+
+function argument(args, name) {
+  const index = args.indexOf(name);
+  return index < 0 ? null : args[index + 1];
+}
+
+export async function runProjectRelease(options) {
+  const {
+    consumerRoot, args,
+    repositoryFacts = readRepositoryFacts(consumerRoot),
+    output = console.log,
+  } = options;
+  const [command, requestedVersion] = args;
+  if (!['preview', 'apply'].includes(command) || !requestedVersion) {
+    throw new Error('usage: project-release <preview|apply> <patch|minor|major|version> [--confirm <token>]');
+  }
+  const profile = await loadProjectReleaseProfile(consumerRoot);
+  await assertSafeReleaseTargets(consumerRoot, profile.versionFiles);
+  const preview = await previewProjectRelease({
+    consumerRoot, profile, requestedVersion, repositoryFacts,
+  });
+  if (command === 'preview') {
+    output(JSON.stringify(preview));
+    return preview;
+  }
+  const result = await applyProjectRelease({
+    consumerRoot,
+    preview,
+    confirmation: argument(args, '--confirm'),
+  });
+  output(JSON.stringify(result));
+  return result;
+}
+
+async function main() {
+  await runProjectRelease({ consumerRoot: process.cwd(), args: process.argv.slice(2) });
+}
+
+if (resolve(process.argv[1] ?? '') === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`project-release: ${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/scripts/test_skill_publish_audit.py

@@ -15,8 +15,9 @@ Deny classes (each with a negative fixture below):
   - residual issue refs (`#NNN`) / hard-rule refs (`HRn`)
   - unresolvable provenance cross-refs (`ADR-####` / `Welle N` / `Slice N`),
     with a documented fixture/example allowlist (PROVENANCE_FIXTURE_SUFFIXES)
-  - `../` cross-skill reaches (skills/scripts/docs — NOT the CLI src, which
-    legitimately imports `../lib/…`)
+  - `../` cross-skill reaches (skills/scripts/docs — except a static top-level
+    script import into the shipped `src/lib` deep-module seam, and CLI `src`
+    imports which legitimately use `../lib/…`)
   - bare owner/maintainer names OUTSIDE the generated credit files
   - high-entropy secrets (after exempting the manifest's own sha256 file-hashes)
 
@@ -92,18 +93,27 @@ BARE_PRIVATE = [
     ("maintainer name", re.compile(r"\bNiko\b")),
 ]
 PARENT_REF = re.compile(r"\.\./")
+SHIPPED_SRC_IMPORT = re.compile(
+    r"^\s*import\b.*\bfrom\s+['\"]\.\./src/lib/[a-z0-9-]+\.mjs['\"];\s*$"
+)
 LONG_HEX = re.compile(r"\b[0-9a-f]{40,}\b")
 GH_TOKEN = re.compile(r"\b(?:ghp|gho|ghu|ghs|github_pat)_[A-Za-z0-9_]{20,}")
 
 
 def _parent_ref_scan_text(rel: str, text: str) -> str:
-    if rel != "scripts/loc_offender_core.py":
-        return text
-    # This is the portable path-traversal guard itself, not a cross-skill reach.
-    return "\n".join(
-        line for line in text.splitlines()
-        if 'p.startswith("../")' not in line and '"/../" in p' not in line
-    )
+    lines = text.splitlines()
+    if rel == "scripts/loc_offender_core.py":
+        # This is the portable path-traversal guard itself, not a cross-skill reach.
+        lines = [
+            line for line in lines
+            if 'p.startswith("../")' not in line and '"/../" in p' not in line
+        ]
+    if rel.startswith("scripts/") and rel.endswith(".mjs"):
+        # Top-level shipped scripts may consume the kit's shipped deep modules.
+        # The exact static-import shape stays inside the bundle root; every other
+        # parent reach remains visible to the deny rule below.
+        lines = [line for line in lines if not SHIPPED_SRC_IMPORT.match(line)]
+    return "\n".join(lines)
 
 
 def _known_hashes(root: Path) -> set:
@@ -230,6 +240,15 @@ class AuditCatchesEachClass(unittest.TestCase):
     def test_parent_ref(self):
         self.assertTrue(any("parent" in v for v in self._body("[x](../../other/SKILL.md)")))
 
+    def test_static_script_import_into_shipped_src_lib_is_allowed(self):
+        script = self.dir / "scripts/release.mjs"
+        script.parent.mkdir()
+        script.write_text(
+            "import { run } from '../src/lib/release-core.mjs';\nrun();\n",
+            encoding="utf-8",
+        )
+        self.assertEqual(audit_dir(self.dir), [])
+
     def test_bare_owner_in_body(self):
         self.assertTrue(any("iKon85" in v for v in self._body("authored by iKon85")))
 

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")