@event4u/agent-config 1.12.0 → 1.14.0

package/scripts/lint_marketplace.py

@@ -10,6 +10,8 @@ shape used by anthropics/skills:
   - metadata must have description + version
   - metadata.version must match package.json (single source of truth)
   - every plugins[].skills[] entry must exist on disk and carry a SKILL.md
+  - every SKILL.md on disk under .claude/skills/ must be listed in some
+    plugin's skills[] (drift detection)
 
 Exit codes: 0 = clean, 1 = problems found, 3 = internal error.
 """
@@ -23,6 +25,7 @@ from pathlib import Path
 ROOT = Path(".")
 MARKETPLACE = ROOT / ".claude-plugin" / "marketplace.json"
 PACKAGE_JSON = ROOT / "package.json"
+CLAUDE_SKILLS_DIR = ROOT / ".claude" / "skills"
 
 
 def fail(errors: list[str]) -> int:
@@ -121,6 +124,30 @@ def main() -> int:
             if not skill_md.exists():
                 errors.append(f"{entry} has no SKILL.md: `{path}`")
 
+    # Reverse-completeness: every SKILL.md on disk under .claude/skills/
+    # must appear in some plugin's skills[]. Catches the drift where new
+    # skills are generated but never added to the marketplace manifest.
+    listed: set[str] = set()
+    for plugin in plugins:
+        if not isinstance(plugin, dict):
+            continue
+        for path in plugin.get("skills", []):
+            if isinstance(path, str):
+                listed.add(path.removeprefix("./"))
+
+    if CLAUDE_SKILLS_DIR.exists():
+        for skill_dir in sorted(CLAUDE_SKILLS_DIR.iterdir()):
+            if not skill_dir.is_dir():
+                continue
+            if not (skill_dir / "SKILL.md").exists():
+                continue
+            rel = f".claude/skills/{skill_dir.name}"
+            if rel not in listed:
+                errors.append(
+                    f"skill exists on disk but is not listed in marketplace.json: "
+                    f"`./{rel}`"
+                )
+
     if errors:
         return fail(errors)
 

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/migrate_command_suggestions.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""One-shot migration: inject the `suggestion:` frontmatter block into every
+command under `.agent-src.uncompressed/commands/`.
+
+Source-of-truth table: `agents/contexts/command-suggestion-eligibility.md`
+(locked at end of road-to-context-aware-command-suggestion Phase 1).
+
+Idempotent: if `suggestion:` is already present for a command, the file is
+left untouched. Re-runnable.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+COMMANDS_DIR = ROOT / ".agent-src.uncompressed" / "commands"
+
+INELIGIBLE: dict[str, str] = {
+    "agent-handoff": "Explicit fresh-chat handoff — must be deliberate, never inferred from prose.",
+    "agent-status": "Pure status display; no natural-language trigger distinct from idle small-talk.",
+    "agents-cleanup": "Consumes prior audit output; only meaningful right after /agents-audit.",
+    "agents-prepare": "One-shot project scaffolding; only run during initial setup.",
+    "chat-history": "Status display only; no NL trigger distinct from 'show status'.",
+    "chat-history-clear": "Destructive log wipe — must be deliberate.",
+    "chat-history-resume": "Explicit resume mechanic with foreign/returning state machine.",
+    "compress": "Package-internal tooling; only the event4u/agent-config repo runs this.",
+    "copilot-agents-init": "Project init — only deliberately during onboarding.",
+    "copilot-agents-optimize": "Maintenance refactor; only when the maintainer chooses to run it.",
+    "do-and-judge": "Subagent orchestration — overlaps /work and judge skills; keep explicit.",
+    "do-in-steps": "Subagent orchestration — overlaps /work and /roadmap-execute; keep explicit.",
+    "fix-portability": "Package-internal — only the event4u/agent-config repo runs this.",
+    "fix-references": "Package-internal — only the event4u/agent-config repo runs this.",
+    "judge": "Sibling of /review-changes — eligibility routed there; keep this explicit.",
+    "memory-full": "Description states 'never auto-triggered' — opt-in deep-load only.",
+    "memory-promote": "Curation pipeline — overlaps /memory-add; keep explicit.",
+    "mode": "Role-mode switch is a deliberate context change.",
+    "onboard": "Gated by the onboarding-gate rule already; never inferred from prose.",
+    "optimize-augmentignore": "Niche maintenance tool with no recurring NL trigger.",
+    "optimize-rtk-filters": "Niche maintenance tool with no recurring NL trigger.",
+    "package-reset": "Package-internal destructive reset.",
+    "package-test": "Package-internal — only the event4u/agent-config repo runs this.",
+    "propose-memory": "Programmatic intake fallback — overlaps /memory-add; keep explicit.",
+    "set-cost-profile": "Settings mutation — must be deliberate.",
+    "sync-agent-settings": "Settings sync — must be deliberate.",
+    "sync-gitignore": "Settings sync — must be deliberate.",
+}
+
+# (trigger_description, trigger_context)
+ELIGIBLE: dict[str, tuple[str, str]] = {
+    "agents-audit": ("audit my agent docs, check the state of the agents/ directory", "stale files under agents/ or recent edits to .augment/ without doc updates"),
+    "analyze-reference-repo": ("look at how X does this, compare with that other repo, study this competitor's approach", "external repo URL or path mentioned in the prompt"),
+    "bug-fix": ("fix this bug, patch the issue, resolve this error", "branch name matches fix/* or bug/*"),
+    "bug-investigate": ("why is this broken, investigate this error, trace the root cause", "Sentry URL, Jira bug ticket key, or stack trace pasted in the prompt"),
+    "commit": ("commit my changes, save this to git, create commits for these changes", "git status shows uncommitted changes"),
+    "commit-in-chunks": ("commit everything autonomously, split and commit without confirmation", "autonomous mode active and uncommitted changes present"),
+    "context-create": ("document this part of the codebase, create a context doc for X", "working in a module without an agents/contexts/ doc"),
+    "context-refactor": ("update the context doc, refresh this context document", "existing agents/contexts/*.md referenced in the prompt"),
+    "create-pr": ("open a PR, create a pull request, make a PR for this branch", "branch is ahead of base and not yet on a PR"),
+    "create-pr-description": ("write a PR description, draft the PR text", "PR exists or branch ready for review without description"),
+    "e2e-heal": ("fix the failing E2E tests, playwright tests are red", "failing test output from tests/e2e/"),
+    "e2e-plan": ("plan E2E tests for this feature, what should we cover in playwright", "new feature or page added without tests/e2e/ coverage"),
+    "estimate-ticket": ("how big is this ticket, estimate PROJ-123, should we split this", "ticket key matching [A-Z]+-[0-9]+ in the prompt and no plan yet"),
+    "feature-dev": ("build this feature end-to-end, run the full feature workflow", "long-form feature description spanning multiple components"),
+    "feature-explore": ("brainstorm this idea, explore this feature concept", "open-ended feature idea without acceptance criteria"),
+    "feature-plan": ("plan this feature, create a feature spec for X", "feature idea referenced and no plan doc exists"),
+    "feature-refactor": ("update the feature plan, refine the feature spec", "existing agents/features/*.md referenced in the prompt"),
+    "feature-roadmap": ("turn this feature into a roadmap, generate the implementation roadmap", "existing feature plan without linked roadmap"),
+    "fix-ci": ("CI is failing, fix the GitHub Actions errors, the pipeline is red", "open PR with failing checks"),
+    "fix-pr-bot-comments": ("address the Copilot/Greptile comments, fix the bot review feedback", "open PR with bot review comments unresolved"),
+    "fix-pr-comments": ("fix all PR review comments, resolve the review feedback", "open PR with unresolved comments (bot + human)"),
+    "fix-pr-developer-comments": ("fix the human reviewer comments, address the developer feedback", "open PR with unresolved human-reviewer comments"),
+    "fix-seeder": ("the seeder is broken, foreign key errors in seeders", "seeder error output or recent edits in database/seeders/"),
+    "implement-ticket": ("implement this ticket, setze ticket X um, build PROJ-123", "ticket key matching [A-Z]+-[0-9]+ in branch name or prompt"),
+    "jira-ticket": ("implement the ticket on this branch, work on the Jira ticket from the branch", "branch name matching feat/PROJ-123-* or similar"),
+    "memory-add": ("remember this for later, add this to engineering memory, capture this learning", "post-incident or post-decision conversation"),
+    "module-create": ("create a new module, scaffold a module for X", "prompt mentions a new domain area without an existing module"),
+    "module-explore": ("show me the X module, load the module context", "existing Modules/<Name>/ referenced in the prompt"),
+    "optimize-agents": ("audit agent infrastructure, tune the agent setup", "maintainer working on .augment/ files"),
+    "optimize-skills": ("audit my skills, find duplicate skills", "maintainer working on .augment/skills/ files"),
+    "override-create": ("override this skill for the project, customize this rule locally", "prompt names a shared skill/rule needing project-specific behavior"),
+    "override-manage": ("review my overrides, update the project overrides", "existing entries under agents/overrides/"),
+    "prepare-for-review": ("get this branch ready for review, rebase and prep for PR", "branch behind base or part of a PR chain"),
+    "project-analyze": ("analyze the project structure, do a full project audit", "new project or after a major refactor"),
+    "project-health": ("check project health, what's the state of my docs and modules", "routine health check, no destructive intent"),
+    "quality-fix": ("fix the quality errors, run PHPStan and fix issues, fix code style", "PHPStan/Rector/ECS output in recent tool results"),
+    "refine-ticket": ("refine PROJ-123, tighten the acceptance criteria, is this ticket clear", "ticket key in prompt with vague acceptance criteria"),
+    "review-changes": ("self-review my changes, judge this diff before PR", "uncommitted or staged changes pre-PR"),
+    "review-routing": ("who should review this, suggest reviewers for this PR", "PR open without assigned reviewers"),
+    "roadmap-create": ("create a roadmap for X, plan this work as a roadmap", "multi-phase work without an existing agents/roadmaps/*.md"),
+    "roadmap-execute": ("execute the roadmap, work through the roadmap step by step", "existing agents/roadmaps/*.md referenced in the prompt"),
+    "rule-compliance-audit": ("audit my rules, check rule trigger quality", "maintainer working on .augment/rules/ files"),
+    "tests-create": ("write tests for these changes, add tests for this branch", "code changes on the branch without matching test changes"),
+    "tests-execute": ("run the tests, execute the test suite", "code changes pending verification"),
+    "threat-model": ("threat model this change, what could go wrong security-wise", "changes touching auth, webhooks, uploads, secrets, or public endpoints"),
+    "update-form-request-messages": ("sync the form request messages, update the validation messages", "edits to app/Http/Requests/*.php referencing rules without messages"),
+    "upstream-contribute": ("contribute this back to agent-config, upstream this learning", "project-local skill/rule that fits the shared package"),
+    "work": ("build this, implement this, drive this end-to-end", "free-form prompt without a ticket key"),
+}
+
+FRONTMATTER_RE = re.compile(r"^(---\n)(.*?)(\n---\n)", re.DOTALL)
+
+
+def build_block(name: str) -> str:
+    if name in INELIGIBLE:
+        rationale = INELIGIBLE[name].replace('"', '\\"')
+        return f'suggestion:\n  eligible: false\n  rationale: "{rationale}"'
+    if name in ELIGIBLE:
+        td, tc = ELIGIBLE[name]
+        td_e = td.replace('"', '\\"')
+        tc_e = tc.replace('"', '\\"')
+        return (f'suggestion:\n  eligible: true\n'
+                f'  trigger_description: "{td_e}"\n'
+                f'  trigger_context: "{tc_e}"')
+    raise SystemExit(f"command not classified: {name}")
+
+
+def migrate_one(path: Path) -> str:
+    name = path.stem
+    text = path.read_text(encoding="utf-8")
+    if "\nsuggestion:" in text.split("\n---\n", 1)[0]:
+        return "skip"
+    m = FRONTMATTER_RE.search(text)
+    if not m:
+        return "no-frontmatter"
+    body = m.group(2)
+    block = build_block(name)
+    new_body = body.rstrip() + "\n" + block
+    new_text = text[: m.start()] + m.group(1) + new_body + m.group(3) + text[m.end():]
+    path.write_text(new_text, encoding="utf-8")
+    return "ok"
+
+
+def main() -> int:
+    files = sorted(COMMANDS_DIR.glob("*.md"))
+    counts = {"ok": 0, "skip": 0, "no-frontmatter": 0}
+    for f in files:
+        status = migrate_one(f)
+        counts[status] += 1
+    print(f"migrated {counts['ok']}, skipped {counts['skip']}, "
+          f"no-frontmatter {counts['no-frontmatter']}, total {len(files)}")
+    expected = len(INELIGIBLE) + len(ELIGIBLE)
+    if len(files) != expected:
+        print(f"WARNING: file count {len(files)} != table count {expected}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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
 

package/scripts/schemas/command.schema.json

@@ -27,6 +27,47 @@
         "type": "string",
         "pattern": "^[a-z][a-z0-9-]*$"
       }
+    },
+    "suggestion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["eligible"],
+      "description": "Context-aware command-suggestion metadata. The suggestion layer is read-only and never auto-executes; see road-to-context-aware-command-suggestion.",
+      "properties": {
+        "eligible": {
+          "type": "boolean",
+          "description": "true → suggestion layer may surface this command; false → never suggest (still works when typed explicitly)."
+        },
+        "rationale": {
+          "type": "string",
+          "minLength": 0,
+          "maxLength": 240,
+          "description": "Why the command is ineligible. Required when eligible: false (enforced by linter)."
+        },
+        "trigger_description": {
+          "type": "string",
+          "minLength": 0,
+          "maxLength": 240,
+          "description": "Natural-language pattern trigger. Required when eligible: true (enforced by linter)."
+        },
+        "trigger_context": {
+          "type": "string",
+          "minLength": 0,
+          "maxLength": 240,
+          "description": "Concrete signal trigger (branch name, file pattern, recent tool output). Required when eligible: true (enforced by linter)."
+        },
+        "confidence_floor": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Optional per-command override of the global confidence floor (0.0–1.0). Defaults to settings."
+        },
+        "cooldown": {
+          "type": "string",
+          "minLength": 0,
+          "maxLength": 16,
+          "description": "Optional per-command override of the global cooldown duration (e.g. '10m'). Defaults to settings."
+        }
+      }
     }
   }
 }