@ikon85/agent-workflow-kit 0.19.0 → 0.20.0

package/.claude/hooks/_hook_utils.py

@@ -193,6 +193,9 @@ def load_worktree_lifecycle_core():
     if existing is not None:
         return existing
     path = Path(__file__).resolve().parents[2] / "scripts" / "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(_WORKTREE_CORE_MODULE, path)
     if spec is None or spec.loader is None:
         raise ImportError(f"cannot load Worktree Lifecycle core from {path}")

package/.claude/hooks/branch-context.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+"""SessionStart adapter for profile-driven branch and worktree facts."""
+
+import json
+import sys
+from pathlib import Path
+
+from _hook_utils import hook_event_output, load_worktree_lifecycle_core
+
+
+def main() -> int:
+    try:
+        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()), "session-start", {})
+    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/hooks/branch-watch.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+"""PostToolUse adapter for branch-changing shell commands."""
+
+import json
+import sys
+from pathlib import Path
+
+from _hook_utils import 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()), "branch-watch", payload)
+    except Exception:
+        return 0
+    if decision.action == "emit":
+        print(json.dumps({"systemMessage": decision.message}))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.claude/hooks/enforce-worktree-cwd.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""PreToolUse adapter for commands that must run in their linked worktree."""
+
+import json
+import sys
+from pathlib import Path
+
+from _hook_utils import 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()), "command-cwd", payload)
+    except Exception:
+        return 0
+    if decision.action == "block":
+        print(decision.message, file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.claude/hooks/enforce-worktree-discipline.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""PreToolUse adapter for issue-branch creation with active worktrees."""
+
+import json
+import sys
+from pathlib import Path
+
+from _hook_utils import 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()), "branch-create", payload)
+    except Exception:
+        return 0
+    if decision.action == "block":
+        print(decision.message, file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.claude/hooks/enforce-worktree.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""PreToolUse adapter for tracked edits on protected worktrees."""
+
+import json
+import sys
+from pathlib import Path
+
+from _hook_utils import 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()), "edit", payload)
+    except Exception:
+        return 0
+    if decision.action == "block":
+        print(decision.message, file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/README.md

@@ -332,6 +332,18 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.20.0
+
+- added: `.claude/hooks/branch-context.py`
+- added: `.claude/hooks/branch-watch.py`
+- added: `.claude/hooks/enforce-worktree.py`
+- added: `.claude/hooks/enforce-worktree-cwd.py`
+- added: `.claude/hooks/enforce-worktree-discipline.py`
+- added: `scripts/worktree-lifecycle/profile.py`
+- added: `scripts/worktree-lifecycle/README.md`
+- changed: `.claude/hooks/_hook_utils.py`
+- changed: `scripts/worktree-lifecycle/core.py`
+
 ### 0.19.0
 
 - added: `.agents/skills/memory-lifecycle/SKILL.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.19.0",
+  "kitVersion": "0.20.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -859,10 +859,24 @@
     {
       "path": ".claude/hooks/_hook_utils.py",
       "kind": "hook",
-      "sha256": "4a4b57633578ee8eabdf8ae70437e590e1747d1df5d76c730e2164e23cdfc2ed",
+      "sha256": "58a7a8ad6cd4f1660e95343d7a0c637cf8aee92948a9c554befa5851723b3f48",
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/hooks/branch-context.py",
+      "kind": "hook",
+      "sha256": "96bbe56a292a89cdb76db0670c2c214678fa60c08e3de5b8db507149ba24c018",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/hooks/branch-watch.py",
+      "kind": "hook",
+      "sha256": "15c7565790e0b108c44175b7527a4bc2b8b244737d5598081e938d2dea032424",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": ".claude/hooks/drift-guard.py",
       "kind": "hook",
@@ -870,6 +884,27 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": ".claude/hooks/enforce-worktree-cwd.py",
+      "kind": "hook",
+      "sha256": "14086536ceb3368a03b84ff550ba5e3db83d6c5198c41c80312507bf6640bb9f",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/hooks/enforce-worktree-discipline.py",
+      "kind": "hook",
+      "sha256": "5bd9fc7a7eea5e8b0778e8272e02b5d8c6c121ea3a168ef11a9c39344085e666",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/hooks/enforce-worktree.py",
+      "kind": "hook",
+      "sha256": "4a5d0247d89049dde0475680595fd785bfbd1b108cdd9c9697fd74e944f52c8b",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": ".claude/hooks/skill-drift-hint.py",
       "kind": "hook",
@@ -2098,7 +2133,21 @@
     {
       "path": "scripts/worktree-lifecycle/core.py",
       "kind": "script",
-      "sha256": "eae5c6076611a36a8fa90e3aef3d1c49345110a392a7d7e9d95be8de00f8d9ff",
+      "sha256": "36848a16ed7eaed1f731399efd2caf5771c9c5b48331771d6aedcbad2156e62a",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/worktree-lifecycle/profile.py",
+      "kind": "script",
+      "sha256": "993b105efd2329b3a206b0c79399aff1c7840017362745966f9b158b1f165f09",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/worktree-lifecycle/README.md",
+      "kind": "doc",
+      "sha256": "59b78826308404497545b0a0ba57ff50f4618be2f6838f64e6a8c18bce83ea7f",
       "mode": 420,
       "origin": "kit"
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.19.0",
+  "version": "0.20.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/worktree-lifecycle/README.md

@@ -0,0 +1,37 @@
+# Worktree Lifecycle contract
+
+The consumer-owned `docs/agents/workflow-capabilities.json` profile activates
+one Worktree Lifecycle. `profile.py` loads that policy. `core.py` is the only
+place that derives repository facts and decides whether an event emits, allows,
+or blocks. Surface adapters translate hook payloads and render the decision;
+they do not carry a second branch regex, worktree traversal, or failure policy.
+
+## Profile
+
+`worktreeLifecycle` supports:
+
+- `enabled`: explicit activation gate.
+- `worktreeRoot`, `branchTemplate`, `pathTemplate`, and `branchRegex`: consumer
+  naming and location policy.
+- `mainBranches` and `protectedBranches`: branches guarded in the main checkout.
+- `setupEntry` and ordered `setupSteps`: the portable setup command and project
+  setup sequence.
+- `riskyCommandPatterns`: commands that must target the active linked worktree.
+
+Unknown or malformed events fail open without changing repository state.
+Security-sensitive, profile-matched edits and commands fail closed only when
+the core proves the target is unsafe.
+
+## Adapters
+
+| Adapter | Event | Outcome |
+|---|---|---|
+| `branch-context.py` | SessionStart | emits branch, issue, status, and active-worktree facts |
+| `branch-watch.py` | PostToolUse | emits the same facts after a branch-changing command |
+| `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 |
+
+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
+core verdict and message.

package/scripts/worktree-lifecycle/core.py

@@ -1,106 +1,219 @@
-"""Consumer-neutral worktree lifecycle profile and git facts."""
+"""Consumer-neutral Worktree Lifecycle facts and decisions."""
 
 from __future__ import annotations
 
-import json
 import re
-import subprocess
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
+from profile import (
+    LifecycleError,
+    WorktreeProfile,
+    load_profile,
+    local_branch_exists,
+    main_worktree,
+    registered_worktrees,
+    run,
+)
 
-class LifecycleError(RuntimeError):
-    """A safe, user-visible lifecycle refusal."""
-
+_BRANCH_CHANGE_RE = re.compile(r"\b(?:git\s+(?:checkout|switch)|gh\s+pr\s+(?:merge|checkout))\b")
+_BRANCH_CREATE_RE = re.compile(r"\bgit\s+(?:checkout|switch)\s+-[bc]\s+(\S+)")
 
 @dataclass(frozen=True)
-class WorktreeProfile:
-    root: str
-    branch_template: str
-    path_template: str
-    main_branches: tuple[str, ...]
-    protected_branches: tuple[str, ...]
-    setup_steps: tuple[dict[str, Any], ...]
-    branch_regex: str
-
-    def branch_name(self, issue: str, slug: str, branch_type: str) -> str:
-        return _render(self.branch_template, issue, slug, branch_type)
+class RepoFacts:
+    root: Path
+    main_root: Path
+    branch: str
+    main_branch: str
+    is_main_worktree: bool
+    worktrees: tuple[Path, ...]
+    changed_count: int
 
-    def relative_path(self, issue: str, slug: str, branch_type: str) -> Path:
-        name = _render(self.path_template, issue, slug, branch_type)
-        return Path(self.root) / name
 
-    def issue_from_branch(self, branch: str) -> str | None:
-        match = re.match(self.branch_regex, branch)
-        return match.groupdict().get("issue") if match else None
+@dataclass(frozen=True)
+class Decision:
+    action: str
+    message: str = ""
+    event_name: str = ""
+
+
+def collect_facts(cwd: Path) -> RepoFacts:
+    root = Path(run(["git", "rev-parse", "--show-toplevel"], cwd=cwd).stdout.strip()).resolve()
+    main = main_worktree(root)
+    branch = run(["git", "branch", "--show-current"], cwd=root).stdout.strip()
+    main_branch = run(
+        ["git", "-C", str(main), "branch", "--show-current"],
+        cwd=root,
+    ).stdout.strip()
+    worktrees = tuple(sorted(registered_worktrees(root)))
+    status = run(["git", "status", "--porcelain"], cwd=root).stdout
+    return RepoFacts(
+        root=root,
+        main_root=main,
+        branch=branch,
+        main_branch=main_branch,
+        is_main_worktree=root == main,
+        worktrees=worktrees,
+        changed_count=len([line for line in status.splitlines() if line]),
+    )
 
 
-def _render(template: str, issue: str, slug: str, branch_type: str) -> str:
-    values = {"issue": issue, "slug": slug, "type": branch_type}
+def branch_context(profile: WorktreeProfile, facts: RepoFacts) -> Decision:
+    lines = [f"Branch: {facts.branch}", f"Status: {facts.changed_count} uncommitted change(s)"]
+    issue = profile.issue_from_branch(facts.branch)
+    if issue:
+        lines.insert(1, f"Issue: #{issue}")
+    elif facts.branch in profile.protected_branches:
+        lines.insert(1, "Warning: direct work on a protected branch")
+    else:
+        lines.insert(1, "Warning: branch has no issue according to the consumer profile")
+    if len(facts.worktrees) > 1:
+        lines.append(f"Worktrees: {len(facts.worktrees)} active")
+        lines.append(f"Setup entry: {profile.setup_entry}")
+    return Decision("emit", "\n".join(lines), "SessionStart")
+
+
+def repo_relative(target: str, root: Path) -> str | None:
+    if not target:
+        return None
+    path = Path(target)
+    if not path.is_absolute():
+        return target
     try:
-        return template.format(**values)
-    except (KeyError, ValueError) as error:
-        raise LifecycleError(f"invalid worktree template: {error}") from error
+        return str(path.resolve().relative_to(root))
+    except ValueError:
+        return None
 
 
-def load_profile(path: Path) -> WorktreeProfile:
-    try:
-        document = json.loads(path.read_text(encoding="utf-8"))
-        raw = document["worktreeLifecycle"]
-    except (OSError, json.JSONDecodeError, KeyError, TypeError) as error:
-        raise LifecycleError(f"cannot load worktree lifecycle profile: {error}") from error
-    if raw.get("enabled") is not True:
-        raise LifecycleError("worktree lifecycle is not enabled")
-    main = tuple(raw.get("mainBranches") or ("main", "master"))
-    return WorktreeProfile(
-        root=raw.get("worktreeRoot", ".worktrees"),
-        branch_template=raw.get("branchTemplate", "{type}/{issue}-{slug}"),
-        path_template=raw.get("pathTemplate", "{type}-{issue}-{slug}"),
-        main_branches=main,
-        protected_branches=tuple(raw.get("protectedBranches") or main),
-        setup_steps=tuple(raw.get("setupSteps") or ()),
-        branch_regex=raw.get(
-            "branchRegex",
-            r"^(?:feat|fix|chore|docs)/(?P<issue>\d+)-",
-        ),
+def is_ignored(root: Path, relative: str) -> bool:
+    result = run(
+        ["git", "check-ignore", "-q", "--", relative],
+        cwd=root,
+        check=False,
     )
+    return result.returncode == 0
 
 
-def run(
-    command: list[str],
-    *,
-    cwd: Path,
-    check: bool = True,
-) -> subprocess.CompletedProcess[str]:
-    result = subprocess.run(command, cwd=cwd, capture_output=True, text=True)
-    if check and result.returncode != 0:
-        detail = (result.stderr or result.stdout).strip()
-        raise LifecycleError(f"{' '.join(command)} failed: {detail}")
-    return result
-
-
-def main_worktree(cwd: Path) -> Path:
-    output = run(["git", "worktree", "list", "--porcelain"], cwd=cwd).stdout
-    first = next((line for line in output.splitlines() if line.startswith("worktree ")), "")
-    if not first:
-        raise LifecycleError("not inside a git worktree")
-    return Path(first.split(" ", 1)[1]).resolve()
-
-
-def registered_worktrees(cwd: Path) -> set[Path]:
-    output = run(["git", "worktree", "list", "--porcelain"], cwd=cwd).stdout
-    return {
-        Path(line.split(" ", 1)[1]).resolve()
-        for line in output.splitlines()
-        if line.startswith("worktree ")
-    }
-
-
-def local_branch_exists(cwd: Path, branch: str) -> bool:
+def is_tracked(root: Path, relative: str) -> bool:
     result = run(
-        ["git", "show-ref", "--verify", "--quiet", f"refs/heads/{branch}"],
-        cwd=cwd,
+        ["git", "ls-files", "--error-unmatch", "--", relative],
+        cwd=root,
         check=False,
     )
     return result.returncode == 0
+
+
+def edit_decision(
+    profile: WorktreeProfile,
+    facts: RepoFacts,
+    payload: dict[str, Any],
+) -> Decision:
+    if payload.get("tool_name") not in {"Edit", "Write", "MultiEdit"}:
+        return Decision("skip")
+    target = str((payload.get("tool_input") or {}).get("file_path") or "")
+    if facts.is_main_worktree and facts.branch in profile.protected_branches:
+        relative = repo_relative(target, facts.root)
+        if relative is not None and not is_ignored(facts.root, relative):
+            return Decision(
+                "block",
+                f"Worktree Lifecycle blocked an edit to {relative} on protected branch "
+                f"{facts.branch}. Use `{profile.setup_entry}` first.",
+            )
+    if not facts.is_main_worktree and Path(target).is_absolute():
+        relative = repo_relative(target, facts.main_root)
+        if (
+            relative is not None
+            and facts.main_branch in profile.protected_branches
+            and is_tracked(facts.main_root, relative)
+            and not is_ignored(facts.main_root, relative)
+        ):
+            return Decision(
+                "block",
+                f"Worktree Lifecycle blocked a cross-worktree edit to {relative} in "
+                f"the protected main checkout. Edit the linked worktree copy instead.",
+            )
+    return Decision("allow")
+
+
+def targets_linked_worktree(command: str, facts: RepoFacts) -> bool:
+    for worktree in facts.worktrees:
+        if worktree == facts.main_root:
+            continue
+        if str(worktree) in command or str(worktree.relative_to(facts.main_root)) in command:
+            return True
+    return False
+
+
+def command_decision(
+    profile: WorktreeProfile,
+    facts: RepoFacts,
+    payload: dict[str, Any],
+) -> Decision:
+    if payload.get("tool_name") != "Bash":
+        return Decision("skip")
+    command = str((payload.get("tool_input") or {}).get("command") or "")
+    if not command:
+        return Decision("skip")
+    risky = any(re.search(pattern, command) for pattern in profile.risky_command_patterns)
+    if not risky:
+        return Decision("allow")
+    if re.search(r"\bgit\s+push\s+\S+\s+--delete\s+\S+", command):
+        return Decision("allow")
+    if targets_linked_worktree(command, facts):
+        return Decision("allow")
+    if (
+        facts.is_main_worktree
+        and facts.branch in profile.protected_branches
+        and len(facts.worktrees) > 1
+    ):
+        active = ", ".join(path.name for path in facts.worktrees if path != facts.main_root)
+        return Decision(
+            "block",
+            f"Worktree Lifecycle blocked `{command}` in the protected main checkout "
+            f"while linked worktrees are active: {active}. Run it in the target worktree.",
+        )
+    return Decision("allow")
+
+
+def branch_create_decision(
+    profile: WorktreeProfile,
+    facts: RepoFacts,
+    payload: dict[str, Any],
+) -> Decision:
+    if payload.get("tool_name") != "Bash":
+        return Decision("skip")
+    command = str((payload.get("tool_input") or {}).get("command") or "")
+    match = _BRANCH_CREATE_RE.search(command)
+    if match is None or profile.issue_from_branch(match.group(1)) is None:
+        return Decision("allow")
+    if facts.is_main_worktree and len(facts.worktrees) > 1:
+        return Decision(
+            "block",
+            f"Worktree Lifecycle blocked branch creation `{match.group(1)}` in the main "
+            f"checkout while linked worktrees are active. Use `{profile.setup_entry}`.",
+        )
+    return Decision("allow")
+
+
+def evaluate(
+    profile: WorktreeProfile,
+    facts: RepoFacts,
+    event: str,
+    payload: dict[str, Any],
+) -> Decision:
+    if event == "session-start":
+        return branch_context(profile, facts)
+    if event == "branch-watch":
+        command = str((payload.get("tool_input") or {}).get("command") or "")
+        if payload.get("tool_name") != "Bash" or not _BRANCH_CHANGE_RE.search(command):
+            return Decision("skip")
+        context = branch_context(profile, facts)
+        return Decision("emit", context.message, "PostToolUse")
+    if event == "edit":
+        return edit_decision(profile, facts, payload)
+    if event == "command-cwd":
+        return command_decision(profile, facts, payload)
+    if event == "branch-create":
+        return branch_create_decision(profile, facts, payload)
+    return Decision("skip")

package/scripts/worktree-lifecycle/profile.py

@@ -0,0 +1,116 @@
+"""Worktree Lifecycle profile loading and low-level git operations."""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+class LifecycleError(RuntimeError):
+    """A safe, user-visible lifecycle refusal."""
+
+
+@dataclass(frozen=True)
+class WorktreeProfile:
+    root: str
+    branch_template: str
+    path_template: str
+    main_branches: tuple[str, ...]
+    protected_branches: tuple[str, ...]
+    setup_steps: tuple[dict[str, Any], ...]
+    branch_regex: str
+    setup_entry: str
+    risky_command_patterns: tuple[str, ...]
+
+    def branch_name(self, issue: str, slug: str, branch_type: str) -> str:
+        return _render(self.branch_template, issue, slug, branch_type)
+
+    def relative_path(self, issue: str, slug: str, branch_type: str) -> Path:
+        name = _render(self.path_template, issue, slug, branch_type)
+        return Path(self.root) / name
+
+    def issue_from_branch(self, branch: str) -> str | None:
+        match = re.match(self.branch_regex, branch)
+        return match.groupdict().get("issue") if match else None
+
+
+def _render(template: str, issue: str, slug: str, branch_type: str) -> str:
+    values = {"issue": issue, "slug": slug, "type": branch_type}
+    try:
+        return template.format(**values)
+    except (KeyError, ValueError) as error:
+        raise LifecycleError(f"invalid worktree template: {error}") from error
+
+
+def load_profile(path: Path) -> WorktreeProfile:
+    try:
+        document = json.loads(path.read_text(encoding="utf-8"))
+        raw = document["worktreeLifecycle"]
+    except (OSError, json.JSONDecodeError, KeyError, TypeError) as error:
+        raise LifecycleError(f"cannot load worktree lifecycle profile: {error}") from error
+    if raw.get("enabled") is not True:
+        raise LifecycleError("worktree lifecycle is not enabled")
+    main = tuple(raw.get("mainBranches") or ("main", "master"))
+    return WorktreeProfile(
+        root=raw.get("worktreeRoot", ".worktrees"),
+        branch_template=raw.get("branchTemplate", "{type}/{issue}-{slug}"),
+        path_template=raw.get("pathTemplate", "{type}-{issue}-{slug}"),
+        main_branches=main,
+        protected_branches=tuple(raw.get("protectedBranches") or main),
+        setup_steps=tuple(raw.get("setupSteps") or ()),
+        branch_regex=raw.get(
+            "branchRegex",
+            r"^(?:feat|fix|chore|docs)/(?P<issue>\d+)-",
+        ),
+        setup_entry=raw.get(
+            "setupEntry",
+            "python3 scripts/worktree-lifecycle/setup.py",
+        ),
+        risky_command_patterns=tuple(raw.get("riskyCommandPatterns") or (
+            r"\b(?:npm|pnpm|yarn)\s+(?:run\s+)?(?:test|typecheck|build)\b",
+            r"\bgit\s+(?:commit|push)\b",
+        )),
+    )
+
+
+def run(
+    command: list[str],
+    *,
+    cwd: Path,
+    check: bool = True,
+) -> subprocess.CompletedProcess[str]:
+    result = subprocess.run(command, cwd=cwd, capture_output=True, text=True)
+    if check and result.returncode != 0:
+        detail = (result.stderr or result.stdout).strip()
+        raise LifecycleError(f"{' '.join(command)} failed: {detail}")
+    return result
+
+
+def main_worktree(cwd: Path) -> Path:
+    output = run(["git", "worktree", "list", "--porcelain"], cwd=cwd).stdout
+    first = next((line for line in output.splitlines() if line.startswith("worktree ")), "")
+    if not first:
+        raise LifecycleError("not inside a git worktree")
+    return Path(first.split(" ", 1)[1]).resolve()
+
+
+def registered_worktrees(cwd: Path) -> set[Path]:
+    output = run(["git", "worktree", "list", "--porcelain"], cwd=cwd).stdout
+    return {
+        Path(line.split(" ", 1)[1]).resolve()
+        for line in output.splitlines()
+        if line.startswith("worktree ")
+    }
+
+
+def local_branch_exists(cwd: Path, branch: str) -> bool:
+    result = run(
+        ["git", "show-ref", "--verify", "--quiet", f"refs/heads/{branch}"],
+        cwd=cwd,
+        check=False,
+    )
+    return result.returncode == 0

package/src/lib/bundle.mjs

@@ -69,12 +69,21 @@ export const HELPER_FILES = [
   // core.py, while capabilities.json keeps the historical 8/8 denominator
   // explicit until the remaining hook and cleanup adapters are activated.
   { 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/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,
   // sync-board-status). Library (imported, not run) → 0o644. MUST ship or those
   // hooks ImportError on arrival.
   { path: '.claude/hooks/_hook_utils.py', kind: 'hook', mode: 0o644 },
+  // Thin Worktree Lifecycle adapters; all branch parsing, traversal and
+  // fail-open/fail-closed policy stays in scripts/worktree-lifecycle/core.py.
+  { path: '.claude/hooks/branch-context.py', kind: 'hook', mode: 0o755 },
+  { path: '.claude/hooks/branch-watch.py', kind: 'hook', mode: 0o755 },
+  { 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/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