pi-dev-team 0.2.0

package/hooks/lib/stryker_invocation.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Shared predicate: does a shell command actually RUN Stryker.NET? (#2185)
+
+Both C# mutation PreToolUse gates (`mutation_testing_smoke_gate.py` and
+`stryker_xunit_shim_guard.py`) used to decide "is this a Stryker run?" with a
+bare `re.search` over the entire command string — no notion of argument
+position, quoting, or comments. Any command that merely *mentioned* the tool
+name in prose (a `gh issue create --body "..."`, a `grep`, an `echo`, a
+Python comment) was treated as an invocation and blocked.
+
+This module parses the command instead of scanning it: tokenize with
+`shlex.shlex(..., punctuation_chars=True)` (posix quoting rules, `&&`/`||`/
+`;`/`|` recognised as their own tokens), split the token stream into
+per-operator segments, and match the tool only in **program position** of a
+segment — `dotnet` with `stryker` as its very next token, a bare
+`dotnet-stryker` token, or the wrapper script (however it's invoked: directly,
+or via an interpreter like `bash <path>` — matched by exact basename, not
+substring, so a quoted prose mention that happens to contain the wrapper's
+name cannot collide with a real path token).
+
+Heredoc bodies are stripped before tokenizing (`<<EOF ... EOF` /
+`<<'EOF' ... EOF` / `<<-EOF ... EOF`) — a command that pipes documentation
+prose through a heredoc is the same false-positive shape as a quoted
+argument, just harder for `shlex` to see through structurally.
+
+Fails closed: if `shlex` raises (unbalanced quotes it cannot tokenize), fall
+back to the old permissive regex over the raw command rather than silently
+returning False — a malformed command still gets caught rather than sliding
+through unblocked.
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+from pathlib import Path
+
+#: Matches only when shlex tokenization itself fails — the pre-#2185
+#: permissive scan, kept as the fail-closed fallback for unparseable input.
+_FALLBACK_TRIGGER = re.compile(
+    r"(?:^|[^a-zA-Z0-9])dotnet[ \t-]+stryker(?:\b|$)|csharp[_-]stryker[_-]net[_-]wrapper"
+)
+
+#: Shell operators that separate one command segment from the next. `>`/`<`
+#: (redirects) deliberately excluded — they don't start a new program.
+_SEGMENT_OPERATORS = {"&&", "||", ";", "|"}
+
+#: A `<<[-]DELIM ... DELIM` heredoc body, DELIM optionally quoted.
+_HEREDOC_RE = re.compile(r"<<-?\s*['\"]?(\w+)['\"]?\n.*?\n\1\b", re.DOTALL)
+
+#: The plugin's Stryker.NET wrapper script, matched against a token's
+#: basename — with or without hyphen/underscore separators, with or without
+#: the `.sh` extension (mirrors the two gates' previously-divergent forms).
+_WRAPPER_NAME_RE = re.compile(r"^csharp[_-]stryker[_-]net[_-]wrapper(\.sh)?$")
+
+
+def _strip_heredocs(command: str) -> str:
+    return _HEREDOC_RE.sub("", command)
+
+
+def _segments(tokens: list[str]) -> list[list[str]]:
+    segments: list[list[str]] = [[]]
+    for tok in tokens:
+        if tok in _SEGMENT_OPERATORS:
+            segments.append([])
+        else:
+            segments[-1].append(tok)
+    return [seg for seg in segments if seg]
+
+
+def _segment_is_stryker(segment: list[str]) -> bool:
+    if not segment:
+        return False
+    first = segment[0]
+    if first == "dotnet" and len(segment) > 1 and segment[1] == "stryker":
+        return True
+    if first == "dotnet-stryker":
+        return True
+    # The wrapper, invoked directly or via an interpreter (`bash <path>`,
+    # `sh <path>`) — only the program and its immediate first argument can
+    # be the wrapper path, so later arguments are never checked.
+    for tok in segment[:2]:
+        if _WRAPPER_NAME_RE.match(Path(tok).name):
+            return True
+    return False
+
+
+def is_stryker_invocation(command: str) -> bool:
+    """True only when `command` actually runs Stryker.NET — `dotnet stryker`,
+    `dotnet-stryker`, or the plugin's wrapper script, in program position of
+    one of the command's operator-separated segments. A mention of the tool
+    name in a --body/grep/echo/comment argument does not count."""
+    if not command:
+        return False
+    stripped = _strip_heredocs(command)
+    try:
+        lexer = shlex.shlex(stripped, posix=True, punctuation_chars=True)
+        lexer.whitespace_split = True
+        tokens = list(lexer)
+    except ValueError:
+        return bool(_FALLBACK_TRIGGER.search(command))
+    return any(_segment_is_stryker(seg) for seg in _segments(tokens))

package/hooks/lib/telemetry_consent.py

@@ -0,0 +1,41 @@
+"""telemetry_consent.py — shared, home-scoped telemetry consent check (#1405).
+
+Single source of truth for whether the user has opted in to the plugin's
+local telemetry writers. Reads **only** `~/.claude/telemetry.json` —
+deliberately no environment-variable branch and no project-scoped
+(`<cwd>/.claude/telemetry.json`) fallback. Consent is a user-level decision,
+not a per-project or per-invocation one.
+
+Fail-open: a missing file, a malformed file, or any read error is treated as
+"not enabled" — never raises, never blocks the calling hook.
+
+Stdlib only. See ADR 0014 / ADR 0015.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def _consent_path() -> Path:
+    return Path.home() / ".claude" / "telemetry.json"
+
+
+def is_enabled() -> bool:
+    """Return True only when `~/.claude/telemetry.json` contains
+    `{"enabled": true}`. Any other state — file absent, malformed JSON,
+    `"enabled"` false or missing, or a read error — returns False."""
+    config = _consent_path()
+    try:
+        if not config.is_file():
+            return False
+        data = json.loads(config.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    if not isinstance(data, dict):
+        return False
+    # Deliberate strict identity check (`is True`, not truthiness): a
+    # non-bool value such as `"true"` or `1` must NOT imply consent — only
+    # the literal JSON boolean `true` does.
+    return data.get("enabled") is True

package/hooks/lib/telemetry_report.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Telemetry report (issues #106, #135).
+
+Aggregates the opt-in, privacy-clean event log written by hooks/telemetry.py
+(~/.claude/metrics/telemetry.jsonl, home-scoped per #1405/#1406 Slice 1) into:
+command usage counts, skill usage counts (including agent-/auto-invoked
+skills, counted distinctly from user-typed commands — #135), and the
+pre-commit review gate's bypass rate (bypassed / (fired + bypassed)). With
+telemetry disabled the log doesn't exist and this reports that nothing was
+collected — satisfying "with it disabled, nothing leaves the machine."
+
+Usage: telemetry_report.py [--log ~/.claude/metrics/telemetry.jsonl] [--json]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import Counter
+from pathlib import Path
+
+_DEFAULT_LOG = Path.home() / ".claude" / "metrics" / "telemetry.jsonl"
+
+
+def aggregate(log: Path) -> dict:
+    commands: Counter = Counter()
+    skills: Counter = Counter()
+    gate_by_name: dict[str, Counter] = {}
+    total_events = 0
+    for line in log.read_text().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            e = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        total_events += 1
+        if e.get("event") == "command":
+            commands[e.get("name", "?")] += 1
+        elif e.get("event") == "skill":
+            skills[e.get("name", "?")] += 1
+        elif e.get("event") == "gate":
+            name = e.get("name", "?")
+            gate_by_name.setdefault(name, Counter())[e.get("outcome", "?")] += 1
+
+    gate_summary = {}
+    for name, oc in gate_by_name.items():
+        fired = oc.get("fired", 0)
+        bypassed = oc.get("bypassed", 0)
+        denom = fired + bypassed
+        gate_summary[name] = {
+            "fired": fired,
+            "bypassed": bypassed,
+            "bypass_rate": round(bypassed / denom, 4) if denom else 0.0,
+        }
+    return {
+        "total_events": total_events,
+        "command_usage": dict(commands.most_common()),
+        "skill_usage": dict(skills.most_common()),
+        "gates": gate_summary,
+    }
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--log", default=str(_DEFAULT_LOG))
+    ap.add_argument("--json", action="store_true")
+    args = ap.parse_args(argv)
+
+    log = Path(args.log)
+    if not log.is_file():
+        print("Telemetry is off (or no events recorded): "
+              f"{log} does not exist. Nothing has left the machine.")
+        return 0
+
+    summary = aggregate(log)
+    if args.json:
+        print(json.dumps(summary, indent=2))
+        return 0
+
+    print(f"# Telemetry report — {summary['total_events']} event(s)\n")
+    print("## Command usage (user-typed slash commands)")
+    if summary["command_usage"]:
+        for name, n in summary["command_usage"].items():
+            print(f"  /{name}: {n}")
+    else:
+        print("  (none)")
+    print("\n## Skill usage (incl. agent-/auto-invoked)")
+    if summary["skill_usage"]:
+        for name, n in summary["skill_usage"].items():
+            print(f"  {name}: {n}")
+    else:
+        print("  (none)")
+    print("\n## Gate bypass rates")
+    if summary["gates"]:
+        for name, g in summary["gates"].items():
+            print(f"  {name}: {g['bypassed']} bypassed / "
+                  f"{g['fired'] + g['bypassed']} attempts "
+                  f"({g['bypass_rate'] * 100:.1f}% bypassed)")
+    else:
+        print("  (none)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/hooks/lib/test_file_classify.py

@@ -0,0 +1,160 @@
+"""test_file_classify — shared test-file classifier + build-phase reader.
+
+Single encoding of `knowledge/test-file-indicators.md` for hooks that need to
+decide "is this a test file?" (the refactor test-freeze guards), plus the
+reader for the build-phase state `/build` records at each step-phase
+transition (`.claude/memory/build-phase.json`).
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+_LIB_DIR = Path(__file__).resolve().parent
+if str(_LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(_LIB_DIR))
+
+import artifact_paths
+
+#: memory/build-phase.json older than this is treated as absent — a crashed
+#: build must not freeze tests forever.
+STALE_AFTER_SECONDS = 4 * 60 * 60
+
+_JS_TS_NAME_RE = re.compile(r"\.(test|spec)\.[^./]+$", re.IGNORECASE)
+_STEP_DEF_RE = re.compile(r"(\.steps\.[^./]+$|StepDefinitions\.[^./]+$|Steps\.[^./]+$)")
+_CSHARP_MARKER_RE = re.compile(r"\[(Fact|Theory|Test|TestCase|TestMethod|TestClass)\]")
+_JAVA_MARKER_RE = re.compile(r"@(Test|ParameterizedTest|TestFactory)\b")
+_JAVA_CLASS_SUFFIXES = ("Test", "Tests", "TestCase", "Spec")
+_PYTHON_NAME_RE = re.compile(r"^(test_.+|.+_test)\.py$", re.IGNORECASE)
+
+#: How much of a file to read when a content probe is needed.
+_CONTENT_PROBE_BYTES = 256 * 1024
+
+
+def _read_probe(path: Path) -> str:
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as handle:
+            return handle.read(_CONTENT_PROBE_BYTES)
+    except OSError:
+        return ""
+
+
+def is_test_file(path: str, content: str | None = None) -> bool:
+    """True when `path` is a test file per knowledge/test-file-indicators.md.
+
+    `content` overrides the on-disk read for the languages whose indicator is
+    content-based (C#, Java) — pass it in tests or when the file is not on
+    disk yet (a PreToolUse Write).
+    """
+    if not path:
+        return False
+    p = Path(path)
+    name = p.name
+    posix = p.as_posix()
+
+    # BDD/Gherkin — a .feature file always counts as a test file.
+    if name.lower().endswith(".feature"):
+        return True
+    if _STEP_DEF_RE.search(name):
+        return True
+
+    # JS/TS — *.test.*, *.spec.*, or inside __tests__/
+    if _JS_TS_NAME_RE.search(name):
+        return True
+    if "/__tests__/" in posix or posix.startswith("__tests__/"):
+        return True
+
+    # Python — test_*.py or *_test.py (pytest/unittest convention).
+    if _PYTHON_NAME_RE.match(name):
+        return True
+
+    suffix = p.suffix.lower()
+    if suffix == ".cs":
+        probe = content if content is not None else _read_probe(p)
+        return bool(_CSHARP_MARKER_RE.search(probe))
+
+    if suffix == ".java":
+        if p.stem.endswith(_JAVA_CLASS_SUFFIXES):
+            return True
+        probe = content if content is not None else _read_probe(p)
+        return bool(_JAVA_MARKER_RE.search(probe))
+
+    return False
+
+
+def _parse_written_at(value: str) -> float | None:
+    """ISO-8601 → epoch seconds, tolerant of a trailing 'Z'. None when unparseable."""
+    if not isinstance(value, str) or not value:
+        return None
+    candidate = value.strip()
+    if candidate.endswith("Z"):
+        candidate = candidate[:-1] + "+00:00"
+    try:
+        parsed = datetime.fromisoformat(candidate)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.timestamp()
+
+
+def build_phase_path(project_dir: Path) -> Path:
+    # Read-only: no Python writer of build-phase.json exists anywhere in
+    # hooks/ — it is agent-instruction-written (build/SKILL.md). migrate=False
+    # so this read never migrates a legacy file or creates .claude/memory/ as
+    # a side effect.
+    return artifact_paths.resolve_file(
+        "memory", "build-phase.json", project_dir, migrate=False
+    )
+
+
+def read_build_phase(
+    project_dir: Path, now: float | None = None
+) -> tuple[dict | None, str | None]:
+    """Read `memory/build-phase.json`. Returns `(state, error)`.
+
+    - `(None, None)`  — no state recorded, or the state is stale
+      (> STALE_AFTER_SECONDS old): guards treat both as "no phase".
+    - `(None, <why>)` — the file exists but is unreadable or malformed:
+      guards fail OPEN and record the reason in the audit log.
+    - `(state, None)` — an active, fresh phase record. `state["phase"]` is a
+      string; `state["test_files_staged"]` is always a list of strings.
+
+    `now` is the injectable clock (epoch seconds) for staleness tests.
+    """
+    path = build_phase_path(project_dir)
+    if not path.is_file():
+        return None, None
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        return None, f"unreadable build-phase state: {exc}"
+    try:
+        data = json.loads(raw)
+    except ValueError:
+        return None, "malformed build-phase state: invalid JSON"
+    if not isinstance(data, dict):
+        return None, "malformed build-phase state: not an object"
+    phase = data.get("phase")
+    if not isinstance(phase, str) or not phase:
+        return None, "malformed build-phase state: missing phase"
+    written_at = _parse_written_at(data.get("written_at", ""))
+    if written_at is None:
+        return None, "malformed build-phase state: missing/unparseable written_at"
+    current = time.time() if now is None else now
+    if current - written_at > STALE_AFTER_SECONDS:
+        return None, None
+    staged = data.get("test_files_staged", [])
+    if not isinstance(staged, list):
+        return None, "malformed build-phase state: test_files_staged not a list"
+    files: list[str] = [f for f in staged if isinstance(f, str) and f]
+    state = dict(data)
+    state["test_files_staged"] = files
+    return state, None

package/hooks/lib/token_efficiency_limits.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""token_efficiency_limits — shared thresholds for token-efficiency checks.
+
+Single source of truth for the limits enforced by both
+`hooks/token_efficiency_review.py` (the shipped PostToolUse hook) and
+`plugins/dev-team/scripts/token_efficiency_review.py` (the review-agent CI runner). Both
+previously hardcoded their own copy of these numbers.
+
+It is also the single source of truth for two small pieces of *logic* that
+drifted between those same two callers: which filename counts as "CLAUDE.md"
+and how "character count" is measured. The hook used to match only the exact
+case `CLAUDE.md` and count bytes; the CI runner matched case-insensitively
+and counted decoded characters — so the same file could report two different
+counts, or be checked in one caller and silently skipped in the other,
+depending on nothing but its name's casing.
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# CLAUDE.md character-count limit (advisory in the hook, hard error in CI).
+CLAUDE_MD_CHAR_LIMIT: int = 5000
+
+# Any tracked source/CLAUDE.md file's line-count limit.
+FILE_LINE_LIMIT: int = 500
+
+# CLAUDE.md rule-count limit. Lives here rather than as a local literal in the
+# CI runner (#1651) so this module's "single source of truth" claim above is
+# true of every limit, not just the two that happened to be duplicated when it
+# was written. Only the CI runner reads it today — the shipped hook does not
+# count rules — but a second reader is exactly how the other two limits drifted
+# into needing this module in the first place.
+CLAUDE_MD_RULE_LIMIT: int = 200
+
+
+def is_claude_md_file(path: Path) -> bool:
+    """Return True when `path`'s filename is CLAUDE.md, case-insensitively."""
+    return path.name.lower() == "claude.md"
+
+
+def char_count(path: Path) -> int:
+    """Return the decoded character count of `path`.
+
+    Character count, not byte count: `CLAUDE_MD_CHAR_LIMIT` is a token-budget
+    proxy, and decoded characters track token count far more closely than
+    bytes do for any file containing multi-byte UTF-8 sequences.
+    """
+    return len(path.read_text(encoding="utf-8", errors="replace"))

package/hooks/lib/turn_identity.py

@@ -0,0 +1,77 @@
+"""turn_identity — shared transcript/turn identity helpers.
+
+Extracted from the tail-window logic that used to live independently in
+both `codegraph_nudge.py` (read side) and `codegraph_turn_mark.py` (write
+side) — the latter's own docstring already flagged this exact duplication
+as intended for a "future PR." Both hooks now import from here so the
+transcript_id/turn_counter computation can't drift between the two sides
+of the sentinel contract.
+
+Stdlib-only.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# Same 1 MiB tail window both hooks applied independently before this
+# extraction — a monotonically growing transcript stays O(1) per read.
+_TAIL_WINDOW_BYTES = 1_048_576
+
+_USER_LINE_MARKER = b'"type":"user"'
+
+
+def transcript_id(path: str) -> str:
+    """basename(path) with the last extension stripped.
+
+    `Path.stem` matches the shapes the harness emits (`.jsonl`, `.json`,
+    no extension).
+    """
+    return Path(path).stem
+
+
+def count_user_lines(transcript_path: Path) -> int:
+    """Count `"type":"user"` occurrences in the last 1 MiB of the transcript.
+
+    Errors -> 0 (fail-open). Reads a bounded tail so growing transcripts
+    don't turn every call into a full-file scan.
+    """
+    try:
+        with transcript_path.open("rb") as fh:
+            fh.seek(0, os.SEEK_END)
+            size = fh.tell()
+            offset = max(0, size - _TAIL_WINDOW_BYTES)
+            fh.seek(offset, os.SEEK_SET)
+            tail = fh.read()
+    except OSError:
+        return 0
+    return tail.count(_USER_LINE_MARKER)
+
+
+# Single source of truth for the sentinel's location relative to the
+# project dir — both code_intelligence_nudge.py (read side) and
+# code_intelligence_turn_mark.py (write side) used to hardcode this
+# path independently.
+SENTINEL_RELATIVE_PATH = Path(".claude") / "code-intelligence-turn-state.json"
+
+
+def matches_current_turn(sentinel: dict, tid: str, tc: int) -> bool:
+    """True when `sentinel`'s identity fields match the freshly computed
+    transcript_id/turn_counter for the current call — i.e. the sentinel was
+    written earlier in the *same* turn.
+
+    Owns the type coercion once for both sides of the sentinel contract:
+    `transcript_id` is compared as a string (coercing a missing/`None`
+    value to `""`), and `turn_counter` is compared via `int()` wrapped in a
+    try/except — a non-numeric or otherwise uncoercible value (corrupt
+    sentinel) resolves to `False` rather than raising, matching this
+    module's fail-open posture.
+    """
+    sentinel_tid = str(sentinel.get("transcript_id") or "")
+    if sentinel_tid != tid:
+        return False
+    try:
+        return int(sentinel.get("turn_counter")) == tc
+    except (TypeError, ValueError):
+        return False

package/hooks/lib/verify_guard_state.py

@@ -0,0 +1,110 @@
+"""Shared per-session state helpers for verify_guard.py and
+verify_guard_edit_marker.py (#708).
+
+verify_guard.py (PreToolUse `Bash`) needs to tell a genuinely stuck loop
+(the same verify command run over and over with zero intervening code
+changes) apart from ordinary TDD re-verification (RED, GREEN, REFACTOR
+each legitimately re-run the same command, but each preceded by a real
+edit). The two hooks communicate that signal through one JSON state file
+per session, keyed identically by both hooks — so this module exists to
+make sure "identically" is actually true, rather than two independently
+maintained copies of the same hashing/keying logic drifting apart.
+
+State shape (JSON object): ``{"hash": str, "count": int, "edited": bool}``.
+``hash`` and ``count`` are verify_guard.py's consecutive-identical-command
+counter; ``edited`` is set true by verify_guard_edit_marker.py whenever an
+Edit/Write/NotebookEdit tool call is observed, and consumed (reset to
+false) by verify_guard.py on its next run.
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import time
+import zlib
+from pathlib import Path
+
+_STATE_DIRNAME = "dev-team-verify-guard"
+
+# Same TTL-purge-on-write pattern as tdd_guard.py / mutation_adapters/lib.py
+# (#732) — one state file is written per session with no expiry otherwise,
+# so long-lived hosts accumulate a file per session forever.
+_STATE_TTL_SECONDS = 14400  # 4 hours
+
+
+def cksum(text: str) -> str:
+    """In-process, deterministic hash used for state-key/hash purposes.
+
+    The bash-parity `cksum` shell-out this used to require is gone (the
+    .sh implementations were removed — ADR 0015 / epic #572); only that
+    both hooks hash the same way matters, so the state key/hash they
+    compute for the same session agrees — hence the shared helper rather
+    than two copies. Uses zlib.crc32, matching bash_retry_guard.py's own
+    `_cksum` exactly so checksums stay comparable if anything ever
+    persists/compares both.
+    """
+    return str(zlib.crc32(text.encode("utf-8")) & 0xFFFFFFFF)
+
+
+def tmpdir() -> Path:
+    return Path(os.environ.get("TMPDIR") or tempfile.gettempdir() or "/tmp")
+
+
+def state_dir() -> Path:
+    return tmpdir() / _STATE_DIRNAME
+
+
+def state_key(session_id: str, cwd: str) -> str:
+    """Prefer session_id, fall back to cksum of cwd (or $PWD when both empty)."""
+    if session_id:
+        return session_id
+    return cksum(cwd or os.getcwd())
+
+
+def state_file(key: str) -> Path:
+    return state_dir() / f"{key}.json"
+
+
+def read_state(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def purge_stale(directory: Path) -> None:
+    """Delete `*.json` state files in `directory` untouched past the TTL.
+
+    Both verify_guard.py and verify_guard_edit_marker.py write through
+    `write_state`, so calling this there is the single choke point that
+    keeps the shared state dir from accumulating one file per session
+    forever (#732).
+    """
+    if not directory.is_dir():
+        return
+    now = time.time()
+    for path in directory.glob("*.json"):
+        try:
+            if now - path.stat().st_mtime > _STATE_TTL_SECONDS:
+                path.unlink()
+        except OSError:
+            pass
+
+
+def write_state(path: Path, data: dict) -> None:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return
+    purge_stale(path.parent)
+    try:
+        path.write_text(json.dumps(data, separators=(",", ":")) + "\n")
+    except OSError:
+        pass