@event4u/agent-config 4.8.0 → 5.0.0

package/scripts/hooks/dispatch_issues.py

@@ -0,0 +1,136 @@
+"""Append-only log of dispatch-time issues — Phase 1 of `road-to-hooks-actually-fire-in-consumers`.
+
+When a concern's resolver returns `None` (script missing, regenerator
+missing, `./agent-config` symlink unresolvable) the dispatcher (or the
+concern hook itself, when invoked as a subprocess) records ONE line in
+`agents/runtime/state/dispatch-issues.jsonl` so the failure is
+discoverable post-hoc instead of vanishing into the never-block
+contract.
+
+**Schema** (locked by Council R3 pre-check, 2026-05-29):
+
+    {
+      "timestamp": "<ISO-8601 UTC>",
+      "hook":      "<concern-id>",
+      "issue":     "prerequisite_missing | script_not_found | "
+                   "permission_denied | execution_failed",
+      "detail":    "<freeform one-line explanation>",
+      "resolution": "<one-line command or doc link>"
+    }
+
+**Cap:** 200 entries (council-revised from the original 50; debug
+sessions with many tool calls would have lost evidence at the old
+cap). Rotation drops the oldest line.
+
+Errors writing the log are swallowed — observability never breaks
+the agent loop.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+
+LOG_CAP = 200
+
+VALID_ISSUE = frozenset({
+    "prerequisite_missing",
+    "script_not_found",
+    "permission_denied",
+    "execution_failed",
+})
+
+
+def _utc_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds").replace(
+        "+00:00", "Z"
+    )
+
+
+def _log_path(workspace_root: Path) -> Path:
+    return Path(workspace_root) / "agents" / "runtime" / "state" / "dispatch-issues.jsonl"
+
+
+def log_dispatch_issue(
+    workspace_root: Path,
+    hook: str,
+    issue: str,
+    detail: str,
+    resolution: str,
+) -> None:
+    """Append one dispatch-issue line. Best-effort; never raises.
+
+    No-op when `AGENT_CONFIG_REPLAY=1` is set — fixture-driven replay
+    must not mutate state (contract: `docs/contracts/hook-architecture-v1.md`
+    § Replay mode).
+    """
+    if os.environ.get("AGENT_CONFIG_REPLAY") == "1":
+        return
+
+    if issue not in VALID_ISSUE:
+        # Schema violation is a bug in the caller, not a runtime
+        # failure — surface on stderr so it's noticed during dev, but
+        # do not crash.
+        sys.stderr.write(
+            f"dispatch_issues: invalid issue {issue!r} (valid: "
+            f"{sorted(VALID_ISSUE)})\n"
+        )
+        return
+
+    log = _log_path(workspace_root)
+    entry = {
+        "timestamp": _utc_iso(),
+        "hook": str(hook),
+        "issue": issue,
+        "detail": str(detail),
+        "resolution": str(resolution),
+    }
+
+    try:
+        log.parent.mkdir(parents=True, exist_ok=True)
+        # Read existing lines (cheap — bounded log).
+        existing: list[str] = []
+        if log.exists():
+            try:
+                existing = log.read_text(encoding="utf-8").splitlines()
+            except OSError:
+                existing = []
+        existing.append(json.dumps(entry, ensure_ascii=False))
+        # Cap rotation: drop the oldest entries.
+        if len(existing) > LOG_CAP:
+            existing = existing[-LOG_CAP:]
+        log.write_text("\n".join(existing) + "\n", encoding="utf-8")
+    except OSError as exc:
+        # Observability never blocks the agent.
+        sys.stderr.write(
+            f"dispatch_issues: failed to append to {log}: {exc}\n"
+        )
+
+
+def read_dispatch_issues(workspace_root: Path) -> list[dict]:
+    """Return the log as a list of dicts. Empty list when missing."""
+    log = _log_path(workspace_root)
+    if not log.exists():
+        return []
+    out: list[dict] = []
+    try:
+        for line in log.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                out.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+    except OSError:
+        return []
+    return out
+
+
+def fix_hint(workspace_root: Optional[Path] = None) -> str:
+    """Best-known fix hint string. Returned for use in `resolution` field."""
+    return "./agent-config init"

package/scripts/hooks_doctor.py

@@ -111,16 +111,41 @@ def collect(project_root: Path, manifest: dict,
             "missing": needs_trampoline and not tpath.is_file(),
         })
 
+    # Phase 1 of road-to-hooks-actually-fire-in-consumers: surface
+    # the dispatch-issues log so users see hooks that tried and failed.
+    state_root = REPO_ROOT / STATE_DIR_DEFAULT
+    issues: list[dict] = []
+    try:
+        sys.path.insert(0, str(REPO_ROOT / "scripts" / "hooks"))
+        from dispatch_issues import read_dispatch_issues  # noqa: PLC0415
+        issues = read_dispatch_issues(REPO_ROOT)[-20:]  # last 20
+    except (ImportError, OSError):
+        issues = []
+
     return {
         "schema_version": 1,
         "platforms": matrix["platforms"],
         "concerns": concerns,
         "trampolines": trampolines,
+        "dispatch_issues": issues,
     }
 
 
 def _render_table(payload: dict) -> str:
-    lines: list[str] = [hooks_status._render_table(payload), ""]
+    lines: list[str] = []
+    # Phase 1 CTA — surfaces at the TOP when issues exist, so a user
+    # reading the report can't miss it.
+    if payload.get("dispatch_issues"):
+        n = len(payload["dispatch_issues"])
+        lines.append(
+            f"⚠️  Hooks tried to fire but couldn't ({n} entry"
+            f"{'ies' if n != 1 else 'y'} in dispatch-issues.jsonl) — "
+            "run `./agent-config hooks:install --claude --regen` "
+            "(or follow the per-concern hints below)"
+        )
+        lines.append("")
+    lines.append(hooks_status._render_table(payload))
+    lines.append("")
     lines.append("Concerns")
     lines.append("-" * 60)
     for c in payload["concerns"]:
@@ -138,6 +163,20 @@ def _render_table(payload: dict) -> str:
         marker = "❌ " if t["missing"] else ("·  " if not t["required"] else "✅ ")
         suffix = "" if t["required"] else "  (not required)"
         lines.append(f"{marker}{t['platform']:<9} {t['expected']}{suffix}")
+    # Dispatch-issues detail — last 20 grouped by concern.
+    if payload.get("dispatch_issues"):
+        lines.append("")
+        lines.append("Dispatch issues (last 20)")
+        lines.append("-" * 60)
+        grouped: dict[str, list[dict]] = {}
+        for entry in payload["dispatch_issues"]:
+            grouped.setdefault(entry.get("hook", "?"), []).append(entry)
+        for hook, entries in sorted(grouped.items()):
+            lines.append(f"⚠️  {hook}: {len(entries)} issue(s)")
+            # Show the most recent reason + resolution per concern.
+            latest = entries[-1]
+            lines.append(f"    {latest.get('issue')}: {latest.get('detail')}")
+            lines.append(f"    fix → {latest.get('resolution')}")
     return "\n".join(lines)
 
 

package/scripts/install.py

@@ -3009,13 +3009,14 @@ CONSUMER_BRIDGE_MARKER_RELPATH = Path("agents") / ".event4u-bridge.yml"
 
 
 # ---------------------------------------------------------------------------
-# Phase 5.2 — migrate-to-global first-run hook
+# First-run migration hook
 # ---------------------------------------------------------------------------
 #
 # Legacy artefacts that signal a pre-ADR-020 install in the project root.
-# Same surface the ``migrate-to-global`` command detects (see
-# ``scripts/_cli/cmd_migrate_to_global.py``). Kept in sync intentionally so
-# the prompt and the migration tool agree on what counts as "legacy".
+# Same surface the unified ``migrate`` command detects (see
+# ``scripts/_cli/cmd_migrate.py`` and ``docs/contracts/migrate-command.md``).
+# Kept in sync intentionally so the prompt and the migration tool agree on
+# what counts as "legacy".
 MIGRATE_LEGACY_YAML_FILES = (".agent-settings.yml", ".agent-user.yml")
 MIGRATE_LEGACY_TOOL_DIRS = (".augment", ".claude", ".cursor")
 
@@ -3125,19 +3126,22 @@ def _detect_legacy_for_migration(project_root: Path) -> list[str]:
 
 
 def _prompt_migrate_to_global(project_root: Path, artefacts: list[str]) -> bool:
-    """Ask the user whether to run ``migrate-to-global`` now.
+    """Ask the user whether to run the unified ``migrate`` command now.
 
     Interactive TTY → ``[Y/n]`` prompt (Enter = yes). Non-interactive (CI
-    or no TTY) → auto-yes per roadmap Phase 5.2 contract. Three invalid
-    replies short-circuit to "no" (defensive, never blocks the install).
+    or no TTY) → auto-yes. Three invalid replies short-circuit to "no"
+    (defensive, never blocks the install). The function name is kept for
+    compatibility with the install flow; the legacy ``migrate-to-global``
+    command was collapsed into the unified ``migrate`` (see
+    ``docs/contracts/migrate-command.md``).
     """
     if not QUIET:
         print()
         warn("Legacy project-local artefacts detected — pre-ADR-020 layout:")
         for rel in artefacts:
             info(f"  {project_root / rel}")
-        info("ADR-020 ships consumer installs as global-only.")
-        info("`agent-config migrate-to-global` copies → verifies → moves them safely.")
+        info("The unified `agent-config migrate` sweeps these in one pass.")
+        info("The wizard recreates fresh config afterwards.")
 
     if not _is_interactive():
         if not QUIET:
@@ -3147,7 +3151,7 @@ def _prompt_migrate_to_global(project_root: Path, artefacts: list[str]) -> bool:
     attempts = 0
     while attempts < 3:
         try:
-            reply = _read_line("Run `agent-config migrate-to-global` now? [Y/n]: ")
+            reply = _read_line("Run `agent-config migrate` now? [Y/n]: ")
         except EOFError:
             return False
         if reply == "" or reply.lower() in ("y", "yes"):
@@ -3160,23 +3164,22 @@ def _prompt_migrate_to_global(project_root: Path, artefacts: list[str]) -> bool:
 
 
 def _run_migrate_to_global(project_root: Path) -> int:
-    """Invoke ``cmd_migrate_to_global._do_migrate`` against ``project_root``.
+    """Invoke the unified ``cmd_migrate`` against ``project_root``.
 
     Returns the migrator's exit code so the caller can abort the install
-    on failure. The perms gate is skipped because the install path runs
-    its own checks; surfacing two perm errors back-to-back would be
-    confusing for first-run users.
+    on failure. The function name is kept for compatibility with the
+    install flow; the legacy ``migrate-to-global`` command was collapsed
+    into the unified ``migrate`` (see ``docs/contracts/migrate-command.md``).
     """
     import importlib  # noqa: PLC0415 — local to keep startup lean.
 
     try:
-        cmd_mod = importlib.import_module("scripts._cli.cmd_migrate_to_global")
+        cmd_mod = importlib.import_module("scripts._cli.cmd_migrate")
     except ImportError as exc:
-        warn(f"migrate-to-global unavailable: {exc}")
+        warn(f"migrate unavailable: {exc}")
         return 1
 
-    install_mod = sys.modules[__name__]
-    return cmd_mod._do_migrate(project_root, force=False, install_mod=install_mod, out=sys.stdout)
+    return cmd_mod.main([], cwd=project_root, out=sys.stdout)
 
 
 def _format_global_root_for_marker(global_root: Path) -> str:
@@ -4976,9 +4979,10 @@ def main(argv: list[str]) -> int:
 
     try:
         if scope == "global":
-            # Phase 5.2 — first-run hook: when legacy artefacts live in the
-            # project tree, prompt before laying down the global surface so
-            # the user is not left with a dual-stack install.
+            # First-run hook: when legacy artefacts live in the project tree,
+            # prompt before laying down the global surface so the user is
+            # not left with a dual-stack install. Delegates to the unified
+            # `agent-config migrate` (see docs/contracts/migrate-command.md).
             artefacts = _detect_legacy_for_migration(detect_root)
             if artefacts and _prompt_migrate_to_global(detect_root, artefacts):
                 rc = _run_migrate_to_global(detect_root)