@event4u/agent-config 4.9.0 → 5.0.0

package/scripts/bench_rtk_savings.py

@@ -0,0 +1,320 @@
+#!/usr/bin/env python3
+"""Measure rtk's token savings on a fixed corpus of verbose CLI invocations.
+
+Phase 2 Step 3 of `agents/roadmaps/road-to-readable-value-dashboard.md`.
+
+For each entry in `internal/bench/corpora/rtk/commands.yaml`:
+  1. Run the raw command, capture stdout + stderr bytes.
+  2. Run the rtk-wrapped command, capture stdout + stderr bytes.
+  3. Compute char + token deltas (chars / 4 approximation).
+  4. Record per-command result + aggregate.
+
+Output: `internal/bench/reports/rtk/<UTC>.json` + `latest.json`.
+
+Each command runs in the repo root with a 30 s timeout. Missing tools
+(`rtk` not installed, raw command not on PATH) emit `skipped: <reason>`
+entries and are excluded from the aggregate. The script never crashes —
+mirror the placeholder discipline of `render_benchmark_md.py`.
+
+Surfaces honoured per `script-writing`:
+  --quiet      suppress per-step progress (errors still print to stderr)
+  --corpus     override the default corpus path
+  --out        override the default report dir
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List
+
+try:
+    import yaml
+except ImportError:
+    yaml = None  # type: ignore[assignment]
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_CORPUS = REPO_ROOT / "internal" / "bench" / "corpora" / "rtk" / "commands.yaml"
+DEFAULT_OUT_DIR = REPO_ROOT / "internal" / "bench" / "reports" / "rtk"
+TIMEOUT_SECONDS = 30
+CHARS_PER_TOKEN = 4
+
+
+def _utc_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def _log(msg: str, quiet: bool, *, err: bool = False) -> None:
+    if err:
+        print(msg, file=sys.stderr)
+        return
+    if not quiet:
+        print(msg)
+
+
+def _run_capture(argv: List[str], cwd: Path) -> Dict[str, Any]:
+    """Run a command, return stdout+stderr bytes + exit code.
+
+    Never raises — TimeoutExpired, FileNotFoundError, OSError each
+    produce a dict marker. Bench results explicitly carry failures so
+    the aggregate can exclude them.
+    """
+    try:
+        result = subprocess.run(
+            argv,
+            cwd=str(cwd),
+            capture_output=True,
+            timeout=TIMEOUT_SECONDS,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        return {
+            "error": f"FileNotFoundError: {exc}",
+            "stdout_bytes": 0,
+            "stderr_bytes": 0,
+            "chars": 0,
+            "tokens_approx": 0,
+            "returncode": None,
+        }
+    except subprocess.TimeoutExpired:
+        return {
+            "error": f"TimeoutExpired after {TIMEOUT_SECONDS}s",
+            "stdout_bytes": 0,
+            "stderr_bytes": 0,
+            "chars": 0,
+            "tokens_approx": 0,
+            "returncode": None,
+        }
+    except OSError as exc:
+        return {
+            "error": f"OSError: {exc}",
+            "stdout_bytes": 0,
+            "stderr_bytes": 0,
+            "chars": 0,
+            "tokens_approx": 0,
+            "returncode": None,
+        }
+    stdout = result.stdout or b""
+    stderr = result.stderr or b""
+    chars = len(stdout) + len(stderr)
+    return {
+        "error": None,
+        "stdout_bytes": len(stdout),
+        "stderr_bytes": len(stderr),
+        "chars": chars,
+        "tokens_approx": chars // CHARS_PER_TOKEN,
+        "returncode": result.returncode,
+    }
+
+
+def measure_one(entry: Dict[str, Any], cwd: Path, quiet: bool) -> Dict[str, Any]:
+    """Measure one corpus entry."""
+    entry_id = entry["id"]
+    description = entry.get("description", "")
+    raw = entry["raw"]
+    rtk = entry["rtk"]
+
+    raw_cmd = raw[0] if raw else None
+    rtk_cmd = rtk[0] if rtk else None
+
+    if raw_cmd and not shutil.which(raw_cmd):
+        return {
+            "id": entry_id,
+            "description": description,
+            "skipped": f"raw command '{raw_cmd}' not on PATH",
+            "raw": None,
+            "rtk": None,
+            "delta": None,
+        }
+    if rtk_cmd and not shutil.which(rtk_cmd):
+        return {
+            "id": entry_id,
+            "description": description,
+            "skipped": f"rtk command '{rtk_cmd}' not on PATH",
+            "raw": None,
+            "rtk": None,
+            "delta": None,
+        }
+
+    _log(f"  {entry_id}: running raw …", quiet)
+    raw_result = _run_capture(raw, cwd)
+    _log(f"  {entry_id}: running rtk …", quiet)
+    rtk_result = _run_capture(rtk, cwd)
+
+    if raw_result.get("error") or rtk_result.get("error"):
+        return {
+            "id": entry_id,
+            "description": description,
+            "skipped": (
+                f"raw error: {raw_result.get('error')}; "
+                f"rtk error: {rtk_result.get('error')}"
+            ),
+            "raw": raw_result,
+            "rtk": rtk_result,
+            "delta": None,
+        }
+
+    raw_chars = raw_result["chars"]
+    rtk_chars = rtk_result["chars"]
+    chars_saved = raw_chars - rtk_chars
+    tokens_saved = chars_saved // CHARS_PER_TOKEN
+    pct_saved = (
+        (chars_saved / raw_chars * 100.0) if raw_chars > 0 else 0.0
+    )
+
+    return {
+        "id": entry_id,
+        "description": description,
+        "skipped": None,
+        "raw": raw_result,
+        "rtk": rtk_result,
+        "delta": {
+            "chars_saved": chars_saved,
+            "tokens_saved": tokens_saved,
+            "pct_saved": round(pct_saved, 3),
+        },
+    }
+
+
+def aggregate(results: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """Compute the aggregate block from per-command results."""
+    measured = [r for r in results if not r.get("skipped") and r.get("delta")]
+    if not measured:
+        return {
+            "commands_measured": 0,
+            "commands_skipped": len(results) - len(measured),
+            "total_chars_saved": 0,
+            "total_tokens_saved": 0,
+            "median_pct_saved": 0.0,
+            "tokens_saved_per_request": 0,
+        }
+    chars_saved_total = sum(r["delta"]["chars_saved"] for r in measured)
+    tokens_saved_total = sum(r["delta"]["tokens_saved"] for r in measured)
+    pcts = sorted(r["delta"]["pct_saved"] for r in measured)
+    median_pct = pcts[len(pcts) // 2]
+    # Per-request approximation: average tokens saved across the corpus.
+    # A real agent invocation typically pipes ONE such command into the
+    # context per request — so the per-request saving is the mean, not
+    # the sum, of the corpus.
+    per_request = tokens_saved_total // len(measured)
+    return {
+        "commands_measured": len(measured),
+        "commands_skipped": len(results) - len(measured),
+        "total_chars_saved": chars_saved_total,
+        "total_tokens_saved": tokens_saved_total,
+        "median_pct_saved": median_pct,
+        "tokens_saved_per_request": per_request,
+    }
+
+
+def run(
+    corpus_path: Path = DEFAULT_CORPUS,
+    out_dir: Path = DEFAULT_OUT_DIR,
+    quiet: bool = False,
+) -> int:
+    """Run the bench, write the report, return 0 on success."""
+    if yaml is None:
+        _log("PyYAML is required to load the rtk corpus.", quiet, err=True)
+        return 1
+    if not corpus_path.exists():
+        _log(f"corpus not found: {corpus_path}", quiet, err=True)
+        return 1
+
+    try:
+        corpus = yaml.safe_load(corpus_path.read_text()) or {}
+    except yaml.YAMLError as exc:
+        _log(f"failed to parse corpus YAML: {exc}", quiet, err=True)
+        return 1
+
+    entries = corpus.get("commands", []) or []
+    if not entries:
+        _log("corpus has no commands", quiet, err=True)
+        return 1
+
+    _log(f"rtk savings bench — {len(entries)} commands", quiet)
+    results = [measure_one(entry, REPO_ROOT, quiet) for entry in entries]
+    agg = aggregate(results)
+
+    report = {
+        "schema_version": 1,
+        "schema_id": "rtk-v1",
+        "generated_at": _utc_iso(),
+        "corpus": {
+            "id": corpus.get("corpus_id", "rtk-commands"),
+            "path": str(corpus_path.relative_to(REPO_ROOT)),
+            "command_count": len(entries),
+        },
+        "commands": results,
+        "aggregate": agg,
+        "notes": [
+            f"Tokens approximated at {CHARS_PER_TOKEN} chars / token.",
+            (
+                "tokens_saved_per_request is the per-command mean across "
+                "measured entries; assumes one CLI invocation per request."
+            ),
+            (
+                "Skipped commands carry a 'skipped' reason and are excluded "
+                "from the aggregate."
+            ),
+        ],
+    }
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    stamp = report["generated_at"].replace(":", "-")
+    timestamped = out_dir / f"{stamp}.json"
+    latest = out_dir / "latest.json"
+    payload = json.dumps(report, indent=2, ensure_ascii=False) + "\n"
+    timestamped.write_text(payload)
+    latest.write_text(payload)
+
+    _log(
+        (
+            f"rtk savings: {agg['commands_measured']}/{len(entries)} measured, "
+            f"median {agg['median_pct_saved']:.1f}% saved, "
+            f"{agg['tokens_saved_per_request']} tokens/request "
+            f"(report: {timestamped.relative_to(REPO_ROOT)})"
+        ),
+        quiet=False,  # always print the headline (one-line summary)
+    )
+    return 0
+
+
+def parse_args(argv: List[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Measure rtk's token savings on a fixed corpus of verbose CLI "
+            "invocations."
+        )
+    )
+    parser.add_argument(
+        "--corpus",
+        type=Path,
+        default=DEFAULT_CORPUS,
+        help="Path to the corpus YAML (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--out",
+        type=Path,
+        default=DEFAULT_OUT_DIR,
+        help="Output directory for reports (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress per-step progress; print one-line summary only.",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: List[str] | None = None) -> int:
+    args = parse_args(argv if argv is not None else sys.argv[1:])
+    return run(corpus_path=args.corpus, out_dir=args.out, quiet=args.quiet)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/compile_router.py

@@ -194,19 +194,33 @@ def build() -> dict:
     }
 
 
+PRETTY_PATH = OUT_PATH.with_suffix(".pretty.json")
+
+
 def main(argv: list[str]) -> int:
     out = build()
-    text = json.dumps(out, indent=2, sort_keys=False) + "\n"
+    # Default: minified (Phase 2 of road-to-value-dashboard-netto-cuts).
+    # `--pretty` writes the human-readable variant ONLY (no minified).
+    # The Python consumers in this repo (`lint_rule_budget`,
+    # `check_router`) use `json.load()` and are format-agnostic.
+    pretty_text = json.dumps(out, indent=2, sort_keys=False) + "\n"
+    minified_text = json.dumps(out, separators=(",", ":"), sort_keys=False) + "\n"
+    text = pretty_text if "--pretty" in argv else minified_text
+    target_path = PRETTY_PATH if "--pretty" in argv else OUT_PATH
     if "--check" in argv:
-        if not OUT_PATH.exists() or OUT_PATH.read_text(encoding="utf-8") != text:
+        if not OUT_PATH.exists() or OUT_PATH.read_text(encoding="utf-8") != minified_text:
             print("router.json out of date — run scripts/compile_router.py", file=sys.stderr)
             return 1
         print("✅  router.json is up to date")
         return 0
-    OUT_PATH.parent.mkdir(parents=True, exist_ok=True)
-    OUT_PATH.write_text(text, encoding="utf-8")
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    target_path.write_text(text, encoding="utf-8")
     counts = (len(out["kernel"]), len(out["tier_1"]), len(out["tier_2"]))
-    print(f"✅  router.json — kernel={counts[0]}  tier-1={counts[1]}  tier-2={counts[2]}")
+    fmt = "pretty" if "--pretty" in argv else "minified"
+    print(
+        f"✅  {target_path.name} ({fmt}) — "
+        f"kernel={counts[0]}  tier-1={counts[1]}  tier-2={counts[2]}"
+    )
     return 0
 
 

package/scripts/expected_perms.json

@@ -1,6 +1,6 @@
 {
   "$schema_version": "expected-perms/v1",
-  "$comment": "Expected POSIX modes for the global install tree. Consumed by scripts/lint_global_paths.py as an entry-gate for the migrate-to-global subcommand (road-to-global-only-install Phase 5.0 / A7). Octal modes are strings so JSON tooling never widens 0700 → 700.",
+  "$comment": "Expected POSIX modes for the global install tree. Consumed by scripts/lint_global_paths.py as a standalone perms audit (historically the entry-gate for the migrate-to-global subcommand; that command was collapsed into agent-config migrate — see docs/contracts/migrate-command.md). Octal modes are strings so JSON tooling never widens 0700 → 700.",
   "global_root": {
     "path": "~/.event4u/agent-config",
     "expected_mode": "0700",

package/scripts/first_run_gate_hook.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""First-run gate — surface the marketplace-install-but-unscaffolded shape.
+
+Phase 2 of `road-to-hooks-actually-fire-in-consumers`.
+
+When a consumer enables the plugin via `/plugin install` but never
+runs `agent-config init` (or `hooks:install --claude --regen`), the
+hooks declared in `hooks/hooks.json` fire but cannot do anything —
+their commands resolve through an `$CLAUDE_PROJECT_DIR/agent-config`
+that does not exist, or call a regenerator script that lives only in
+package source-checkouts. The user has no way to discover this.
+
+This hook runs on `session_start` only. It detects the failure shape
+and surfaces it two ways (Council R3 HIGH — stderr alone is invisible
+to the average user):
+
+1. One stderr line — Claude shows session-start hook stderr in its
+   lifecycle log; power users will see it there.
+2. A file at `$CLAUDE_PROJECT_DIR/.augment/.first-run-action-needed.md`
+   that the user discovers on the next `ls` of their tree.
+
+Setup-complete detector (Council R3 MEDIUM — prevents banner spam):
+the hook exits early without writing if the checklist passes
+(`./agent-config` symlink executable + `.augment/scripts/update_roadmap_progress.py`
+exists). Once the user runs `hooks:install --claude --regen`, the
+file written by a prior run gets cleaned up the next time this hook
+runs successfully.
+
+Contract: never blocks. Returns 0 on every path.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+
+PLUGIN_ID = "agent-config@event4u-agent-config"
+ACTION_NEEDED_FILE = ".augment/.first-run-action-needed.md"
+
+REGENERATOR_PATHS = (
+    ".augment/scripts/update_roadmap_progress.py",
+    ".agent-src/scripts/update_roadmap_progress.py",
+    ".agent-src.uncondensed/scripts/update_roadmap_progress.py",
+)
+
+ACTION_NEEDED_BODY = """# First-run action needed — `agent-config` plugin
+
+You enabled the `agent-config@event4u-agent-config` plugin via
+`/plugin install`, but your project is missing the prerequisites
+the plugin's hooks need to actually fire:
+
+- `./agent-config` symlink at the repo root (needed by every hook).
+- `.augment/scripts/update_roadmap_progress.py` (needed by the
+  roadmap-progress hook to regenerate the dashboard).
+
+Fix in one command:
+
+```bash
+./agent-config hooks:install --claude --regen
+```
+
+Or run the full installer:
+
+```bash
+./agent-config init
+```
+
+After either command, this file deletes itself on the next session
+start. If you don't want the plugin's hooks, disable it via
+`/plugin disable agent-config@event4u-agent-config` and delete
+this file manually.
+"""
+
+
+def _plugin_enabled(consumer_root: Path) -> bool:
+    """Returns True iff `.claude/settings.json` has the plugin id under
+    `enabledPlugins` with a truthy value."""
+    settings = consumer_root / ".claude" / "settings.json"
+    if not settings.is_file():
+        return False
+    try:
+        data = json.loads(settings.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    if not isinstance(data, dict):
+        return False
+    enabled = data.get("enabledPlugins")
+    if not isinstance(enabled, dict):
+        return False
+    return bool(enabled.get(PLUGIN_ID))
+
+
+def _agent_config_executable(consumer_root: Path) -> bool:
+    """`./agent-config` exists AND is executable (whether file or symlink)."""
+    p = consumer_root / "agent-config"
+    if not p.exists():
+        return False
+    return os.access(p, os.X_OK)
+
+
+def _regenerator_present(consumer_root: Path) -> bool:
+    return any((consumer_root / rel).is_file() for rel in REGENERATOR_PATHS)
+
+
+def _setup_complete(consumer_root: Path) -> bool:
+    return _agent_config_executable(consumer_root) and _regenerator_present(consumer_root)
+
+
+def _write_action_file(consumer_root: Path) -> bool:
+    """Best-effort write. Returns True on success."""
+    target = consumer_root / ACTION_NEEDED_FILE
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(ACTION_NEEDED_BODY, encoding="utf-8")
+        return True
+    except OSError as exc:
+        sys.stderr.write(
+            f"first-run-gate: could not write {target}: {exc}\n"
+        )
+        return False
+
+
+def _cleanup_action_file(consumer_root: Path) -> None:
+    """Remove the action-needed file once setup is complete. Best-effort."""
+    target = consumer_root / ACTION_NEEDED_FILE
+    if target.exists():
+        try:
+            target.unlink()
+        except OSError:
+            pass
+
+
+def run(consumer_root: Path) -> int:
+    if os.environ.get("AGENT_CONFIG_REPLAY") == "1":
+        # Fixture-driven replay must not mutate state.
+        return 0
+    if not _plugin_enabled(consumer_root):
+        # Plugin not enabled — nothing to gate on. Silent.
+        return 0
+    if _setup_complete(consumer_root):
+        # Setup checklist passes — clean up any stale action-needed file
+        # left by a prior run, then exit silently.
+        _cleanup_action_file(consumer_root)
+        return 0
+
+    # Failure shape detected. Two visible surfaces:
+    sys.stderr.write(
+        "first-run-gate: agent-config plugin is enabled but "
+        "scaffolding is missing — run `./agent-config hooks:install "
+        "--claude --regen` (details written to "
+        f"{ACTION_NEEDED_FILE})\n"
+    )
+    _write_action_file(consumer_root)
+    return 0
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--platform", default="generic")
+    return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    _ = parse_args(argv if argv is not None else sys.argv[1:])
+    # Drain stdin envelope so the dispatcher pipe contract holds.
+    try:
+        sys.stdin.read()
+    except OSError:
+        pass
+    consumer_root = Path(os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd())
+    return run(consumer_root)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/hook_manifest.yaml

@@ -45,16 +45,25 @@ concerns:
     script: scripts/minimal_safe_diff_hook.py
     args: []
     fail_closed: false
+  # Phase 2 of road-to-hooks-actually-fire-in-consumers — session_start
+  # gate that surfaces the marketplace-install-but-unscaffolded shape.
+  # Writes .augment/.first-run-action-needed.md + one stderr line so
+  # both file-browser users and lifecycle-log readers see the issue.
+  # Council R3 HIGH: stderr alone is invisible to the average user.
+  first-run-gate:
+    script: scripts/first_run_gate_hook.py
+    args: []
+    fail_closed: false
 
 platforms:
   augment:
-    session_start:    [chat-history, onboarding-gate, verify-before-complete, minimal-safe-diff]
+    session_start:    [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff]
     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, onboarding-gate, verify-before-complete, minimal-safe-diff]
+    session_start:    [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff]
     session_end:      [chat-history]
     stop:             [chat-history, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
@@ -75,7 +84,7 @@ platforms:
   # Decision matrix + upstream blockers tracked in
   # agents/settings/contexts/chat-history-platform-hooks.md § Cowork.
   cowork:
-    session_start:    [chat-history, onboarding-gate, verify-before-complete, minimal-safe-diff]
+    session_start:    [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff]
     session_end:      [chat-history]
     stop:             [chat-history, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
@@ -89,7 +98,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, onboarding-gate, verify-before-complete, minimal-safe-diff]
+    session_start:      [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff]
     session_end:        [chat-history]
     stop:               [chat-history, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
@@ -104,7 +113,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, onboarding-gate, verify-before-complete, minimal-safe-diff]
+    session_start:      [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff]
     session_end:        [chat-history]
     stop:               [chat-history, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
@@ -123,7 +132,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, onboarding-gate, verify-before-complete]
+    session_start:      [chat-history, first-run-gate, onboarding-gate, verify-before-complete]
     stop:               [chat-history, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete]
 
@@ -138,7 +147,7 @@ platforms:
   # turn-check semantics. AfterAgent fires when the agent loop ends
   # — this is our `stop` slot.
   gemini:
-    session_start:      [chat-history, onboarding-gate, verify-before-complete, minimal-safe-diff]
+    session_start:      [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff]
     session_end:        [chat-history]
     stop:               [chat-history, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]

package/scripts/hooks/dispatch_hook.py

@@ -38,6 +38,7 @@ MANIFEST_PATH = REPO_ROOT / "scripts" / "hook_manifest.yaml"
 # hooks package state_io has changed (test isolation).
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from state_io import atomic_write_json, feedback_dir, is_replay_mode  # noqa: E402
+from dispatch_issues import log_dispatch_issue, fix_hint  # noqa: E402
 
 EXIT_ALLOW = 0
 EXIT_BLOCK = 1
@@ -234,6 +235,23 @@ def _run_concern(concern: dict, envelope: dict) -> tuple[int, str, str, int]:
     cmd = [sys.executable, str(script), *(concern.get("args") or [])]
     cmd.extend(["--platform", envelope.get("platform", "generic")])
     workspace = envelope.get("workspace_root") or str(Path.cwd())
+
+    # Phase 1 of road-to-hooks-actually-fire-in-consumers: surface
+    # script-not-found via dispatch-issues.jsonl rather than silently
+    # consuming the OSError.
+    if not script.exists():
+        log_dispatch_issue(
+            workspace_root=Path(workspace),
+            hook=str(concern.get("name") or concern.get("script") or "unknown"),
+            issue="script_not_found",
+            detail=f"concern script missing on disk: {script}",
+            resolution=fix_hint(),
+        )
+        # Still return as if the concern failed — fail-open behaviour
+        # depends on the concern's `fail_closed` flag, which the
+        # dispatcher handles downstream.
+        return (3, f"{concern.get('name')}: script missing: {script}", "", 0)
+
     started = time.monotonic()
     try:
         proc = subprocess.run(
@@ -247,6 +265,15 @@ def _run_concern(concern: dict, envelope: dict) -> tuple[int, str, str, int]:
         )
     except (OSError, subprocess.TimeoutExpired) as exc:
         elapsed = int((time.monotonic() - started) * 1000)
+        # Phase 1: also log execution-failed (subprocess errors) so the
+        # never-block contract keeps a trace.
+        log_dispatch_issue(
+            workspace_root=Path(workspace),
+            hook=str(concern.get("name") or "unknown"),
+            issue="execution_failed",
+            detail=f"{type(exc).__name__}: {exc}",
+            resolution=fix_hint(),
+        )
         return (3, f"{concern.get('name')}: {exc}", "", elapsed)
     elapsed = int((time.monotonic() - started) * 1000)
     return (proc.returncode, proc.stderr or "", proc.stdout or "", elapsed)