@ikon85/agent-workflow-kit 0.23.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` + capability assets | consumer-owned Worktree Lifecycle activation and one-time Memory Lifecycle policy seeds (Sections A4–A5) |
+| `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,7 @@ 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` — existing capability choices/profile and Worktree Lifecycle 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?
 
@@ -199,6 +199,25 @@ 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.
@@ -284,11 +303,12 @@ 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

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` + capability assets | consumer-owned Worktree Lifecycle activation and one-time Memory Lifecycle policy seeds (Sections A4–A5) |
+| `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,7 @@ 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` — existing capability choices/profile and Worktree Lifecycle 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?
 
@@ -199,6 +199,25 @@ 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.
@@ -284,11 +303,12 @@ 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

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,20 @@ 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`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.23.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": "247250aa38a81b542600db42cfe4d02eecc1236e8af47df1f4def627f4df0668",
+      "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": "247250aa38a81b542600db42cfe4d02eecc1236e8af47df1f4def627f4df0668",
+      "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",
@@ -2194,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/package.json

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

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

@@ -91,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