@ikon85/agent-workflow-kit 0.22.0 → 0.24.0

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

@@ -26,7 +26,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `## Agent skills` + `## Prod` in CLAUDE.md **and** AGENTS.md | one-line pointers + deploy target (Sections C/G + Write) |
 | `.github/workflows/agent-workflow-kit-update.yml` | optional tested Kit update pull request for GitHub consumers (Section A2) |
 | `docs/agents/census.md` | optional-census choice, paths, state, and safe disable contract seeded from [census.md](./census.md) (Section A3) |
-| `docs/agents/workflow-capabilities.json` | consumer-owned capability profile, including optional Worktree Lifecycle activation (Section A4) |
+| `docs/agents/workflow-capabilities.json` + capability assets | consumer-owned Worktree Lifecycle, Memory Lifecycle, and Workflow Advisories choices (Sections A4–A6) |
 
 ## Idempotency contract — read before writing anything
 
@@ -57,7 +57,8 @@ Read the current state; don't assume. For every target file, read its first line
 - `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/` — domain-doc layout.
 - `docs/agents/`, `docs/agents/skills/`, `docs/conventions/` — prior output of this skill.
 - `docs/agents/census.md`, `.census/profile.json`, `.census/active.json` — an existing census choice or consumer-owned census to adopt.
-- `docs/agents/workflow-capabilities.json`, `.claude/settings.json` — an existing Worktree Lifecycle choice/profile and hook wiring to adopt.
+- `docs/agents/workflow-capabilities.json`, `.claude/settings.json` — existing capability choices/profile plus Worktree Lifecycle and Workflow Advisories hook wiring to adopt.
+- `.memory/active/`, `.memory/archive/`, and `.memory/receipts/` — consumer-owned Memory Lifecycle policies or recovery evidence to adopt without normalization.
 - `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
 
 ### 2. Section A — Issue tracker
@@ -165,6 +166,58 @@ The default setup entry is
 may remain the configured `setupEntry` for parity. The handoff advisory always
 reads that configured entry and never hardcodes a project script.
 
+### 2d. Section A5 — Optional Memory Lifecycle
+
+> Memory Lifecycle keeps project memories inside consumer-owned roots and makes
+> restore operations previewable, collision-safe, and reversible. The policy
+> templates become fully consumer-owned after their first seed.
+
+Read the `memoryLifecycle` section of
+`docs/agents/workflow-capabilities.json` before offering anything. Missing or
+disabled configuration remains unchanged on an ordinary setup rerun. An
+existing enabled section is adopted byte-for-byte; preserve unknown profile
+keys, placement/retention settings, restore grants, and consumer-specific memory
+rows.
+If no section exists, explain the capability and offer an explicit opt-in. Only
+an affirmative consumer decision may run:
+
+```bash
+node scripts/memory-lifecycle/setup.mjs --enable
+```
+
+That command adds the minimal enabled section while preserving every existing
+top-level profile key, sets restore and pruning approval to `false` unless the
+consumer already recorded values, and seeds
+`meta_decision_layer_choice.md` plus `meta_memory_lifecycle.md` into the
+configured active root exactly once. Existing files are adopted and never
+overwritten. The profile's `templatesSeeded` marker transfers full ownership:
+later setup runs do not recreate a template the consumer edited, moved, or
+deleted.
+Choosing later, declining, or merely running `init`, `update`, or ordinary
+`setup-workflow` performs no Memory Lifecycle write and never changes
+activation, roots, retention, restore, or pruning grants. Template files have
+no kit-managed or `append-managed` region; a future bounded-region contract
+requires a separate decision.
+
+### 2e. Section A6 — Optional Workflow Advisories
+
+> Workflow Advisories provides non-blocking, low-noise hints and
+> affected-surface checks around large reads, first-impacting edits, refactors,
+> and Stop. Paths, commands, thresholds, timeouts, and output budgets remain
+> consumer-owned.
+
+Read [workflow-advisories.md](./workflow-advisories.md) in full. Reconcile its
+complete `yes / later / no / existing / disable` matrix. If no choice exists,
+ask: *"Should setup activate the portable Workflow Advisories for this
+repository?"* Offer exactly **Yes**, **Later**, and **No**.
+
+- **Yes** — reconcile only `workflowAdvisories` in the shared capability
+  profile and only the exact kit-owned hook commands named by the seed.
+- **Later / No** — record the choice without hook wiring.
+- **Existing** — adopt profile and wiring byte-safely.
+- **Disable** — remove exact kit-owned commands first, then set `enabled:
+  false`; preserve every profile value and unknown key.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
@@ -250,11 +303,17 @@ pre-existing consumer-owned census file. `yes`, `later`, `no`, and an adopted
 existing census are terminal for ordinary setup reruns. Only an explicit user
 request changes a recorded choice.
 
-For `docs/agents/workflow-capabilities.json`, reconcile only the selected
+For `docs/agents/workflow-capabilities.json`, reconcile only each selected
 capability section. Never replace the whole file: Project Release, Memory
-Lifecycle, Worktree Lifecycle, future sections, and unknown consumer keys share
-this profile. Apply the Worktree Lifecycle transition and hook ownership rules
-from [worktree-lifecycle.md](./worktree-lifecycle.md) transactionally.
+Lifecycle, Worktree Lifecycle, Workflow Advisories, future sections, and
+unknown consumer keys share this profile. Apply the transition and hook
+ownership rules from [worktree-lifecycle.md](./worktree-lifecycle.md) and
+[workflow-advisories.md](./workflow-advisories.md) transactionally.
+
+For Memory Lifecycle, use only the deterministic setup helper from Section A5.
+Do not copy templates with shell commands or edit the capability profile by
+hand. Report `seeded · adopted · skipped`; do not print memory contents or
+receipt contents.
 
 For the **`## Workflow`**, **`## Agent skills`**, and **`## Prod`** blocks, reconcile per section in **both** CLAUDE.md and AGENTS.md that exist:
 

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

@@ -0,0 +1,75 @@
+# Workflow Advisories setup contract
+
+Workflow Advisories is one opt-in capability backed by the consumer-owned
+`docs/agents/workflow-capabilities.json` profile. Enabling it activates
+non-blocking large-read, baseline, pre-refactor, and affected-surface Stop
+adapters. Every threshold, glob, branch rule, command, timeout, and output
+budget stays consumer-owned.
+
+## Choice matrix
+
+| State | Setup action |
+|---|---|
+| `missing` | Ask `yes / later / no`; do not infer or write before the answer. |
+| `yes` | Reconcile the enabled profile and exact kit-owned hook commands. |
+| `later` | Record the retryable deferral; do not activate hooks. |
+| `no` | Record the opt-out; do not activate hooks. |
+| `existing` | Adopt the consumer profile byte-safely and preserve unknown keys. |
+| `disable` | Remove only kit-owned hook wiring, then set `enabled: false`; retain profile values and unknown keys. |
+
+```json workflow-advisories-setup-effects
+[
+  {"state":"missing","choice":null,"operations":[]},
+  {"state":"yes","choice":"yes","operations":["record-choice","reconcile-profile-enabled","reconcile-hook-wiring"]},
+  {"state":"later","choice":"later","operations":["record-choice"]},
+  {"state":"no","choice":"no","operations":["record-choice"]},
+  {"state":"existing","choice":"yes","operations":["adopt-existing"]},
+  {"state":"disable","choice":"yes","operations":["remove-hook-wiring","update-profile-disabled"]}
+]
+```
+
+## Profile shape
+
+Reconcile only `workflowAdvisories`; preserve every sibling section and unknown
+key. Consumer values are never normalized on adoption.
+
+```json
+{
+  "workflowAdvisories": {
+    "choice": "yes",
+    "enabled": true,
+    "largeRead": {"tools": ["Read"], "lineThreshold": 500, "outputBudget": 500},
+    "baseline": {
+      "sourceGlobs": ["src/**"],
+      "branchRegex": "^(?:feat|fix)/",
+      "manifestPath": ".agent/baseline.json",
+      "stateDir": ".claude/logs/advisory-state",
+      "outputBudget": 500
+    },
+    "preRefactor": {
+      "promptMatchers": ["refactor"],
+      "surfaces": [],
+      "timeoutSeconds": 15,
+      "outputBudget": 1000
+    },
+    "stopChecks": {"surfaces": [], "timeoutSeconds": 30, "outputBudget": 1000}
+  }
+}
+```
+
+Empty command surfaces are honest inactive defaults. Setup recommends concrete
+project commands from the tools already present, then asks before activating.
+
+## Hook ownership
+
+- PreToolUse on Read:
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/recon-size-hint.py"`
+- PreToolUse on Edit/Write/MultiEdit:
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/baseline-capture-hint.py"`
+- UserPromptSubmit:
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-refactor-sweep.py"`
+- Stop:
+  `"$CLAUDE_PROJECT_DIR/.claude/hooks/typecheck-on-stop.sh"`
+
+All adapters are non-blocking. A failed or timed-out configured command remains
+visibly failed in hook context; it is never reported as green.

package/.claude/hooks/_hook_utils.py

@@ -30,6 +30,7 @@ from pathlib import Path
 # (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"
+_ADVISORY_CORE_MODULE = "_agent_workflow_kit_workflow_advisories"
 
 
 def rotate_log_if_needed(log_path: Path, max_bytes: int = 100_000, generations: int = 3) -> None:
@@ -205,6 +206,21 @@ def load_worktree_lifecycle_core():
     return module
 
 
+def load_workflow_advisories_core():
+    """Load the shipped Workflow Advisories core without requiring a Python package."""
+    existing = sys.modules.get(_ADVISORY_CORE_MODULE)
+    if existing is not None:
+        return existing
+    path = Path(__file__).resolve().parents[2] / "scripts" / "workflow-advisories" / "core.py"
+    spec = importlib.util.spec_from_file_location(_ADVISORY_CORE_MODULE, path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"cannot load Workflow Advisories core from {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[_ADVISORY_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 {

package/.claude/hooks/baseline-capture-hint.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+"""PreToolUse once-per-branch baseline advisory for impacting edits."""
+import json
+import sys
+from pathlib import Path
+
+from _hook_utils import current_branch, hook_event_output, load_workflow_advisories_core
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+        core = load_workflow_advisories_core()
+        profile = core.load_profile(Path("docs/agents/workflow-capabilities.json"))
+        branch = payload.get("branch") or current_branch()
+        decision = core.baseline_decision(profile, payload, Path.cwd(), branch)
+        if decision.context:
+            print(json.dumps(hook_event_output(decision.event_name, decision.context)))
+    except Exception:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/hooks/pre-refactor-sweep.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+"""UserPromptSubmit non-blocking profile-driven pre-refactor command sweep."""
+import json
+import sys
+from pathlib import Path
+
+from _hook_utils import hook_event_output, load_workflow_advisories_core, run
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+        if "changed_files" not in payload:
+            changed = run(["git", "diff", "--name-only", "HEAD"])
+            payload["changed_files"] = changed.splitlines() if changed else []
+        core = load_workflow_advisories_core()
+        profile = core.load_profile(Path("docs/agents/workflow-capabilities.json"))
+        decision = core.pre_refactor_decision(profile, payload, Path.cwd())
+        if decision.context:
+            print(json.dumps(hook_event_output(decision.event_name, decision.context)))
+    except Exception:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/hooks/recon-size-hint.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+"""PreToolUse non-blocking advisory for profile-defined large reads."""
+import json
+import sys
+from pathlib import Path
+
+from _hook_utils import hook_event_output, load_workflow_advisories_core
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+        core = load_workflow_advisories_core()
+        profile = core.load_profile(Path("docs/agents/workflow-capabilities.json"))
+        decision = core.large_read_decision(profile, payload)
+        if decision.context:
+            print(json.dumps(hook_event_output(decision.event_name, decision.context)))
+    except Exception:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/hooks/typecheck-on-stop.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+"""Stop-event adapter for profile-defined affected-surface checks."""
+import json
+import sys
+from pathlib import Path
+
+from _hook_utils import hook_event_output, load_workflow_advisories_core, run
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+        if "changed_files" not in payload:
+            changed = run(["git", "diff", "--name-only", "HEAD"])
+            payload["changed_files"] = changed.splitlines() if changed else []
+        core = load_workflow_advisories_core()
+        profile = core.load_profile(Path("docs/agents/workflow-capabilities.json"))
+        decision = core.stop_check_decision(profile, payload, Path.cwd())
+        if decision.context:
+            print(json.dumps(hook_event_output(decision.event_name, decision.context)))
+    except Exception:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/hooks/typecheck-on-stop.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+exec python3 "$(dirname "$0")/typecheck-on-stop.py"

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

@@ -26,7 +26,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `## Agent skills` + `## Prod` in CLAUDE.md **and** AGENTS.md | one-line pointers + deploy target (Sections C/G + Write) |
 | `.github/workflows/agent-workflow-kit-update.yml` | optional tested Kit update pull request for GitHub consumers (Section A2) |
 | `docs/agents/census.md` | optional-census choice, paths, state, and safe disable contract seeded from [census.md](./census.md) (Section A3) |
-| `docs/agents/workflow-capabilities.json` | consumer-owned capability profile, including optional Worktree Lifecycle activation (Section A4) |
+| `docs/agents/workflow-capabilities.json` + capability assets | consumer-owned Worktree Lifecycle, Memory Lifecycle, and Workflow Advisories choices (Sections A4–A6) |
 
 ## Idempotency contract — read before writing anything
 
@@ -57,7 +57,8 @@ Read the current state; don't assume. For every target file, read its first line
 - `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/` — domain-doc layout.
 - `docs/agents/`, `docs/agents/skills/`, `docs/conventions/` — prior output of this skill.
 - `docs/agents/census.md`, `.census/profile.json`, `.census/active.json` — an existing census choice or consumer-owned census to adopt.
-- `docs/agents/workflow-capabilities.json`, `.claude/settings.json` — an existing Worktree Lifecycle choice/profile and hook wiring to adopt.
+- `docs/agents/workflow-capabilities.json`, `.claude/settings.json` — existing capability choices/profile plus Worktree Lifecycle and Workflow Advisories hook wiring to adopt.
+- `.memory/active/`, `.memory/archive/`, and `.memory/receipts/` — consumer-owned Memory Lifecycle policies or recovery evidence to adopt without normalization.
 - `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
 
 ### 2. Section A — Issue tracker
@@ -165,6 +166,58 @@ The default setup entry is
 may remain the configured `setupEntry` for parity. The handoff advisory always
 reads that configured entry and never hardcodes a project script.
 
+### 2d. Section A5 — Optional Memory Lifecycle
+
+> Memory Lifecycle keeps project memories inside consumer-owned roots and makes
+> restore operations previewable, collision-safe, and reversible. The policy
+> templates become fully consumer-owned after their first seed.
+
+Read the `memoryLifecycle` section of
+`docs/agents/workflow-capabilities.json` before offering anything. Missing or
+disabled configuration remains unchanged on an ordinary setup rerun. An
+existing enabled section is adopted byte-for-byte; preserve unknown profile
+keys, placement/retention settings, restore grants, and consumer-specific memory
+rows.
+If no section exists, explain the capability and offer an explicit opt-in. Only
+an affirmative consumer decision may run:
+
+```bash
+node scripts/memory-lifecycle/setup.mjs --enable
+```
+
+That command adds the minimal enabled section while preserving every existing
+top-level profile key, sets restore and pruning approval to `false` unless the
+consumer already recorded values, and seeds
+`meta_decision_layer_choice.md` plus `meta_memory_lifecycle.md` into the
+configured active root exactly once. Existing files are adopted and never
+overwritten. The profile's `templatesSeeded` marker transfers full ownership:
+later setup runs do not recreate a template the consumer edited, moved, or
+deleted.
+Choosing later, declining, or merely running `init`, `update`, or ordinary
+`setup-workflow` performs no Memory Lifecycle write and never changes
+activation, roots, retention, restore, or pruning grants. Template files have
+no kit-managed or `append-managed` region; a future bounded-region contract
+requires a separate decision.
+
+### 2e. Section A6 — Optional Workflow Advisories
+
+> Workflow Advisories provides non-blocking, low-noise hints and
+> affected-surface checks around large reads, first-impacting edits, refactors,
+> and Stop. Paths, commands, thresholds, timeouts, and output budgets remain
+> consumer-owned.
+
+Read [workflow-advisories.md](./workflow-advisories.md) in full. Reconcile its
+complete `yes / later / no / existing / disable` matrix. If no choice exists,
+ask: *"Should setup activate the portable Workflow Advisories for this
+repository?"* Offer exactly **Yes**, **Later**, and **No**.
+
+- **Yes** — reconcile only `workflowAdvisories` in the shared capability
+  profile and only the exact kit-owned hook commands named by the seed.
+- **Later / No** — record the choice without hook wiring.
+- **Existing** — adopt profile and wiring byte-safely.
+- **Disable** — remove exact kit-owned commands first, then set `enabled:
+  false`; preserve every profile value and unknown key.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
@@ -250,11 +303,17 @@ pre-existing consumer-owned census file. `yes`, `later`, `no`, and an adopted
 existing census are terminal for ordinary setup reruns. Only an explicit user
 request changes a recorded choice.
 
-For `docs/agents/workflow-capabilities.json`, reconcile only the selected
+For `docs/agents/workflow-capabilities.json`, reconcile only each selected
 capability section. Never replace the whole file: Project Release, Memory
-Lifecycle, Worktree Lifecycle, future sections, and unknown consumer keys share
-this profile. Apply the Worktree Lifecycle transition and hook ownership rules
-from [worktree-lifecycle.md](./worktree-lifecycle.md) transactionally.
+Lifecycle, Worktree Lifecycle, Workflow Advisories, future sections, and
+unknown consumer keys share this profile. Apply the transition and hook
+ownership rules from [worktree-lifecycle.md](./worktree-lifecycle.md) and
+[workflow-advisories.md](./workflow-advisories.md) transactionally.
+
+For Memory Lifecycle, use only the deterministic setup helper from Section A5.
+Do not copy templates with shell commands or edit the capability profile by
+hand. Report `seeded · adopted · skipped`; do not print memory contents or
+receipt contents.
 
 For the **`## Workflow`**, **`## Agent skills`**, and **`## Prod`** blocks, reconcile per section in **both** CLAUDE.md and AGENTS.md that exist:
 

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

@@ -0,0 +1,75 @@
+# Workflow Advisories setup contract
+
+Workflow Advisories is one opt-in capability backed by the consumer-owned
+`docs/agents/workflow-capabilities.json` profile. Enabling it activates
+non-blocking large-read, baseline, pre-refactor, and affected-surface Stop
+adapters. Every threshold, glob, branch rule, command, timeout, and output
+budget stays consumer-owned.
+
+## Choice matrix
+
+| State | Setup action |
+|---|---|
+| `missing` | Ask `yes / later / no`; do not infer or write before the answer. |
+| `yes` | Reconcile the enabled profile and exact kit-owned hook commands. |
+| `later` | Record the retryable deferral; do not activate hooks. |
+| `no` | Record the opt-out; do not activate hooks. |
+| `existing` | Adopt the consumer profile byte-safely and preserve unknown keys. |
+| `disable` | Remove only kit-owned hook wiring, then set `enabled: false`; retain profile values and unknown keys. |
+
+```json workflow-advisories-setup-effects
+[
+  {"state":"missing","choice":null,"operations":[]},
+  {"state":"yes","choice":"yes","operations":["record-choice","reconcile-profile-enabled","reconcile-hook-wiring"]},
+  {"state":"later","choice":"later","operations":["record-choice"]},
+  {"state":"no","choice":"no","operations":["record-choice"]},
+  {"state":"existing","choice":"yes","operations":["adopt-existing"]},
+  {"state":"disable","choice":"yes","operations":["remove-hook-wiring","update-profile-disabled"]}
+]
+```
+
+## Profile shape
+
+Reconcile only `workflowAdvisories`; preserve every sibling section and unknown
+key. Consumer values are never normalized on adoption.
+
+```json
+{
+  "workflowAdvisories": {
+    "choice": "yes",
+    "enabled": true,
+    "largeRead": {"tools": ["Read"], "lineThreshold": 500, "outputBudget": 500},
+    "baseline": {
+      "sourceGlobs": ["src/**"],
+      "branchRegex": "^(?:feat|fix)/",
+      "manifestPath": ".agent/baseline.json",
+      "stateDir": ".claude/logs/advisory-state",
+      "outputBudget": 500
+    },
+    "preRefactor": {
+      "promptMatchers": ["refactor"],
+      "surfaces": [],
+      "timeoutSeconds": 15,
+      "outputBudget": 1000
+    },
+    "stopChecks": {"surfaces": [], "timeoutSeconds": 30, "outputBudget": 1000}
+  }
+}
+```
+
+Empty command surfaces are honest inactive defaults. Setup recommends concrete
+project commands from the tools already present, then asks before activating.
+
+## Hook ownership
+
+- PreToolUse on Read:
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/recon-size-hint.py"`
+- PreToolUse on Edit/Write/MultiEdit:
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/baseline-capture-hint.py"`
+- UserPromptSubmit:
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-refactor-sweep.py"`
+- Stop:
+  `"$CLAUDE_PROJECT_DIR/.claude/hooks/typecheck-on-stop.sh"`
+
+All adapters are non-blocking. A failed or timed-out configured command remains
+visibly failed in hook context; it is never reported as green.

package/README.md

@@ -332,6 +332,29 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.24.0
+
+- added: `.agents/skills/setup-workflow/workflow-advisories.md`
+- added: `.claude/hooks/baseline-capture-hint.py`
+- added: `.claude/hooks/pre-refactor-sweep.py`
+- added: `.claude/hooks/recon-size-hint.py`
+- added: `.claude/hooks/typecheck-on-stop.py`
+- added: `.claude/hooks/typecheck-on-stop.sh`
+- added: `.claude/skills/setup-workflow/workflow-advisories.md`
+- added: `scripts/workflow-advisories/core.py`
+- changed: `.agents/skills/setup-workflow/SKILL.md`
+- changed: `.claude/hooks/_hook_utils.py`
+- changed: `.claude/skills/setup-workflow/SKILL.md`
+
+### 0.23.0
+
+- added: `assets/memory-templates/meta_decision_layer_choice.md`
+- added: `assets/memory-templates/meta_memory_lifecycle.md`
+- added: `scripts/memory-lifecycle/setup.mjs`
+- changed: `.agents/skills/setup-workflow/SKILL.md`
+- changed: `.claude/skills/setup-workflow/SKILL.md`
+- changed: `scripts/memory-lifecycle/index.mjs`
+
 ### 0.22.0
 
 - added: `.agents/skills/setup-workflow/worktree-lifecycle.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.22.0",
+  "kitVersion": "0.24.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -573,7 +573,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "a1145034dbc334fb388be27dfb77cf1d93f3cefc6f760d5f4fa5d3ee98050dff",
+      "sha256": "96c0c3ba9ed6b194030a8c45be618caf934e9c4ca8415ea19d726af33cd763cb",
       "mode": 420,
       "origin": "kit"
     },
@@ -613,6 +613,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".agents/skills/setup-workflow/workflow-advisories.md",
+      "kind": "skill",
+      "ownerSkill": "setup-workflow",
+      "surface": "codex",
+      "sha256": "320f893a6e148f0bfabe1f1be81112728ae4fed84f7505dc630e5b0d931ec32c",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".agents/skills/setup-workflow/workflow-overview.md",
       "kind": "skill",
@@ -877,10 +886,17 @@
     {
       "path": ".claude/hooks/_hook_utils.py",
       "kind": "hook",
-      "sha256": "58a7a8ad6cd4f1660e95343d7a0c637cf8aee92948a9c554befa5851723b3f48",
+      "sha256": "26c645eaa7cb87e899ab3900e9f6711658848cab8a18a29656ae3ca30736d172",
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/hooks/baseline-capture-hint.py",
+      "kind": "hook",
+      "sha256": "8f5cddfbb567afc677cf51f39d37e10804bf03e93d7d2fac7793cb5a42473ed3",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": ".claude/hooks/branch-context.py",
       "kind": "hook",
@@ -923,6 +939,20 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": ".claude/hooks/pre-refactor-sweep.py",
+      "kind": "hook",
+      "sha256": "24e8554da18b00f2dbbcf6a3e186f9fb675a4b18471ce60e0ac63000f95a4906",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/hooks/recon-size-hint.py",
+      "kind": "hook",
+      "sha256": "3fd702d8875552ce3b79b5db1dda51403031bcacc80901a13553d2f60a2deb9b",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": ".claude/hooks/skill-drift-hint.py",
       "kind": "hook",
@@ -944,6 +974,20 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": ".claude/hooks/typecheck-on-stop.py",
+      "kind": "hook",
+      "sha256": "459e5f25f5fe97c62687eff1d3e7e76051ba8390e2b2908fc50c16ea53a95250",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/hooks/typecheck-on-stop.sh",
+      "kind": "hook",
+      "sha256": "1bb57f53d53d18af92a8c7ce63f46be0658ae7d675a95d387646b4232001f1bc",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/ask-matt/SKILL.md",
       "kind": "skill",
@@ -1642,7 +1686,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "a1145034dbc334fb388be27dfb77cf1d93f3cefc6f760d5f4fa5d3ee98050dff",
+      "sha256": "96c0c3ba9ed6b194030a8c45be618caf934e9c4ca8415ea19d726af33cd763cb",
       "mode": 420,
       "origin": "kit"
     },
@@ -1682,6 +1726,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/setup-workflow/workflow-advisories.md",
+      "kind": "skill",
+      "ownerSkill": "setup-workflow",
+      "surface": "claude",
+      "sha256": "320f893a6e148f0bfabe1f1be81112728ae4fed84f7505dc630e5b0d931ec32c",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/setup-workflow/workflow-overview.md",
       "kind": "skill",
@@ -1970,6 +2023,20 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "assets/memory-templates/meta_decision_layer_choice.md",
+      "kind": "template",
+      "sha256": "b22bd1d0e3daa31cbdbb9a3a81964d7a00d5275e69c92c9bd4ad3b4e40995b41",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "assets/memory-templates/meta_memory_lifecycle.md",
+      "kind": "template",
+      "sha256": "215e865d4e803ce0b2cd43e88d76501a61269dfa90aae5e6a474941a0b72b0ca",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": "docs/agents/security-audit-runbook-template.md",
       "kind": "template",
@@ -2099,7 +2166,14 @@
     {
       "path": "scripts/memory-lifecycle/index.mjs",
       "kind": "script",
-      "sha256": "d83a71891e9c070179a00d6413b18d073061eef75e50919a7f28b8510f7ca20d",
+      "sha256": "871507e20133ccbb11f2a57f092bcb41aa1f6b7deaaa74df2418573316e6bd96",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/memory-lifecycle/setup.mjs",
+      "kind": "script",
+      "sha256": "c2c8885b806a830239ae54314c9dd0400399140870b6e62dc1e8b043dffcb78f",
       "mode": 420,
       "origin": "kit"
     },
@@ -2173,6 +2247,13 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "scripts/workflow-advisories/core.py",
+      "kind": "script",
+      "sha256": "7923d328f2a4e8b0ac8823cba5779003a52c6fabeb012157af49c3c5e13ccfc9",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": "scripts/worktree-lifecycle/capabilities.json",
       "kind": "doc",

package/assets/memory-templates/meta_decision_layer_choice.md

@@ -0,0 +1,25 @@
+# Durable Knowledge Placement
+
+Use this consumer-owned policy to decide where a learning belongs. Edit the
+categories and examples to match this repository's terminology.
+
+## Placement layers
+
+- Repository instructions: stable rules that should guide every relevant task.
+- Workflow skill: repeatable procedure with a named entry point and verification.
+- Domain documentation: product language, boundaries, and durable decisions.
+- Local memory: contextual knowledge that helps future sessions but is not yet a
+  repository-wide rule.
+
+## Decision check
+
+Before retaining a learning, record:
+
+1. who needs it;
+2. when it should be loaded;
+3. what evidence would make it stale;
+4. which tracked layer is the narrowest durable owner.
+
+Prefer a tracked repository layer when the knowledge changes how work should be
+performed. Keep personal preferences and user-profile information outside
+project-owned memories unless the user explicitly places them here.

package/assets/memory-templates/meta_memory_lifecycle.md

@@ -0,0 +1,25 @@
+# Memory Lifecycle Policy
+
+This file is consumer-owned after its first seed. Edit roots, retention classes,
+and review cadence to match the repository. Kit updates must never overwrite it.
+
+## Retention classes
+
+- Active: still relevant to current work and safe to load.
+- Archive candidate: useful history that should leave the active set.
+- Protected: user-profile, preference, or other content that must not be pruned
+  by an automated repository workflow.
+
+## Archive and restore
+
+- Archive only inside the configured consumer-owned archive root.
+- Preview every action before mutation.
+- Restore only with an explicit restore grant.
+- Preserve the archive and refuse destination collisions.
+- Record path verdicts and hashes in a content-free, collision-safe receipt.
+
+## Pruning
+
+Pruning is never implied by setup, update, archive, or restore. It requires a
+separate preview and explicit user approval. A failed or interrupted operation
+must leave the last safe active and archived state recoverable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.22.0",
+  "version": "0.24.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": {
@@ -21,6 +21,7 @@
     ".claude/",
     "!.claude/logs/",
     ".agents/",
+    "assets/",
     "scripts/",
     "docs/",
     "src/",

package/scripts/memory-lifecycle/index.mjs

@@ -10,6 +10,8 @@ import { createHash, randomUUID } from 'node:crypto';
 import { dirname, isAbsolute, normalize, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
+export { setupMemoryLifecycle } from './setup.mjs';
+
 async function exists(path) {
   try {
     return await lstat(path);

package/scripts/memory-lifecycle/setup.mjs

@@ -0,0 +1,167 @@
+import {
+  lstat,
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from 'node:fs/promises';
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+
+const PROFILE_PATH = 'docs/agents/workflow-capabilities.json';
+const TEMPLATE_NAMES = [
+  'meta_decision_layer_choice.md',
+  'meta_memory_lifecycle.md',
+];
+
+function contained(root, path) {
+  if (isAbsolute(path)) return null;
+  const normalized = normalize(path);
+  if (normalized === '..' || normalized.startsWith(`..${sep}`)) return null;
+  const absolute = resolve(root, normalized);
+  return relative(resolve(root), absolute).split(sep)[0] === '..' ? null : absolute;
+}
+
+async function lstatIfPresent(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function hasSymlink(root, path) {
+  let current = resolve(root);
+  const segments = relative(current, path).split(sep).filter(Boolean);
+  for (const segment of segments) {
+    current = resolve(current, segment);
+    if ((await lstatIfPresent(current))?.isSymbolicLink()) return true;
+  }
+  return false;
+}
+
+async function readJson(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function writeJsonAtomic(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  const staged = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(staged, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx' });
+    await rename(staged, path);
+  } finally {
+    await rm(staged, { force: true });
+  }
+}
+
+function defaultCapability() {
+  return {
+    enabled: true,
+    activeRoot: '.memory/active',
+    archiveRoot: '.memory/archive',
+    receiptRoot: '.memory/receipts',
+    approvals: { restore: false, prune: false },
+    memories: TEMPLATE_NAMES.map((path) => ({ path, enabled: true })),
+    templatesSeeded: true,
+  };
+}
+
+export async function setupMemoryLifecycle({
+  projectRoot = process.cwd(),
+  templateRoot = join(projectRoot, 'assets', 'memory-templates'),
+  decision,
+} = {}) {
+  const profilePath = resolve(projectRoot, PROFILE_PATH);
+  if (await hasSymlink(projectRoot, profilePath)) {
+    throw new Error('memoryLifecycle profile path contains a symlink');
+  }
+  const profile = await readJson(profilePath);
+  const existing = profile?.memoryLifecycle;
+
+  if (decision !== 'enable') {
+    return {
+      state: existing?.enabled ? 'enabled' : 'disabled',
+      seeded: [],
+      adopted: [],
+    };
+  }
+
+  const capability = {
+    ...defaultCapability(),
+    ...existing,
+    enabled: true,
+    approvals: {
+      restore: false,
+      prune: false,
+      ...existing?.approvals,
+    },
+    templatesSeeded: true,
+  };
+  const activeRoot = contained(projectRoot, capability.activeRoot);
+  if (!activeRoot) throw new Error('memoryLifecycle.activeRoot must stay inside the project');
+  if (await hasSymlink(projectRoot, activeRoot)) {
+    throw new Error('memoryLifecycle.activeRoot contains a symlink');
+  }
+
+  const shouldSeed = existing?.templatesSeeded !== true;
+  const sources = shouldSeed
+    ? await Promise.all(TEMPLATE_NAMES.map(async (name) => ({
+        name,
+        content: await readFile(join(templateRoot, name)),
+      })))
+    : [];
+  const seeded = [];
+  const adopted = [];
+  const destinations = sources.map(({ name, ...source }) => ({
+    ...source,
+    name,
+    destination: contained(activeRoot, name),
+  }));
+  for (const { destination } of destinations) {
+    if (await hasSymlink(activeRoot, destination)) {
+      throw new Error('memory policy destination contains a symlink');
+    }
+  }
+  for (const { content, destination } of destinations) {
+    await mkdir(dirname(destination), { recursive: true });
+    try {
+      await writeFile(destination, content, { flag: 'wx' });
+      seeded.push(relative(projectRoot, destination));
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      adopted.push(relative(projectRoot, destination));
+    }
+  }
+
+  await writeJsonAtomic(profilePath, {
+    schemaVersion: 1,
+    ...profile,
+    memoryLifecycle: capability,
+  });
+  return { state: 'enabled', seeded, adopted };
+}
+
+export const MEMORY_POLICY_TEMPLATES = Object.freeze([...TEMPLATE_NAMES]);
+
+async function main(argv) {
+  const result = await setupMemoryLifecycle({
+    decision: argv.includes('--enable') ? 'enable' : undefined,
+  });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/workflow-advisories/core.py

@@ -0,0 +1,185 @@
+"""Profile-driven decision core for non-blocking Workflow Advisories."""
+from __future__ import annotations
+
+import fnmatch
+import json
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Decision:
+    context: str | None
+    event_name: str
+
+
+def load_profile(path: Path) -> dict:
+    body = json.loads(path.read_text(encoding="utf-8"))
+    section = body.get("workflowAdvisories", {})
+    return section if section.get("enabled") is True else {}
+
+
+def _line_count(path: Path) -> int:
+    count = 0
+    last = b""
+    with path.open("rb") as handle:
+        while chunk := handle.read(64 * 1024):
+            count += chunk.count(b"\n")
+            last = chunk[-1:]
+    return count if not last or last == b"\n" else count + 1
+
+
+def _bounded(message: str, budget: int) -> str:
+    if budget <= 0 or len(message) <= budget:
+        return message
+    return message[: max(0, budget - 1)] + "…"
+
+
+def large_read_decision(profile: dict, payload: dict) -> Decision:
+    config = profile.get("largeRead", {})
+    if payload.get("tool_name") not in config.get("tools", []):
+        return Decision(None, "PreToolUse")
+    raw_path = payload.get("tool_input", {}).get("file_path")
+    if not raw_path:
+        return Decision(None, "PreToolUse")
+    path = Path(raw_path)
+    try:
+        lines = _line_count(path)
+    except (OSError, ValueError):
+        return Decision(None, "PreToolUse")
+    threshold = int(config.get("lineThreshold", 0))
+    if lines < threshold:
+        return Decision(None, "PreToolUse")
+    message = (
+        f"Large read advisory: {path.name} has {lines} lines "
+        f"(profile threshold {threshold}). Prefer a bounded read or delegated recon."
+    )
+    return Decision(_bounded(message, int(config.get("outputBudget", 500))), "PreToolUse")
+
+
+def _repo_relative(root: Path, raw_path: str) -> str | None:
+    try:
+        return str(Path(raw_path).resolve().relative_to(root.resolve()))
+    except (OSError, ValueError):
+        return None
+
+
+def _valid_baseline(path: Path, branch: str) -> bool:
+    try:
+        body = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError, TypeError):
+        return False
+    return (
+        body.get("branch") == branch
+        and bool(body.get("capturedAt"))
+        and bool(body.get("sources"))
+    )
+
+
+def baseline_decision(profile: dict, payload: dict, root: Path, branch: str) -> Decision:
+    config = profile.get("baseline", {})
+    if payload.get("tool_name") not in {"Edit", "Write", "MultiEdit"}:
+        return Decision(None, "PreToolUse")
+    if not re.search(config.get("branchRegex", r"$^"), branch):
+        return Decision(None, "PreToolUse")
+    raw_path = payload.get("tool_input", {}).get("file_path")
+    relative = _repo_relative(root, raw_path) if raw_path else None
+    if not relative or not any(
+        fnmatch.fnmatch(relative, pattern) for pattern in config.get("sourceGlobs", [])
+    ):
+        return Decision(None, "PreToolUse")
+    manifest = root / config.get("manifestPath", ".agent/baseline.json")
+    if _valid_baseline(manifest, branch):
+        return Decision(None, "PreToolUse")
+    state_dir = root / config.get("stateDir", ".claude/logs/advisory-state")
+    marker = state_dir / f"{re.sub(r'[^A-Za-z0-9._-]', '-', branch)}.hinted"
+    if marker.exists():
+        return Decision(None, "PreToolUse")
+    state_dir.mkdir(parents=True, exist_ok=True)
+    marker.write_text(f"{branch}\n", encoding="utf-8")
+    message = (
+        f"Baseline advisory for {branch}: capture a valid baseline before the first "
+        f"impacting edit to {relative}. Empty or stale manifests do not count."
+    )
+    return Decision(_bounded(message, int(config.get("outputBudget", 500))), "PreToolUse")
+
+
+def pre_refactor_decision(profile: dict, payload: dict, root: Path) -> Decision:
+    config = profile.get("preRefactor", {})
+    prompt = payload.get("prompt", "")
+    if not any(
+        re.search(pattern, prompt, re.IGNORECASE)
+        for pattern in config.get("promptMatchers", [])
+    ):
+        return Decision(None, "UserPromptSubmit")
+    changed = payload.get("changed_files", [])
+    commands: list[list[str]] = []
+    seen: set[tuple[str, ...]] = set()
+    for surface in config.get("surfaces", []):
+        if not any(
+            fnmatch.fnmatch(path, pattern)
+            for path in changed
+            for pattern in surface.get("globs", [])
+        ):
+            continue
+        for command in surface.get("commands", []):
+            key = tuple(command)
+            if key not in seen:
+                commands.append(command)
+                seen.add(key)
+    return _command_decision(
+        commands, config, root, "Pre-refactor sweep:", "UserPromptSubmit",
+    )
+
+
+def _command_decision(
+    commands: list[list[str]], config: dict, root: Path, heading: str, event_name: str,
+) -> Decision:
+    if not commands:
+        return Decision(None, event_name)
+    timeout = float(config.get("timeoutSeconds", 15))
+    lines = [heading]
+    for command in commands:
+        try:
+            result = subprocess.run(
+                command, cwd=root, capture_output=True, text=True, timeout=timeout,
+            )
+            detail = (result.stdout + result.stderr).strip()
+            verdict = "PASS" if result.returncode == 0 else f"FAIL (exit {result.returncode})"
+        except subprocess.TimeoutExpired as error:
+            detail = ((error.stdout or "") + (error.stderr or "")).strip()
+            verdict = f"FAIL (timeout {timeout:g}s)"
+        except OSError as error:
+            detail = str(error)
+            verdict = "FAIL (exec)"
+        lines.append(f"- {verdict}: {' '.join(command)}")
+        if detail:
+            lines.append(f"  {detail}")
+    return Decision(
+        _bounded("\n".join(lines), int(config.get("outputBudget", 1000))),
+        event_name,
+    )
+
+
+def stop_check_decision(profile: dict, payload: dict, root: Path) -> Decision:
+    config = profile.get("stopChecks", {})
+    changed = payload.get("changed_files", [])
+    commands: list[list[str]] = []
+    seen: set[tuple[str, ...]] = set()
+    for surface in config.get("surfaces", []):
+        if not any(
+            fnmatch.fnmatch(path, pattern)
+            for path in changed
+            for pattern in surface.get("globs", [])
+        ):
+            continue
+        command = surface.get("command", [])
+        key = tuple(command)
+        if command and key not in seen:
+            commands.append(command)
+            seen.add(key)
+    return _command_decision(
+        commands, config, root, "Changed-surface stop checks:", "Stop",
+    )

package/src/lib/bundle.mjs

@@ -65,9 +65,11 @@ export const HELPER_FILES = [
   { path: 'scripts/census/delta.mjs', kind: 'script', mode: 0o644 },
   { path: 'scripts/census/state.mjs', kind: 'script', mode: 0o644 },
   { path: 'scripts/census/transaction.mjs', kind: 'script', mode: 0o644 },
-  // Consumer-owned memory planning and recovery. The module is both the stable
-  // skill API and the no-write-by-default CLI.
+  // Consumer-owned memory planning, one-time policy seeding, and recovery.
   { path: 'scripts/memory-lifecycle/index.mjs', kind: 'script', mode: 0o644 },
+  { path: 'scripts/memory-lifecycle/setup.mjs', kind: 'script', mode: 0o644 },
+  { path: 'assets/memory-templates/meta_decision_layer_choice.md', kind: 'template', mode: 0o644 },
+  { path: 'assets/memory-templates/meta_memory_lifecycle.md', kind: 'template', 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.
@@ -89,6 +91,14 @@ export const HELPER_FILES = [
   { 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/slice-handoff-hint.py', kind: 'hook', mode: 0o755 },
+  // Profile-driven non-blocking change-lifecycle advisories. The shell Stop
+  // entry delegates to its sibling Python adapter; decisions stay in core.py.
+  { path: 'scripts/workflow-advisories/core.py', kind: 'script', mode: 0o644 },
+  { path: '.claude/hooks/recon-size-hint.py', kind: 'hook', mode: 0o755 },
+  { path: '.claude/hooks/baseline-capture-hint.py', kind: 'hook', mode: 0o755 },
+  { path: '.claude/hooks/pre-refactor-sweep.py', kind: 'hook', mode: 0o755 },
+  { path: '.claude/hooks/typecheck-on-stop.py', kind: 'hook', mode: 0o755 },
+  { path: '.claude/hooks/typecheck-on-stop.sh', 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