@event4u/agent-config 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -7,6 +7,30 @@ versioning policy is documented in [CONTRIBUTING.md](CONTRIBUTING.md#versioning-
 > Entries before 1.3.3 were reconstructed from git history after the fact.
 > Early releases did not maintain release notes.
 
+## [1.13.0](https://github.com/event4u-app/agent-config/compare/1.12.0...1.13.0) (2026-04-27)
+
+### Features
+
+* **postinstall:** hint about optional @event4u/agent-memory backend ([395cff1](https://github.com/event4u-app/agent-config/commit/395cff164770da4a18d4287effd9ce06b2cee8b9))
+* **npm:** declare @event4u/agent-memory as optional peer dependency ([cef7715](https://github.com/event4u-app/agent-config/commit/cef77159d2d7cd0ba29c78c9c2115f1d08f0e649))
+* **composer:** suggest @event4u/agent-memory as optional memory backend ([6585c32](https://github.com/event4u-app/agent-config/commit/6585c324fcc65ad08f1d50f0e54a7f56b2018d03))
+* **scripts:** fail check mode on unarchived complete roadmaps ([f017979](https://github.com/event4u-app/agent-config/commit/f0179792a9b15588182815a17e4ac7366dad1db0))
+* **scripts:** add hooks:install and pre-commit roadmap-progress hook ([cab9048](https://github.com/event4u-app/agent-config/commit/cab90482ad2bf70fa08f9494236eb19b72e5d58b))
+* **templates:** ship roadmap-progress-check GitHub Actions workflow ([a16c560](https://github.com/event4u-app/agent-config/commit/a16c560d57f3cefd0b99aeaadd0946c3a8865866))
+* **memory:** real backend health envelope ([145bd13](https://github.com/event4u-app/agent-config/commit/145bd13ec6027d48a90cdacc3622ef9cca7d8c05))
+* **memory:** package-backed operational provider (Drift #2) ([284be4c](https://github.com/event4u-app/agent-config/commit/284be4c4addca37490b727a2aec9d45c1fa9b274))
+* **rules:** require recommendations on every numbered-option question ([ed9f5c9](https://github.com/event4u-app/agent-config/commit/ed9f5c9271c486a920fed3fbbea10fc16e75f685))
+* **memory:** wire agent-memory MCP server + recognize 'memory' binary ([e24168b](https://github.com/event4u-app/agent-config/commit/e24168b12bd8f5711ec02f6511c3afa952e595a8))
+
+### Documentation
+
+* **readme:** document @event4u/agent-memory as optional companion ([350930f](https://github.com/event4u-app/agent-config/commit/350930fcee3134275bbed26a6783d54837eba568))
+* **agent-memory:** align contract with reality — CLI surface + drift status ([6cdf19e](https://github.com/event4u-app/agent-config/commit/6cdf19ee256b52aa7602419fde730477d2a904de))
+
+### CI
+
+* wire roadmap-progress-check into task ci ([2022396](https://github.com/event4u-app/agent-config/commit/20223964f2c391598efca5b9e76fd5ca1365f05e))
+
 ## [1.12.0](https://github.com/event4u-app/agent-config/compare/1.10.0...1.12.0) (2026-04-25)
 
 ### Features

package/README.md

@@ -71,6 +71,27 @@ Install directly in your agent for global, cross-project use:
 
 → [Full getting started guide](docs/getting-started.md)
 
+### Optional: persistent agent memory
+
+`agent-config` integrates with [`@event4u/agent-memory`](https://www.npmjs.com/package/@event4u/agent-memory)
+— an MCP-based memory backend that gives agents persistent learnings
+across sessions. It is **strictly optional**:
+
+- Not a required dependency (declared as `suggest` in Composer and as an
+  optional peer in npm). `agent-config` itself never imports it.
+- Without it, agent skills fall back to **file-based memory** under
+  `agents/memory/` and continue to work normally.
+- Recommended for teams that want learnings to survive across machines,
+  branches, and chat sessions.
+
+Install in the same project (dev-only):
+
+```bash
+npm install --save-dev @event4u/agent-memory
+```
+
+→ [Memory contract & retrieval API](agents/contexts/agent-memory-contract.md)
+
 ---
 
 ## 2-minute demo: `/implement-ticket`

package/composer.json

@@ -6,6 +6,9 @@
     "require": {
         "php": ">=8.0"
     },
+    "suggest": {
+        "@event4u/agent-memory": "Optional MCP-based memory backend (npm: @event4u/agent-memory ^1.1.0). Adds persistent agent learnings across sessions. Install with `npm install --save-dev @event4u/agent-memory` if your team wants the memory layer; otherwise agent-config falls back to file-based memory."
+    },
     "bin": [
         "bin/install.php",
         "scripts/agent-config"

package/docs/getting-started.md

@@ -28,6 +28,7 @@ so you can run a few package scripts without installing `go-task`,
 ```bash
 ./agent-config mcp:render          # sync MCP server config into .cursor/ and .windsurf/
 ./agent-config roadmap:progress    # regenerate agents/roadmaps-progress.md
+./agent-config hooks:install       # install pre-commit roadmap-progress hook (opt-in)
 ./agent-config first-run           # guided setup
 ./agent-config help                # full command list
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.12.0",
+    "version": "1.13.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,
@@ -38,5 +38,13 @@
     "publishConfig": {
         "access": "public",
         "provenance": true
+    },
+    "peerDependencies": {
+        "@event4u/agent-memory": "^1.1.0"
+    },
+    "peerDependenciesMeta": {
+        "@event4u/agent-memory": {
+            "optional": true
+        }
     }
 }

package/scripts/agent-config

@@ -46,6 +46,8 @@ Commands:
   mcp:check                  Dry-run mcp:render; exit non-zero if targets are stale
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
+  hooks:install              Install the pre-commit roadmap-progress hook
+                             (use --print to dump it, --force to overwrite an existing hook)
   first-run                  Guided first-run setup — cost profile, settings, tooling
   help                       Show this help
   --version, -V              Print package version
@@ -55,6 +57,7 @@ Examples:
   ./agent-config mcp:render --claude-desktop
   ./agent-config mcp:check
   ./agent-config roadmap:progress
+  ./agent-config hooks:install
   ./agent-config first-run
 
 All commands operate on the CURRENT DIRECTORY (your project root).
@@ -132,6 +135,77 @@ cmd_first_run() {
   exec bash "$script" "$@"
 }
 
+cmd_hooks_install() {
+  local force=false
+  local print_only=false
+  for arg in "$@"; do
+    case "$arg" in
+      --force)   force=true ;;
+      --print)   print_only=true ;;
+      -h|--help)
+        cat <<'HELP'
+agent-config hooks:install — install the pre-commit roadmap-progress hook.
+
+Usage:
+  ./agent-config hooks:install [--force] [--print]
+
+Without flags: copies the hook to .git/hooks/pre-commit. Refuses to
+overwrite an existing pre-commit hook unless --force is given (the
+existing hook may already chain other tooling).
+
+  --print   dump the hook script to stdout (for manual chaining into an
+            existing pre-commit script, husky, lefthook, etc.)
+  --force   overwrite an existing .git/hooks/pre-commit (DESTRUCTIVE)
+HELP
+        return 0 ;;
+      *)
+        echo "❌  hooks:install: unknown argument: $arg" >&2
+        echo "    Run \`./agent-config hooks:install --help\` for usage." >&2
+        return 2 ;;
+    esac
+  done
+
+  local hook_src
+  hook_src="$(resolve_script ".agent-src/templates/hooks/pre-commit-roadmap-progress" ".augment/templates/hooks/pre-commit-roadmap-progress")" || return 1
+
+  if $print_only; then
+    cat "$hook_src"
+    return 0
+  fi
+
+  local git_dir
+  git_dir="$(git -C "$CONSUMER_ROOT" rev-parse --git-dir 2>/dev/null || true)"
+  if [[ -z "$git_dir" ]]; then
+    echo "❌  hooks:install: $CONSUMER_ROOT is not a git repository." >&2
+    return 1
+  fi
+  # Resolve relative git-dir paths (worktrees, submodules) against CONSUMER_ROOT.
+  [[ "$git_dir" != /* ]] && git_dir="$CONSUMER_ROOT/$git_dir"
+
+  local hook_dir="$git_dir/hooks"
+  local target="$hook_dir/pre-commit"
+  mkdir -p "$hook_dir"
+
+  if [[ -f "$target" ]] && ! $force; then
+    if grep -q "pre-commit-roadmap-progress" "$target" 2>/dev/null; then
+      echo "✅  hooks:install: already installed at $target"
+      return 0
+    fi
+    echo "⚠️   hooks:install: $target already exists and looks unrelated." >&2
+    echo "    Options:" >&2
+    echo "      1. Inspect it and append the snippet manually:" >&2
+    echo "         ./agent-config hooks:install --print >> $target" >&2
+    echo "      2. Replace it (destructive):" >&2
+    echo "         ./agent-config hooks:install --force" >&2
+    return 1
+  fi
+
+  cp "$hook_src" "$target"
+  chmod +x "$target"
+  echo "✅  hooks:install: pre-commit hook installed at $target"
+  echo "    To uninstall: rm $target"
+}
+
 main() {
   local cmd="${1-}"
   [[ $# -gt 0 ]] && shift || true
@@ -141,6 +215,7 @@ main() {
     mcp:check)               cmd_mcp_check "$@" ;;
     roadmap:progress)        cmd_roadmap_progress "$@" ;;
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
+    hooks:install)           cmd_hooks_install "$@" ;;
     first-run)               cmd_first_run "$@" ;;
     help|--help|-h|"")        usage ;;
     --version|-V)            print_version ;;

package/scripts/memory_lookup.py

@@ -1,21 +1,28 @@
 #!/usr/bin/env python3
-"""File-based retrieval for the `absent` path.
+"""Hybrid retrieval — file-first with optional package augmentation.
 
 Implements the shared `retrieve(types, keys, limit)` abstraction used
 by skills. Reads YAML under `agents/memory/<type>/` (curated, hand-
 reviewed) and JSONL under `agents/memory/intake/*.jsonl` (agent-written,
 append-only, supersede-chain aware).
 
-The returned shape is identical to the `present`-path adapter over the
-`@event4u/agent-memory` API, so skills stay backend-agnostic.
+When the `@event4u/agent-memory` package is present (see
+`scripts/memory_status.py`), callers can pass the result of
+:func:`package_operational_provider` to route additional retrieval
+through the package's semantic CLI. Repo entries always win on
+conflict — see `_apply_conflict_rule`.
 
 Usage:
     python3 scripts/memory_lookup.py --types domain-invariants,ownership \\
         --key "app/Http/Controllers/Foo" --limit 5
     python3 scripts/memory_lookup.py --types incident-learnings --format json
+    python3 scripts/memory_lookup.py --types ownership --key billing --auto
 
-    from scripts.memory_lookup import retrieve
-    hits = retrieve(types=["ownership"], keys=["app/Http"], limit=3)
+    from scripts.memory_lookup import retrieve, package_operational_provider
+    hits = retrieve(
+        types=["ownership"], keys=["app/Http"], limit=3,
+        operational_provider=package_operational_provider(),
+    )
 """
 
 from __future__ import annotations
@@ -23,6 +30,8 @@ from __future__ import annotations
 import argparse
 import fnmatch
 import json
+import os
+import subprocess
 import sys
 from dataclasses import dataclass, asdict, field
 from pathlib import Path
@@ -229,6 +238,125 @@ def _apply_conflict_rule(
     return merged, shadows
 
 
+# ---------------------------------------------------------------------------
+# Package-backed operational provider (the `present` path)
+# ---------------------------------------------------------------------------
+#
+# When `memory_status.status() == "present"` the consumer-facing contract
+# says retrieval should route through `@event4u/agent-memory`. The package
+# CLI is purely **semantic** (`memory retrieve <query> --type T …`); the
+# shared `retrieve(types, keys, …)` API is **key-based**. The hybrid
+# resolution agreed in `agents/contexts/agent-memory-contract.md` synthesises
+# `keys` into a single natural-language query for the package call, while
+# the file fallback continues to do glob/substring matching on the same
+# keys. Both legs land in the same `Hit` shape so the conflict rule can
+# merge them transparently.
+
+_CLI_TIMEOUT_SECONDS = 5.0
+_CLI_RETRIEVE_LIMIT_DEFAULT = 20
+
+
+def _synthesize_query(keys: list[str]) -> str:
+    """Turn a list of retrieval keys into one natural-language query.
+
+    Keys are typically file paths (`app/Http/Controllers/Foo`), feature
+    names (`billing`), or short identifiers — joining them with spaces
+    gives the package's semantic search enough surface to score against
+    without inventing structure. Empty or whitespace-only keys are
+    dropped; if nothing remains the caller falls back to the file path.
+    """
+    cleaned = [k.strip() for k in keys if isinstance(k, str) and k.strip()]
+    return " ".join(cleaned)
+
+
+def _cli_operational_provider(
+    types: list[str],
+    keys: list[str],
+    *,
+    cli_path: str = "memory",
+    timeout: float = _CLI_TIMEOUT_SECONDS,
+    limit: int = _CLI_RETRIEVE_LIMIT_DEFAULT,
+) -> Iterable[Hit]:
+    """Run `memory retrieve` and yield operational `Hit` objects.
+
+    Pino structured logs from the package go to stderr; stdout is a
+    clean v1 retrieval envelope. Any non-zero exit, timeout, or parse
+    failure degrades to "no operational hits" — `retrieve()` already
+    treats provider exceptions as a soft warning, so the caller still
+    gets the file-fallback result.
+    """
+    query = _synthesize_query(keys)
+    if not query:
+        return
+    cmd: list[str] = [cli_path, "retrieve", query, "--limit", str(limit)]
+    for t in types:
+        cmd.extend(["--type", t])
+    try:
+        out = subprocess.run(
+            cmd,
+            capture_output=True, text=True, timeout=timeout,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return
+    if out.returncode != 0:
+        return
+    try:
+        envelope = json.loads(out.stdout)
+    except (ValueError, TypeError):
+        return
+    entries = envelope.get("entries") if isinstance(envelope, dict) else None
+    if not isinstance(entries, list):
+        return
+    for e in entries:
+        if not isinstance(e, dict):
+            continue
+        eid = e.get("id")
+        etype = e.get("type")
+        if not isinstance(eid, str) or not isinstance(etype, str):
+            continue
+        # The package returns `confidence` (0..1) per the v1 envelope;
+        # map it onto our internal `score` field so the conflict rule
+        # and ranking work uniformly across providers.
+        try:
+            score = float(e.get("confidence", 0.0))
+        except (TypeError, ValueError):
+            score = 0.0
+        body = e.get("body") if isinstance(e.get("body"), dict) else {}
+        yield Hit(
+            id=eid,
+            type=etype,
+            source="operational",
+            path=f"agent-memory:{eid}",
+            score=score,
+            entry=body,
+        )
+
+
+def package_operational_provider() -> Optional[OperationalProvider]:
+    """Return a CLI-backed provider when the package is `present`, else None.
+
+    Callers who want automatic backend routing pass the result directly
+    to :func:`retrieve` — `None` is a safe value that yields file-only
+    retrieval, so this is the recommended one-liner for skills:
+
+        retrieve(types, keys, operational_provider=package_operational_provider())
+
+    The status probe is bounded (≤ 2s, cached per process) — see
+    `scripts/memory_status.py`. We import lazily so pure file-fallback
+    callers never pay for the probe.
+    """
+    # Late import: keeps `memory_lookup` importable even when
+    # `memory_status` is missing in stripped consumer installs.
+    try:
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        import memory_status  # type: ignore[import-not-found]
+    except ImportError:
+        return None
+    if memory_status.status().status != "present":
+        return None
+    return _cli_operational_provider
+
+
 def retrieve(
     types: list[str],
     keys: list[str],
@@ -402,16 +530,24 @@ def main() -> int:
     ap.add_argument("--with-shadows", action="store_true",
                     help="Include shadowed-operational entries in the output "
                          "(no-op until an operational backend is wired)")
+    ap.add_argument("--auto", action="store_true",
+                    help="Auto-route to the @event4u/agent-memory package "
+                         "when memory_status.status() == 'present'; "
+                         "falls through to file-only retrieval otherwise")
     args = ap.parse_args()
     types = [t.strip() for t in args.types.split(",") if t.strip()]
     if not types:
         print("error: --types is required", file=sys.stderr)
         return 2
+    op_provider = package_operational_provider() if args.auto else None
     if args.envelope == "v1":
-        envelope = retrieve_v1(types, args.key, args.limit)
+        envelope = retrieve_v1(types, args.key, args.limit,
+                               operational_provider=op_provider)
         print(json.dumps(envelope, indent=2, default=str))
         return 0
-    result = retrieve(types, args.key, args.limit, with_shadows=args.with_shadows)
+    result = retrieve(types, args.key, args.limit,
+                      operational_provider=op_provider,
+                      with_shadows=args.with_shadows)
     if args.with_shadows:
         assert isinstance(result, RetrievalResult)
         hits, shadows = result.hits, result.shadows

package/scripts/memory_status.py

@@ -35,7 +35,7 @@ from typing import Literal
 
 Status = Literal["absent", "misconfigured", "present"]
 
-_CLI_CANDIDATES = ("agent-memory", "agentmem")
+_CLI_CANDIDATES = ("memory", "agent-memory", "agentmem")
 _HEALTH_TIMEOUT_SECONDS = 2.0
 _CACHE_ENV = "AGENT_MEMORY_STATUS"
 _CACHE_FILE = Path(".agent-memory") / "status.cache"
@@ -54,6 +54,11 @@ class Result:
     reason: str             # short explanation
     elapsed_ms: int         # time spent probing (0 if cached)
     cli_path: str = ""      # resolved CLI path, if any
+    # Populated only when status == "present" — sourced from the
+    # `health` CLI envelope so the v1 health() reports real package
+    # capabilities instead of file-fallback placeholders.
+    backend_version: str = ""
+    features: tuple = ()
 
 
 def _find_cli() -> str:
@@ -64,8 +69,45 @@ def _find_cli() -> str:
     return ""
 
 
-def _probe_health(cli_path: str) -> tuple[bool, str]:
-    """Returns (healthy, reason)."""
+def _parse_health_envelope(stdout: str) -> dict | None:
+    """Extract the v1 health envelope from `memory health` stdout.
+
+    The package emits a single JSON object on stdout (pino structured
+    logs go to stderr). We tolerate older builds that may have leaked
+    log lines into stdout by scanning for the first top-level object
+    that carries ``contract_version``.
+    """
+    text = (stdout or "").strip()
+    if not text:
+        return None
+    try:
+        obj = json.loads(text)
+    except ValueError:
+        obj = None
+    if isinstance(obj, dict) and obj.get("contract_version"):
+        return obj
+    # Fallback: line-by-line scan for an envelope-shaped object — covers
+    # the case where structured logs accidentally share stdout.
+    for line in text.splitlines():
+        line = line.strip()
+        if not line.startswith("{"):
+            continue
+        try:
+            cand = json.loads(line)
+        except ValueError:
+            continue
+        if isinstance(cand, dict) and cand.get("contract_version"):
+            return cand
+    return None
+
+
+def _probe_health(cli_path: str) -> tuple[bool, str, dict | None]:
+    """Returns (healthy, reason, envelope).
+
+    On success ``envelope`` is the parsed v1 health envelope (may still
+    be ``None`` for very old CLIs that don't emit one). On failure it
+    is always ``None``.
+    """
     try:
         out = subprocess.run(
             [cli_path, "health"],
@@ -73,15 +115,16 @@ def _probe_health(cli_path: str) -> tuple[bool, str]:
             timeout=_HEALTH_TIMEOUT_SECONDS,
         )
     except subprocess.TimeoutExpired:
-        return False, f"health() timed out after {_HEALTH_TIMEOUT_SECONDS}s"
+        return False, f"health() timed out after {_HEALTH_TIMEOUT_SECONDS}s", None
     except FileNotFoundError:
-        return False, "CLI vanished between which() and invoke"
+        return False, "CLI vanished between which() and invoke", None
     if out.returncode != 0:
         # First line of combined output, capped, for the reason field.
         msg = (out.stderr or out.stdout or "exit != 0").strip().splitlines()
         head = msg[0][:120] if msg else "exit != 0"
-        return False, f"health() returned {out.returncode}: {head}"
-    return True, "ok"
+        return False, f"health() returned {out.returncode}: {head}", None
+    envelope = _parse_health_envelope(out.stdout)
+    return True, "ok", envelope
 
 
 def _read_cache() -> Result | None:
@@ -131,10 +174,23 @@ def status(refresh: bool = False) -> Result:
         result = Result("absent", "file",
                         "agent-memory CLI not on PATH", 0)
     else:
-        healthy, reason = _probe_health(cli)
+        healthy, reason, envelope = _probe_health(cli)
         elapsed = int((time.monotonic() - t0) * 1000)
         if healthy:
-            result = Result("present", "package", reason, elapsed, cli)
+            backend_version = ""
+            features: tuple = ()
+            if isinstance(envelope, dict):
+                bv = envelope.get("backend_version")
+                if isinstance(bv, str):
+                    backend_version = bv
+                feats = envelope.get("features")
+                if isinstance(feats, list) and all(
+                    isinstance(f, str) for f in feats
+                ):
+                    features = tuple(feats)
+            result = Result("present", "package", reason, elapsed, cli,
+                            backend_version=backend_version,
+                            features=features)
         else:
             result = Result("misconfigured", "file", reason, elapsed, cli)
     _write_cache(result)
@@ -148,6 +204,11 @@ def health(refresh: bool = False) -> dict:
     Maps the three-state :func:`status` result onto the contract's
     ``ok | degraded | error`` so consumers can read
     ``contract_version`` without caring about the file-vs-package split.
+
+    When the package backs the call (``status == "present"``), the
+    envelope reports the package's own ``backend_version`` and
+    ``features`` so consumers can feature-detect against real
+    capabilities. Otherwise the file-fallback markers are returned.
     """
     r = status(refresh=refresh)
     envelope_status = {
@@ -155,11 +216,12 @@ def health(refresh: bool = False) -> dict:
         "misconfigured": "degraded",
         "absent": "ok",
     }[r.status]
-    # When the package is present, report its version from `health()`
-    # output; until we parse that, keep the file-fallback marker so the
-    # envelope never lies about what backed the response.
-    backend_version = _FILE_BACKEND_VERSION
-    features = list(_FILE_BACKEND_FEATURES)
+    if r.status == "present" and (r.backend_version or r.features):
+        backend_version = r.backend_version or _FILE_BACKEND_VERSION
+        features = list(r.features) if r.features else list(_FILE_BACKEND_FEATURES)
+    else:
+        backend_version = _FILE_BACKEND_VERSION
+        features = list(_FILE_BACKEND_FEATURES)
     return {
         "contract_version": CONTRACT_VERSION,
         "status": envelope_status,

package/scripts/postinstall.sh

@@ -33,6 +33,22 @@ trap 'rm -f "$LOG"' EXIT
 bash "$INSTALLER" --quiet >"$LOG" 2>&1
 CODE=$?
 if [[ $CODE -eq 0 ]]; then
+    # Optional companion: @event4u/agent-memory. Suggest it once, only if
+    # the consumer hasn't already installed it (locally or on PATH). The
+    # hint is purely informational; agent-config falls back to file-based
+    # memory when the backend is absent.
+    if ! command -v memory >/dev/null 2>&1 \
+       && ! command -v agent-memory >/dev/null 2>&1 \
+       && [[ ! -d "$SCRIPT_DIR/../../@event4u/agent-memory" ]]; then
+        cat >&2 <<'HINT'
+💡 agent-config tip: install @event4u/agent-memory for persistent agent
+   learnings across sessions (optional, dev-only):
+
+       npm install --save-dev @event4u/agent-memory
+
+   Skip if you don't need it — agent-config falls back to file-based memory.
+HINT
+    fi
     exit 0
 fi