@event4u/agent-config 5.10.0 → 5.10.1

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "5.10.0",
+    "version": "5.10.1",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -820,6 +820,19 @@ our recommendation order, not its support status.
 > that forces a new era split (`# Era: 5.10.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [5.10.1](https://github.com/event4u-app/agent-config/compare/5.10.0...5.10.1) (2026-06-02)
+
+### Bug Fixes
+
+* **hooks:** self-heal stale ./agent-config wrapper on session_start ([c36ad4d](https://github.com/event4u-app/agent-config/commit/c36ad4dbfbccfcaac017a4f8e2cb526223cbf5fa))
+* **cli:** refresh project ./agent-config wrapper on upgrade and refresh --project ([abf2936](https://github.com/event4u-app/agent-config/commit/abf293657cc6630aca548d5afa9385d8c7690522))
+
+### Chores
+
+* **git:** untrack agents/runtime council artifacts ([b58705d](https://github.com/event4u-app/agent-config/commit/b58705d96bd4ee813f2565ee73e4f9f484fa720d))
+
+Tests: 5512 (+12 since 5.10.0)
+
 ## [5.10.0](https://github.com/event4u-app/agent-config/compare/5.9.0...5.10.0) (2026-06-02)
 
 ### Features

package/dist/discovery/deprecation-report.md

@@ -1,6 +1,6 @@
 # Discovery — Deprecation Report
 
-- Generated: `2026-06-02T12:33:08Z`
+- Generated: `2026-06-02T13:30:57Z`
 - Deprecated artefacts: **0**
 
 _None. Tree is clean._

package/dist/discovery/discovery-manifest.json

@@ -10004,7 +10004,7 @@
       "reason": "scaffold for new SKILL.md authoring"
     }
   ],
-  "generated_at": "2026-06-02T12:33:08Z",
+  "generated_at": "2026-06-02T13:30:57Z",
   "packs": [
     {
       "artefact_count": 85,

package/dist/discovery/discovery-manifest.json.sha256

@@ -1 +1 @@
-b30fc8174fa095e23447c3419bbbd0b610fb33e895bc5df99ea6160cb6dac1c2  discovery-manifest.json
+4ab7f294f2a0fdb6122559d63cdbc8fb6cb7ac64661141535bc217431cfe8e01  discovery-manifest.json

package/dist/discovery/discovery-manifest.summary.md

@@ -1,6 +1,6 @@
 # Discovery Manifest — Summary
 
-- Generated: `2026-06-02T12:33:08Z`
+- Generated: `2026-06-02T13:30:57Z`
 - Scanner: `ca7acd2ec7af`
 - Artefacts: **453**
 - Unassigned: **0**

package/dist/discovery/orphan-report.md

@@ -1,6 +1,6 @@
 # Discovery — Orphan Report
 
-- Generated: `2026-06-02T12:33:08Z`
+- Generated: `2026-06-02T13:30:57Z`
 - Orphan artefacts: **0**
 
 > An orphan is an artefact whose declared pack has no other members.

package/dist/discovery/packs.json

@@ -1,6 +1,6 @@
 {
   "checksum": "sha256:b55ddc4224e45ec7627ece7c2fd6f043df8c7030efbe50df87573f0da4de4173",
-  "generated_at": "2026-06-02T12:33:08Z",
+  "generated_at": "2026-06-02T13:30:57Z",
   "packs": [
     {
       "artefact_count": 85,

package/dist/discovery/trust-report.md

@@ -1,6 +1,6 @@
 # Discovery — Trust Report
 
-- Generated: `2026-06-02T12:33:08Z`
+- Generated: `2026-06-02T13:30:57Z`
 - Workspaces tracked: **8**
 - Human-review-required artefacts: **2**
 

package/dist/discovery/workspaces.json

@@ -1,6 +1,6 @@
 {
   "checksum": "sha256:b55ddc4224e45ec7627ece7c2fd6f043df8c7030efbe50df87573f0da4de4173",
-  "generated_at": "2026-06-02T12:33:08Z",
+  "generated_at": "2026-06-02T13:30:57Z",
   "scanner_version": "ca7acd2ec7af",
   "workspaces": [
     {

package/dist/mcp/registry-manifest.json

@@ -9,7 +9,7 @@
     "homepage": "https://github.com/event4u-app/agent-config#readme",
     "name": "@event4u/agent-config",
     "repository": "https://github.com/event4u-app/agent-config",
-    "version": "5.10.0"
+    "version": "5.10.1"
   },
   "registries": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "5.10.0",
+    "version": "5.10.1",
     "description": "Universal AI Agent OS \u2014 audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/scripts/_cli/cmd_refresh.py

@@ -84,7 +84,7 @@ def _is_source_repo(project_root: Path) -> bool:
 def _refresh_project(project_root: Path, out, err) -> int:
     # Imported lazily: scripts.install is large and only needed for --project.
     from scripts import install as installer
-    from scripts._lib import installed_lock
+    from scripts._lib import cli_wrapper, installed_lock
 
     if _is_source_repo(project_root):
         print("ℹ️  refresh --project skipped: this is the agent-config package "
@@ -114,6 +114,12 @@ def _refresh_project(project_root: Path, out, err) -> int:
             encoding="utf-8")
     print(f"✅  overrides scaffold: {overrides}", file=out)
 
+    # Re-stamp the ``./agent-config`` wrapper from the canonical template so
+    # an older, fallback-less wrapper cannot linger and break the hooks.
+    wrapper = cli_wrapper.install_cli_wrapper(project_root)
+    if wrapper is not None:
+        print(f"✅  ./agent-config wrapper refreshed: {wrapper}", file=out)
+
     rc = _sync_gitignore(project_root, out, err)
     if rc != 0:
         return rc

package/scripts/_cli/cmd_upgrade.py

@@ -8,12 +8,16 @@ goal: it installs the latest published package globally and re-runs the
 global install so new skills / rules / hooks reach every consumer at
 once.
 
-Two side effects, in order:
+Side effects, in order:
 
 1. ``npm install -g @event4u/agent-config@latest`` — refresh the global
    binary on PATH (the binary the Claude plugin hook resolves).
 2. ``agent-config global`` (→ ``install.py --global``) — refresh the
    global root (``~/.event4u/agent-config/``) + regenerate plugin hooks.
+3. If run from inside a consumer project that already has a
+   ``./agent-config`` wrapper, re-stamp that wrapper from the canonical
+   template so an older, fallback-less copy cannot linger and break the
+   hooks. Skipped in the source repo and never creates a wrapper.
 
 The **Claude marketplace plugin** updates on Claude Code's own cadence,
 independent of npm; ``upgrade`` cannot drive it. ``agent-config doctor``
@@ -72,12 +76,36 @@ def _agent_config_bin() -> str:
         Path(__file__).resolve().parents[2] / "agent-config")
 
 
+def _maybe_refresh_project_wrapper(project_root: Path, out, err) -> None:
+    """Re-stamp the project-local ``./agent-config`` wrapper after a global
+    upgrade — but only when the upgrade was run from inside a consumer
+    project that *already* has a wrapper. Never creates one (that is an
+    install action, out of scope), never touches the source repo.
+
+    This closes the gap where ``upgrade`` refreshed the global binary while
+    an older, fallback-less project wrapper kept breaking the Claude hooks.
+    """
+    from scripts._lib import cli_wrapper
+    from scripts._cli.cmd_refresh import _is_source_repo
+
+    if _is_source_repo(project_root):
+        return
+    if not (project_root / "agent-config").is_file():
+        return  # not a consumer project root (or never installed) — leave it
+    if not cli_wrapper.needs_refresh(project_root):
+        return
+    wrapper = cli_wrapper.install_cli_wrapper(project_root)
+    if wrapper is not None:
+        print(f"✅  refreshed stale project wrapper: {wrapper}", file=out)
+
+
 def main(
     argv: Optional[list[str]] = None,
     *,
     runner: Runner = _default_runner,
     fetcher=update_check.fetch_latest_from_npm,
     installed: Optional[str] = None,
+    project_root: Optional[Path] = None,
     out=sys.stdout,
     err=sys.stderr,
 ) -> int:
@@ -128,6 +156,8 @@ def main(
                   f"{' '.join(cmd)}", file=err)
             return 1
 
+    _maybe_refresh_project_wrapper(project_root or Path.cwd(), out, err)
+
     print("✅  agent-config upgraded. Run `agent-config doctor` to verify "
           "PATH + plugin parity.", file=out)
     return 0

package/scripts/_lib/cli_wrapper.py

@@ -0,0 +1,64 @@
+"""Install / refresh the consumer-facing ``./agent-config`` wrapper.
+
+Python counterpart to ``install_cli_wrapper`` in ``scripts/install.sh``.
+The wrapper is gitignored and meant to be regenerated on every install,
+but the normal update cadence (``upgrade``, ``refresh --project``) never
+re-ran the bash installer — so an older, fallback-less wrapper could
+linger in a consumer project and break every Claude hook (the hook
+resolves the master CLI *through* this wrapper). These helpers let the
+update commands re-stamp the wrapper from the canonical template.
+
+The template is the single source of truth (``templates/agent-config-wrapper.sh``);
+the installer copies it verbatim with no substitution, so refreshing is a
+plain copy + ``chmod``.
+"""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Optional
+
+# scripts/_lib/cli_wrapper.py → parents[2] is the package root.
+_PACKAGE_ROOT = Path(__file__).resolve().parents[2]
+_TEMPLATE = _PACKAGE_ROOT / "templates" / "agent-config-wrapper.sh"
+
+
+def template_path() -> Path:
+    """Absolute path to the canonical wrapper template."""
+    return _TEMPLATE
+
+
+def _target(project_root: Path) -> Path:
+    return Path(project_root) / "agent-config"
+
+
+def needs_refresh(project_root: Path) -> bool:
+    """True when the project wrapper is missing or differs from the template.
+
+    Returns ``False`` when the template itself is unavailable (corrupt /
+    maintainer-only checkout) — there is nothing to refresh *to*.
+    """
+    if not _TEMPLATE.is_file():
+        return False
+    target = _target(project_root)
+    if not target.is_file():
+        return True
+    try:
+        return target.read_text(encoding="utf-8") != _TEMPLATE.read_text(
+            encoding="utf-8")
+    except OSError:
+        return True
+
+
+def install_cli_wrapper(project_root: Path) -> Optional[Path]:
+    """Copy the canonical wrapper template to ``<project_root>/agent-config``.
+
+    Returns the written target path, or ``None`` when the template is
+    missing (corrupt package / maintainer checkout without templates).
+    """
+    if not _TEMPLATE.is_file():
+        return None
+    target = _target(project_root)
+    shutil.copyfile(_TEMPLATE, target)
+    target.chmod(0o755)
+    return target

package/scripts/hook_manifest.yaml

@@ -62,16 +62,25 @@ concerns:
     script: scripts/profile_staleness_hook.py
     args: []
     fail_closed: false
+  # Defense-in-depth twin of the update-command wrapper refresh
+  # (cmd_upgrade / cmd_refresh). On session_start, re-stamps a stale
+  # project-local ./agent-config wrapper from the canonical template so
+  # an outdated, fallback-less copy cannot keep breaking the hooks.
+  # Never creates a wrapper, never touches the source repo, fail-open.
+  wrapper-freshness:
+    script: scripts/wrapper_freshness_hook.py
+    args: []
+    fail_closed: false
 
 platforms:
   augment:
-    session_start:    [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness]
+    session_start:    [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
     session_end:      [chat-history]
     stop:             [chat-history, verify-before-complete]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff]
 
   claude:
-    session_start:    [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness]
+    session_start:    [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
     session_end:      [chat-history]
     stop:             [chat-history, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
@@ -92,7 +101,7 @@ platforms:
   # Decision matrix + upstream blockers tracked in
   # agents/settings/contexts/chat-history-platform-hooks.md § Cowork.
   cowork:
-    session_start:    [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness]
+    session_start:    [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
     session_end:      [chat-history]
     stop:             [chat-history, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
@@ -106,7 +115,7 @@ platforms:
   # IDE-only — CLI-only users fall back to /checkpoint per
   # agents/settings/contexts/chat-history-platform-hooks.md.
   cursor:
-    session_start:      [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness]
+    session_start:      [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
     session_end:        [chat-history]
     stop:               [chat-history, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
@@ -121,7 +130,7 @@ platforms:
   # both map to session_start. TaskCancel maps to stop because the
   # session is interrupted with partial state (mirrors Augment Stop).
   cline:
-    session_start:      [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness]
+    session_start:      [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
     session_end:        [chat-history]
     stop:               [chat-history, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
@@ -140,7 +149,7 @@ platforms:
   # surface to record verification commands; documented limitation).
   # minimal-safe-diff is omitted entirely on Windsurf for the same reason.
   windsurf:
-    session_start:      [chat-history, first-run-gate, onboarding-gate, verify-before-complete, profile-staleness]
+    session_start:      [chat-history, first-run-gate, onboarding-gate, verify-before-complete, profile-staleness, wrapper-freshness]
     stop:               [chat-history, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete]
 
@@ -155,7 +164,7 @@ platforms:
   # turn-check semantics. AfterAgent fires when the agent loop ends
   # — this is our `stop` slot.
   gemini:
-    session_start:      [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness]
+    session_start:      [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
     session_end:        [chat-history]
     stop:               [chat-history, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]

package/scripts/wrapper_freshness_hook.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""session_start concern — keep the project-local ``./agent-config`` fresh.
+
+Defense-in-depth twin of the update-command refresh (``upgrade`` /
+``refresh --project``). On every session_start the dispatcher runs this in
+the consumer workspace; if a ``./agent-config`` wrapper exists there and
+differs from the canonical template, it is re-stamped so an outdated,
+fallback-less copy cannot keep breaking the hooks.
+
+Bootstrapping note: this can only heal a wrapper functional enough to
+invoke the dispatcher in the first place (the current template's global +
+npx fallbacks guarantee that). A *completely* broken wrapper never reaches
+this concern — that recovery path is ``agent-config upgrade`` /
+``refresh --project``.
+
+Contract: never creates a wrapper where none exists (that is an install
+action); never touches the agent-config source repo; always fail-open
+(exit 0) — hook self-heal must not block a session.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+# Make `scripts` importable when invoked as a bare script path.
+_REPO = Path(__file__).resolve().parent.parent
+if str(_REPO) not in sys.path:
+    sys.path.insert(0, str(_REPO))
+
+EXIT_ALLOW = 0
+
+
+def _project_root() -> Path:
+    env = os.environ.get("CLAUDE_PROJECT_DIR") or os.environ.get(
+        "AGENT_CONFIG_PROJECT_DIR")
+    if env:
+        return Path(env)
+    return Path.cwd()
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        description="Project ./agent-config wrapper freshness (session_start).")
+    ap.add_argument("--root", default=None)
+    args, _ = ap.parse_known_args(argv)
+
+    # Drain stdin (the dispatcher passes a JSON envelope); we do not need it.
+    try:
+        if not sys.stdin.isatty():
+            sys.stdin.read()
+    except Exception:
+        pass
+
+    try:
+        from scripts._lib import cli_wrapper
+        from scripts._cli.cmd_refresh import _is_source_repo
+    except Exception:  # pragma: no cover — defensive; never block the loop
+        return EXIT_ALLOW
+
+    root = Path(args.root) if args.root else _project_root()
+    try:
+        if _is_source_repo(root):
+            return EXIT_ALLOW
+        if not (root / "agent-config").is_file():
+            return EXIT_ALLOW  # no wrapper here — never create one
+        if not cli_wrapper.needs_refresh(root):
+            return EXIT_ALLOW
+        wrapper = cli_wrapper.install_cli_wrapper(root)
+    except Exception:
+        return EXIT_ALLOW  # fail-open — never block the session
+
+    if wrapper is not None:
+        print(f"[wrapper] re-stamped stale ./agent-config at {wrapper}",
+              file=sys.stderr)
+        sys.stdout.write(json.dumps({
+            "decision": "allow",
+            "reason": f"refreshed stale ./agent-config wrapper at {wrapper}",
+        }))
+    return EXIT_ALLOW
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())