@ikon85/agent-workflow-kit 0.16.4 → 0.18.0

package/.claude/hooks/_hook_utils.py

@@ -21,12 +21,15 @@ Migration notes for hook refactors:
 """
 import re
 import subprocess
+import importlib.util
+import sys
 from datetime import datetime
 from pathlib import Path
 
 # Resolved relative to CWD at call time. Hooks are invoked from repo root
 # (or from a linked worktree root), so this resolves to <root>/.claude/logs.
 LOG_DIR = Path(".claude/logs")
+_WORKTREE_CORE_MODULE = "_agent_workflow_kit_worktree_lifecycle"
 
 
 def rotate_log_if_needed(log_path: Path, max_bytes: int = 100_000, generations: int = 3) -> None:
@@ -182,3 +185,28 @@ def normalize_to_repo_relative(file_path: str, root: str) -> str | None:
         return str(rel)
     except ValueError:
         return None
+
+
+def load_worktree_lifecycle_core():
+    """Load the shipped Worktree Lifecycle core without requiring a Python package."""
+    existing = sys.modules.get(_WORKTREE_CORE_MODULE)
+    if existing is not None:
+        return existing
+    path = Path(__file__).resolve().parents[2] / "scripts" / "worktree-lifecycle" / "core.py"
+    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}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[_WORKTREE_CORE_MODULE] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def hook_event_output(event_name: str, context: str) -> dict:
+    """Canonical non-blocking context payload for Claude hook events."""
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": event_name,
+            "additionalContext": context,
+        }
+    }

package/README.md

@@ -332,6 +332,18 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.18.0
+
+- added: `scripts/worktree-lifecycle/capabilities.json`
+- added: `scripts/worktree-lifecycle/core.py`
+- added: `scripts/worktree-lifecycle/setup.py`
+- changed: `.claude/hooks/_hook_utils.py`
+
+### 0.17.0
+
+- added: `src/lib/release-preview.mjs`
+- added: `src/lib/semver.mjs`
+
 ### 0.16.4
 
 - Metadata-only release.

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.16.4",
+  "kitVersion": "0.18.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -850,7 +850,7 @@
     {
       "path": ".claude/hooks/_hook_utils.py",
       "kind": "hook",
-      "sha256": "d16ca26f3057a500cc67242fd67125d1715e7e7fd2984398545f6374fef497bb",
+      "sha256": "4a4b57633578ee8eabdf8ae70437e590e1747d1df5d76c730e2164e23cdfc2ed",
       "mode": 420,
       "origin": "kit"
     },
@@ -2063,12 +2063,47 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "scripts/worktree-lifecycle/capabilities.json",
+      "kind": "doc",
+      "sha256": "3e51acaf2a8ac3ace0a400e23a30732ff0c3e9b4864f763c7abf82019605f309",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/worktree-lifecycle/core.py",
+      "kind": "script",
+      "sha256": "eae5c6076611a36a8fa90e3aef3d1c49345110a392a7d7e9d95be8de00f8d9ff",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/worktree-lifecycle/setup.py",
+      "kind": "script",
+      "sha256": "c720cbff9123f136a53658671d880b9a73f9da4faa0611e37a2a981fa89cda92",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": "scripts/wrapup-land.py",
       "kind": "script",
       "sha256": "24ce9373c464cc8363c53b0c690c3231cbf11362e6e08336e0e97663579d1f19",
       "mode": 493,
       "origin": "kit"
+    },
+    {
+      "path": "src/lib/release-preview.mjs",
+      "kind": "script",
+      "sha256": "a4e6627fac2d62812e44cfcb80c46539563734e7fa11f94b3dda37ff6fe6ae8f",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "src/lib/semver.mjs",
+      "kind": "script",
+      "sha256": "7d0a8da3740ed1eb79edb80f0eedb3cd1de47692d4886c6b119b39073a6468d1",
+      "mode": 420,
+      "origin": "kit"
     }
   ]
 }

package/docs/research/wave-43-script-hook-census.md

@@ -0,0 +1,128 @@
+# Wave 43 script and hook census
+
+Verified on 2026-07-15 against `agent-workflow-kit` commit
+`2d47dce23d9204b44951334c3c370bdb997c0943` and Testreporter commit
+[`458747ebe8d67f66840cb3c1e75284cf2be7fb20`](https://github.com/iKon85/Testreporter/tree/458747ebe8d67f66840cb3c1e75284cf2be7fb20).
+This is the research input for issue #59. It records facts only; it does not make
+ship, opt-in, profile-seam, or maintenance decisions.
+
+## Method and reconciliation
+
+The public-repository denominator is every tracked file below `scripts/**` and
+`.claude/hooks/**`, excluding `test_*.py`, `*.test.mjs`, and the metadata file
+`scripts/.npmignore`. The recount is:
+
+```text
+68 tracked entries
+- 31 tests
+-  1 metadata file
+= 36 current script/hook entries
+= 32 scripts + 4 hooks
+= 30 shipped helpers + 6 maintainer-only helpers
+```
+
+The shipped/helper split is derived from
+[`src/lib/bundle.mjs`](../../src/lib/bundle.mjs), whose `HELPER_FILES` list is
+the public distribution authority. The historical input is the 26-candidate
+list in [Testreporter #1976](https://github.com/iKon85/Testreporter/issues/1976),
+originally reconciled as 11 portable plus 15 generalize-first candidates in
+[Testreporter #1964](https://github.com/iKon85/Testreporter/issues/1964).
+
+Fresh exact-path comparison:
+
+```text
+Historical candidates:                       26/26 accounted for
+Still present at the exact Testreporter path: 26/26
+Present at the exact public-repo path:         0/26
+Proven exact rename in the public repo:        0/26
+Explicitly retired by a locked decision:       0/26
+```
+
+Therefore every historical row is classified as **present in the current
+consumer and absent from the current public denominator**. Related public
+primitives are called out only as inputs to the later grill; similarity is not
+treated as proof of a rename or as a ship decision.
+
+## Fresh public denominator: 36 of 36
+
+| Current path | Distribution status |
+|---|---|
+| `.claude/hooks/_hook_utils.py` | shipped helper |
+| `.claude/hooks/drift-guard.py` | shipped helper |
+| `.claude/hooks/skill-drift-hint.py` | shipped helper |
+| `.claude/hooks/sync-board-status.py` | shipped helper |
+| `scripts/anchor_table.py` | shipped helper |
+| `scripts/board-sync.py` | shipped helper |
+| `scripts/board_config.py` | shipped helper |
+| `scripts/board_fields.py` | shipped helper |
+| `scripts/build-kit.mjs` | maintainer-only |
+| `scripts/census/delta.mjs` | shipped helper |
+| `scripts/census/fingerprint.mjs` | shipped helper |
+| `scripts/census/index.mjs` | shipped helper |
+| `scripts/census/scan.mjs` | shipped helper |
+| `scripts/census/state.mjs` | shipped helper |
+| `scripts/census/transaction.mjs` | shipped helper |
+| `scripts/check-kit-staleness.mjs` | maintainer-only |
+| `scripts/execute-ready-check.py` | shipped helper |
+| `scripts/grill-census-wiring-guard.mjs` | maintainer-only |
+| `scripts/issue_deps.py` | shipped helper |
+| `scripts/kit-release.mjs` | shipped helper |
+| `scripts/kit-update-pr.mjs` | shipped helper |
+| `scripts/lib/audit-refs.mjs` | maintainer-only |
+| `scripts/lib/scrub.mjs` | maintainer-only |
+| `scripts/loc_offender_core.py` | shipped helper |
+| `scripts/loc_offender_gate.py` | shipped helper |
+| `scripts/node_kind.py` | shipped helper |
+| `scripts/portability_profile_scan.py` | maintainer-only |
+| `scripts/pr-body-check.py` | shipped helper |
+| `scripts/program_graph.py` | shipped helper |
+| `scripts/program_graph_parse.py` | shipped helper |
+| `scripts/program_graph_validate.py` | shipped helper |
+| `scripts/program_sync.py` | shipped helper |
+| `scripts/release-delta-guard.mjs` | shipped helper |
+| `scripts/release-parity.mjs` | shipped helper |
+| `scripts/release-state.mjs` | shipped helper |
+| `scripts/wrapup-land.py` | shipped helper |
+
+## Historical candidate crosswalk: 26 of 26
+
+All Testreporter links below are pinned to the verified consumer commit. “No
+dedicated tracked test found” means the fresh tracked-tree search found no test
+named for that candidate; it is not a statement about runtime correctness.
+
+| Historical candidate | Current public status and adjacent evidence | Current consumer dependency | Existing consumer test evidence |
+|---|---|---|---|
+| `scripts/audit_gate.py` | Exact path absent. | [`package.json#L44`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/package.json#L44) and `.githooks/pre-push` invoke it. | [`scripts/test_audit_gate.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/scripts/test_audit_gate.py), [`scripts/test_pre_push_audit_gate.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/scripts/test_pre_push_audit_gate.py) |
+| `scripts/cleanup-worktrees.sh` | Exact path absent. Public `scripts/wrapup-land.py` has adjacent worktree-cleanup behavior, not a proven rename. | No separate tracked consumer found beyond direct/manual use. | No dedicated tracked test found. |
+| `scripts/install-git-hooks.sh` | Exact path absent. | [`package.json#L45`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/package.json#L45) invokes it during postinstall. | [`scripts/test_install_git_hooks.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/scripts/test_install_git_hooks.py) |
+| `scripts/ensure-gitleaks.sh` | Exact path absent. | [`package.json#L45`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/package.json#L45) invokes it during postinstall; `docs/security/secret-scan.md` documents it. | No dedicated tracked test found. |
+| `.claude/hooks/block-bg-double-background.py` | Exact path absent. | [`.claude/settings.json#L85`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L85) wires it. | [`.claude/hooks/test_block_bg_double_background.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_block_bg_double_background.py) |
+| `.claude/hooks/block-npm-install-in-pnpm.py` | Exact path absent. | [`.claude/settings.json#L75`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L75) wires it. | [`.claude/hooks/test_block_npm_install_in_pnpm.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_block_npm_install_in_pnpm.py) |
+| `.claude/hooks/block-secrets.py` | Exact path absent. | [`.claude/settings.json#L56-L65`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L56-L65) wires it at two hook events. | [`.claude/hooks/test_block_secrets_smoke.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_block_secrets_smoke.py) |
+| `.claude/hooks/branch-watch.py` | Exact path absent. | [`.claude/settings.json#L161`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L161) wires it. | [`.claude/hooks/test_branch_watch_smoke.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_branch_watch_smoke.py) |
+| `.claude/hooks/grep-shim-guard.py` | Exact path absent. | [`.claude/settings.json#L80`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L80) wires it. | [`.claude/hooks/test_grep_shim_guard.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_grep_shim_guard.py) |
+| `.claude/hooks/recon-size-hint.py` | Exact path absent. | [`.claude/settings.json#L134`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L134) wires it. | [`.claude/hooks/test_recon_size_hint.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_recon_size_hint.py) |
+| `.claude/hooks/loc-offender-forewarn.py` | Exact path absent. Public `scripts/loc_offender_core.py` and `scripts/loc_offender_gate.py` are related shipped primitives, not a proven rename. | [`.claude/settings.json#L18`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L18) wires it. | [`scripts/test_loc_offender_forewarn.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/scripts/test_loc_offender_forewarn.py) |
+| `scripts/bump-version.sh` | Exact path absent. Public `scripts/kit-release.mjs` contains tested SemVer and metadata-update behavior, not a proven rename. | No separate consumer wiring found; the script is directly invoked. | No dedicated tracked test found for the historical script. |
+| `scripts/consolidate-memories.sh` | Exact path absent. | The two historical memory templates name it as their consolidator. | No dedicated tracked test found. |
+| `scripts/memory-templates/meta_decision_layer_choice.md` | Exact path absent. | Input consumed by `scripts/consolidate-memories.sh`. | No dedicated tracked test found. |
+| `scripts/memory-templates/meta_memory_lifecycle.md` | Exact path absent. | Input consumed by `scripts/consolidate-memories.sh`. | No dedicated tracked test found. |
+| `scripts/setup-worktree.sh` | Exact path absent. Public workflow prose allows a project helper or plain `git worktree add`; that is not a rename. | Central Testreporter worktree, port, and local-env setup primitive referenced by workflow documentation. | [`scripts/setup-worktree.test.mjs`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/scripts/setup-worktree.test.mjs), [`scripts/test_pre_push_loc_gate.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/scripts/test_pre_push_loc_gate.py) |
+| `.claude/hooks/baseline-capture-hint.py` | Exact path absent. | [`.claude/settings.json#L114`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L114) wires it. | [`.claude/hooks/test_baseline_capture_hint_smoke.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_baseline_capture_hint_smoke.py) |
+| `.claude/hooks/branch-context.py` | Exact path absent. | [`.claude/settings.json#L13`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L13) wires it. | [`.claude/hooks/test_branch_context_smoke.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_branch_context_smoke.py) |
+| `.claude/hooks/convention-drift-hint.py` | Exact path absent. Public `.claude/hooks/skill-drift-hint.py` and `drift-guard.py` are narrower adjacent mechanisms, not proven renames. | [`.claude/settings.json#L33`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L33) and rule `SOURCES.txt` files refer to it. | No dedicated tracked test found. |
+| `.claude/hooks/enforce-worktree.py` | Exact path absent. | [`.claude/settings.json#L109`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L109) wires it. | [`.claude/hooks/test_enforce_worktree.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_enforce_worktree.py) |
+| `.claude/hooks/enforce-worktree-cwd.py` | Exact path absent. | [`.claude/settings.json#L95`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L95) wires it. | [`.claude/hooks/test_enforce_worktree_cwd_smoke.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_enforce_worktree_cwd_smoke.py) |
+| `.claude/hooks/enforce-worktree-discipline.py` | Exact path absent. | [`.claude/settings.json#L70`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L70) wires it. | [`.claude/hooks/test_enforce_worktree_discipline_smoke.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_enforce_worktree_discipline_smoke.py) |
+| `.claude/hooks/migration-snapshot-reminder.py` | Exact path absent. | [`.claude/settings.json#L166`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L166) wires it. | [`.claude/hooks/test_migration_snapshot_reminder_smoke.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_migration_snapshot_reminder_smoke.py) |
+| `.claude/hooks/pre-refactor-sweep.py` | Exact path absent. | [`.claude/settings.json#L23`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L23) wires it. | [`.claude/hooks/test_pre_refactor_sweep.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_pre_refactor_sweep.py) |
+| `.claude/hooks/typecheck-on-stop.sh` | Exact path absent. | [`.claude/settings.json#L145`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L145) wires it. | No dedicated tracked test found. |
+| `.claude/hooks/slice-handoff-hint.py` | Exact path absent. | [`.claude/settings.json#L44`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L44) wires it. | [`.claude/hooks/test_slice_handoff_hint_smoke.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_slice_handoff_hint_smoke.py) |
+
+## Inputs for the decision grill
+
+The crosswalk establishes the decision set but intentionally leaves its verdict
+columns blank. Issue #59 must decide, with the user, each row’s outcome, opt-in,
+profile seam, security and maintenance cost, and ship verdict. In particular,
+the adjacent public primitives identified above must be compared behaviorally
+before any row is called replaced, redundant, or already shipped.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.16.4",
+  "version": "0.18.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/capabilities.json

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

package/scripts/worktree-lifecycle/core.py

@@ -0,0 +1,106 @@
+"""Consumer-neutral worktree lifecycle profile and git facts."""
+
+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
+
+    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+)-",
+        ),
+    )
+
+
+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/scripts/worktree-lifecycle/setup.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Create a configured, rollback-safe consumer worktree."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+import zlib
+from pathlib import Path
+
+from core import (
+    LifecycleError,
+    load_profile,
+    local_branch_exists,
+    main_worktree,
+    registered_worktrees,
+    run,
+)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--profile", default="docs/agents/workflow-capabilities.json")
+    parser.add_argument("--base", default="origin/main")
+    parser.add_argument("issue")
+    parser.add_argument("slug")
+    parser.add_argument("branch_type", nargs="?", default="feat")
+    return parser.parse_args()
+
+
+def port_slot(step: dict, issue: str, branch: str) -> int:
+    modulo = int(step.get("slotModulo", 900))
+    offset = int(step.get("slotOffset", 1))
+    seed = int(issue) if issue.isdigit() else zlib.crc32(branch.encode("utf-8"))
+    return seed % modulo + offset
+
+
+def write_ports(step: dict, *, worktree: Path, issue: str, branch: str) -> None:
+    slot = port_slot(step, issue, branch)
+    stride = int(step.get("stride", 10))
+    outputs = step.get("outputs") or {}
+    if not outputs:
+        raise LifecycleError("ports step requires outputs")
+    unsafe = {int(port) for port in step.get("unsafePorts", ())}
+    modulo = int(step.get("slotModulo", 900))
+    for _ in range(modulo):
+        ports = [int(base) + slot * stride for base in outputs.values()]
+        if not unsafe.intersection(ports):
+            break
+        slot = slot % modulo + 1
+    else:
+        raise LifecycleError("port profile has no safe allocation")
+    lines = [f"{name}={int(base) + slot * stride}" for name, base in outputs.items()]
+    (worktree / ".dev-ports").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def execute_step(
+    step: dict,
+    *,
+    main: Path,
+    worktree: Path,
+    issue: str,
+    branch: str,
+) -> None:
+    kind = step.get("kind")
+    if kind == "copy":
+        source = main / step["source"]
+        target = worktree / step.get("target", step["source"])
+        if not source.exists() and step.get("optional"):
+            return
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, target)
+        return
+    if kind == "command":
+        command = step.get("command")
+        if not isinstance(command, list) or not all(isinstance(part, str) for part in command):
+            raise LifecycleError("setup command must be a JSON string array")
+        run(command, cwd=worktree)
+        return
+    if kind == "ports":
+        write_ports(step, worktree=worktree, issue=issue, branch=branch)
+        return
+    raise LifecycleError(f"unsupported setup step kind: {kind!r}")
+
+
+def remove_failed_worktree(main: Path, target: Path, branch: str, created_branch: bool) -> None:
+    run(["git", "worktree", "remove", "--force", str(target)], cwd=main, check=False)
+    if created_branch:
+        run(["git", "branch", "-d", branch], cwd=main, check=False)
+
+
+def create(args: argparse.Namespace) -> Path:
+    cwd = Path.cwd()
+    main = main_worktree(cwd)
+    profile_path = Path(args.profile)
+    if not profile_path.is_absolute():
+        profile_path = main / profile_path
+    profile = load_profile(profile_path)
+    branch = profile.branch_name(args.issue, args.slug, args.branch_type)
+    target = (main / profile.relative_path(args.issue, args.slug, args.branch_type)).resolve()
+
+    if target in registered_worktrees(main):
+        print(f"Worktree already exists: {target} ({branch})")
+        return target
+
+    branch_existed = local_branch_exists(main, branch)
+    command = ["git", "worktree", "add", str(target)]
+    command += [branch] if branch_existed else ["-b", branch, args.base]
+    run(command, cwd=main)
+    try:
+        for step in profile.setup_steps:
+            execute_step(
+                step,
+                main=main,
+                worktree=target,
+                issue=args.issue,
+                branch=branch,
+            )
+    except Exception:
+        remove_failed_worktree(main, target, branch, not branch_existed)
+        raise
+    print(f"Worktree ready: {target} ({branch})")
+    return target
+
+
+def main() -> int:
+    try:
+        create(parse_args())
+        return 0
+    except LifecycleError as error:
+        print(f"STOP: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/lib/bundle.mjs

@@ -47,6 +47,10 @@ export const HELPER_FILES = [
   // the parity primitive rather than growing a second registry/GitHub comparison.
   { path: 'scripts/release-parity.mjs', kind: 'script', mode: 0o644 },
   { path: 'scripts/release-state.mjs', kind: 'script', mode: 0o644 },
+  // Consumer-owned project release profiles use these read-only shared
+  // primitives before any apply/commit/tag action is allowed.
+  { path: 'src/lib/semver.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/release-preview.mjs', kind: 'script', mode: 0o644 },
   // GitHub-consumer automation: invokes the existing update command, then owns
   // only the stable tested branch/pull-request upsert.
   { path: 'scripts/kit-update-pr.mjs', kind: 'script', mode: 0o755 },
@@ -58,6 +62,12 @@ 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 },
+  // 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/setup.py', kind: 'script', mode: 0o755 },
+  { path: 'scripts/worktree-lifecycle/capabilities.json', 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.

package/src/lib/release-preview.mjs

@@ -0,0 +1,114 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { nextVersion, parseSemver } from './semver.mjs';
+
+export const PROJECT_RELEASE_PROFILE = 'docs/agents/workflow-capabilities.json';
+
+export async function loadProjectReleaseProfile(consumerRoot) {
+  const profile = JSON.parse(
+    await readFile(join(consumerRoot, PROJECT_RELEASE_PROFILE), 'utf8'),
+  );
+  if (profile.schemaVersion !== 1 || !profile.projectRelease) {
+    throw new Error('project release profile must contain schemaVersion 1 and projectRelease');
+  }
+  if (!Array.isArray(profile.projectRelease.versionFiles)
+      || profile.projectRelease.versionFiles.length === 0) {
+    throw new Error('project release profile requires at least one versionFiles entry');
+  }
+  return profile.projectRelease;
+}
+
+async function readVersionFile(consumerRoot, path) {
+  const raw = await readFile(join(consumerRoot, path), 'utf8');
+  const body = JSON.parse(raw);
+  return {
+    path,
+    version: body.version,
+    sha256: createHash('sha256').update(raw).digest('hex'),
+  };
+}
+
+export async function previewProjectRelease(options) {
+  const {
+    consumerRoot, profile, requestedVersion,
+    repositoryFacts = { dirtyPaths: [], existingTags: [] },
+  } = options;
+  const files = await Promise.all(
+    profile.versionFiles.map((path) => readVersionFile(consumerRoot, path)),
+  );
+  const currentVersion = files[0].version;
+  const paths = files.map(({ path }) => path);
+  const invalidFiles = files.filter(({ version }) => {
+    try { parseSemver(version); return false; } catch { return true; }
+  });
+  if (invalidFiles.length) {
+    return {
+      status: 'blocked',
+      summary: {
+        currentVersion,
+        targetVersion: null,
+        packageCount: paths.length,
+        synchronizedFiles: paths,
+      },
+      blockers: [{
+        code: 'invalid-current-version',
+        files: invalidFiles.map(({ path, version }) => ({ path, version })),
+      }],
+      actions: [],
+      repositoryFacts,
+    };
+  }
+  let targetVersion;
+  try {
+    targetVersion = nextVersion(currentVersion, requestedVersion);
+  } catch {
+    return {
+      status: 'blocked',
+      summary: {
+        currentVersion,
+        targetVersion: null,
+        packageCount: paths.length,
+        synchronizedFiles: paths,
+      },
+      blockers: [{ code: 'invalid-target-version', requestedVersion }],
+      actions: [],
+      repositoryFacts,
+    };
+  }
+  const tag = `${profile.tagPrefix ?? 'v'}${targetVersion}`;
+  const blockers = [];
+  if (files.some(({ version }) => version !== currentVersion)) {
+    blockers.push({
+      code: 'divergent-versions',
+      files: files.map(({ path, version }) => ({ path, version })),
+    });
+  }
+  const dirtyTargets = paths.filter((path) => repositoryFacts.dirtyPaths.includes(path));
+  if (dirtyTargets.length) blockers.push({ code: 'dirty-targets', paths: dirtyTargets });
+  if (repositoryFacts.existingTags.includes(tag)) {
+    blockers.push({ code: 'existing-tag', tag });
+  }
+  const snapshot = files.map(({ path, sha256 }) => ({ path, sha256 }));
+  const confirmation = createHash('sha256').update(JSON.stringify({
+    currentVersion, targetVersion, snapshot, tag,
+  })).digest('hex');
+  return {
+    status: blockers.length ? 'blocked' : 'ready',
+    summary: {
+      currentVersion,
+      targetVersion,
+      packageCount: paths.length,
+      synchronizedFiles: paths,
+    },
+    blockers,
+    actions: [
+      { type: 'write-version', version: targetVersion, paths },
+      { type: 'commit', message: `chore: prepare project release ${targetVersion}` },
+      { type: 'tag', name: tag },
+    ],
+    repositoryFacts,
+    snapshot,
+    confirmation,
+  };
+}

package/src/lib/semver.mjs

@@ -0,0 +1,25 @@
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+export function parseSemver(version) {
+  const match = SEMVER.exec(version);
+  if (!match) throw new Error(`invalid semver: ${version}`);
+  return match.slice(1).map(Number);
+}
+
+export function compareSemver(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  for (let index = 0; index < a.length; index += 1) {
+    if (a[index] !== b[index]) return Math.sign(a[index] - b[index]);
+  }
+  return 0;
+}
+
+export function nextVersion(current, requested) {
+  const [major, minor, patch] = parseSemver(current);
+  if (requested === 'major') return `${major + 1}.0.0`;
+  if (requested === 'minor') return `${major}.${minor + 1}.0`;
+  if (requested === 'patch') return `${major}.${minor}.${patch + 1}`;
+  parseSemver(requested);
+  return requested;
+}