@ikon85/agent-workflow-kit 0.18.0 → 0.20.0

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

@@ -62,16 +62,28 @@ export const HELPER_FILES = [
   { path: 'scripts/census/delta.mjs', kind: 'script', mode: 0o644 },
   { path: 'scripts/census/state.mjs', kind: 'script', mode: 0o644 },
   { path: 'scripts/census/transaction.mjs', kind: 'script', mode: 0o644 },
+  // Consumer-owned memory planning and recovery. The module is both the stable
+  // skill API and the no-write-by-default CLI.
+  { path: 'scripts/memory-lifecycle/index.mjs', kind: 'script', mode: 0o644 },
   // Profile-driven Worktree Lifecycle foundation. The setup adapter imports
   // 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