interwatch

keep priority P2 effort M wave 2

What it does: A doc freshness + correctness monitor (v0.5.0). interwatch-scan.py evaluates 17 deterministic/probabilistic drift signals (version_bump, component_count_changed, bead_closed/created deltas, file renamed/deleted/created via git, commits_since_update, bead_reference_stale, bead_count_mismatch, unsynthesized_doc_count, skills_without_compact, etc.) against a declarative watchables registry with auto-discovery, computes weighted drift scores → confidence tiers (Green/Low/Medium/High/Certain), and writes .interwatch/drift.json as a published producer/consumer contract. Two automation layers: Layer 1 git post-commit/post-merge hook refreshes drift state (pure-Python, fail-open, opt-in); Layer 2 PreToolUse hook surfaces drift on doc Read/Edit/Write and auto-fires /interwatch:refresh only on Certain with Goodhart guardrails (24h cooldown, 5/day budget, kill-switch, per-watchable opt-out, content-hash no-op detection). interwatch-audit.py gathers executable ground truth (real counts, build systems, file existence, versions, cross-doc consistency) and dispatches a sonnet stranger-perspective agent to validate doc claims against that ground truth. Regeneration delegated to interpath (product docs) / interdoc (code docs).

Rationale: Mature, distinctively engineered, and aligned with several 2026 frontier findings. The correctness audit’s core design — grounding the LLM critique in tool-computed ground truth (real counts, build-system detection, file existence, cross-doc consistency) rather than free-form prose — is exactly the structured/tool-grounded verification pattern the reflection-loop research (ReVeal; ‘From Code to Courtroom’) says is the only kind of critique that reliably improves output. The Goodhart guardrails (cooldown + daily budget + no-op content-hash detection + kill-switch) and pervasive fail-open discipline embody the ‘controlled blast radius’ security framing and human-auditable git-tracked state the memory-integrity findings advocate. The Layer-1/Layer-2 deterministic hooks match the harness-engineering discipline (anything that must happen every time is a hook, not a hope). This is the ecosystem’s only ‘is this doc stale or wrong?’ sensor; it should be kept and incrementally improved, not modernized wholesale.

SOTA gap: All drift detection is lexical/structural — regex/glob counts, git name-status, bead CLI deltas, mtime thresholds. It cannot detect SEMANTIC drift: prose that still describes a renamed concept, a changed formula, or behavior that no longer matches reality while the surface numbers/paths still line up (precisely the elf-revel ‘changed formulas / renamed concepts’ wiki-drift case its host project cares about). The frontier idea it lacks is embedding-based semantic drift detection: embed doc sections vs. current code/AGENTS.md and flag low-similarity sections as a new probabilistic signal — drawing on the agentic-RAG/embedding-gating findings and the ecosystem’s own intersearch/interknow(qmd) embedding infra (qmd reports ‘No vector embeddings yet’). Secondary, smaller gap: the correctness audit dispatches a single sonnet agent with no variance/reliability check, against the Beyond-pass@1 finding that one success run is not evidence of reliability.

Redundancy: Minimal and largely intentional. interpath consumes drift.json (interpath:all reads it) — a deliberate sensor/generator contract documented in AGENTS.md as an intentional structural cycle that should NOT be refactored to a third coordinator. interdoc and interpath are regeneration targets, not overlaps. interscribe enforces CLAUDE.md/AGENTS.md content boundaries (structure), a different concern from freshness/correctness. No true duplication with any other interverse plugin.

Actions:

Fix the stale self-contradiction: README.md line 61 still says ‘No hooks: drift detection is on-demand, not event-driven’ but two hook layers (git post-commit/merge + PreToolUse) shipped since; the doc-freshness plugin has stale docs. Update README to describe the hook layers (P1/S).
Add a semantic_drift signal: embed watched-doc sections vs. current source/AGENTS.md via intersearch/interknow(qmd) embeddings and emit a probabilistic count when section similarity drops below a threshold — closes the lexical-only gap (P2/L, gated on qmd embed being enabled).
Harden the correctness audit against single-shot stochasticity per the Beyond-pass@1 finding: run the audit agent k=2-3 trials and report only findings that reproduce, or mask author identity / use a distinct judge model to guard against self-preference bias (P3/M).
Reconcile signal-count drift in the docs themselves: README/AGENTS/CLAUDE variously say 14, 16, and 17 signal types and ‘4 vs 5 commands’ — interwatch should pass its own component_count_changed audit; align the numbers (P2/S).