@ikon85/agent-workflow-kit 0.18.0 → 0.20.0

package/.agents/skills/memory-lifecycle/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: memory-lifecycle
+description: "Preview and apply a consumer-owned memory lifecycle without crossing configured roots or overwriting active, archived, or recovery evidence. Use when a user wants to restore archived memories, inspect memory placement, or run an approved memory recovery."
+---
+
+# Memory Lifecycle
+
+Coordinate the current repository's memory placement and recovery through the
+deterministic helper at `scripts/memory-lifecycle/index.mjs`. The helper owns
+path validation, dry-run verdicts, exclusive restore writes, hashing, and
+receipts. Keep this skill thin: do not reimplement those rules with shell file
+operations.
+
+## Boundaries
+
+- Work only below the consumer-owned roots in
+  `docs/agents/workflow-capabilities.json`.
+- Never scan another repository or a user-global memory root that the current
+  consumer profile does not explicitly own.
+- Treat active memories, archives, policy templates, and restore receipts as
+  consumer-owned. Never overwrite them.
+- `init`, `update`, and an ordinary `setup-workflow` rerun must not enable this
+  capability or change placement, retention, restore, or pruning grants.
+- Destructive pruning is outside the helper. It requires a separate preview and
+  explicit user approval; do not infer that approval from restore permission.
+
+## Consumer profile
+
+Adopt the `memoryLifecycle` section of
+`docs/agents/workflow-capabilities.json`. Missing or disabled configuration is
+a valid no-write `disabled` result.
+
+```json
+{
+  "memoryLifecycle": {
+    "enabled": true,
+    "activeRoot": ".memory/active",
+    "archiveRoot": ".memory/archive",
+    "receiptRoot": ".memory/receipts",
+    "approvals": { "restore": false, "prune": false },
+    "memories": [
+      { "path": "decisions/example.md", "enabled": true }
+    ]
+  }
+}
+```
+
+Preserve unknown profile keys. Every configured root and candidate path must be
+repository-relative. Absolute paths, parent escapes, symlink traversal,
+different-content collisions, and missing restore approval are refused.
+
+## Workflow
+
+1. **Preview.** Run:
+
+   ```sh
+   node scripts/memory-lifecycle/index.mjs
+   ```
+
+   This is the default no-write mode. Count the candidate paths and confirm each
+   appears exactly once as `create`, `restore`, `preserve`, `skip`, or `refuse`.
+2. **Review refusals.** Explain every refusal. Do not weaken root, symlink,
+   collision, or approval checks to make the run green.
+3. **Confirm recovery.** Before applying, require the consumer profile's
+   `approvals.restore` to already record the explicit restore grant. A chat
+   instruction does not silently rewrite the tracked policy.
+4. **Apply.** Run:
+
+   ```sh
+   node scripts/memory-lifecycle/index.mjs --apply
+   ```
+
+   The helper restores with exclusive-create semantics and keeps the archive.
+   A concurrent destination collision becomes `refused`, never an overwrite.
+5. **Read back.** Verify restored files by path and hash, not by printing memory
+   contents. Confirm the receipt has schema/source versions plus
+   `restored`/`skipped`/`refused` path verdicts and contains no memory content.
+6. **Rerun.** Run the preview again. An identical restored file is preserved;
+   the rerun writes no duplicate receipt.
+
+Use `--profile <repository-relative-path>` only when the repository documents a
+different consumer-owned profile location.
+
+## Final report
+
+Report:
+
+- dry-run counts for all five action classes;
+- applied `restored`/`skipped`/`refused` counts;
+- receipt path and source versions, without memory contents;
+- archive-preservation and rerun/no-write result;
+- any pruning request left pending explicit approval.

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

@@ -18,6 +18,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
 - **Multi-session build from a PRD or issue:** use `implement` to drive `tdd` end-to-end, one red-green slice at a time.
 - **Implementation slice:** use `tdd` for one behavior at a time: RED, GREEN, then refactor.
 - **Build or refresh a project-local census:** use `census-update` to scan facts, resolve ambiguous decisions one at a time, and transactionally activate a counted census.
+- **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`.
 - **Kit update:** use `kit-update` to preview and transactionally apply a parity-verified scoped release without overwriting local modifications.

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/memory-lifecycle/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: memory-lifecycle
+description: "Preview and apply a consumer-owned memory lifecycle without crossing configured roots or overwriting active, archived, or recovery evidence. Use when a user wants to restore archived memories, inspect memory placement, or run an approved memory recovery."
+---
+
+# Memory Lifecycle
+
+Coordinate the current repository's memory placement and recovery through the
+deterministic helper at `scripts/memory-lifecycle/index.mjs`. The helper owns
+path validation, dry-run verdicts, exclusive restore writes, hashing, and
+receipts. Keep this skill thin: do not reimplement those rules with shell file
+operations.
+
+## Boundaries
+
+- Work only below the consumer-owned roots in
+  `docs/agents/workflow-capabilities.json`.
+- Never scan another repository or a user-global memory root that the current
+  consumer profile does not explicitly own.
+- Treat active memories, archives, policy templates, and restore receipts as
+  consumer-owned. Never overwrite them.
+- `init`, `update`, and an ordinary `setup-workflow` rerun must not enable this
+  capability or change placement, retention, restore, or pruning grants.
+- Destructive pruning is outside the helper. It requires a separate preview and
+  explicit user approval; do not infer that approval from restore permission.
+
+## Consumer profile
+
+Adopt the `memoryLifecycle` section of
+`docs/agents/workflow-capabilities.json`. Missing or disabled configuration is
+a valid no-write `disabled` result.
+
+```json
+{
+  "memoryLifecycle": {
+    "enabled": true,
+    "activeRoot": ".memory/active",
+    "archiveRoot": ".memory/archive",
+    "receiptRoot": ".memory/receipts",
+    "approvals": { "restore": false, "prune": false },
+    "memories": [
+      { "path": "decisions/example.md", "enabled": true }
+    ]
+  }
+}
+```
+
+Preserve unknown profile keys. Every configured root and candidate path must be
+repository-relative. Absolute paths, parent escapes, symlink traversal,
+different-content collisions, and missing restore approval are refused.
+
+## Workflow
+
+1. **Preview.** Run:
+
+   ```sh
+   node scripts/memory-lifecycle/index.mjs
+   ```
+
+   This is the default no-write mode. Count the candidate paths and confirm each
+   appears exactly once as `create`, `restore`, `preserve`, `skip`, or `refuse`.
+2. **Review refusals.** Explain every refusal. Do not weaken root, symlink,
+   collision, or approval checks to make the run green.
+3. **Confirm recovery.** Before applying, require the consumer profile's
+   `approvals.restore` to already record the explicit restore grant. A chat
+   instruction does not silently rewrite the tracked policy.
+4. **Apply.** Run:
+
+   ```sh
+   node scripts/memory-lifecycle/index.mjs --apply
+   ```
+
+   The helper restores with exclusive-create semantics and keeps the archive.
+   A concurrent destination collision becomes `refused`, never an overwrite.
+5. **Read back.** Verify restored files by path and hash, not by printing memory
+   contents. Confirm the receipt has schema/source versions plus
+   `restored`/`skipped`/`refused` path verdicts and contains no memory content.
+6. **Rerun.** Run the preview again. An identical restored file is preserved;
+   the rerun writes no duplicate receipt.
+
+Use `--profile <repository-relative-path>` only when the repository documents a
+different consumer-owned profile location.
+
+## Final report
+
+Report:
+
+- dry-run counts for all five action classes;
+- applied `restored`/`skipped`/`refused` counts;
+- receipt path and source versions, without memory contents;
+- archive-preservation and rerun/no-write result;
+- any pruning request left pending explicit approval.

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

@@ -18,6 +18,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
 - **Multi-session build from a PRD or issue:** use `implement` to drive `tdd` end-to-end, one red-green slice at a time.
 - **Implementation slice:** use `tdd` for one behavior at a time: RED, GREEN, then refactor.
 - **Build or refresh a project-local census:** use `census-update` to scan facts, resolve ambiguous decisions one at a time, and transactionally activate a counted census.
+- **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`.
 - **Kit update:** use `kit-update` to preview and transactionally apply a parity-verified scoped release without overwriting local modifications.

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

@@ -404,6 +404,16 @@
         "codex"
       ],
       "provenance": "own"
+    },
+    "memory-lifecycle": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
     }
   }
 }

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 — covered by the root LICENSE.
+census-update, memory-lifecycle — 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,26 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.20.0
+
+- added: `.claude/hooks/branch-context.py`
+- added: `.claude/hooks/branch-watch.py`
+- added: `.claude/hooks/enforce-worktree.py`
+- added: `.claude/hooks/enforce-worktree-cwd.py`
+- added: `.claude/hooks/enforce-worktree-discipline.py`
+- added: `scripts/worktree-lifecycle/profile.py`
+- added: `scripts/worktree-lifecycle/README.md`
+- changed: `.claude/hooks/_hook_utils.py`
+- changed: `scripts/worktree-lifecycle/core.py`
+
+### 0.19.0
+
+- added: `.agents/skills/memory-lifecycle/SKILL.md`
+- added: `.claude/skills/memory-lifecycle/SKILL.md`
+- added: `scripts/memory-lifecycle/index.mjs`
+- changed: `.agents/skills/setup-workflow/workflow-overview.md`
+- changed: `.claude/skills/setup-workflow/workflow-overview.md`
+
 ### 0.18.0
 
 - added: `scripts/worktree-lifecycle/capabilities.json`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.18.0",
+  "kitVersion": "0.20.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -352,6 +352,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".agents/skills/memory-lifecycle/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "memory-lifecycle",
+      "surface": "codex",
+      "sha256": "f4cd4a744044b59fd4ce6b7348e30f437ca4200f5f5bbae6e6aebdc30d6b3f35",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".agents/skills/orchestrate-wave/references/builder-contract.md",
       "kind": "skill",
@@ -600,7 +609,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "b83fa87dc0226f21e01d31c91840b78d1ccad0a92e646de203fc3c003e9098f3",
+      "sha256": "c522a7de1b8eaa827a72880651a94aca6d066687e8c21b789d9008e3321f7362",
       "mode": 420,
       "origin": "kit"
     },
@@ -850,10 +859,24 @@
     {
       "path": ".claude/hooks/_hook_utils.py",
       "kind": "hook",
-      "sha256": "4a4b57633578ee8eabdf8ae70437e590e1747d1df5d76c730e2164e23cdfc2ed",
+      "sha256": "58a7a8ad6cd4f1660e95343d7a0c637cf8aee92948a9c554befa5851723b3f48",
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/hooks/branch-context.py",
+      "kind": "hook",
+      "sha256": "96bbe56a292a89cdb76db0670c2c214678fa60c08e3de5b8db507149ba24c018",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/hooks/branch-watch.py",
+      "kind": "hook",
+      "sha256": "15c7565790e0b108c44175b7527a4bc2b8b244737d5598081e938d2dea032424",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": ".claude/hooks/drift-guard.py",
       "kind": "hook",
@@ -861,6 +884,27 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": ".claude/hooks/enforce-worktree-cwd.py",
+      "kind": "hook",
+      "sha256": "14086536ceb3368a03b84ff550ba5e3db83d6c5198c41c80312507bf6640bb9f",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/hooks/enforce-worktree-discipline.py",
+      "kind": "hook",
+      "sha256": "5bd9fc7a7eea5e8b0778e8272e02b5d8c6c121ea3a168ef11a9c39344085e666",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/hooks/enforce-worktree.py",
+      "kind": "hook",
+      "sha256": "4a5d0247d89049dde0475680595fd785bfbd1b108cdd9c9697fd74e944f52c8b",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": ".claude/hooks/skill-drift-hint.py",
       "kind": "hook",
@@ -1334,6 +1378,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/memory-lifecycle/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "memory-lifecycle",
+      "surface": "claude",
+      "sha256": "f4cd4a744044b59fd4ce6b7348e30f437ca4200f5f5bbae6e6aebdc30d6b3f35",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/orchestrate-wave/references/builder-contract.md",
       "kind": "skill",
@@ -1600,7 +1653,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "b83fa87dc0226f21e01d31c91840b78d1ccad0a92e646de203fc3c003e9098f3",
+      "sha256": "c522a7de1b8eaa827a72880651a94aca6d066687e8c21b789d9008e3321f7362",
       "mode": 420,
       "origin": "kit"
     },
@@ -2000,6 +2053,13 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": "scripts/memory-lifecycle/index.mjs",
+      "kind": "script",
+      "sha256": "d83a71891e9c070179a00d6413b18d073061eef75e50919a7f28b8510f7ca20d",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": "scripts/node_kind.py",
       "kind": "script",
@@ -2073,7 +2133,21 @@
     {
       "path": "scripts/worktree-lifecycle/core.py",
       "kind": "script",
-      "sha256": "eae5c6076611a36a8fa90e3aef3d1c49345110a392a7d7e9d95be8de00f8d9ff",
+      "sha256": "36848a16ed7eaed1f731399efd2caf5771c9c5b48331771d6aedcbad2156e62a",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/worktree-lifecycle/profile.py",
+      "kind": "script",
+      "sha256": "993b105efd2329b3a206b0c79399aff1c7840017362745966f9b158b1f165f09",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/worktree-lifecycle/README.md",
+      "kind": "doc",
+      "sha256": "59b78826308404497545b0a0ba57ff50f4618be2f6838f64e6a8c18bce83ea7f",
       "mode": 420,
       "origin": "kit"
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {