recx-cli 0.0.3__tar.gz → 0.0.4__tar.gz

{recx_cli-0.0.3 → recx_cli-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: recx-cli
-Version: 0.0.3
+Version: 0.0.4
 Summary: Validator for RECX.yaml manifests: the recx check command.
 Project-URL: Homepage, https://github.com/jbmv/recx
 Project-URL: Repository, https://github.com/jbmv/recx

{recx_cli-0.0.3 → recx_cli-0.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "recx-cli"
-version = "0.0.3"
+version = "0.0.4"
 description = "Validator for RECX.yaml manifests: the recx check command."
 readme = "README.md"
 requires-python = ">=3.10"

{recx_cli-0.0.3 → recx_cli-0.0.4}/src/recx_cli/cli.py

@@ -76,15 +76,22 @@ def build_parser() -> argparse.ArgumentParser:
         "RECX_STOP_HOOK=block (default) blocks the stop while RECX.yaml is invalid, "
         "warn only gives feedback, off does nothing.",
     )
+    hook_sub.add_parser(
+        "session-start",
+        help="SessionStart hook: record HEAD so the Stop hook can remind about manifest drift",
+        description="Read Claude Code's SessionStart hook JSON on stdin and record the "
+        "repository's HEAD for the session. Always exits 0 with no output. "
+        "RECX_DRIFT_REMINDER=off or RECX_STOP_HOOK=off does nothing.",
+    )
     return parser
 
 
 def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
     if args.command == "hook":
-        from recx_cli.hook import stop
+        from recx_cli.hook import session_start, stop
 
-        return stop()
+        return session_start() if args.hook_command == "session-start" else stop()
     if args.command == "evidence":
         return evidence(args.path, args.list, args.only)
     target = Path(args.path)

recx_cli-0.0.4/src/recx_cli/drift.py

@@ -0,0 +1,178 @@
+"""Drift reminder: a manifest can be valid and stale.
+
+`recx hook session-start` records the repository's HEAD for the session.
+`recx hook stop` then asks which modules have changed files since, and, when
+RECX.yaml is not among them, reminds once per set of modules. The reminder is
+only ever feedback, never a block. Callers swallow every exception raised here.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+
+from recx_cli.check import parse
+
+MANIFEST = "RECX.yaml"
+SKILL = "recx:manifest"
+_HEAD = re.compile(r"[0-9a-fA-F]{7,64}")
+_SAFE_ID = re.compile(r"[A-Za-z0-9_-]{1,128}")
+
+
+def enabled() -> bool:
+    return os.environ.get("RECX_DRIFT_REMINDER", "").strip().lower() != "off"
+
+
+def state_dir() -> Path:
+    plugin_data = os.environ.get("CLAUDE_PLUGIN_DATA")
+    if plugin_data:
+        return Path(plugin_data)
+    base = os.environ.get("XDG_STATE_HOME") or str(Path.home() / ".local" / "state")
+    return Path(base) / "recx"
+
+
+def _state_file(session_id: str) -> Path | None:
+    if not isinstance(session_id, str) or not _SAFE_ID.fullmatch(session_id):
+        return None
+    return state_dir() / f"{session_id}.json"
+
+
+def read_state(session_id: str) -> dict:
+    """The session's state, or {} when absent, unreadable or corrupt."""
+    try:
+        path = _state_file(session_id)
+        if path is None:
+            return {}
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            return {}
+        state: dict = {}
+        head = data.get("head")
+        if isinstance(head, str) and _HEAD.fullmatch(head):
+            state["head"] = head
+        reminded = data.get("reminded")
+        if isinstance(reminded, list):
+            state["reminded"] = [m for m in reminded if isinstance(m, str)]
+        return state
+    except Exception:  # noqa: BLE001 - a bad state file is ignored
+        return {}
+
+
+def write_state(session_id: str, state: dict) -> None:
+    path = _state_file(session_id)
+    if path is None:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=".tmp-", suffix=".json")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(state, fh)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _git(top: Path, *args: str) -> str:
+    out = subprocess.run(
+        ["git", "-C", str(top), *args], capture_output=True, text=True, timeout=20, check=True
+    )
+    return out.stdout
+
+
+def head_of(top: Path) -> str | None:
+    value = _git(top, "rev-parse", "HEAD").strip()
+    return value if _HEAD.fullmatch(value) else None
+
+
+STATE_MAX_AGE_DAYS = 30
+
+
+def prune_state(max_age_days: int = STATE_MAX_AGE_DAYS) -> None:
+    """Delete session state files older than max_age_days; one is written per session."""
+    try:
+        cutoff = time.time() - max_age_days * 86400
+        for path in state_dir().glob("*.json"):
+            try:
+                if path.stat().st_mtime < cutoff:
+                    path.unlink()
+            except OSError:
+                continue
+    except OSError:
+        pass
+
+
+def session_start(session_id: str, top: Path) -> None:
+    """Record HEAD for the session. Skips when there is no manifest or the reminder is off."""
+    if not enabled() or not (top / MANIFEST).is_file():
+        return
+    prune_state()
+    head = head_of(top)
+    if head:
+        write_state(session_id, {"head": head, "reminded": []})
+
+
+def changed_files(top: Path, head: str | None) -> set[str]:
+    files: set[str] = set()
+    for base in [head, "HEAD"] if head else ["HEAD"]:
+        try:
+            files.update(_git(top, "diff", "--name-only", "-z", base, "--").split("\0"))
+            break
+        except (OSError, subprocess.SubprocessError):
+            continue
+    files.update(_git(top, "ls-files", "--others", "--exclude-standard", "-z").split("\0"))
+    files.discard("")
+    return files
+
+
+def affected_modules(manifest: Path, files: set[str]) -> list[str]:
+    data = parse(manifest.read_text(encoding="utf-8"))
+    modules = data.get("modules") if isinstance(data, dict) else None
+    found: list[str] = []
+    for mod in modules if isinstance(modules, list) else []:
+        if not isinstance(mod, dict):
+            continue
+        mid, path = mod.get("id"), mod.get("path")
+        if not isinstance(mid, str) or not isinstance(path, str):
+            continue
+        if path.endswith("/"):
+            hit = any(f.startswith(path) for f in files)
+        else:
+            hit = path in files
+        if hit and mid not in found:
+            found.append(mid)
+    return found
+
+
+def reminder(session_id: str | None, top: Path) -> str | None:
+    """The reminder text to emit now, or None. Records what it reminded about."""
+    if not enabled():
+        return None
+    state = read_state(session_id) if session_id else {}
+    files = changed_files(top, state.get("head"))
+    if MANIFEST in files:
+        return None
+    affected = affected_modules(top / MANIFEST, files)
+    already = set(state.get("reminded", []))
+    if not affected or set(affected) <= already:
+        return None
+    if session_id:
+        try:
+            write_state(session_id, {**state, "reminded": sorted(already | set(affected))})
+        except Exception:  # noqa: BLE001 - failing to record must not lose the reminder
+            pass
+    names = ", ".join(affected)
+    return (
+        f"Reminder, not an error: files under these {MANIFEST} modules changed this session "
+        f"while {MANIFEST} did not: {names}. Check whether the manifest still describes them, "
+        f"using the {SKILL} skill, and update it if it does not. If it is still accurate, "
+        f"nothing needs doing."
+    )

{recx_cli-0.0.3 → recx_cli-0.0.4}/src/recx_cli/hook.py

@@ -13,6 +13,7 @@ import subprocess
 import sys
 from pathlib import Path
 
+from recx_cli import drift
 from recx_cli.check import Unreadable, check_file, format_problem
 
 MANIFEST = "RECX.yaml"
@@ -41,44 +42,89 @@ def _manifest_dir(cwd: str) -> Path:
     return start
 
 
-def _run() -> None:
-    if _mode() == "off":
-        return
+def _read_event() -> tuple[dict, Path] | None:
     raw = sys.stdin.read()
     if not raw.strip():
-        return
+        return None
     event = json.loads(raw)
     if not isinstance(event, dict):
-        return
+        return None
     cwd = event.get("cwd")
     if not isinstance(cwd, str) or not cwd:
-        return
-    manifest = _manifest_dir(cwd) / MANIFEST
+        return None
+    return event, _manifest_dir(cwd)
+
+
+def _validity(event: dict, top: Path) -> tuple[bool, str | None]:
+    """(manifest is valid, output to print). Knows nothing about drift."""
+    manifest = top / MANIFEST
     if not manifest.is_file():
-        return
+        return False, None
     try:
         problems = check_file(manifest, repo=True)
     except Unreadable:
-        return
+        return False, None
     if not problems:
-        return
+        return True, None
     lines = "\n".join(format_problem(MANIFEST, p) for p in problems)
     if _mode() == "block" and event.get("stop_hook_active") is not True:
         reason = (
             f"{MANIFEST} is invalid. Fix every problem below, using the {SKILL} skill, "
             f"then check it with `recx check` (or `uvx --from recx-cli recx check`):\n{lines}"
         )
-        print(json.dumps({"decision": "block", "reason": reason}))
-    else:
-        still = " still" if event.get("stop_hook_active") is True else ""
-        context = (
-            f"{MANIFEST} is{still} invalid. The {SKILL} skill explains how to fix it:\n{lines}"
-        )
-        print(
-            json.dumps(
-                {"hookSpecificOutput": {"hookEventName": "Stop", "additionalContext": context}}
-            )
-        )
+        return False, json.dumps({"decision": "block", "reason": reason})
+    still = " still" if event.get("stop_hook_active") is True else ""
+    context = f"{MANIFEST} is{still} invalid. The {SKILL} skill explains how to fix it:\n{lines}"
+    return False, json.dumps(
+        {"hookSpecificOutput": {"hookEventName": "Stop", "additionalContext": context}}
+    )
+
+
+def _drift(event: dict, top: Path) -> str | None:
+    try:
+        session = event.get("session_id")
+        text = drift.reminder(session if isinstance(session, str) else None, top)
+    except BaseException:  # noqa: BLE001 - the drift path must never block or raise
+        return None
+    if text is None:
+        return None
+    return json.dumps({"hookSpecificOutput": {"hookEventName": "Stop", "additionalContext": text}})
+
+
+def _run() -> None:
+    if _mode() == "off":
+        return
+    parsed = _read_event()
+    if parsed is None:
+        return
+    event, top = parsed
+    valid, output = _validity(event, top)
+    if output is not None:
+        print(output)
+    elif valid:
+        extra = _drift(event, top)
+        if extra is not None:
+            print(extra)
+
+
+def _session_start() -> None:
+    if _mode() == "off" or not drift.enabled():
+        return
+    parsed = _read_event()
+    if parsed is None:
+        return
+    event, top = parsed
+    session = event.get("session_id")
+    if isinstance(session, str):
+        drift.session_start(session, top)
+
+
+def session_start() -> int:
+    try:
+        _session_start()
+    except BaseException:  # noqa: BLE001 - a hook failure must not block the session
+        pass
+    return 0
 
 
 def stop() -> int:

recx_cli-0.0.4/tests/test_drift.py

@@ -0,0 +1,424 @@
+import io
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from recx_cli import drift, hook
+from recx_cli.cli import main
+
+ROOT = Path(__file__).resolve().parents[1]
+STOP_SCRIPT = ROOT / "plugin" / "scripts" / "stop-hook.sh"
+START_SCRIPT = ROOT / "plugin" / "scripts" / "session-start-hook.sh"
+
+MANIFEST = """recx: "0.1"
+name: example
+summary: An example project.
+license: MIT
+status: experimental
+capabilities:
+  - do one thing
+modules:
+  - id: lib
+    path: src/lib/
+    summary: The library.
+    interface:
+      type: library
+      entrypoints:
+        - "import lib"
+    extract:
+      method: copy
+  - id: tool
+    path: tool.py
+    summary: The tool.
+    interface:
+      type: cli
+      entrypoints:
+        - "python tool.py"
+    extract:
+      method: copy
+"""
+INVALID = MANIFEST.replace("status: experimental\n", "status: bogus\n")
+GIT_ENV = {
+    "GIT_AUTHOR_NAME": "t",
+    "GIT_AUTHOR_EMAIL": "t@example.com",
+    "GIT_COMMITTER_NAME": "t",
+    "GIT_COMMITTER_EMAIL": "t@example.com",
+}
+
+
+@pytest.fixture(autouse=True)
+def _env(monkeypatch, tmp_path):
+    for k in ("RECX_STOP_HOOK", "RECX_DRIFT_REMINDER"):
+        monkeypatch.delenv(k, raising=False)
+    monkeypatch.setenv("CLAUDE_PLUGIN_DATA", str(tmp_path / "data"))
+    for k, v in GIT_ENV.items():
+        monkeypatch.setenv(k, v)
+
+
+def git(repo, *args):
+    return subprocess.run(["git", "-C", str(repo), *args], check=True, capture_output=True, text=True).stdout
+
+
+@pytest.fixture
+def repo(tmp_path):
+    r = tmp_path / "repo"
+    (r / "src" / "lib").mkdir(parents=True)
+    (r / "src" / "lib" / "a.py").write_text("a = 1\n")
+    (r / "tool.py").write_text("print(1)\n")
+    (r / "RECX.yaml").write_text(MANIFEST)
+    subprocess.run(["git", "init", "-q", str(r)], check=True)
+    git(r, "add", "-A")
+    git(r, "commit", "-qm", "init")
+    return r
+
+
+def run(capsys, monkeypatch, sub, repo, session="s1", **kw):
+    ev = {"session_id": session, "cwd": str(repo), "stop_hook_active": False, **kw}
+    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps(ev)))
+    code = main(["hook", sub])
+    return code, capsys.readouterr().out
+
+
+def start(capsys, monkeypatch, repo, **kw):
+    assert run(capsys, monkeypatch, "session-start", repo, **kw) == (0, "")
+
+
+def stop(capsys, monkeypatch, repo, **kw):
+    return run(capsys, monkeypatch, "stop", repo, **kw)
+
+
+def state_file(tmp_path, session="s1"):
+    return tmp_path / "data" / f"{session}.json"
+
+
+def edit_lib(repo):
+    (repo / "src" / "lib" / "a.py").write_text("a = 2\n")
+
+
+def reminder_of(out):
+    data = json.loads(out)
+    assert "decision" not in data
+    spec = data["hookSpecificOutput"]
+    assert spec["hookEventName"] == "Stop"
+    return spec["additionalContext"]
+
+
+# -- session-start ---------------------------------------------------------
+
+
+def test_session_start_records_head(capsys, monkeypatch, repo, tmp_path):
+    start(capsys, monkeypatch, repo)
+    state = json.loads(state_file(tmp_path).read_text())
+    assert state["head"] == git(repo, "rev-parse", "HEAD").strip()
+
+
+def test_session_start_default_state_dir(capsys, monkeypatch, repo, tmp_path):
+    monkeypatch.delenv("CLAUDE_PLUGIN_DATA")
+    monkeypatch.setenv("XDG_STATE_HOME", str(tmp_path / "xdg"))
+    start(capsys, monkeypatch, repo)
+    assert (tmp_path / "xdg" / "recx" / "s1.json").is_file()
+
+
+def test_session_start_skips_without_manifest(capsys, monkeypatch, repo, tmp_path):
+    (repo / "RECX.yaml").unlink()
+    start(capsys, monkeypatch, repo)
+    assert not (tmp_path / "data").exists()
+
+
+@pytest.mark.parametrize("var", ["RECX_DRIFT_REMINDER", "RECX_STOP_HOOK"])
+def test_session_start_skips_when_off(capsys, monkeypatch, repo, tmp_path, var):
+    monkeypatch.setenv(var, "off")
+    start(capsys, monkeypatch, repo)
+    assert not (tmp_path / "data").exists()
+
+
+@pytest.mark.parametrize("stdin", ["", "{nope", "[]", '{"cwd": 3}', '{"session_id": "x"}'])
+def test_session_start_bad_input_is_silent(capsys, monkeypatch, stdin):
+    monkeypatch.setattr(sys, "stdin", io.StringIO(stdin))
+    assert main(["hook", "session-start"]) == 0
+    assert capsys.readouterr().out == ""
+
+
+def test_session_start_unsafe_session_id_writes_nothing(capsys, monkeypatch, repo, tmp_path):
+    start(capsys, monkeypatch, repo, session="../evil")
+    assert not (tmp_path / "data").exists()
+
+
+def test_session_start_outside_git_is_silent(capsys, monkeypatch, tmp_path):
+    d = tmp_path / "plain"
+    d.mkdir()
+    (d / "RECX.yaml").write_text(MANIFEST)
+    start(capsys, monkeypatch, d)
+
+
+# -- stop: the reminder ----------------------------------------------------
+
+
+def test_uncommitted_change_in_module_dir_reminds(capsys, monkeypatch, repo):
+    start(capsys, monkeypatch, repo)
+    edit_lib(repo)
+    code, out = stop(capsys, monkeypatch, repo)
+    text = reminder_of(out)
+    assert code == 0 and "lib" in text and "tool" not in text.split(":")[-1]
+    assert "recx:manifest" in text and "not an error" in text
+
+
+def test_file_module_path_matches_exactly(capsys, monkeypatch, repo):
+    start(capsys, monkeypatch, repo)
+    (repo / "tool.py").write_text("print(2)\n")
+    text = reminder_of(stop(capsys, monkeypatch, repo)[1])
+    assert text.rstrip(".").split("did not: ")[1].split(".")[0] == "tool"
+
+
+def test_sibling_with_shared_prefix_is_not_under_module(capsys, monkeypatch, repo):
+    start(capsys, monkeypatch, repo)
+    (repo / "src" / "library.py").write_text("x = 1\n")
+    (repo / "tool.py.bak").write_text("x\n")
+    assert stop(capsys, monkeypatch, repo) == (0, "")
+
+
+def test_untracked_file_under_module_reminds(capsys, monkeypatch, repo):
+    start(capsys, monkeypatch, repo)
+    (repo / "src" / "lib" / "new.py").write_text("b = 1\n")
+    assert "lib" in reminder_of(stop(capsys, monkeypatch, repo)[1])
+
+
+def test_commits_since_recorded_head_count(capsys, monkeypatch, repo):
+    start(capsys, monkeypatch, repo)
+    edit_lib(repo)
+    git(repo, "commit", "-qam", "change lib")
+    assert git(repo, "status", "--porcelain") == ""
+    assert "lib" in reminder_of(stop(capsys, monkeypatch, repo)[1])
+
+
+def test_without_recorded_head_only_uncommitted_counts(capsys, monkeypatch, repo):
+    edit_lib(repo)
+    git(repo, "commit", "-qam", "committed before, no record")
+    assert stop(capsys, monkeypatch, repo) == (0, "")
+    (repo / "tool.py").write_text("print(3)\n")
+    assert "tool" in reminder_of(stop(capsys, monkeypatch, repo)[1])
+
+
+def test_corrupt_state_is_ignored_like_no_record(capsys, monkeypatch, repo, tmp_path):
+    state_file(tmp_path).parent.mkdir(parents=True)
+    state_file(tmp_path).write_text("{corrupt")
+    (repo / "tool.py").write_text("print(3)\n")
+    assert "tool" in reminder_of(stop(capsys, monkeypatch, repo)[1])
+
+
+def test_manifest_changed_means_no_reminder(capsys, monkeypatch, repo):
+    start(capsys, monkeypatch, repo)
+    edit_lib(repo)
+    (repo / "RECX.yaml").write_text(MANIFEST + "tags: [x]\n")
+    assert stop(capsys, monkeypatch, repo) == (0, "")
+
+
+def test_no_changes_no_reminder(capsys, monkeypatch, repo):
+    start(capsys, monkeypatch, repo)
+    assert stop(capsys, monkeypatch, repo) == (0, "")
+
+
+def test_reminds_once_then_only_when_set_grows(capsys, monkeypatch, repo):
+    start(capsys, monkeypatch, repo)
+    edit_lib(repo)
+    assert "lib" in reminder_of(stop(capsys, monkeypatch, repo)[1])
+    assert stop(capsys, monkeypatch, repo) == (0, "")
+    assert stop(capsys, monkeypatch, repo) == (0, "")
+    (repo / "tool.py").write_text("print(4)\n")
+    text = reminder_of(stop(capsys, monkeypatch, repo)[1])
+    assert "lib" in text and "tool" in text
+    assert stop(capsys, monkeypatch, repo) == (0, "")
+
+
+def test_other_session_is_reminded_separately(capsys, monkeypatch, repo):
+    start(capsys, monkeypatch, repo, session="a")
+    start(capsys, monkeypatch, repo, session="b")
+    edit_lib(repo)
+    assert reminder_of(stop(capsys, monkeypatch, repo, session="a")[1])
+    assert reminder_of(stop(capsys, monkeypatch, repo, session="b")[1])
+
+
+def test_reminder_keeps_recorded_head(capsys, monkeypatch, repo, tmp_path):
+    start(capsys, monkeypatch, repo)
+    before = json.loads(state_file(tmp_path).read_text())["head"]
+    edit_lib(repo)
+    stop(capsys, monkeypatch, repo)
+    state = json.loads(state_file(tmp_path).read_text())
+    assert state["head"] == before and state["reminded"] == ["lib"]
+
+
+# -- switches and validity -------------------------------------------------
+
+
+def test_drift_off_silences_reminder_only(capsys, monkeypatch, repo):
+    start(capsys, monkeypatch, repo)
+    edit_lib(repo)
+    monkeypatch.setenv("RECX_DRIFT_REMINDER", "off")
+    assert stop(capsys, monkeypatch, repo) == (0, "")
+    (repo / "RECX.yaml").write_text(INVALID)
+    out = stop(capsys, monkeypatch, repo)[1]
+    assert json.loads(out)["decision"] == "block"
+
+
+def test_stop_hook_off_disables_everything(capsys, monkeypatch, repo):
+    start(capsys, monkeypatch, repo)
+    edit_lib(repo)
+    monkeypatch.setenv("RECX_STOP_HOOK", "off")
+    assert stop(capsys, monkeypatch, repo) == (0, "")
+
+
+@pytest.mark.parametrize("mode", ["block", "warn"])
+def test_invalid_manifest_gets_only_validity_output(capsys, monkeypatch, repo, mode):
+    start(capsys, monkeypatch, repo)
+    edit_lib(repo)
+    (repo / "RECX.yaml").write_text(INVALID)
+    monkeypatch.setenv("RECX_STOP_HOOK", mode)
+    code, out = stop(capsys, monkeypatch, repo)
+    assert code == 0 and len(out.strip().splitlines()) == 1
+    data = json.loads(out)
+    if mode == "block":
+        assert data["decision"] == "block"
+    else:
+        assert "invalid" in data["hookSpecificOutput"]["additionalContext"]
+    assert "Reminder" not in out
+
+
+def test_invalid_manifest_with_active_stop_gets_no_reminder(capsys, monkeypatch, repo):
+    start(capsys, monkeypatch, repo)
+    edit_lib(repo)
+    (repo / "RECX.yaml").write_text(INVALID)
+    out = stop(capsys, monkeypatch, repo, stop_hook_active=True)[1]
+    assert "Reminder" not in out and "invalid" in out
+
+
+# -- failure isolation -----------------------------------------------------
+
+
+def test_no_git_never_blocks(capsys, monkeypatch, repo):
+    start(capsys, monkeypatch, repo)
+    edit_lib(repo)
+    monkeypatch.setenv("PATH", str(repo))
+    assert stop(capsys, monkeypatch, repo) == (0, "")
+
+
+def test_non_git_directory_is_silent(capsys, monkeypatch, tmp_path):
+    d = tmp_path / "plain"
+    (d / "src" / "lib").mkdir(parents=True)
+    (d / "tool.py").write_text("x\n")
+    (d / "RECX.yaml").write_text(MANIFEST)
+    assert stop(capsys, monkeypatch, d) == (0, "")
+
+
+def test_drift_exception_does_not_alter_validity_output(capsys, monkeypatch, repo):
+    def boom(*a, **k):
+        raise RuntimeError("boom")
+
+    monkeypatch.setattr(drift, "reminder", boom)
+    assert stop(capsys, monkeypatch, repo) == (0, "")
+    (repo / "RECX.yaml").write_text(INVALID)
+    assert json.loads(stop(capsys, monkeypatch, repo)[1])["decision"] == "block"
+
+
+def test_unwritable_state_dir_still_reminds(capsys, monkeypatch, repo, tmp_path):
+    start(capsys, monkeypatch, repo)
+    shutil_target = tmp_path / "data"
+    for p in shutil_target.iterdir():
+        p.unlink()
+    shutil_target.rmdir()
+    shutil_target.write_text("a file, not a directory")
+    edit_lib(repo)
+    assert "lib" in reminder_of(stop(capsys, monkeypatch, repo)[1])
+
+
+def test_missing_state_dir_is_fine(capsys, monkeypatch, repo):
+    edit_lib(repo)
+    assert "lib" in reminder_of(stop(capsys, monkeypatch, repo)[1])
+
+
+def test_unknown_recorded_head_falls_back_to_working_tree(capsys, monkeypatch, repo, tmp_path):
+    state_file(tmp_path).parent.mkdir(parents=True)
+    state_file(tmp_path).write_text(json.dumps({"head": "deadbeef" * 5, "reminded": []}))
+    edit_lib(repo)
+    assert "lib" in reminder_of(stop(capsys, monkeypatch, repo)[1])
+
+
+def test_hook_module_exports(monkeypatch):
+    assert callable(hook.session_start) and callable(hook.stop)
+
+
+# -- scripts ---------------------------------------------------------------
+
+
+def test_scripts_are_executable_in_git():
+    out = subprocess.run(
+        ["git", "ls-files", "-s", "plugin/scripts"], cwd=ROOT, capture_output=True, text=True
+    ).stdout
+    modes = {line.split()[-1]: line.split()[0] for line in out.splitlines()}
+    assert modes["plugin/scripts/session-start-hook.sh"] == "100755"
+    assert modes["plugin/scripts/stop-hook.sh"] == "100755"
+
+
+def test_hooks_json_registers_session_start():
+    data = json.loads((ROOT / "plugin" / "hooks" / "hooks.json").read_text())
+    cmd = data["hooks"]["SessionStart"][0]["hooks"][0]["command"]
+    assert cmd == '"${CLAUDE_PLUGIN_ROOT}"/scripts/session-start-hook.sh'
+
+
+def test_scripts_require_0_0_4():
+    for script in (START_SCRIPT, STOP_SCRIPT):
+        assert "recx-cli>=0.0.4" in script.read_text()
+
+
+def sh(script, stdin, env):
+    return subprocess.run(["/bin/sh", str(script)], input=stdin, capture_output=True, text=True, env=env)
+
+
+def test_scripts_end_to_end(repo, tmp_path):
+    recx_dir = Path(sys.executable).parent
+    assert (recx_dir / "recx").exists()
+    env = {k: v for k, v in os.environ.items() if k not in ("VIRTUAL_ENV", "RECX_STOP_HOOK", "RECX_DRIFT_REMINDER")}
+    env["PATH"] = f"{recx_dir}{os.pathsep}{env['PATH']}"
+    env["CLAUDE_PLUGIN_DATA"] = str(tmp_path / "data")
+    env.update(GIT_ENV)
+    ev = json.dumps({"session_id": "e2e", "cwd": str(repo), "stop_hook_active": False})
+
+    r = sh(START_SCRIPT, ev, env)
+    assert (r.returncode, r.stdout) == (0, "")
+    assert json.loads((tmp_path / "data" / "e2e.json").read_text())["head"] == git(repo, "rev-parse", "HEAD").strip()
+
+    assert sh(STOP_SCRIPT, ev, env).stdout == ""
+    edit_lib(repo)
+    git(repo, "commit", "-qam", "change lib")
+    r = sh(STOP_SCRIPT, ev, env)
+    assert r.returncode == 0, r.stderr
+    assert "lib" in reminder_of(r.stdout) and "recx:manifest" in reminder_of(r.stdout)
+    assert sh(STOP_SCRIPT, ev, env).stdout == ""
+
+    env["RECX_DRIFT_REMINDER"] = "off"
+    (repo / "tool.py").write_text("print(9)\n")
+    assert sh(STOP_SCRIPT, ev, env).stdout == ""
+
+
+def test_session_start_script_is_silent_and_zero_without_recx(repo, tmp_path):
+    bindir = tmp_path / "bin"
+    bindir.mkdir()
+    env = {"PATH": str(bindir), "CLAUDE_PLUGIN_DATA": str(tmp_path / "data")}
+    r = sh(START_SCRIPT, json.dumps({"session_id": "x", "cwd": str(repo)}), env)
+    assert (r.returncode, r.stdout) == (0, "")
+
+
+def test_session_start_prunes_old_state_files(capsys, monkeypatch, tmp_path, repo):
+    data = tmp_path / "data"
+    data.mkdir(parents=True, exist_ok=True)
+    old, recent = data / "old-session.json", data / "recent-session.json"
+    for f in (old, recent):
+        f.write_text('{"head": "abcdef1", "reminded": []}')
+    month_ago = __import__("time").time() - 31 * 86400
+    os.utime(old, (month_ago, month_ago))
+    start(capsys, monkeypatch, repo)
+    assert not old.exists()
+    assert recent.exists() and state_file(tmp_path).exists()