@ikon85/agent-workflow-kit 0.19.0 → 0.21.0

package/.agents/skills/project-release/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: project-release
+description: "Preview and prepare one coherent version change across a consumer's profiled packages without duplicating release logic or creating commits, tags, pushes, publishes, or merges."
+---
+
+# Project Release
+
+Prepare a consumer-owned multi-package release through the kit's shared
+SemVer, preview, and transactional apply engine. This skill changes only the
+profiled version files. It does not commit, tag, push, publish, or merge.
+
+## Profile contract
+
+Read `docs/agents/workflow-capabilities.json`. The consumer owns this file and
+its unknown keys. Project Release requires this versioned section:
+
+```json
+{
+  "schemaVersion": 1,
+  "projectRelease": {
+    "versionFiles": [
+      "package.json",
+      "packages/example/package.json"
+    ],
+    "tagPrefix": "v"
+  }
+}
+```
+
+Every `versionFiles` path is repository-relative and must name a JSON file with
+the same current SemVer. Never infer or silently add package files.
+
+## Workflow
+
+1. Run a byte-neutral preview for exactly one Patch, Minor, Major, or explicit
+   SemVer target:
+
+   ```sh
+   node scripts/project-release.mjs preview <patch|minor|major|version>
+   ```
+
+2. Report the structured result: exact current and target version, package
+   count, synchronized files, planned commit/tag actions, confirmation token,
+   and every blocker. Invalid or divergent versions, dirty profiled targets,
+   and an existing target tag block before the first write.
+
+3. Ask the user to confirm the exact target and preview confirmation token.
+   Do not treat a bump recommendation or a prior preview as confirmation.
+
+4. Apply only that still-current preview:
+
+   ```sh
+   node scripts/project-release.mjs apply <patch|minor|major|version> \
+     --confirm <confirmation-token>
+   ```
+
+   Apply re-reads repository facts and every target byte. A stale token,
+   changed target, blocked preview, partial write, or repeated apply fails
+   without a double bump. Partial writes roll back to the original bytes.
+
+5. Inspect the resulting version-file diff, then hand commit, tag, push,
+   publish, and merge to the repository's normal release/landing workflow.
+   Project Release does not commit, tag, push, publish, or merge.
+
+## Safety contract
+
+- Preview is repeatable and byte-neutral.
+- Apply writes only `projectRelease.versionFiles`.
+- Commit and tag entries in preview output are plans, never side effects.
+- Existing tags are never overwritten.
+- No runtime dependency is required beyond Node.js and Git.

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

@@ -21,6 +21,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
 - **Preview or restore consumer-owned memories:** use `memory-lifecycle` to classify every configured path without writing, then apply an explicitly approved collision-safe restore with a content-free receipt.
 - **Finished slice:** use `wrapup` to prepare the branch, PR, and cleanup steps your repo expects.
 - **Kit release:** use `kit-release` to derive the shipped delta, confirm Semver, regenerate the manifest, run all gates, and then hand landing to `wrapup`.
+- **Consumer project release:** use `project-release` to preview and transactionally prepare one coherent version across the package files named by the consumer-owned capability profile.
 - **Kit update:** use `kit-update` to preview and transactionally apply a parity-verified scoped release without overwriting local modifications.
 - **A huge, foggy effort, too big for one session:** use `wayfinder` — it charts it as a shared map of investigation tickets, resolving one per session.
 

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/.claude/skills/project-release/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: project-release
+description: "Preview and prepare one coherent version change across a consumer's profiled packages without duplicating release logic or creating commits, tags, pushes, publishes, or merges."
+---
+
+# Project Release
+
+Prepare a consumer-owned multi-package release through the kit's shared
+SemVer, preview, and transactional apply engine. This skill changes only the
+profiled version files. It does not commit, tag, push, publish, or merge.
+
+## Profile contract
+
+Read `docs/agents/workflow-capabilities.json`. The consumer owns this file and
+its unknown keys. Project Release requires this versioned section:
+
+```json
+{
+  "schemaVersion": 1,
+  "projectRelease": {
+    "versionFiles": [
+      "package.json",
+      "packages/example/package.json"
+    ],
+    "tagPrefix": "v"
+  }
+}
+```
+
+Every `versionFiles` path is repository-relative and must name a JSON file with
+the same current SemVer. Never infer or silently add package files.
+
+## Workflow
+
+1. Run a byte-neutral preview for exactly one Patch, Minor, Major, or explicit
+   SemVer target:
+
+   ```sh
+   node scripts/project-release.mjs preview <patch|minor|major|version>
+   ```
+
+2. Report the structured result: exact current and target version, package
+   count, synchronized files, planned commit/tag actions, confirmation token,
+   and every blocker. Invalid or divergent versions, dirty profiled targets,
+   and an existing target tag block before the first write.
+
+3. Ask the user to confirm the exact target and preview confirmation token.
+   Do not treat a bump recommendation or a prior preview as confirmation.
+
+4. Apply only that still-current preview:
+
+   ```sh
+   node scripts/project-release.mjs apply <patch|minor|major|version> \
+     --confirm <confirmation-token>
+   ```
+
+   Apply re-reads repository facts and every target byte. A stale token,
+   changed target, blocked preview, partial write, or repeated apply fails
+   without a double bump. Partial writes roll back to the original bytes.
+
+5. Inspect the resulting version-file diff, then hand commit, tag, push,
+   publish, and merge to the repository's normal release/landing workflow.
+   Project Release does not commit, tag, push, publish, or merge.
+
+## Safety contract
+
+- Preview is repeatable and byte-neutral.
+- Apply writes only `projectRelease.versionFiles`.
+- Commit and tag entries in preview output are plans, never side effects.
+- Existing tags are never overwritten.
+- No runtime dependency is required beyond Node.js and Git.

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

@@ -21,6 +21,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
 - **Preview or restore consumer-owned memories:** use `memory-lifecycle` to classify every configured path without writing, then apply an explicitly approved collision-safe restore with a content-free receipt.
 - **Finished slice:** use `wrapup` to prepare the branch, PR, and cleanup steps your repo expects.
 - **Kit release:** use `kit-release` to derive the shipped delta, confirm Semver, regenerate the manifest, run all gates, and then hand landing to `wrapup`.
+- **Consumer project release:** use `project-release` to preview and transactionally prepare one coherent version across the package files named by the consumer-owned capability profile.
 - **Kit update:** use `kit-update` to preview and transactionally apply a parity-verified scoped release without overwriting local modifications.
 - **A huge, foggy effort, too big for one session:** use `wayfinder` — it charts it as a shared map of investigation tickets, resolving one per session.
 

package/.claude/skills/skill-manifest.json

@@ -395,6 +395,16 @@
       ],
       "provenance": "own"
     },
+    "project-release": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
     "kit-update": {
       "class": "generic",
       "publish": true,

package/PROVENANCE.md

@@ -33,7 +33,7 @@ carries Chase's `THIRD-PARTY-NOTICES.md`.
 
 retro, wrapup, spec-self-critique, board-to-waves, verify-spike, decision-gate,
 codex-adapter-sync, setup-pre-commit, code-review, orchestrate-wave,
-census-update, memory-lifecycle — covered by the root LICENSE.
+census-update, memory-lifecycle, project-release — covered by the root LICENSE.
 `setup-pre-commit` was rewritten from Matt Pocock's husky-based skill to a
 zero-dep native git `core.hooksPath` scaffold; nothing of the original
 mechanic remains (courtesy attribution).

package/README.md

@@ -332,6 +332,28 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.21.0
+
+- added: `.agents/skills/project-release/SKILL.md`
+- added: `.claude/skills/project-release/SKILL.md`
+- added: `scripts/project-release.mjs`
+- added: `src/lib/release-apply.mjs`
+- changed: `.agents/skills/setup-workflow/workflow-overview.md`
+- changed: `.claude/skills/setup-workflow/workflow-overview.md`
+- changed: `scripts/kit-release.mjs`
+
+### 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`
@@ -640,12 +662,13 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## What's in the box
 
-**41 skills** (Router: ask-matt — "which skill/flow fits?" · Plan: grill-me,
+**42 skills** (Router: ask-matt — "which skill/flow fits?" · Plan: grill-me,
 grill-with-docs, to-prd, to-issues, board-to-waves, triage, spec-self-critique,
 verify-spike, decision-gate, scale-check, to-waves, wayfinder, research · Execute: tdd, prototype, implement, orchestrate-wave ·
 Design/diagnose/refactor streams: diagnose, zoom-out,
 improve-codebase-architecture, codebase-design, domain-modeling, security-audit · Land: wrapup,
-resolving-merge-conflicts, code-review, local-ci, git-worktree-recover, kit-release · Learn: retro, audit-skills, write-a-skill · Setup:
+resolving-merge-conflicts, code-review, local-ci, git-worktree-recover, kit-release,
+project-release · Learn: retro, audit-skills, write-a-skill · Setup:
 setup-workflow, git-guardrails, setup-pre-commit · Codex cross-model: grill-me-codex,
 grill-with-docs-codex, codex-review, codex-build),
 installed for both surfaces — `.claude/skills`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.19.0",
+  "kitVersion": "0.21.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",
@@ -609,7 +618,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "c522a7de1b8eaa827a72880651a94aca6d066687e8c21b789d9008e3321f7362",
+      "sha256": "bc4db6413135ad9056cc63691cb823a9b198ad47538f292b37fcbb915477a716",
       "mode": 420,
       "origin": "kit"
     },
@@ -859,10 +868,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 +893,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",
@@ -1370,6 +1414,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",
@@ -1618,7 +1671,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "c522a7de1b8eaa827a72880651a94aca6d066687e8c21b789d9008e3321f7362",
+      "sha256": "bc4db6413135ad9056cc63691cb823a9b198ad47538f292b37fcbb915477a716",
       "mode": 420,
       "origin": "kit"
     },
@@ -1993,7 +2046,7 @@
     {
       "path": "scripts/kit-release.mjs",
       "kind": "script",
-      "sha256": "d3148aab63fa670c0a3407d2816d287b7cdeaa130588fb55b6075217da95d3d3",
+      "sha256": "3c86eb5fc4b2071b423d87f023ba4c3f778ffe716a2603dcecdbe4e83ec1b8df",
       "mode": 420,
       "origin": "kit"
     },
@@ -2067,6 +2120,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",
@@ -2098,7 +2158,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"
     },
@@ -2116,6 +2190,13 @@
       "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.19.0",
+  "version": "0.21.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/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

@@ -48,9 +48,12 @@ export const HELPER_FILES = [
   { 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.
+  // primitives before any apply/commit/tag action is allowed. The thin CLI
+  // owns only repository-fact collection and delegates to the same engine.
   { path: 'src/lib/semver.mjs', kind: 'script', mode: 0o644 },
   { path: 'src/lib/release-preview.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/release-apply.mjs', kind: 'script', mode: 0o644 },
+  { path: 'scripts/project-release.mjs', kind: 'script', mode: 0o755 },
   // 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 },
@@ -69,12 +72,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

package/src/lib/release-apply.mjs

@@ -0,0 +1,81 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { writeAtomic } from './atomicWrite.mjs';
+
+const sha256 = (body) => createHash('sha256').update(body).digest('hex');
+
+async function readSnapshot(consumerRoot, snapshot) {
+  return Promise.all(snapshot.map(async ({ path }) => {
+    const body = await readFile(join(consumerRoot, path), 'utf8');
+    return { path, body, version: JSON.parse(body).version, sha256: sha256(body) };
+  }));
+}
+
+const escapes = (root, target) => {
+  const path = relative(root, target);
+  return path === '..' || path.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`)
+    || isAbsolute(path);
+};
+
+export async function assertSafeReleaseTargets(consumerRoot, paths) {
+  const canonicalRoot = await realpath(consumerRoot);
+  for (const path of paths) {
+    const target = resolve(consumerRoot, path);
+    if (isAbsolute(path) || escapes(resolve(consumerRoot), target)) {
+      throw new Error(`release target is outside consumer root: ${path}`);
+    }
+    if ((await lstat(target)).isSymbolicLink()) {
+      throw new Error(`symlinked release target is not allowed: ${path}`);
+    }
+    if (escapes(canonicalRoot, await realpath(target))) {
+      throw new Error(`release target resolves outside consumer root: ${path}`);
+    }
+  }
+}
+
+export async function applyProjectRelease(options) {
+  const { consumerRoot, preview, confirmation } = options;
+  const write = options.write ?? writeAtomic;
+  if (preview.status !== 'ready') throw new Error('release preview is blocked');
+  if (confirmation !== preview.confirmation) {
+    throw new Error('release confirmation does not match preview');
+  }
+  await assertSafeReleaseTargets(
+    consumerRoot, preview.snapshot.map(({ path }) => path),
+  );
+  const current = await readSnapshot(consumerRoot, preview.snapshot);
+  if (current.every(({ version }) => version === preview.summary.targetVersion)) {
+    throw new Error(`release already prepared at ${preview.summary.targetVersion}`);
+  }
+  for (const expected of preview.snapshot) {
+    const actual = current.find(({ path }) => path === expected.path);
+    if (actual.sha256 !== expected.sha256) {
+      throw new Error(`release target changed after preview: ${expected.path}`);
+    }
+  }
+  const version = preview.summary.targetVersion;
+  const candidates = current.map((file) => {
+    const body = JSON.parse(file.body);
+    body.version = version;
+    return { ...file, next: `${JSON.stringify(body, null, 2)}\n` };
+  });
+  const written = [];
+  try {
+    for (const file of candidates) {
+      await write(join(consumerRoot, file.path), file.next);
+      written.push(file);
+    }
+  } catch (error) {
+    for (const file of written.reverse()) {
+      await writeAtomic(join(consumerRoot, file.path), file.body);
+    }
+    throw error;
+  }
+  return {
+    status: 'prepared',
+    version,
+    updated: candidates.map(({ path }) => path),
+    plannedTag: preview.actions.find(({ type }) => type === 'tag').name,
+  };
+}